AGENTS.md · diff
git:20260502.8c00a56 to git:20260804.ea7d573
15 added, 3 removed. Audit A to A.
# AGENTS.md
## Commands
```bash
pnpm dev # Start dev server (http://localhost:3000)
pnpm build # Production build
pnpm lint # ESLint
pnpm format # Prettier write
pnpm payload generate:types # Regenerate Payload CMS types
pnpm devsafe # Clean .next and restart dev
```
Note: All node commands require `NODE_OPTIONS=--no-deprecation` (set automatically in scripts).
## Architecture
- **Locale routing**: `[locale]/` route segment — all public pages under `src/app/[locale]/(main)/`
- **Payload admin**: `/admin` via `(payload)` route group
- - **Collections**: `src/collections/*.ts` — maps to PostgreSQL tables
- - **Components**: `src/components/ui/` for primitives, `src/components/` for domain components
- - **Features**: `src/features/` for feature-specific logic
+ - **Collections**: `src/shared/collections/*.ts` — maps to PostgreSQL tables
+ - **Shared**: `src/shared/components/ui/` for primitives (Section, Skeleton, TechChip…), `src/shared/components/` for layout chrome (Dock, Footer), `src/shared/lib/` for utilities
+
+ ### Feature structure (views → containers → widgets → ui)
+
+ Each feature under `src/features/<name>/` follows a layered flow:
+
+ - **`views/`** — page-level composition. Owns shared page state and arranges containers (wrapped in `<Suspense>` with skeleton fallbacks). A view can have many containers.
+ - **`containers/`** — async server components that orchestrate data: fetch via `api/`, transform to widget props. A container can feed many widgets.
+ - **`widgets/`** — receive data from a container and pick the UI by state: `undefined` → skeleton UI, `null`/empty → empty UI (section hidden), data → data UI.
+ - **`ui/`** — smallest presentational components (lists, cards, skeletons, static sections).
+ - **`api/`** — data fetchers (Payload local API via `shared/lib/collection-query`, GitHub, external APIs).
+ - **`actions/`**, **`hooks/`**, **`lib/`** — server actions, client hooks, feature utilities.
+
+ Routes in `src/app/` stay thin: metadata/SEO + render the feature's view.
## Tech Stack
- Next.js 16 (App Router), React 19, Tailwind CSS 4
- Payload CMS 3.0 + Vercel Postgres adapter
- i18n via next-intl (`src/i18n/`)
- Strict TypeScript (`strict: true` in tsconfig)
## Dev Notes
- Requires `.env` with `POSTGRES_URL`, `PAYLOAD_SECRET`, `GROQ_API_KEY`
- Use `@payload-config` import alias for config file
- Use `@/*` alias for `src/*`
- Migrations in `src/migrations/`
## Git/Workflow
- Husky pre-commit hooks active
- commitlint uses Conventional Commits format
- lint-staged runs ESLint fix + Prettier write on staged files