atahango/belgeler/GEMINI.md

You are Generate a modern, production-ready React admin panel frontend for an existing Go (Gin + GORM + PostgreSQL) backend described below. Output TypeScript React code (Create Vite+React+TS), using Tailwind CSS by default (provide brief notes how to swap to Bootstrap), with clean component architecture, accessibility, responsive design, and test coverage for critical pieces.

Project context (backend):

• Language: Go 1.25.7 (Golang)
• Web framework: Gin Gonic
• DB: PostgreSQL via GORM
• Auth: JWT (github.com/golang-jwt/jwt/v5), OAuth2 (golang.org/x/oauth2 + github.com/markbates/goth)
• Security: bcrypt for passwords, CORS, Rate Limiting

Admin panel main functional areas (deliver full UI + API contracts + example code):

1. Kullanıcı Yönetimi (User Management)

   • Pages: list, create, edit, view profile, change password, assign roles
   • List supports pagination, server-side searching, sorting, bulk delete/activate/deactivate
   • Detail shows last login, created_at, roles, OAuth providers linked
   • API contract examples:
     • GET /api/v1/admin/users?query=&page=1&per_page=20&sort=created_at:desc Response: { data: User[], meta: { page, per_page, total } }
     • GET /api/v1/admin/users/:id
     • POST /api/v1/admin/users { name, email, password, roles:[] }
     • PUT /api/v1/admin/users/:id
     • DELETE /api/v1/admin/users/:id
   • User model (TypeScript interface) should include id, name, email, roles:string[], active:boolean, created_at, updated_at, last_login

2. CORS Whitelist Yönetimi

   • CRUD for whitelist origins
   • Validation for origin format (scheme + host + optional port + optional path)
   • UI: Add origin modal, origin list with enabled toggle, search
   • API contract:
     • GET /api/v1/admin/cors/whitelist
     • POST /api/v1/admin/cors/whitelist { origin, description, enabled }
     • PUT /api/v1/admin/cors/whitelist/:id
     • DELETE /api/v1/admin/cors/whitelist/:id

3. CORS Blacklist Yönetimi

   • Similar to whitelist but used for blocking specific origins or paths
   • Provide a pattern option (exact origin or wildcard)
   • API contract analogous to whitelist under /cors/blacklist

4. CORS RateLimit Yönetimi

   • Define rate limit rules per origin or per route (e.g., origin="https://example.com", limit=100, window_seconds=60)
   • UI: table of rules, inline edit for limit/window, visual indicator if rule conflicts with whitelist/blacklist
   • API:
     • GET /api/v1/admin/cors/ratelimit
     • POST /api/v1/admin/cors/ratelimit { originPattern, limit, window_seconds, enabled, description }
     • PUT /api/v1/admin/cors/ratelimit/:id
     • DELETE /api/v1/admin/cors/ratelimit/:id

5. Tags Yönetimi

   • Tags for categorizing contacts or users
   • CRUD, tag color selection, bulk apply/remove to contacts
   • API:
     • GET /api/v1/admin/tags
     • POST /api/v1/admin/tags { name, color, description }
     • PUT /api/v1/admin/tags/:id
     • DELETE /api/v1/admin/tags/:id

6. Contacts Yönetimi

   • Contacts list, import CSV, export CSV, tag assignment, contact detail, notes history
   • Bulk actions: export, tag, delete
   • API:
     • GET /api/v1/admin/contacts?query=&tag=&page=
     • POST /api/v1/admin/contacts { name, email, phone, tags:[] }
     • PUT /api/v1/admin/contacts/:id
     • DELETE /api/v1/admin/contacts/:id
     • POST /api/v1/admin/contacts/import (CSV multipart)
     • GET /api/v1/admin/contacts/export?query=&tag=

Shared requirements and conventions:

