# mittai17/foodpack-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mittai17/foodpack-ai
- Repository: https://github.com/mittai17/foodpack-ai

## Overview

FoodPack AI is a decision-support platform for selecting food packaging. Users enter commodity, storage, transport, shelf-life and objective details in the web or mobile client; the API derives packaging requirements, scores and ranks validated candidates, persists the analysis, and can optionally generate a plain-English explanation. Food and material browsing, saved projects, and transport-risk assessment are additional product capabilities. The README documents the recommendation stages and integrations; unsampled subsystems are represented only where the tree or README supports them.

Main entry points: [`apps/api/src/recommendation/recommendation.service.ts`](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/recommendation.service.ts) (Recommendation coordinator), [`apps/api/src/analysis/analysis.service.ts`](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/analysis/analysis.service.ts) (Analysis workflow), [`apps/web/src/app/(app)/analysis/new/page.tsx`](https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/app/(app)/analysis/new/page.tsx) (Web app), [`apps/api/src/analysis/analysis.controller.ts`](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/analysis/analysis.controller.ts) (Analysis routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User applications"]
  node_web["Web app<br/>[page.tsx]"]
  node_mobile["Mobile app<br/>[step-4-review.tsx]"]
end

subgraph group_api["API and catalog"]
  node_api_entry["REST API<br/>[main.ts]"]
  node_analysis_api["Analysis routes"]
  node_analysis_service["Analysis workflow"]
  node_foods["Food catalog<br/>[foods.service.ts]"]
  node_materials["Material catalog"]
  node_projects["Saved projects"]
end

subgraph group_recommendation["Recommendation engine"]
  node_requirements["Requirement derivation"]
  node_candidates["Candidate generation"]
  node_scoring["Candidate scoring<br/>[scoring.service.ts]"]
  node_optimization["Objective ranking"]
  node_recommendation_service["Recommendation coordinator"]
end

subgraph group_persistence["Data and explanation"]
  node_db[("PostgreSQL")]
  node_ai["Explanation service<br/>[ai.service.ts]"]
end

subgraph group_transport["Transport assessment"]
  node_transport_ui["Transport dashboard"]
  node_transport_engine["Transport risk engine"]
end

node_user(("User"))
node_gemini{{"Gemini API"}}
node_mapbox{{"Mapbox"}}
node_weather{{"Open-Meteo"}}
node_supabase_auth{{"Supabase Auth"}}

node_user -.->|"enters analysis"| node_web
node_user -.->|"enters analysis"| node_mobile
node_web -->|"REST requests"| node_api_entry
node_mobile -->|"submits analysis"| node_api_entry
node_api_entry -.->|"routes requests"| node_analysis_api
node_analysis_api -->|"calls"| node_analysis_service
node_analysis_service -->|"runs recommendation"| node_recommendation_service
node_analysis_service -->|"persists analysis"| node_db
node_analysis_service -->|"reads analysis"| node_db
node_recommendation_service -->|"derives requirements"| node_requirements
node_recommendation_service -->|"generates candidates"| node_candidates
node_recommendation_service -->|"scores candidates"| node_scoring
node_recommendation_service -->|"ranks candidates"| node_optimization
node_recommendation_service -->|"persists results"| node_db
node_recommendation_service -.->|"requests explanation"| node_ai
node_ai -.->|"generates prose"| node_gemini
node_web -->|"authenticates"| node_supabase_auth
node_analysis_api -.-> node_foods
node_web -.->|"views transport"| node_transport_ui
node_transport_ui -.->|"assesses risk"| node_transport_engine
node_transport_engine -.->|"uses route data"| node_mapbox
node_transport_engine -.->|"uses forecast data"| node_weather
node_analysis_service -.-> node_projects
node_foods -.->|"reads catalog"| node_db
node_materials -.->|"reads catalog"| node_db
node_projects -.->|"stores projects"| node_db

click node_web "https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/app/(app)/analysis/new/page.tsx"
click node_mobile "https://github.com/mittai17/foodpack-ai/blob/master/mobile/app/analysis/wizard/step-4-review.tsx"
click node_api_entry "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/main.ts"
click node_analysis_api "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/analysis/analysis.controller.ts"
click node_analysis_service "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/analysis/analysis.service.ts"
click node_foods "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/foods/foods.service.ts"
click node_materials "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/materials/materials.service.ts"
click node_projects "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/projects/projects.service.ts"
click node_requirements "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/requirement-engine.service.ts"
click node_candidates "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/candidate-generator.service.ts"
click node_scoring "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/scoring.service.ts"
click node_optimization "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/optimization.service.ts"
click node_recommendation_service "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/recommendation.service.ts"
click node_ai "https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/ai/ai.service.ts"
click node_transport_ui "https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/app/(app)/transport/transport-dashboard.tsx"
click node_transport_engine "https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/lib/transport/transport-engine.ts"

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_web,node_mobile,node_user toneBlue
class node_api_entry,node_analysis_api,node_analysis_service,node_foods,node_materials,node_projects toneAmber
class node_requirements,node_candidates,node_scoring,node_optimization,node_recommendation_service,node_gemini toneMint
class node_db,node_ai toneRose
class node_transport_ui,node_transport_engine,node_mapbox,node_weather,node_supabase_auth toneIndigo
```

## Components

### User applications

- [Web app](https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/app/(app)/analysis/new/page.tsx): `apps/web/src/app/(app)/analysis/new/page.tsx`
- [Mobile app](https://github.com/mittai17/foodpack-ai/blob/master/mobile/app/analysis/wizard/step-4-review.tsx): `mobile/app/analysis/wizard/step-4-review.tsx`

### API and catalog

- [REST API](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/main.ts): `apps/api/src/main.ts`
- [Analysis routes](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/analysis/analysis.controller.ts): `apps/api/src/analysis/analysis.controller.ts`
- [Analysis workflow](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/analysis/analysis.service.ts): `apps/api/src/analysis/analysis.service.ts`
- [Food catalog](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/foods/foods.service.ts): `apps/api/src/foods/foods.service.ts`
- [Material catalog](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/materials/materials.service.ts): `apps/api/src/materials/materials.service.ts`
- [Saved projects](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/projects/projects.service.ts): `apps/api/src/projects/projects.service.ts`

### Recommendation engine

- [Requirement derivation](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/requirement-engine.service.ts): `apps/api/src/recommendation/services/requirement-engine.service.ts`
- [Candidate generation](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/candidate-generator.service.ts): `apps/api/src/recommendation/services/candidate-generator.service.ts`
- [Candidate scoring](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/scoring.service.ts): `apps/api/src/recommendation/services/scoring.service.ts`
- [Objective ranking](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/services/optimization.service.ts): `apps/api/src/recommendation/services/optimization.service.ts`
- [Recommendation coordinator](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/recommendation/recommendation.service.ts): `apps/api/src/recommendation/recommendation.service.ts`

### Data and explanation

- **PostgreSQL**
- [Explanation service](https://github.com/mittai17/foodpack-ai/blob/master/apps/api/src/ai/ai.service.ts): `apps/api/src/ai/ai.service.ts`

### Transport assessment

- [Transport dashboard](https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/app/(app)/transport/transport-dashboard.tsx): `apps/web/src/app/(app)/transport/transport-dashboard.tsx`
- [Transport risk engine](https://github.com/mittai17/foodpack-ai/blob/master/apps/web/src/lib/transport/transport-engine.ts): `apps/web/src/lib/transport/transport-engine.ts`

### Other components

- **User**
- **Gemini API**
- **Mapbox**
- **Open-Meteo**
- **Supabase Auth**

## Connections

- User → Web app: enters analysis
- User → Mobile app: enters analysis
- Web app → REST API: REST requests
- Mobile app → REST API: submits analysis (evidence: `mobile/app/analysis/wizard/step-4-review.tsx`)
- REST API → Analysis routes: routes requests
- Analysis routes → Analysis workflow: calls (evidence: `apps/api/src/analysis/analysis.controller.ts`)
- Analysis workflow → Recommendation coordinator: runs recommendation (evidence: `apps/api/src/analysis/analysis.service.ts`)
- Analysis workflow → PostgreSQL: persists analysis
- Analysis workflow → PostgreSQL: reads analysis
- Recommendation coordinator → Requirement derivation: derives requirements
- Recommendation coordinator → Candidate generation: generates candidates
- Recommendation coordinator → Candidate scoring: scores candidates
- Recommendation coordinator → Objective ranking: ranks candidates
- Recommendation coordinator → PostgreSQL: persists results
- Recommendation coordinator → Explanation service: requests explanation
- Explanation service → Gemini API: generates prose
- Web app → Supabase Auth: authenticates
- Analysis routes → Food catalog
- Web app → Transport dashboard: views transport
- Transport dashboard → Transport risk engine: assesses risk
- Transport risk engine → Mapbox: uses route data (evidence: `apps/web/src/lib/transport/transport-engine.ts`)
- Transport risk engine → Open-Meteo: uses forecast data (evidence: `apps/web/src/lib/transport/transport-engine.ts`)
- Analysis workflow → Saved projects
- Food catalog → PostgreSQL: reads catalog
- Material catalog → PostgreSQL: reads catalog
- Saved projects → PostgreSQL: stores projects
