# MeshiTrack — Large-Scale Project Plan

> **Nutrition, Medicine & Pantry Management Platform**
> A self-hosted, multi-user app for medicine tracking, nutrition tracking, pantry/fridge management, recipe management, meal planning, and price surveillance across stores.

## Project Summary

MeshiTrack helps households manage medicines and food. Medicine tracking comes first as the simpler domain: catalog medicines, track inventory in a medicine cabinet, define daily regimens, batch-dispense via a pill organizer, compare pharmacy prices, and get automatic refill alerts. Food tracking follows the same architectural patterns: product catalog, recipes, pantry tracking, meal planning, grocery lists, and price comparison. Both domains share infrastructure (auth, households, stores).

## Tech Stack

| Layer               | Technology                              |
| ------------------- | --------------------------------------- |
| **Backend**         | Fastify 5 (TypeScript, ESM)             |
| **DI Container**    | Awilix 13 + @fastify/awilix             |
| **Frontend**        | Next.js 16 (React 19, TypeScript)       |
| **Styling**         | Tailwind CSS 4 (CSS-first config)       |
| **Database**        | MongoDB (Mongoose 9)                    |
| **Auth**            | Keycloak (OIDC), jose 6 (JWT)           |
| **Validation**      | Zod 4 (shared schemas)                  |
| **Shared Code**     | TypeScript package (types, Zod schemas) |
| **Testing**         | Vitest 4 (unit + integration)           |
| **Mobile (future)** | React Native                            |
| **LLM**            | Abstracted interface (provider TBD)     |
| **Deployment**      | Docker Compose (self-hosted)            |
| **Monorepo**        | Turborepo 2                             |
| **Runtime**         | Node.js 22+ (ESM-only)                  |

## Phase Overview

### Medicine Tracking (Phases 1-4)

| Phase | Name                           | Description                                                      | Doc                                                                                       |
| ----- | ------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 0     | Foundation & Infrastructure    | Repo scaffolding, Docker, auth                                   | [phase-0-foundation.md](phases/phase-0-foundation.md)                                     |
| 1     | Medicine Library               | Searchable medicine catalog with dosage/form info                | [phase-1-medicine-library.md](phases/phase-1-medicine-library.md)                         |
| 2     | Medicine Cabinet               | Inventory tracking with quantity, expiry, low-stock alerts       | [phase-2-medicine-cabinet.md](phases/phase-2-medicine-cabinet.md)                         |
| 3     | Regimens & Pill Organizer      | Daily medication schedules, batch-dispense, burn rate            | [phase-3-regimens-pill-organizer.md](phases/phase-3-regimens-pill-organizer.md)           |
| 4     | Pharmacies, Prices & Refills   | Shared store infrastructure, price tracking, refill alerts       | [phase-4-pharmacies-prices-refills.md](phases/phase-4-pharmacies-prices-refills.md)       |

### Food Tracking (Phases 5-9)

| Phase | Name                           | Description                                                      | Doc                                                                                       |
| ----- | ------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 5     | Product Library                | Searchable food product catalog with nutrition data              | [phase-5-product-library.md](phases/phase-5-product-library.md)                           |
| 6     | Recipe Management              | Recipe CRUD, nutrition auto-calculation, import                  | [phase-6-recipes.md](phases/phase-6-recipes.md)                                           |
| 7     | Pantry & Fridge Tracking       | Track item lifecycle, freshness, spoilage estimation             | [phase-7-pantry.md](phases/phase-7-pantry.md)                                             |
| 8     | Meal Planning & Waste Reduction| Suggest meals from pantry, nutrition targets, weekly planning    | [phase-8-meal-planning.md](phases/phase-8-meal-planning.md)                               |
| 9     | Grocery & Price Tracking       | Shopping lists, price analytics, store comparison (reuses Phase 4 stores) | [phase-9-grocery.md](phases/phase-9-grocery.md)                               |

### Shared (Phase 10)

| Phase | Name                           | Description                                                      | Doc                                                                                       |
| ----- | ------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 10    | LLM Integration & Smart Features | Wire up LLM providers, enable smart features across both domains | [phase-10-llm.md](phases/phase-10-llm.md)                                               |

## Cross-Cutting Concerns

See [cross-cutting.md](cross-cutting.md) for API versioning, pagination, audit trails, real-time events, testing strategy, and mobile readiness.

## Architecture Decisions

See [architecture.md](architecture.md) for key decisions and rationale.

## Monorepo Structure (Target)

```
MeshiTrack/
├── docs/                        # This documentation
├── packages/
│   ├── api/                     # Fastify backend
│   │   ├── src/
│   │   │   ├── modules/
│   │   │   │   ├── health/
│   │   │   │   ├── users/
│   │   │   │   ├── households/
│   │   │   │   ├── medicines/       # Phase 1: Medicine catalog
│   │   │   │   ├── cabinet/         # Phase 2: Medicine inventory
│   │   │   │   ├── regimens/        # Phase 3: Medication schedules
│   │   │   │   ├── organizer/       # Phase 3: Pill organizer fills
│   │   │   │   ├── stores/          # Phase 4: Shared store infrastructure
│   │   │   │   ├── medicine-prices/ # Phase 4: Medicine price tracking
│   │   │   │   ├── refills/         # Phase 4: Refill alerts & lists
│   │   │   │   ├── products/        # Phase 5: Food product catalog
│   │   │   │   ├── recipes/         # Phase 6: Recipe management
│   │   │   │   ├── pantry/          # Phase 7: Food inventory
│   │   │   │   ├── meal-plans/      # Phase 8: Meal planning
│   │   │   │   ├── grocery/         # Phase 9: Grocery shopping
│   │   │   │   └── llm/            # Phase 10: LLM integration
│   │   │   ├── plugins/         # Fastify plugins (auth, mongoose, etc.)
│   │   │   ├── schemas/         # Mongoose schemas
│   │   │   ├── common/          # Error classes, shared types
│   │   │   └── config/
│   │   ├── vitest.config.ts
│   │   └── package.json
│   ├── web/                     # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/             # App Router pages
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/        # API client layer
│   │   │   └── styles/
│   │   └── package.json
│   └── shared/                  # Shared TypeScript types & validation
│       ├── src/
│       │   ├── types/
│       │   ├── enums/
│       │   └── validation/      # Zod 4 schemas
│       └── package.json
├── docker/
│   ├── docker-compose.yml
│   ├── keycloak/                # Realm export, themes
│   └── mongo/                   # Init scripts
├── .github/
│   └── workflows/
├── turbo.json                   # Turborepo config
├── package.json                 # Root workspace config
└── tsconfig.base.json
```

## Verification Strategy

- **Per-phase**: each phase ends with a working `docker compose up` that demos the new feature
- **Integration**: Postman/Bruno collection maintained alongside API development
- **E2E smoke test (medicine)**: automated script that creates a user, adds medicines, stocks cabinet, creates regimen, fills organizer, checks refill alerts
- **E2E smoke test (food)**: automated script that adds products, creates a recipe, stocks the pantry, generates a meal plan, and creates a shopping list
- **Performance**: MongoDB indexes reviewed per phase; query profiling before phase sign-off