MeshiTrack/docs/PLAN.md

# 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 (generic level)
│   │   │   │   ├── medicine-products/ # Phase 1: Purchasable brands/packages
│   │   │   │   ├── 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
Setup initial project 2026-03-27 14:50:34 +09:00			`# 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/`
Implement medicine library and cabinet 2026-03-28 08:19:48 +09:00			`│ │ │ │ ├── medicines/ # Phase 1: Medicine catalog (generic level)`
			`│ │ │ │ ├── medicine-products/ # Phase 1: Purchasable brands/packages`
Setup initial project 2026-03-27 14:50:34 +09:00			`│ │ │ │ ├── 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`