72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# Agent Instructions
|
|
|
|
## Monorepo Package Map
|
|
|
|
| Package | Purpose |
|
|
|---|---|
|
|
| `@repo/core` | Clean architecture: entities, use cases, interfaces, DI |
|
|
| `@repo/api` | tRPC router definitions (calls core controllers) |
|
|
| `@repo/api-client` | Shared React Query hooks + ApiProvider |
|
|
| `@repo/cms-core` | Payload CMS config, collections, hooks, globals |
|
|
| `@repo/cms-client` | Dual-mode Payload client (local + HTTP) |
|
|
| `@repo/ui` | shadcn/ui + Atomic Design component library |
|
|
| `@repo/eslint-config` | Shared ESLint flat configs |
|
|
| `@repo/typescript-config` | Shared TypeScript configs |
|
|
|
|
| App | Purpose |
|
|
|---|---|
|
|
| `apps/web-next` | Next.js 15 reference app |
|
|
| `apps/web-tanstack` | TanStack Start reference app |
|
|
| `apps/cms` | Thin Next.js shell for Payload admin |
|
|
| `apps/storybook` | Centralized Storybook instance |
|
|
|
|
## Dependency Flow (one direction only)
|
|
|
|
```
|
|
apps/web-next, apps/web-tanstack → @repo/api-client → @repo/api → @repo/core
|
|
apps/cms → @repo/cms-core → @repo/core/application (hooks only)
|
|
@repo/core/infrastructure → @repo/cms-client (standalone)
|
|
@repo/ui (standalone)
|
|
```
|
|
|
|
## HARD RULES — NEVER VIOLATE
|
|
|
|
- **NEVER:** packages/core → apps/*
|
|
- **NEVER:** apps/cms → packages/core/infrastructure
|
|
- **NEVER:** packages/cms-client → apps/cms or packages/core or packages/cms-core
|
|
- **NEVER:** packages/cms-core → packages/cms-client
|
|
- **NEVER:** core/entities → anything
|
|
- **NEVER:** core/application → core/infrastructure
|
|
|
|
## How to Add a New Feature (end-to-end)
|
|
|
|
1. Define entity in `packages/core/src/entities/models/`
|
|
2. Define repository interface in `packages/core/src/application/repositories/`
|
|
3. Write use case in `packages/core/src/application/use-cases/{domain}/`
|
|
4. Write controller in `packages/core/src/interface-adapters/controllers/{domain}/`
|
|
5. Write infrastructure implementation in `packages/core/src/infrastructure/`
|
|
6. Register in DI container (`packages/core/src/di/`)
|
|
7. Add tRPC router in `packages/api/src/router/`
|
|
8. Add React Query hook in `packages/api-client/src/hooks/`
|
|
9. If CMS collection needed: add to `packages/cms-core/src/collections/`
|
|
10. Build UI component in `packages/ui/src/` (classify atomic level)
|
|
11. Write Storybook story (co-located `.stories.tsx`)
|
|
12. Write tests (unit in packages/core/tests/, E2E in tests/e2e/)
|
|
|
|
## How to Add a New UI Component
|
|
|
|
1. Classify: atom (single element), molecule (2-3 atoms), organism (complex section), template (layout)
|
|
2. Create folder: `packages/ui/src/{level}/{component-name}/`
|
|
3. Create: `{name}.tsx`, `{name}.stories.tsx`, `index.ts`
|
|
4. Story title: `"{Level}/{ComponentName}"` (e.g., `"Atoms/Button"`)
|
|
5. Export from level's `index.ts` barrel file
|
|
6. Import rules: atoms ← nothing | molecules ← atoms | organisms ← atoms+molecules | templates ← all
|
|
|
|
## How to Add a Payload CMS Collection
|
|
|
|
1. Create folder: `packages/cms-core/src/collections/{name}/`
|
|
2. Create: `index.ts` (CollectionConfig), `fields.ts`, optionally `hooks/`, `access/`
|
|
3. Import in `packages/cms-core/src/payload.config.ts` collections array
|
|
4. Export from `packages/cms-core/src/index.ts`
|
|
5. Hooks that contain business logic must delegate to use cases in `@repo/core/application`
|