# kavyapushpala/foodsheild-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kavyapushpala/foodsheild-ai
- Repository: https://github.com/kavyapushpala/foodsheild-ai

## Overview

FoodShield AI is a food-product analysis application with a separate regulatory Q&A feature. The main workflow accepts a product image and/or barcode, analyzes product and safety signals, and returns results to the web UI. The regulatory path retrieves source material and generates a grounded answer. The analysis service and RAG flow are supported by sampled source; frontend and API wiring beyond the sampled entry points is inferred only where module names and documented responsibilities indicate it.

Main entry points: [`backend/app/services/analysis_service.py`](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/analysis_service.py) (Analysis orchestrator), [`backend/app/api/rag.py`](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/api/rag.py) (RAG endpoint), [`frontend/src/pages/Analyze.tsx`](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/pages/Analyze.tsx) (Analyze page), [`backend/app/main.py`](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App routes<br/>[App.tsx]"]
  node_analyze_page["Analyze page<br/>[Analyze.tsx]"]
  node_analysis_hook["Analysis state<br/>[useAnalysis.ts]"]
  node_analysis_client["Analysis client<br/>[analysisService.ts]"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_upload_ui["Upload and barcode UI<br/>[UploadPanel.tsx]"]
  node_results_ui["Analysis results UI<br/>[ResultCard.tsx]"]
end

subgraph group_api["API boundary"]
  node_main_api["FastAPI application<br/>[main.py]"]
  node_analyze_route["Analysis endpoint<br/>[analyze.py]"]
  node_rag_route["RAG endpoint<br/>[rag.py]"]
end

subgraph group_analysis["Product analysis"]
  node_analysis_orchestrator["Analysis orchestrator"]
  node_ocr["OCR extraction<br/>[ocr_service.py]"]
  node_product_extract["Product extraction"]
  node_barcode["Barcode validation<br/>[barcode_service.py]"]
  node_product_lookup["Product lookup"]
  node_recall_lookup["Recall lookup<br/>[recall_service.py]"]
  node_safety["Safety assessment<br/>[safety_service.py]"]
  node_authenticity["Authenticity assessment"]
  node_ml["Image ML analysis<br/>[ml_service.py]"]
end

subgraph group_regulatory["Regulatory Q&amp;A"]
  node_rag_service["Regulation retrieval<br/>[rag_service.py]"]
  node_vector_store[("Regulation vectors")]
  node_answer_generation["Grounded answer generation<br/>[gemini_service.py]"]
end

node_consumer(("Product user"))
node_gemini{{"Gemini API"}}

node_consumer -->|"opens"| node_app
node_app -->|"routes to"| node_analyze_page
node_consumer -->|"provides input"| node_upload_ui
node_analyze_page -->|"uses"| node_analysis_hook
node_analysis_hook -->|"submits"| node_analysis_client
node_analysis_client -->|"posts request"| node_api_client
node_api_client -->|"sends HTTP"| node_main_api
node_main_api -->|"dispatches"| node_analyze_route
node_analyze_route -->|"analyzes product"| node_analysis_orchestrator
node_analysis_orchestrator -->|"extracts text"| node_ocr
node_analysis_orchestrator -->|"extracts fields"| node_product_extract
node_analysis_orchestrator -->|"validates barcode"| node_barcode
node_analysis_orchestrator -->|"looks up product"| node_product_lookup
node_analysis_orchestrator -->|"checks recalls"| node_recall_lookup
node_analysis_orchestrator -->|"assesses safety"| node_safety
node_analysis_orchestrator -->|"assesses authenticity"| node_authenticity
node_analysis_orchestrator -->|"runs image analysis"| node_ml
node_analyze_route -->|"returns result"| node_analysis_client
node_analyze_page -->|"renders result"| node_results_ui
node_consumer -->|"asks question"| node_rag_route
node_main_api -->|"dispatches"| node_rag_route
node_rag_route -->|"retrieves context"| node_rag_service
node_rag_service -->|"queries"| node_vector_store
node_rag_route -->|"generates answer"| node_answer_generation
node_rag_service -->|"returns context and sources"| node_rag_route
node_answer_generation -->|"requests completion"| node_gemini
node_gemini -->|"returns answer"| node_answer_generation

click node_app "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/App.tsx"
click node_analyze_page "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/pages/Analyze.tsx"
click node_analysis_hook "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/hooks/useAnalysis.ts"
click node_analysis_client "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/services/analysisService.ts"
click node_api_client "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/services/api.ts"
click node_upload_ui "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/components/UploadPanel.tsx"
click node_results_ui "https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/components/ResultCard.tsx"
click node_main_api "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/main.py"
click node_analyze_route "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/api/analyze.py"
click node_rag_route "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/api/rag.py"
click node_analysis_orchestrator "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/analysis_service.py"
click node_ocr "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/ocr_service.py"
click node_product_extract "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/product_extraction_service.py"
click node_barcode "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/barcode_service.py"
click node_product_lookup "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/product_database_service.py"
click node_recall_lookup "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/recall_service.py"
click node_safety "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/safety_service.py"
click node_authenticity "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/authenticity_service.py"
click node_ml "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/ml_service.py"
click node_rag_service "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/rag/rag_service.py"
click node_answer_generation "https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/rag/gemini_service.py"

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_analyze_page,node_analysis_hook,node_analysis_client,node_api_client,node_upload_ui,node_results_ui,node_consumer toneBlue
class node_main_api,node_analyze_route,node_rag_route toneAmber
class node_analysis_orchestrator,node_ocr,node_product_extract,node_barcode,node_product_lookup,node_recall_lookup,node_safety,node_authenticity,node_ml,node_gemini toneMint
class node_rag_service,node_vector_store,node_answer_generation toneRose
```

## Components

### Web application

- [App routes](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Analyze page](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/pages/Analyze.tsx): `frontend/src/pages/Analyze.tsx`
- [Analysis state](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/hooks/useAnalysis.ts): `frontend/src/hooks/useAnalysis.ts`
- [Analysis client](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/services/analysisService.ts): `frontend/src/services/analysisService.ts`
- [HTTP client](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Upload and barcode UI](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/components/UploadPanel.tsx): `frontend/src/components/UploadPanel.tsx`
- [Analysis results UI](https://github.com/kavyapushpala/foodsheild-ai/blob/main/frontend/src/components/ResultCard.tsx): `frontend/src/components/ResultCard.tsx`

### API boundary

- [FastAPI application](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Analysis endpoint](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/api/analyze.py): `backend/app/api/analyze.py`
- [RAG endpoint](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/api/rag.py): `backend/app/api/rag.py`

### Product analysis

- [Analysis orchestrator](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/analysis_service.py): `backend/app/services/analysis_service.py`
- [OCR extraction](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/ocr_service.py): `backend/app/services/ocr_service.py`
- [Product extraction](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/product_extraction_service.py): `backend/app/services/product_extraction_service.py`
- [Barcode validation](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/barcode_service.py): `backend/app/services/barcode_service.py`
- [Product lookup](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/product_database_service.py): `backend/app/services/product_database_service.py`
- [Recall lookup](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/recall_service.py): `backend/app/services/recall_service.py`
- [Safety assessment](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/safety_service.py): `backend/app/services/safety_service.py`
- [Authenticity assessment](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/authenticity_service.py): `backend/app/services/authenticity_service.py`
- [Image ML analysis](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/services/ml_service.py): `backend/app/services/ml_service.py`

### Regulatory Q&A

- [Regulation retrieval](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/rag/rag_service.py): `backend/app/rag/rag_service.py`
- **Regulation vectors**
- [Grounded answer generation](https://github.com/kavyapushpala/foodsheild-ai/blob/main/backend/app/rag/gemini_service.py): `backend/app/rag/gemini_service.py`

### Other components

- **Product user**
- **Gemini API**

## Connections

- Product user → App routes: opens
- App routes → Analyze page: routes to
- Product user → Upload and barcode UI: provides input
- Analyze page → Analysis state: uses
- Analysis state → Analysis client: submits
- Analysis client → HTTP client: posts request
- HTTP client → FastAPI application: sends HTTP
- FastAPI application → Analysis endpoint: dispatches
- Analysis endpoint → Analysis orchestrator: analyzes product
- Analysis orchestrator → OCR extraction: extracts text
- Analysis orchestrator → Product extraction: extracts fields
- Analysis orchestrator → Barcode validation: validates barcode
- Analysis orchestrator → Product lookup: looks up product
- Analysis orchestrator → Recall lookup: checks recalls
- Analysis orchestrator → Safety assessment: assesses safety
- Analysis orchestrator → Authenticity assessment: assesses authenticity
- Analysis orchestrator → Image ML analysis: runs image analysis
- Analysis endpoint → Analysis client: returns result
- Analyze page → Analysis results UI: renders result
- Product user → RAG endpoint: asks question
- FastAPI application → RAG endpoint: dispatches
- RAG endpoint → Regulation retrieval: retrieves context
- Regulation retrieval → Regulation vectors: queries
- RAG endpoint → Grounded answer generation: generates answer
- Regulation retrieval → RAG endpoint: returns context and sources
- Grounded answer generation → Gemini API: requests completion
- Gemini API → Grounded answer generation: returns answer