# hoanganhcq/nutriplan architecture

> Architecture diagram of the GitHub repository hoanganhcq/nutriplan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hoanganhcq/nutriplan
- Repository: https://github.com/hoanganhcq/nutriplan

## Overview

NutriPlan is a project scaffold for a family-oriented nutrition PWA: users manage household profiles, capture meals, review AI analysis, keep a diary, and plan menus around health conditions. The README describes a backend that coordinates analysis, nutrition calculations, medical rules, privacy, media, and exports, alongside AI vision, portion estimation, retrieval, and LLM capabilities. The frontend route and layout links are visible in sampled code; backend and AI implementation details are not sampled, so those branches reflect documented responsibilities rather than verified call paths.

Main entry points: [`backend/src/api`](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/api) (API layer), [`frontend/src/App.jsx`](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/App.jsx) (App router), [`backend/src/services/meal_analysis`](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/meal_analysis) (Analysis orchestration), [`ai/src/rag`](https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/rag) (Knowledge retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Family nutrition PWA"]
  node_app["App router<br/>[App.jsx]"]
  node_layout["App layout<br/>[AppLayout.jsx]"]
  node_nav["Navigation<br/>[NavBar.jsx]"]
  node_home["Home page<br/>[HomePage.jsx]"]
  node_capture["Meal capture<br/>[CapturePage.jsx]"]
  node_family["Family profiles<br/>[FamilyPage.jsx]"]
  node_diary["Meal diary<br/>[DiaryPage.jsx]"]
  node_menus["Menu planning UI<br/>[MenuPage.jsx]"]
end

subgraph group_backend["Backend services"]
  node_api["API layer"]
  node_orchestration["Analysis orchestration"]
  node_profiles["Profile services"]
  node_media["Media handling"]
  node_nutrition["Nutrition calculation"]
  node_rules["Medical rules"]
  node_menu["Menu generation"]
  node_diary_service["Diary services"]
  node_privacy["Privacy services"]
  node_pdf["PDF export"]
end

subgraph group_ai["AI analysis"]
  node_vision["Food recognition"]
  node_portion["Portion estimation"]
  node_rag["Knowledge retrieval"]
  node_llm["LLM explanation"]
end

subgraph group_data["Data and persistence"]
  node_knowledge["Nutrition and source data"]
  node_database[("Application storage")]
  node_vector[("Vector store")]
end

subgraph group_contracts["Shared contracts"]
  node_contracts["API schemas"]
end

node_user(("Family user"))

node_user -->|"uses"| node_app
node_app -->|"renders routes in"| node_layout
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_capture
node_app -->|"routes to"| node_family
node_app -->|"routes to"| node_diary
node_app -->|"routes to"| node_menus
node_layout -->|"renders"| node_nav
node_app -.->|"exchanges data with"| node_api
node_api -->|"coordinates"| node_orchestration
node_orchestration -.->|"uses"| node_media
node_orchestration -.->|"analyzes meals with"| node_vision
node_orchestration -.->|"estimates portions with"| node_portion
node_orchestration -->|"coordinates"| node_nutrition
node_orchestration -.->|"uses retrieval"| node_rag
node_orchestration -.->|"uses"| node_llm
node_orchestration -.->|"uses profiles"| node_profiles
node_orchestration -->|"applies constraints"| node_rules
node_menus -.->|"requests planning"| node_api
node_diary -.->|"requests diary data"| node_api
node_family -.->|"requests profiles"| node_api
node_api -.->|"coordinates"| node_diary_service
node_api -->|"coordinates"| node_menu
node_api -->|"coordinates"| node_privacy
node_api -->|"coordinates"| node_pdf
node_api -.->|"reads and writes"| node_database
node_nutrition -->|"uses nutrition data"| node_knowledge
node_rules -->|"uses medical rules"| node_knowledge
node_rag -->|"retrieves from"| node_knowledge
node_rag -->|"queries"| node_vector
node_api -->|"uses shared schemas"| node_contracts
node_app -->|"shares API schemas"| node_contracts

click node_app "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/App.jsx"
click node_layout "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/layouts/AppLayout.jsx"
click node_nav "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/layouts/NavBar.jsx"
click node_home "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/home/HomePage.jsx"
click node_capture "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/meal_capture/CapturePage.jsx"
click node_family "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/family_profiles/FamilyPage.jsx"
click node_diary "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/meal_diary/DiaryPage.jsx"
click node_menus "https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/menu_planning/MenuPage.jsx"
click node_api "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/api"
click node_orchestration "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/meal_analysis"
click node_profiles "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/profiles"
click node_media "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/media"
click node_nutrition "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/nutrition"
click node_rules "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/rule_engine"
click node_menu "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/menu_planning"
click node_diary_service "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/meal_diary"
click node_privacy "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/privacy"
click node_pdf "https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/pdf_export"
click node_vision "https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/vision"
click node_portion "https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/portion_estimation"
click node_rag "https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/rag"
click node_llm "https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/llm"
click node_knowledge "https://github.com/hoanganhcq/nutriplan/tree/main/data"
click node_database "https://github.com/hoanganhcq/nutriplan/tree/main/database"
click node_vector "https://github.com/hoanganhcq/nutriplan/tree/main/database/vector_store"
click node_contracts "https://github.com/hoanganhcq/nutriplan/tree/main/contracts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_layout,node_nav,node_home,node_capture,node_family,node_diary,node_menus,node_user toneBlue
class node_api,node_orchestration,node_profiles,node_media,node_nutrition,node_rules,node_menu,node_diary_service,node_privacy,node_pdf toneAmber
class node_vision,node_portion,node_rag,node_llm toneMint
class node_knowledge,node_database,node_vector toneRose
class node_contracts toneIndigo
```

## Components

### Family nutrition PWA

- [App router](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [App layout](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/layouts/AppLayout.jsx): `frontend/src/layouts/AppLayout.jsx`
- [Navigation](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/layouts/NavBar.jsx): `frontend/src/layouts/NavBar.jsx`
- [Home page](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/home/HomePage.jsx): `frontend/src/features/home/HomePage.jsx`
- [Meal capture](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/meal_capture/CapturePage.jsx): `frontend/src/features/meal_capture/CapturePage.jsx`
- [Family profiles](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/family_profiles/FamilyPage.jsx): `frontend/src/features/family_profiles/FamilyPage.jsx`
- [Meal diary](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/meal_diary/DiaryPage.jsx): `frontend/src/features/meal_diary/DiaryPage.jsx`
- [Menu planning UI](https://github.com/hoanganhcq/nutriplan/blob/main/frontend/src/features/menu_planning/MenuPage.jsx): `frontend/src/features/menu_planning/MenuPage.jsx`

### Backend services

- [API layer](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/api): `backend/src/api`
- [Analysis orchestration](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/meal_analysis): `backend/src/services/meal_analysis`
- [Profile services](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/profiles): `backend/src/services/profiles`
- [Media handling](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/media): `backend/src/services/media`
- [Nutrition calculation](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/nutrition): `backend/src/services/nutrition`
- [Medical rules](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/rule_engine): `backend/src/services/rule_engine`
- [Menu generation](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/menu_planning): `backend/src/services/menu_planning`
- [Diary services](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/meal_diary): `backend/src/services/meal_diary`
- [Privacy services](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/privacy): `backend/src/services/privacy`
- [PDF export](https://github.com/hoanganhcq/nutriplan/tree/main/backend/src/services/pdf_export): `backend/src/services/pdf_export`

### AI analysis

- [Food recognition](https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/vision): `ai/src/vision`
- [Portion estimation](https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/portion_estimation): `ai/src/portion_estimation`
- [Knowledge retrieval](https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/rag): `ai/src/rag`
- [LLM explanation](https://github.com/hoanganhcq/nutriplan/tree/main/ai/src/llm): `ai/src/llm`

### Data and persistence

- [Nutrition and source data](https://github.com/hoanganhcq/nutriplan/tree/main/data): `data`
- [Application storage](https://github.com/hoanganhcq/nutriplan/tree/main/database): `database`
- [Vector store](https://github.com/hoanganhcq/nutriplan/tree/main/database/vector_store): `database/vector_store`

### Shared contracts

- [API schemas](https://github.com/hoanganhcq/nutriplan/tree/main/contracts): `contracts`

### Other components

- **Family user**

## Connections

- Family user → App router: uses (evidence: `README.md`)
- App router → App layout: renders routes in (evidence: `frontend/src/App.jsx`)
- App router → Home page: routes to (evidence: `frontend/src/App.jsx`)
- App router → Meal capture: routes to (evidence: `frontend/src/App.jsx`)
- App router → Family profiles: routes to (evidence: `frontend/src/App.jsx`)
- App router → Meal diary: routes to (evidence: `frontend/src/App.jsx`)
- App router → Menu planning UI: routes to (evidence: `frontend/src/App.jsx`)
- App layout → Navigation: renders (evidence: `frontend/src/layouts/AppLayout.jsx`)
- App router → API layer: exchanges data with
- API layer → Analysis orchestration: coordinates (evidence: `README.md`)
- Analysis orchestration → Media handling: uses
- Analysis orchestration → Food recognition: analyzes meals with
- Analysis orchestration → Portion estimation: estimates portions with
- Analysis orchestration → Nutrition calculation: coordinates (evidence: `README.md`)
- Analysis orchestration → Knowledge retrieval: uses retrieval
- Analysis orchestration → LLM explanation: uses
- Analysis orchestration → Profile services: uses profiles
- Analysis orchestration → Medical rules: applies constraints (evidence: `README.md`)
- Menu planning UI → API layer: requests planning
- Meal diary → API layer: requests diary data
- Family profiles → API layer: requests profiles
- API layer → Diary services: coordinates
- API layer → Menu generation: coordinates (evidence: `README.md`)
- API layer → Privacy services: coordinates (evidence: `README.md`)
- API layer → PDF export: coordinates (evidence: `README.md`)
- API layer → Application storage: reads and writes
- Nutrition calculation → Nutrition and source data: uses nutrition data (evidence: `README.md`)
- Medical rules → Nutrition and source data: uses medical rules (evidence: `README.md`)
- Knowledge retrieval → Nutrition and source data: retrieves from (evidence: `README.md`)
- Knowledge retrieval → Vector store: queries (evidence: `README.md`)
- API layer → API schemas: uses shared schemas (evidence: `README.md`)
- App router → API schemas: shares API schemas (evidence: `README.md`)
