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
1	Medicine Library	Searchable medicine catalog with dosage/form info	phase-1-medicine-library.md
2	Medicine Cabinet	Inventory tracking with quantity, expiry, low-stock alerts	phase-2-medicine-cabinet.md
3	Regimens & Pill Organizer	Daily medication schedules, batch-dispense, burn rate	phase-3-regimens-pill-organizer.md
4	Pharmacies, Prices & Refills	Shared store infrastructure, price tracking, refill alerts	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
6	Recipe Management	Recipe CRUD, nutrition auto-calculation, import	phase-6-recipes.md
7	Pantry & Fridge Tracking	Track item lifecycle, freshness, spoilage estimation	phase-7-pantry.md
8	Meal Planning & Waste Reduction	Suggest meals from pantry, nutrition targets, weekly planning	phase-8-meal-planning.md
9	Grocery & Price Tracking	Shopping lists, price analytics, store comparison (reuses Phase 4 stores)	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

Cross-Cutting Concerns

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

Architecture Decisions

See 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

8.9 KiB Raw Blame History