MeshiTrack/docs/architecture.md

# Architecture Decisions

Key architectural decisions for MeshiTrack with rationale.

---

## ADR-001: Monorepo with Shared Types Package

**Decision**: Use a Turborepo/Nx monorepo with `packages/api`, `packages/web`, and `packages/shared`.

**Rationale**:

- Type-safe API contracts: DTOs and validation schemas (Zod) are defined once in `shared`, consumed by both API and web
- Future React Native app imports directly from `shared` — no duplication
- Atomic commits across API + web when contracts change
- Turborepo handles caching and parallel builds efficiently

**Trade-offs**:

- Slightly more complex initial setup vs separate repos
- Needs careful dependency management between packages

---

## ADR-002: Keycloak for Authentication

**Decision**: Use Keycloak as an external OIDC identity provider rather than custom JWT auth.

**Rationale**:

- Production-grade OIDC/OAuth2 out of the box
- Built-in user management admin UI — no need to build user registration/password reset flows
- Social login support if needed later
- Household multi-tenancy via custom token claims (custom protocol mapper injects `householdIds[]` into JWT)
- Self-hosted, aligns with deployment strategy

**Trade-offs**:

- Heavier infrastructure (JVM-based, ~512MB RAM)
- Steeper learning curve for Keycloak config vs simple Passport.js
- Adds complexity to Docker Compose

---

## ADR-003: MongoDB over PostgreSQL

**Decision**: Use MongoDB as the primary database.

**Rationale**:

- Flexible schema suits the product catalog (products have varying nutrition fields, optional barcodes, tags)
- Embedded documents reduce need for joins (recipe ingredients embed product references, pantry items embed freshness rules)
- Time-series-like data (price records) works well with MongoDB's TTL indexes and time-series collections
- Native JSON — no ORM impedance mismatch with TypeScript objects
- Good Atlas Search capabilities for full-text product search

**Trade-offs**:

- Less strict referential integrity vs PostgreSQL (mitigated by application-level validation)
- Aggregation pipeline can be complex for reporting queries
- Need to be intentional about data modeling to avoid unbounded array growth

---

## ADR-004: Household-Scoped Multi-Tenancy

**Decision**: All domain data (products, recipes, pantry items, shopping lists) is scoped to a `householdId`. Users belong to one or more households.

**Rationale**:

- Enables sharing: family members share a pantry, shopping list, and recipe collection
- Clean data isolation between households within the same MongoDB instance
- Every query includes `householdId` filter — implemented via a Fastify preHandler hook that validates it from the URI param (`:householdId`) against the user's `householdIds[]` JWT claim

**Data model**:

```
User { keycloakId, displayName, householdIds[], defaultHouseholdId }
Household { name, memberIds[], ownerUserId, inviteCode, settings }
```

**Trade-offs**:

- Slightly more complex than single-user: need to manage household membership, invitations, role checks
- Every query must include household filter (enforced by middleware, not developer discipline)

---

## ADR-005: LLM Abstraction Layer (Provider Pattern)

**Decision**: Define an `ILlmProvider` interface in Phase 1, implement concrete providers in Phase 6. All LLM-dependent features have manual fallback paths.

**Rationale**:

- Avoids blocking core functionality on LLM availability or cost decisions
- The LLM landscape changes rapidly — abstraction allows swapping providers without touching feature code
- Users who don't want LLM features get a fully functional app
- Each feature (product recognition, recipe parsing, meal suggestions) calls the interface; a `NoOpLlmProvider` returns graceful "not available" responses until real providers are wired

**Interface sketch**:

```typescript
interface ILlmProvider {
  extractNutrition(input: string | Buffer): Promise<NutritionData | null>;
  parseRecipe(text: string): Promise<ParsedRecipe | null>;
  parseRecipeFromUrl(url: string): Promise<ParsedRecipe | null>;
  parseReceipt(image: Buffer): Promise<ParsedReceipt | null>;
  suggestMealPlan(context: MealPlanContext): Promise<MealPlanSuggestion | null>;
  parseNaturalLanguage(text: string): Promise<StructuredAction | null>;
}
```

**Trade-offs**:

- Delayed gratification — smart features come last
- Interface may need revision as we learn what each feature actually needs (acceptable — iterate)

---

