Phases 6-7
This commit is contained in:
parent
76a516a417
commit
029940b079
111 changed files with 17247 additions and 447 deletions
164
ANTIGRAVITY.md
Normal file
164
ANTIGRAVITY.md
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
# ANTIGRAVITY.md
|
||||
|
||||
This file provides guidance to Antigravity (the Gemini-based coding assistant) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
MeshiTrack is a self-hosted medicine & nutrition management platform. It is a TypeScript monorepo with three packages: `packages/api` (Fastify backend), `packages/web` (Next.js frontend), and `packages/shared` (types + Zod schemas used by both). Medicine tracking is implemented first (Phases 1-4), followed by food tracking (Phases 5-9).
|
||||
|
||||
## Commands
|
||||
|
||||
### Root (all packages via Turborepo)
|
||||
|
||||
```bash
|
||||
npm run dev # Start all services in dev mode
|
||||
npm run build # Build all packages (shared → api/web)
|
||||
npm run test # Run all tests
|
||||
npm run test:cov # Run all tests with coverage
|
||||
npm run lint # Lint all packages
|
||||
npm run lint-fix # Auto-fix lint issues
|
||||
npm run typecheck # Type-check all packages
|
||||
npm run clean # Remove build artifacts
|
||||
npm run seed # Seed the database (delegates to packages/api)
|
||||
```
|
||||
|
||||
### Single package
|
||||
|
||||
```bash
|
||||
npm run test -w packages/api # Run API tests
|
||||
npm run test:cov -w packages/api # API tests with coverage
|
||||
npm run test -- --watch -w packages/api # Watch mode
|
||||
npm run dev -w packages/api # API dev server only
|
||||
```
|
||||
|
||||
### API package (packages/api)
|
||||
|
||||
```bash
|
||||
npm run dev # tsx watch src/main.ts
|
||||
npm run build # tsc
|
||||
npm run seed # tsx src/scripts/seed.ts
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
docker compose -f docker/docker-compose.yml up -d # Start all services
|
||||
docker compose -f docker/docker-compose.yml down # Stop all services
|
||||
```
|
||||
|
||||
## Implementation Workflow
|
||||
|
||||
Every feature or phase implementation must follow this "Vertical Slice" approach:
|
||||
|
||||
1. **Shared Layer**: Define types, enums, and Zod v4 schemas in `packages/shared`. Add unit tests.
|
||||
2. **Database Layer**: Create the Mongoose schema and Repository in `packages/api`. All reads must use `.lean().exec()`.
|
||||
3. **Service Layer**: Implement business logic in the Service class, using Awilix for constructor injection. Add unit tests.
|
||||
4. **Route Layer**: Create the Fastify route plugin and register it. Add route tests (using `app.inject`).
|
||||
5. **Web API Client**: Implement the frontend service in `packages/web/src/services/`. Add unit tests.
|
||||
6. **Web UI**: Create the Next.js pages and components. Use Server Components by default. Add component tests (React Testing Library).
|
||||
|
||||
**Verification Gate (Mandatory)**:
|
||||
Before considering a task complete, run:
|
||||
- `npm run build`
|
||||
- `npm run test:cov` (must meet 100/100/100/90 for API/Shared and 90/85/75/85 for Web)
|
||||
- `npm run lint`
|
||||
|
||||
## Architecture
|
||||
|
||||
### Monorepo Structure
|
||||
|
||||
- **`packages/shared`** — Single source of truth for all domain types, enums, and Zod v4 schemas. Consumed by both `api` and `web`. Must be pure TypeScript with no Node.js, browser, or framework dependencies.
|
||||
- **`packages/api`** — Fastify 5 backend. ESM-only, TypeScript strict. Uses Awilix for DI, Mongoose 9 for MongoDB, jose 6 for JWT verification.
|
||||
- **`packages/web`** — Next.js 16 (React 19) frontend. App Router, Tailwind CSS 4.
|
||||
|
||||
### API Layer Architecture (Fastify + Awilix)
|
||||
|
||||
The API follows a **routes → services → repositories** pattern with Awilix constructor-injection DI:
|
||||
|
||||
- Each domain feature lives in `src/modules/<feature>/` with files: `*.routes.ts`, `*.service.ts`, `*.repository.ts`
|
||||
- Route plugins use `fastify-plugin` (`fp()`) to export routes and register Awilix dependencies
|
||||
- Services receive dependencies via destructured constructor: `constructor({ productsRepository }: { productsRepository: ProductsRepository })`
|
||||
- Resolve services per-request via `request.diScope.resolve<T>('serviceName')`
|
||||
- All Mongoose read queries must use `.lean().exec()`
|
||||
|
||||
Plugin registration order in `main.ts`: security → compression → swagger → DI container → database → auth → household guard → route modules.
|
||||
|
||||
### Domain Modules
|
||||
|
||||
**Medicine domain** (Phases 1-4): `medicines/`, `medicine-products/`, `cabinet/`, `regimens/`, `organizer/`, `medicine-prices/`, `purchases/`, `refills/`
|
||||
**Food domain** (Phases 5-9): `products/`, `recipes/`, `pantry/`, `meal-plans/`, `grocery/`
|
||||
**Shared**: `health/`, `users/`, `households/`, `stores/`, `llm/`
|
||||
|
||||
### Multi-tenancy
|
||||
|
||||
Every domain document is scoped to a `householdId`. A Fastify `preHandler` hook validates the `householdId` from the URI against the user's `householdIds[]` JWT claim. **Every data query must filter by `householdId`.**
|
||||
|
||||
Routes can opt out with `config: { public: true }` (skips auth) or `config: { skipHousehold: true }` (skips household validation).
|
||||
|
||||
### Auth
|
||||
|
||||
Keycloak is the OIDC provider. The API verifies JWTs via `jose`. The custom Keycloak protocol mapper injects `householdIds[]` into the JWT claims.
|
||||
|
||||
### Shared Package Rules
|
||||
|
||||
- All domain types and Zod schemas live here — never duplicate types across packages
|
||||
- Import from `'zod/v4'` (not `'zod'`)
|
||||
- Use `z.enum()` for enums, `z.email()` / `z.url()` as top-level calls
|
||||
- Every directory has a barrel `index.ts`
|
||||
- Use `import type` for type-only imports
|
||||
|
||||
### Pagination
|
||||
|
||||
All list endpoints use cursor-based pagination. **Never use `skip()`** on MongoDB queries. Response shape:
|
||||
|
||||
```typescript
|
||||
{ data: T[], pagination: { cursor: string | null, hasMore: boolean, total?: number } }
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
Services throw `AppError` subclasses (`NotFoundError`, `ConflictError`, `ForbiddenError`, etc.). The global Fastify error handler maps them to the standard `ApiError` response shape (`statusCode`, `error`, `message`, `timestamp`, `path`).
|
||||
|
||||
## Key Rules
|
||||
|
||||
1. **No `any` types** — use `unknown` + Zod validation at boundaries
|
||||
2. **ESM everywhere** — `"type": "module"`, `.js` extensions on all imports, `import type` for type-only
|
||||
3. **Cursor-based pagination only** — never `skip()` for large collections
|
||||
4. **Zod v4** — import from `'zod/v4'`
|
||||
5. **`.lean().exec()`** on all Mongoose read queries
|
||||
6. **`householdId` filter** on every domain query — this is the multi-tenancy boundary
|
||||
7. **No emojis** — never use emoji characters in source code, UI text, console output, or documentation
|
||||
8. **`npx` is banned** — never run `npx` for any reason. Use `npm run <script>` for all test, lint, build, and tool invocations. No exceptions.
|
||||
9. **Never pipe or redirect `npm run` commands** — run `npm run <script>` exactly as written; never append `2>&1`, `|`, `Select-Object`, `Select-String`, or any other shell constructs to it.
|
||||
10. **Never use shell commands to read files** — always use `view_file` tool. Commands like `Get-Content`, `cat`, `head`, `tail` will be denied.
|
||||
11. **Never use shell commands to search** — always use `grep_search` or `file_search`. Commands like `Select-String`, `grep`, `rg`, `find` will be denied.
|
||||
12. **Never call tools in parallel** — always wait for one tool call to complete before calling the next. This applies to all tools: file reads, searches, and terminal commands.
|
||||
13. **Every implementation task must end with `npm run build`, `npm run test:cov`, and `npm run lint` all passing.** Always use `test:cov` (not `test`) to enforce coverage thresholds. If coverage fails, write additional tests before considering the task done.
|
||||
14. **No `.js` extensions on `@/` imports in `packages/web`** — Next.js resolves TypeScript files directly; `.js` extensions on `@/` path-alias imports break Turbopack and webpack. Only use `.js` extensions in `packages/api` and `packages/shared` (Node ESM).
|
||||
|
||||
## Testing
|
||||
|
||||
- **Unit tests**: Vitest, co-located with source files as `*.routes.test.ts` / `*.service.test.ts`
|
||||
- **Integration tests**: Vitest + `mongodb-memory-server` (`*.integration.test.ts`)
|
||||
- **Component tests**: React Testing Library (`__tests__/*.test.tsx`)
|
||||
- **E2E**: Playwright (root-level `e2e/`)
|
||||
- **Use `ClassName.name` for `describe` labels** (not string literals)
|
||||
- Coverage targets:
|
||||
- `packages/api` & `packages/shared`: 100% lines/functions/statements, 90% branches
|
||||
- `packages/web`: 90% lines, 85% functions, 75% branches, 85% statements
|
||||
- Mark untestable lines with `/* v8 ignore */`
|
||||
|
||||
## Documentation
|
||||
|
||||
Before writing code, consult the relevant docs:
|
||||
|
||||
- `docs/instructions/` — coding conventions, Fastify patterns, Next.js patterns, MongoDB, Zod/TypeScript, testing, Docker, Keycloak, Turborepo
|
||||
- `docs/phases/` — per-phase specs with schemas, endpoints, and business logic
|
||||
- `docs/architecture.md` — ADRs explaining key technology choices
|
||||
- `docs/cross-cutting.md` — API versioning, pagination, security, audit trail
|
||||
|
||||
## Git Conventions
|
||||
|
||||
Branches: `feature/MESH-001-description`, `fix/MESH-042-description`, `chore/description`
|
||||
|
||||
Commits follow Conventional Commits: `feat(products): add barcode lookup`, `fix(pantry): correct freshness calc`
|
||||
Loading…
Add table
Add a link
Reference in a new issue