|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Commands |
| 4 | + |
| 5 | +```bash |
| 6 | +# webapp |
| 7 | +cd webapp && npm ci |
| 8 | +cd webapp && npm run dev # starts on port 3010 |
| 9 | +cd webapp && npm run build |
| 10 | +cd webapp && npm run lint |
| 11 | +cd webapp && npm run format |
| 12 | + |
| 13 | +# cdk |
| 14 | +cd cdk && npm ci |
| 15 | +cd cdk && npm run build |
| 16 | +cd cdk && npm test |
| 17 | +cd cdk && npm run format |
| 18 | +cd cdk && npx cdk deploy --all |
| 19 | +cd cdk && npx cdk diff |
| 20 | + |
| 21 | +# local development (requires Docker) |
| 22 | +docker compose up -d # PostgreSQL on port 5432 |
| 23 | +cd webapp && npx prisma db push # sync schema to local DB |
| 24 | +cd webapp && npm run dev |
| 25 | +``` |
| 26 | + |
| 27 | +## Development guide |
| 28 | + |
| 29 | +### Authentication |
| 30 | + |
| 31 | +All server-side mutations must go through `authActionClient` (defined in `lib/safe-action.ts`). It validates the Cognito session via Amplify server-side auth and injects `ctx.userId`. Never call Prisma directly from a Server Action without this middleware. |
| 32 | + |
| 33 | +`proxy.ts` handles route protection (redirect to `/sign-in` for unauthenticated users). It is NOT a Next.js middleware file — it runs inside the Lambda handler. There is no `middleware.ts` in this project. |
| 34 | + |
| 35 | +### Async jobs |
| 36 | + |
| 37 | +The dispatch flow is: Server Action → `runJob()` (Lambda async invoke) → `async-job-runner.ts` (discriminated union dispatch) → job handler → `sendEvent()` (AppSync Events) → client `useEventBus` hook. |
| 38 | + |
| 39 | +To add a new job: |
| 40 | +1. Add a Zod schema with a `type` literal to the discriminated union in `async-job-runner.ts` |
| 41 | +2. Implement the handler in `src/jobs/async-job/` |
| 42 | +3. Add the case to the switch statement |
| 43 | + |
| 44 | +All job types share a single Lambda function via `job.Dockerfile`. The CDK `cmd` parameter selects the entry point. |
| 45 | + |
| 46 | +### Database migration |
| 47 | + |
| 48 | +`prisma db push` is used for schema sync by default. The migration runner Lambda is invoked automatically during `cdk deploy` via CDK Trigger. For manual invocation, use the `MigrationCommand` from CDK outputs. |
| 49 | + |
| 50 | +Schema changes: edit `prisma/schema.prisma` → run `npx prisma db push` locally → commit. The `zod-prisma-types` generator auto-generates Zod schemas from the Prisma schema. If you switch to `prisma migrate`, update the migration runner accordingly. |
| 51 | + |
| 52 | +### Lambda environment |
| 53 | + |
| 54 | +The webapp runs on Lambda behind CloudFront via Lambda Web Adapter (response streaming). `next.config.ts` uses `output: 'standalone'`. Build-time env vars (prefixed `NEXT_PUBLIC_`) are injected via CDK `ContainerImageBuild` build args — they cannot be changed at runtime. |
| 55 | + |
| 56 | +### Real-time notifications |
| 57 | + |
| 58 | +Server → client push uses AppSync Events. Server-side: `sendEvent(channelName, payload)` with IAM SigV4 signing. Client-side: `useEventBus` hook with Cognito user pool auth. The channel namespace is `event-bus/`. |
| 59 | + |
| 60 | +## Documentation policy |
| 61 | + |
| 62 | +- Do not document what can be derived from code. An agent can read the codebase. |
| 63 | +- Enforce verifiable constraints with tests and linters, not prose. |
| 64 | +- Code comments explain "why not" only — the non-obvious reason something was done a certain way. |
| 65 | +- Before adding a line to this file, ask: "If I remove this line, will an agent make a mistake?" If no, don't add it. If a root cause is fixed, remove the corresponding line. |
| 66 | + |
| 67 | +## Conventions |
| 68 | + |
| 69 | +- PR titles and code comments in English. |
| 70 | +- Issues and discussions in English or Japanese. |
| 71 | +- PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, etc.). |
| 72 | +- UI components: use [shadcn/ui](https://ui.shadcn.com/). Do not introduce alternative component libraries. |
| 73 | +- Logs: use JSON structured output. |
| 74 | +- Dependencies: esbuild and Next.js bundle everything, so only packages with native binaries needed at Lambda runtime belong in `dependencies`. Everything else goes in `devDependencies`. |
| 75 | + |
| 76 | +## Do not |
| 77 | + |
| 78 | +- Do not bypass `authActionClient` for any mutation. No raw Prisma calls from Server Actions. |
| 79 | +- Do not add `middleware.ts`. Route protection is handled by `proxy.ts` inside the Lambda runtime. |
| 80 | +- Do not use `prisma migrate` commands unless you have explicitly switched from `prisma db push`. The default setup uses `prisma db push`. |
| 81 | +- Do not hardcode AWS region or account IDs. Use CDK context or environment variables. |
| 82 | +- Do not add `NEXT_PUBLIC_` env vars to `.env.local` for deployed builds — they must be set as CDK build args in `webapp.ts`. |
0 commit comments