## ADR-006: Docker Compose for Self-Hosted Deployment

**Decision**: Primary deployment target is Docker Compose on a single server or VPS.

**Rationale**:

- Aligns with self-hosted preference
- Simple to operate: `docker compose up -d` starts everything
- Easy backup: MongoDB volume + Keycloak DB volume
- Can scale vertically on a single machine for household-sized workloads

**Services in Docker Compose**:

```
services:
  mongodb        # Data store
  keycloak       # Auth
  api            # NestJS backend
  web            # Next.js frontend
  mongo-express  # Dev-only: DB admin UI
```

**Trade-offs**:

- No horizontal scaling (acceptable for household app)
- Single point of failure (mitigated by container restart policies)
- Need manual backup strategy (cron + mongodump)

---

## ADR-007: React Native for Future Mobile App

**Decision**: When mobile is needed, build with React Native to share code with the Next.js web frontend.

**Rationale**:

- Shares TypeScript types and validation from `packages/shared`
- React component patterns and hooks can be adapted (not 1:1, but concepts transfer)
- Single team can maintain web + mobile with same language
- Large ecosystem, good Android support

**Preparation (done now)**:

- All business logic and types live in `packages/shared`, not in `packages/web`
- API is the single source of truth — web is a thin UI layer
- No server-side rendering dependencies in shared code

**Trade-offs**:

- React Native doesn't share actual UI components with Next.js (different render targets)
- May need a `packages/mobile` that depends on `packages/shared`

---

## ADR-008: Denormalized Nutrition on Recipes

**Decision**: When a recipe is saved, compute `totalNutrition` and `perServingNutrition` from ingredients and store them directly on the recipe document.

**Rationale**:

- Avoids expensive aggregation lookups on every recipe read
- Recipe pages load fast — nutrition data is pre-computed
- Recipes are read far more often than edited

**Recalculation triggers**:

- Recipe ingredient list is edited → recalculate
- A product's nutrition data is updated → background job recalculates affected recipes

**Trade-offs**:

- Data can become stale if a product is updated but recipe recalc fails (mitigated by eventual consistency via background job)
- Slight write amplification on product nutrition updates

---

## ADR-009: Fastify + Awilix over NestJS

**Decision**: Replace NestJS with Fastify 5 + Awilix (DI) + fastify-plugin architecture. Replace Jest with Vitest.

**Rationale**:

- **ESM-native**: NestJS is locked to CommonJS. Fastify 5, Awilix 13, and Vitest 4 are all ESM-first, aligning with the Node.js ecosystem direction.
- **No decorators**: NestJS relies on TypeScript experimental decorators and `emitDecoratorMetadata`, which are non-standard and incompatible with `verbatimModuleSyntax`. Fastify + Awilix use plain functions and constructor injection.
- **Performance**: Fastify is consistently the fastest Node.js HTTP framework. No reflection overhead.
- **Simpler mental model**: Fastify's plugin system is composable and explicit. Dependencies are declared, not magically resolved via decorators.
- **Better testing**: Fastify's `app.inject()` tests routes without HTTP overhead. Vitest is faster than Jest and natively supports ESM.
- **Lighter dependency tree**: NestJS pulls in 40+ packages. Fastify core is 3 packages.

**Migration pattern**:

```
NestJS               →  Fastify + Awilix
@Module              →  fp() plugin (fastify-plugin)
@Controller          →  Route definitions inside plugin
@Injectable          →  Plain class + Awilix registration
@InjectModel         →  Import Mongoose model directly
class-validator      →  Zod schemas (fastify-type-provider-zod)
@UseGuards           →  onRequest/preHandler hooks
Jest                 →  Vitest
```

**Stack versions** (as of migration):

- Fastify 5.8, Awilix 13, @fastify/awilix 8.2
- fastify-type-provider-zod 6.1 (Zod v4 support)
- jose 6.2 (ESM-only JWT, replaces passport-jwt)
- Vitest 4.1, TypeScript 6.0, Mongoose 9.3

**Trade-offs**:

- NestJS has more opinionated structure — new developers may need to learn Fastify's plugin model
- No built-in CLI scaffolding (acceptable — our module structure is documented)
- Awilix DI is less "magical" than NestJS — requires explicit registration (this is actually a benefit)