Locked decisions
| Layer | Decision |
|---|---|
| Monorepo | pnpm workspaces |
| Frontend | Next.js (app router), TypeScript required |
| API | Next.js route handlers (app/api/) by default |
| Database | MongoDB + Mongoose |
| Validation | Zod (shared schemas in packages/shared) |
| Environments | local → non-prod → prod |
| Secrets | .env.local for dev; AWS for production |
| Containers | Not required unless deployment target forces it |
Project layout
code
apps/web/ # Next.js app app/api/ # API route handlers src/server/ # Server-only code packages/shared/ # Zod schemas, types, utilities .github/workflows/ # CI/CD (root configs) # eslint, prettier, tsconfig
When to add a separate API service
Only justified if:
- •Long-running jobs exceed serverless timeouts
- •WebSocket/persistent connections required
- •Shared API serves multiple non-Next.js clients
- •Compliance requires API isolation
Default: keep API in Next.js route handlers.
Reference
For versions, env setup, and deployment patterns, see reference/mern-stack-reference.md