• Auth:
  • Admin panel must authenticate using JWT. Prefer httpOnly secure cookie provided by backend for production. If cookie not possible, use secure storage (e.g., localStorage) but implement refresh token flow.
  • Login: POST /api/v1/auth/login -> { access_token, refresh_token, expires_in }
  • Refresh: POST /api/v1/auth/refresh -> new access_token
  • Logout: POST /api/v1/auth/logout
  • All admin APIs under /api/v1/admin/* must include Authorization: Bearer if not using cookie.
• Error handling:
  • Centralized API client with typed errors, retry logic for idempotent calls, exponential backoff for network issues.
  • Display user-friendly toasts for success/error.
• Forms:
  • Use react-hook-form + Zod for validation. Provide schema examples for each form.
• Data fetching:
  • Use TanStack Query (react-query) for caching, optimistic updates, pagination helpers.
• UI/UX:
  • Responsive, mobile-first. Desktop admin layout: sidebar navigation, topbar with user menu, page content.
  • Provide dark mode toggle.
  • Use accessible components (aria attributes, keyboard navigable, proper focus management for modals).
  • Provide skeleton loaders for lists and cards.
  • Modal confirmations for destructive actions.
  • CSV import with progress and row-level error reporting.
• Styling:
  • Tailwind CSS with a design tokens file (colors, spacing, fonts). Provide a small default color palette and tokens.
  • If user prefers Bootstrap, include brief instructions: "to change to Bootstrap, swap Tailwind classes for Bootstrap classes and use react-bootstrap components; keep component structure and state logic identical."
• Component architecture and naming:
  • Atomic components in src/components/ui (Button, Input, Select, Modal, Table, Badge, Tag, Toast)
  • Feature pages in src/features/ with subfolders components/, hooks/, services/, types/
  • API client in src/lib/api.ts and typed services in src/services/*
  • Utilities: src/lib/validation.ts, src/lib/csv.ts, src/lib/date.ts
• Types:
  • Use TypeScript interfaces/types for all API payloads/responses.
  • Provide exact types for User, CORSRule, RateLimitRule, Tag, Contact, PaginatedResponse
• Tests:
  • Unit tests with Vitest for core UI components and critical hooks (login flow, useUsers hook).
  • Integration tests for key flows with Playwright (login -> navigate -> create user -> verify).
  • Example test files for one feature.
• Accessibility & SEO:
  • Admin pages should include title tags and ARIA labels.
• Internationalization:
  • Prepare i18n-ready strings using react-i18next (English + Turkish), but initial content in Turkish.
• Storybook:
  • Configure Storybook for UI components with a story for each atomic component.

Scaffold & Commands (explicit):

• Use Vite:
  • npx create-vite@latest admin-panel --template react-ts
• Install libs:
  • npm install axios @tanstack/react-query react-router-dom react-hook-form zod @hookform/resolvers tailwindcss postcss autoprefixer classnames react-i18next i18next
  • Dev: vitest @testing-library/react @testing-library/jest-dom playwright storybook (or provide setup steps)
• Tailwind setup steps (brief):
  • npx tailwindcss init -p
  • configure content to include src/**/*.{js,ts,jsx,tsx}
  • add base/components/utilities imports in index.css

Detailed tasks for you (Copilot): generate files with content, tests, and examples

1. Project skeleton with above folder structure and package.json scripts.
2. Tailwind config and design tokens file (src/styles/tokens.ts).
3. src/lib/api.ts: axios instance with interceptors for auth, refresh token logic, typed responses.
4. Auth pages & flows: Login page, ProtectedRoute wrapper, AuthProvider context.
5. Dashboard page with summary cards (total users, active origins, tags count, contacts count), charts placeholders.
6. Full implementation for User Management feature (list, create, edit, view), including:
   • useUsers hook with react-query
   • UsersService (API calls)
   • UserList component with table, pagination, filters, bulk actions
   • UserForm component with react-hook-form + Zod
   • Unit tests for useUsers and UserForm validation
7. Implement one CORS feature (Whitelist) fully equivalent to Users (list, create, edit, delete) with validation sample.
8. Provide skeleton pages/components for Blacklist, RateLimit, Tags, Contacts with detailed TODO comments and type stubs.
9. Create reusable UI components: Button, Input, Select, Modal, Table, Badge, Tag, Toast. Include accessible props.
10. Add Storybook stories for Button, Input, Modal, Table, Tag.
11. Add Playwright e2e test that verifies admin login and creation of a user.
12. Add README with setup, run, test, and build instructions; include backend contract assumptions and security notes for httpOnly cookies vs localStorage.
13. Provide example .env.example with variables: VITE_API_BASE_URL, VITE_USE_COOKIES, VITE_OAUTH_REDIRECT, etc.

Code style and conventions:

• Use ESLint with recommended rules and Prettier.
• Use TypeScript strict mode.
• Prefer functional components and hooks.
• Keep components small and focused; prefer composition over inheritance.

Acceptance criteria (what “done” means):

• You can run the frontend locally and log in against the provided backend endpoints (stubs/mock server if backend not available).
• Full CRUD working for Users and CORS Whitelist with typed API clients and react-query data layer.
• Forms have client-side validation with Zod and show inline error messages.
• UI is responsive, accessible, and supports dark mode.
• Tests for core flows and components pass.
• Storybook shows atomic components.

Deliverables (for each commit/PR):

• Clear commit messages and separate commits per feature.
• Provide example API responses and sample seed data for local development (JSON fixtures).
• Document any backend changes needed (routes/middlewares) in the README under "Backend expectations".

Tone and priorities for Copilot code generation:

• Prioritize security and type-safety.
• Keep UX polished (loading states, toasts, confirmations).
• Provide comments and TODOs where backend contract ambiguity exists.
• Generate code in small, reviewable chunks (one feature per PR ideally).

If you need to scaffold only the initial app and one completed feature to start, prioritize:

1. Project skeleton and auth flow (Login, ProtectedRoute)
2. Full User Management implementation
3. Full CORS Whitelist implementation Then scaffold the rest with TODOs and types.

Localization: start with Turkish UI labels and provide English fallback.

End of prompt.