128 lines
8.9 KiB
Markdown
128 lines
8.9 KiB
Markdown
# 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
|