diff --git a/ AGENTS.md b/AGENTS.md similarity index 99% rename from AGENTS.md rename to AGENTS.md index 9cb11b5..70d8b4d 100644 --- a/ AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ For new features, architecture changes, domain rule changes, or public behavior Update documentation only when implementation changes affect: - feature scope - business rules -- architectureڑڑ +- architecture - public behavior Do not update documentation for small isolated fixes or purely visual changes. diff --git a/CLAUDE.md b/CLAUDE.md index ea4bc29..19b8e97 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,29 +12,30 @@ npm run lint # Run ESLint npm run test # Run all tests with Vitest npx vitest run tests/some-file.test.ts # Run a single test file -# Database -npm run prisma:generate # Regenerate Prisma client after schema changes -npm run db:migrate # Apply migrations (production) -npm run db:migrate:dev # Create and apply dev migration -npm run db:seed # Seed the database +# Database (Drizzle ORM + drizzle-kit) +npm run db:generate # Generate a migration from schema changes +npm run db:migrate # Apply migrations +npm run db:push # Push schema to DB directly (dev shortcut, no migration) +npm run db:studio # Open Drizzle Studio to browse the database ``` -### Docker (production/staging) +### Docker / task runner (see Makefile) ```bash -make start # Build and start all containers +make start # Start DB container + dev server (http://localhost:3014) make stop # Stop containers -make deploy # Pull + rebuild + restart -make logs # Follow container logs -make db-init # Generate client, apply migrations, and seed (first run) -make db-shell # Open psql shell -make app-shell # Open shell in app container +make db-up # Start only the database container +make migrate # Apply Drizzle migrations +make studio # Open Drizzle Studio +make psql # Open a psql shell on the database +make test # Run the whole test suite + copy-paste summary +make deploy # (on server) Pull + rebuild + restart make health # Hit /api/health via public URL ``` ## Architecture -This is a multilingual Next.js (App Router) portfolio site with an admin workspace. Stack: TypeScript, next-intl, Prisma + PostgreSQL, Tailwind CSS, Radix UI, framer-motion, nodemailer. +This is a multilingual Next.js (App Router) portfolio site with an admin workspace. Stack: TypeScript, next-intl, Drizzle ORM + PostgreSQL, Tailwind CSS, Radix UI, framer-motion, nodemailer. ### Routing overview @@ -46,7 +47,7 @@ Localized routes for `de`, `en`, `ar`. Default locale is dynamic (stored in `App **Admin workspace** — `app/_admin/` (canonical source) Accessed via a dedicated subdomain (`root.mohfarawati.de`) in production, or via the `/root` path prefix in development. The middleware rewrites both to `app/admin-internal/`. The `app/root/` and `app/admin-internal/` directories mirror `app/_admin/` — treat `app/_admin/` as the source of truth. -The full routing rewrite logic lives in `lib/admin-routing.ts` and `middleware.ts`. +The full routing rewrite logic lives in `lib/admin-routing.ts` and `proxy.ts` (the Next.js 16 middleware entry point — this project has no `middleware.ts`). ### i18n @@ -58,7 +59,7 @@ The full routing rewrite logic lives in `lib/admin-routing.ts` and `middleware.t ### Persistence -Prisma client is in `lib/prisma.ts`. All DB access must go through server-side modules in `lib/`. Client components must never access Prisma. +The Drizzle client is in `lib/db/index.ts` (postgres.js driver); the schema is in `lib/db/schema.ts` and DB enums in `lib/db/enums.ts`. All DB access must go through server-side modules in `lib/`. Client components must never access the database. `AppConfig` is a key-value table used for all runtime configuration: site settings, SMTP, marquee, maintenance mode, default locale. `lib/app-config.ts` is the aggregate entry point; individual settings are in `lib/site-settings.ts`, `lib/mail-settings.ts`, `lib/marquee-settings.ts`. @@ -77,8 +78,9 @@ Prisma client is in `lib/prisma.ts`. All DB access must go through server-side m |---|---| | i18n routing | `i18n/routing.ts` | | Admin routing logic | `lib/admin-routing.ts` | -| Middleware (routing + auth) | `middleware.ts` | -| Prisma client | `lib/prisma.ts` | +| Middleware (routing + auth) | `proxy.ts` | +| DB client (Drizzle) | `lib/db/index.ts` | +| DB schema | `lib/db/schema.ts` | | AppConfig aggregate | `lib/app-config.ts` | | Portfolio queries | `lib/portfolio.ts` | | Media handling | `lib/media.ts` | @@ -116,11 +118,11 @@ SITE_RUNTIME_ORIGIN Internal origin for middleware to fetch runtime state - Do not modify unrelated files. - Preserve existing architecture, naming, and folder conventions. - Prefer server-side logic in `lib/*` and keep business logic out of UI components. -- Never access Prisma from client components. +- Never access the database (Drizzle) from client components. - For admin-related changes, treat `app/_admin/` as the canonical source of truth unless explicitly told otherwise. - Do not add new dependencies unless absolutely necessary and explicitly justified. - After code changes, run only the minimum relevant checks (for example: targeted test, lint on changed files, or build if necessary). -- If a task may affect routing, auth, i18n, or runtime config, inspect `middleware.ts`, `lib/admin-routing.ts`, `i18n/routing.ts`, and the relevant `lib/app-config.ts` modules first. -- For schema or database changes, inspect Prisma schema, migration flow, and seed impact before editing. +- If a task may affect routing, auth, i18n, or runtime config, inspect `proxy.ts`, `lib/admin-routing.ts`, `i18n/routing.ts`, and the relevant `lib/app-config.ts` modules first. +- For schema or database changes, inspect the Drizzle schema (`lib/db/schema.ts`), the drizzle-kit migration flow, and migration impact before editing. - Ask before performing large refactors, file moves, destructive changes, or broad formatting changes. - When updating behavior, also update docs/specs if the change affects public behavior, business rules, or architecture. \ No newline at end of file