Cline rules

1## Brief overview
2This file contains guidelines for developing on the **PureCore** project — a full-stack Go web framework using GoFiber v3 + PostgreSQL (backend) and Bun + Vite + Vue 3 + TailwindCSS + DaisyUI (frontend).
3 
4## Project architecture
5- Backend entry: `main.go` → Cobra CLI (`cmd/`) → GoFiber v3 server
6- Core layer (`core/`) provides: database singleton, request/response wrappers, router builder, JWT middleware helpers, language manager, migration runner
7- Routes defined in `routes/api.go` using Laravel-style chaining: `Prefix → Middleware → Group`
8- Models in `app/Models/` embed `core.Model` (ID, CreatedAt, UpdatedAt, DeletedAt)
9- Controllers in `app/Http/Controllers/` use `core.H()` wrapper that auto-injects `*core.Request` and `*core.Response`
10- Frontend entry: `web/` — Vite SSR with `server.js` as the Node/Bun SSR server
11- Shared translations in `lang/` (used by both Go backend and Vue frontend)
12 
13## Database and migrations
14- All database schema changes MUST be done via migration files only
15- Use `purecore make:migration <name>` to generate a new migration file in `database/migrations/`
16- Never modify existing migration files — always create new ones
17- Migrations are registered via `init()` and tracked in a `migrations` table in the database
18- Models should extend `core.Model` for consistent base fields
19 
20## Frontend layout rules
21- All admin pages after login MUST use `AdminLayout`/`AdminNavbar` — never use the public-facing `Navbar.vue`
22- Admin pages include: AdminDashboard, AdminSettings, and any future pages under the `/{admin}/` route prefix
23- Public pages (HomePage, NotFound, etc.) use `Navbar.vue` + `Footer.vue`
24- Login and Register pages use the public `Navbar.vue` + `Footer.vue` — they are NOT standalone pages
25 
26## Frontend conventions
27- Vue 3 with `<script setup>` syntax and Composition API
28- Styling: TailwindCSS 4 utility classes + DaisyUI 5 component classes
29- Routing: Vue Router 5 with SSR (memory history on server, web history on client)
30- State management: Vue composables (`web/src/composables/`)
31- API calls: proxy `/api` to backend (port 9002) via Vite dev server or SSR server
32- Environment variables: `VITE_ADMIN_ROUTE_PREFIX` for admin route prefix
33 
34## CLI commands (code generation)
35- `purecore serve` — start the HTTP server
36- `purecore migrate` — run pending migrations
37- `purecore make:model <Name>` — create a GORM model
38- `purecore make:controller <Name>` — scaffold a CRUD controller
39- `purecore make:migration <name>` — create a timestamped migration file
40 
41## Migration and model/controller synchronization
42- When creating a new migration file, you MUST also create or update the corresponding model and controller
43- Migration → Model → Controller should always stay in sync
44- For example: creating a `create_web_options_table` migration means also creating `WebOption` model and `OptionController` with CRUD endpoints
45- New models embed `core.Model` for consistent ID, timestamps, and soft delete fields
46 
47## Response format
48All API endpoints return JSON in this shape:
49```json
50{ "code": 0, "message": "success", "data": ... }
51```
52Error responses: `{ "code": 4xx/5xx, "message": "error description" }`
53Paginated responses include: `total`, `page`, `per_page` alongside `data`
54 
55## SEO (Search Engine Optimization)
56- `web/src/composables/useSEO.js` provides a Vue composable for setting page-level SEO meta tags
57- `useSEO({ title, description, keywords })` sets `<title>`, `<meta name="description">`, and `<meta name="keywords">` tags
58- Title format: `"Page Title - Site Name"` or just `"Site Name"` if page title is empty
59- Site name, description, and keywords are loaded from admin options (`site_name`, `site_description`, `site_keywords`) via `initSEO()`
60- `initSEO()` is called in `web/src/main.js` at app startup alongside `initI18n()`
61- SSR meta tags are injected in `web/server.js` using project info from `web/package.json` — placeholders `<!--seo-title-->`, `<!--seo-description-->`, `<!--seo-keywords-->` in `web/index.html` are replaced at render time
62- Every page component should call `useSEO()` with page-specific title and description
63 
64## Authentication
65- Admin routes use JWT with access token (15 min) + refresh token (7 days)
66- Admin route prefix is configurable via `ADMIN_ROUTE_PREFIX` env var
67- `AdminAuth` middleware verifies the token and checks `token_version` for invalidation
68- `useAuth.js` composable handles client-side token management and auto-refresh
69 
70## Language / i18n
71- Backend loads translations from `lang/` directory (JSON files, nested structure)
72- Frontend i18n module loads translations via `/lang/{locale}.json` (proxied from `web/public/lang/`)
73- Cookie `purecore-locale` persists user language choice across requests
74- Both sides flatten nested JSON to `"group.key"` format
75