aerimagne/MeshiTrack
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
MeshiTrack/docs/PLAN.md
Aerilyn Dziedzelė 029940b079 Phases 6-7
2026-05-14 14:47:23 +09:00

223 lines
12 KiB
Markdown
Raw Permalink Blame History

# 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 Completion Criteria (Mandatory)
Every phase MUST deliver ALL of the following before being considered complete. No phase may be marked done if any layer is missing.
### 1. Shared Package (`packages/shared`)
- [ ] Types defined in `src/types/`
- [ ] Enums defined in `src/enums/` with unit tests
- [ ] Zod validation schemas in `src/validation/` with unit tests
- [ ] Barrel exports updated in `index.ts`
- [ ] 100% line/function/statement coverage, 90% branch coverage
### 2. API Package (`packages/api`)
- [ ] Mongoose schema in `src/schemas/`
- [ ] Repository with `.lean().exec()` on all reads
- [ ] Service with business logic
- [ ] Route plugin registered in `main.ts`
- [ ] Unit tests for repository, service, and routes (100% coverage)
- [ ] All queries scoped to `householdId`
### 3. Web Package (`packages/web`)
- [ ] API client service in `src/services/` with unit tests
- [ ] Page(s) in `src/app/(dashboard)/` implementing the UI spec
- [ ] Component tests (React Testing Library) for every page and interactive component
- [ ] Server Components by default; `'use client'` only where interactivity is needed
### 4. CI Gate (must pass before phase sign-off)
```bash
npm run build # All packages compile
npm run test:cov # Coverage thresholds enforced (100/100/100/90)
npm run lint # Zero lint errors
```
### 5. Documentation
- [ ] Phase spec updated with `[x]` on completed tasks
- [ ] Acceptance criteria verified
---
## Phase Overview
### Medicine Tracking (Phases 1-4)
| Phase | Name | Description | Status | Doc |
| ----- | ------------------------------ | ---------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| 0 | Foundation & Infrastructure | Repo scaffolding, Docker, auth | DONE | [phase-0-foundation.md](phases/phase-0-foundation.md) |
| 1 | Medicine Library | Searchable medicine catalog with dosage/form info | DONE | [phase-1-medicine-library.md](phases/phase-1-medicine-library.md) |
| 2 | Medicine Cabinet | Inventory tracking with quantity, expiry, low-stock alerts | DONE | [phase-2-medicine-cabinet.md](phases/phase-2-medicine-cabinet.md) |
| 3 | Regimens & Pill Organizer | Daily medication schedules, batch-dispense, burn rate | DONE | [phase-3-regimens-pill-organizer.md](phases/phase-3-regimens-pill-organizer.md) |
| 4 | Pharmacies, Prices & Refills | Shared store infrastructure, price tracking, refill alerts | DONE | [phase-4-pharmacies-prices-refills.md](phases/phase-4-pharmacies-prices-refills.md) |
### Food Tracking (Phases 5-9)
| Phase | Name | Description | Status | Doc |
| ----- | ------------------------------ | ---------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| 5 | Product Library | Searchable food product catalog with nutrition data | DONE | [phase-5-product-library.md](phases/phase-5-product-library.md) |
| 6 | Recipe Management | Recipe CRUD, nutrition auto-calculation, import | DONE | [phase-6-recipes.md](phases/phase-6-recipes.md) |
| 7 | Pantry & Fridge Tracking | Track item lifecycle, freshness, spoilage estimation | DONE | [phase-7-pantry.md](phases/phase-7-pantry.md) |
| 8 | Meal Planning & Waste Reduction| Suggest meals from pantry, nutrition targets, weekly planning | NOT STARTED | [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) | NOT STARTED | [phase-9-grocery.md](phases/phase-9-grocery.md) |
### Shared (Phase 10)
| Phase | Name | Description | Status | Doc |
| ----- | ------------------------------ | ---------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| 10 | LLM Integration & Smart Features | Wire up LLM providers, enable smart features across both domains | PARTIAL | [phase-10-llm.md](phases/phase-10-llm.md) |
---
## Current Status & Gaps
### Phase 8 — Meal Planning (Next Priority)
The foundation for food tracking (Phases 5-7) is fully implemented and integrated. The next major milestone is Phase 8, which introduces the meal planning calendar and the algorithmic suggestion engine.
**Immediate Goals:**
- Implement `MealPlan` and `NutritionTarget` schemas.
- Build the `SuggestionEngineService` for pantry-based recipe ranking.
- Create the weekly calendar UI with drag-and-drop support.
### Phase 10 — LLM (PARTIAL)
The `ILlmProvider` interface and `NoOpLlmProvider` are implemented. Actual provider implementations and smart features are deferred.
### Lessons Learned
Previous phases (6 & 7) were completed without finishing Phase 5's full stack (API routes + web UI). This created a gap where the Product Library has no user-facing interface despite being consumed internally. **Going forward, every phase must deliver its complete vertical slice (shared -> API -> web -> tests) before the next phase starts.**
## 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 Gate (Blocking)
Every phase must pass these checks before sign-off:
1. **Build**: `npm run build` succeeds (all packages compile)
2. **Coverage**: `npm run test:cov` passes with thresholds:
- `packages/api`: 100% lines/functions/statements, 90% branches
- `packages/shared`: 100% lines/functions/statements, 90% branches
- `packages/web`: all component tests pass
3. **Lint**: `npm run lint` reports zero errors
4. **Web UI Exists**: every phase that adds API endpoints also adds corresponding web pages with component tests
5. **Services Tested**: every `*.service.ts` in web has a corresponding `*.test.ts`
### Per-Phase Deliverable Checklist
For each phase, the task breakdown must follow this template order:
```
X.1 — Shared Types & Validation (+ tests)
X.2 — Mongoose Schema & Repository (+ tests)
X.3 — Service (+ tests)
X.4 — Routes (+ tests)
X.5 — Web: API Client Service (+ tests)
X.6 — Web: Pages & Components (+ component tests)
X.7 — CI Verification (build + test:cov + lint)
```
### Integration Testing
- Postman/Bruno collection maintained alongside API development
- E2E smoke test (medicine): creates user, adds medicines, stocks cabinet, creates regimen, fills organizer, checks refill alerts
- E2E smoke test (food): adds products, creates recipe, stocks pantry, generates meal plan, creates shopping list
### Performance
- MongoDB indexes reviewed per phase; query profiling before phase sign-off
Reference in a new issue View git blame Copy permalink