# ryuo-00/nutriscan architecture

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

- Interactive diagram: https://gitdiagram.com/ryuo-00/nutriscan
- Repository: https://github.com/ryuo-00/nutriscan

## Overview

NutriScan is a local Flask food-label screening prototype. A user uploads a label or chooses the bundled sample; the Flask application coordinates image preparation, OCR, text/section parsing, ingredient and additive matching, allergen checks, unit-aware nutrient screening, scoring, and locally saved results. The UI also exposes scan history, and OCR can retry layout-specific reads. The README documents the end-to-end stages; the source excerpts show selected implementation details, so unsampled subsystem links are limited to documented workflow relationships.

Main entry points: [`app.py`](https://github.com/ryuo-00/nutriscan/blob/main/app.py) (Flask routes), [`templates`](https://github.com/ryuo-00/nutriscan/tree/main/templates) (Upload and results UI), [`ocr.py`](https://github.com/ryuo-00/nutriscan/blob/main/ocr.py) (OCR and retries), [`nutrition.py`](https://github.com/ryuo-00/nutriscan/blob/main/nutrition.py) (Nutrient screening)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_ui["Upload and results UI"]
  node_web_assets["Browser interactions<br/>[app.js]"]
  node_flask["Flask routes<br/>[app.py]"]
end

subgraph group_recognition["Image recognition"]
  node_preprocess["Image preparation<br/>[preprocess.py]"]
  node_ocr["OCR and retries<br/>[ocr.py]"]
  node_ocr_resources["OCR vocabulary"]
end

subgraph group_analysis["Label analysis"]
  node_parser["Text and sections<br/>[parser.py]"]
  node_matcher["Ingredient matching<br/>[matcher.py]"]
  node_allergens["Allergen screening<br/>[matcher.py]"]
  node_nutrition["Nutrient screening<br/>[nutrition.py]"]
  node_scoring["Explainable score<br/>[scoring.py]"]
  node_configuration["Rules and paths<br/>[config.py]"]
end

subgraph group_persistence["Local data"]
  node_knowledge["Screening knowledge"]
  node_storage["Local persistence<br/>[storage.py]"]
  node_history[("Scan history<br/>[storage.py]")]
end

node_user(("User"))
node_tesseract["Tesseract OCR"]

node_user -->|"uploads label"| node_web_ui
node_web_ui -->|"uses interactions"| node_web_assets
node_web_ui -->|"submits scan"| node_flask
node_flask -->|"prepares image"| node_preprocess
node_flask -->|"runs OCR"| node_ocr
node_preprocess -.->|"supplies image"| node_ocr
node_ocr -->|"recognizes text"| node_tesseract
node_ocr -.->|"uses vocabulary"| node_ocr_resources
node_flask -->|"parses text"| node_parser
node_flask -->|"matches ingredients"| node_matcher
node_flask -->|"checks allergens"| node_allergens
node_flask -->|"screens nutrients"| node_nutrition
node_flask -->|"calculates score"| node_scoring
node_nutrition -->|"normalizes text"| node_parser
node_matcher -.->|"uses records"| node_knowledge
node_allergens -.->|"uses records"| node_knowledge
node_nutrition -->|"reads thresholds"| node_configuration
node_scoring -->|"checks comparability"| node_nutrition
node_scoring -->|"reads weights"| node_configuration
node_flask -->|"loads and saves"| node_storage
node_storage -.->|"loads knowledge"| node_knowledge
node_storage -->|"reads and writes"| node_history
node_flask -.->|"renders results"| node_web_ui
node_user -->|"reopens scans"| node_history

click node_web_ui "https://github.com/ryuo-00/nutriscan/tree/main/templates"
click node_web_assets "https://github.com/ryuo-00/nutriscan/blob/main/static/js/app.js"
click node_flask "https://github.com/ryuo-00/nutriscan/blob/main/app.py"
click node_preprocess "https://github.com/ryuo-00/nutriscan/blob/main/preprocess.py"
click node_ocr "https://github.com/ryuo-00/nutriscan/blob/main/ocr.py"
click node_parser "https://github.com/ryuo-00/nutriscan/blob/main/parser.py"
click node_matcher "https://github.com/ryuo-00/nutriscan/blob/main/matcher.py"
click node_allergens "https://github.com/ryuo-00/nutriscan/blob/main/matcher.py"
click node_nutrition "https://github.com/ryuo-00/nutriscan/blob/main/nutrition.py"
click node_scoring "https://github.com/ryuo-00/nutriscan/blob/main/scoring.py"
click node_configuration "https://github.com/ryuo-00/nutriscan/blob/main/config.py"
click node_knowledge "https://github.com/ryuo-00/nutriscan/tree/main/data/knowledge"
click node_ocr_resources "https://github.com/ryuo-00/nutriscan/tree/main/data/ocr"
click node_storage "https://github.com/ryuo-00/nutriscan/blob/main/storage.py"
click node_history "https://github.com/ryuo-00/nutriscan/blob/main/storage.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_web_ui,node_web_assets,node_flask,node_user toneBlue
class node_preprocess,node_ocr,node_ocr_resources toneAmber
class node_parser,node_matcher,node_allergens,node_nutrition,node_scoring,node_configuration toneMint
class node_knowledge,node_storage,node_history toneRose
class node_tesseract toneIndigo
```

## Components

### Web application

- [Upload and results UI](https://github.com/ryuo-00/nutriscan/tree/main/templates): `templates`
- [Browser interactions](https://github.com/ryuo-00/nutriscan/blob/main/static/js/app.js): `static/js/app.js`
- [Flask routes](https://github.com/ryuo-00/nutriscan/blob/main/app.py): `app.py`

### Image recognition

- [Image preparation](https://github.com/ryuo-00/nutriscan/blob/main/preprocess.py): `preprocess.py`
- [OCR and retries](https://github.com/ryuo-00/nutriscan/blob/main/ocr.py): `ocr.py`
- [OCR vocabulary](https://github.com/ryuo-00/nutriscan/tree/main/data/ocr): `data/ocr`

### Label analysis

- [Text and sections](https://github.com/ryuo-00/nutriscan/blob/main/parser.py): `parser.py`
- [Ingredient matching](https://github.com/ryuo-00/nutriscan/blob/main/matcher.py): `matcher.py`
- [Allergen screening](https://github.com/ryuo-00/nutriscan/blob/main/matcher.py): `matcher.py`
- [Nutrient screening](https://github.com/ryuo-00/nutriscan/blob/main/nutrition.py): `nutrition.py`
- [Explainable score](https://github.com/ryuo-00/nutriscan/blob/main/scoring.py): `scoring.py`
- [Rules and paths](https://github.com/ryuo-00/nutriscan/blob/main/config.py): `config.py`

### Local data

- [Screening knowledge](https://github.com/ryuo-00/nutriscan/tree/main/data/knowledge): `data/knowledge`
- [Local persistence](https://github.com/ryuo-00/nutriscan/blob/main/storage.py): `storage.py`
- [Scan history](https://github.com/ryuo-00/nutriscan/blob/main/storage.py): `storage.py`

### Other components

- **User**
- **Tesseract OCR**

## Connections

- User → Upload and results UI: uploads label (evidence: `README.md`)
- Upload and results UI → Browser interactions: uses interactions
- Upload and results UI → Flask routes: submits scan (evidence: `README.md`)
- Flask routes → Image preparation: prepares image (evidence: `app.py`)
- Flask routes → OCR and retries: runs OCR (evidence: `app.py`)
- Image preparation → OCR and retries: supplies image (evidence: `ocr.py`)
- OCR and retries → Tesseract OCR: recognizes text (evidence: `README.md`)
- OCR and retries → OCR vocabulary: uses vocabulary
- Flask routes → Text and sections: parses text (evidence: `app.py`)
- Flask routes → Ingredient matching: matches ingredients (evidence: `app.py`)
- Flask routes → Allergen screening: checks allergens (evidence: `README.md`)
- Flask routes → Nutrient screening: screens nutrients (evidence: `app.py`)
- Flask routes → Explainable score: calculates score (evidence: `app.py`)
- Nutrient screening → Text and sections: normalizes text (evidence: `nutrition.py`)
- Ingredient matching → Screening knowledge: uses records
- Allergen screening → Screening knowledge: uses records
- Nutrient screening → Rules and paths: reads thresholds (evidence: `nutrition.py`)
- Explainable score → Nutrient screening: checks comparability (evidence: `scoring.py`)
- Explainable score → Rules and paths: reads weights (evidence: `scoring.py`)
- Flask routes → Local persistence: loads and saves (evidence: `app.py`)
- Local persistence → Screening knowledge: loads knowledge
- Local persistence → Scan history: reads and writes (evidence: `storage.py`)
- Flask routes → Upload and results UI: renders results
- User → Scan history: reopens scans (evidence: `README.md`)
