# sud747/vizualai architecture

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

- Interactive diagram: https://gitdiagram.com/sud747/vizualai
- Repository: https://github.com/sud747/vizualai

## Overview

#### Purpose and deployment shape
VizualAI recognizes foods in tray images and returns an itemized bill. It is a multi-client repository centered on a Python FastAPI inference service, with packaged ML weights and Flutter/native Android clients. The API is intended to run locally on port 8001; Docker support is present via `Dockerfile`.

#### Backend API entry points
The documented service entry point is `backend/food_app.py`, which exposes REST endpoints and hosts model inference. `backend/app.py` is a second backend application/module and should be assessed before consolidating server startup behavior. A static browser-facing dashboard is co-located with the backend at `backend/static/food_ui.html` and `backend/static/index.html`.

#### Vision inference pipeline
The core recognition boundary is the two-stage pipeline in `backend/yolo_pipeline.py`:
1. YOLOv8 detects candidate tray objects and bounding boxes.
2. Regions are cropped/preprocessed and classified by fine-tuned MobileNetV2.
3. Custom post-processing/NMS removes duplicates.
4. Recognized classes feed pricing/billing returned by the API.

The deployable model artifacts are `models/yolov8n.pt` and `models/best_food_classifier.pth`. `backend/detect_food.py` provides a likely CLI-oriented invocation path separate from the HTTP service.

#### Model lifecycle
Inference consumes checked-in model weights from `models/`. Training is separated from serving in `backend/train_classifier.py`, creating a material lifecycle boundary: training or replacing classifier weights must preserve the class-label and pricing assumptions used by the runtime pipeline. GPU acceleration is optional through CUDA-compatible PyTorch; CPU execution remains supported.

#### Flutter client flow
The principal cross-platform client starts at `apps/flutter/lib/main.dart` and targets Android, iOS, web, Windows, macOS, and Linux through Flutter platform hosts. UI flows are organized around start, scanning, and billing screens: `apps/flutter/lib/screens/start_screen.dart`, `apps/flutter/lib/screens/scanner_screen.dart`, and `apps/flutter/lib/screens/billing_screen.dart`. Scanner and payment state/control flows use BLoC boundaries in `apps/flutter/lib/blocs/scanner/scanner_bloc.dart` and `apps/flutter/lib/blocs/payment/payment_bloc.dart`.

#### Client-to-service and billing boundary
The Flutter repository layer, `apps/flutter/lib/repositories/food_repository.dart`, is the client-side boundary for food/API data. API endpoint configuration is isolated in `apps/flutter/lib/config/api_config.dart`. Domain payloads are represented by `apps/flutter/lib/models/food_item.dart` and `apps/flutter/lib/models/bill.dart`; the expected flow is scan image → API prediction → recognized items → bill display/payment state.

#### Native Android client
A separate Kotlin/Jetpack Compose Android implementation exists, entered through `apps/android/app/src/main/java/com/example/foodsight/MainActivity.kt`. It uses navigation via `Navigation.kt`, presents its primary UI in `ui/main/MainScreen.kt`, and separates screen state in `ui/main/MainScreenViewModel.kt`. Its data boundary is `data/DataRepository.kt`; it should be treated as an independent client implementation rather than a Flutter platform wrapper.

#### Infrastructure and external dependencies
Runtime dependencies include FastAPI/Uvicorn, Ultralytics YOLOv8, PyTorch/Torchvision, Pillow, and multipart upload handling, declared at repository level in `requirements.txt`. External execution dependencies are Python 3.8+, optional NVIDIA CUDA/GPU support, Flutter SDK for the cross-platform app, and Android Gradle tooling for the native client.

Main entry points: [`backend/yolo_pipeline.py`](https://github.com/sud747/vizualai/blob/main/backend/yolo_pipeline.py) (Food recognition pipeline), [`apps/flutter/lib/repositories/food_repository.dart`](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/repositories/food_repository.dart) (Food repository), [`apps/flutter/lib/screens/scanner_screen.dart`](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/screens/scanner_screen.dart) (Start, scan, bill UI), [`backend/food_app.py`](https://github.com/sud747/vizualai/blob/main/backend/food_app.py) (FastAPI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python Inference Service"]
  node_api["FastAPI service<br/>HTTP API<br/>[food_app.py]"]
  node_secondary_api["Second backend module<br/>Python module<br/>[app.py]"]
  node_pipeline["Food recognition pipeline<br/>vision pipeline<br/>[yolo_pipeline.py]"]
  node_cli["CLI detection<br/>CLI entry<br/>[detect_food.py]"]
  node_dashboard["Static dashboard<br/>browser UI<br/>[food_ui.html]"]
end

subgraph group_models["Model Lifecycle"]
  node_yolo_weights[("YOLOv8 weights<br/>model artifact<br/>[yolov8n.pt]")]
  node_classifier_weights[("Food classifier weights<br/>model artifact")]
  node_training["Classifier training<br/>training job"]
end

subgraph group_flutter["Flutter Client"]
  node_flutter_app["Flutter app<br/>application entry<br/>[main.dart]"]
  node_flutter_screens["Start, scan, bill UI<br/>screen flow"]
  node_scanner_bloc["Scanner BLoC<br/>state controller<br/>[scanner_bloc.dart]"]
  node_payment_bloc["Payment BLoC<br/>state controller<br/>[payment_bloc.dart]"]
  node_food_repo["Food repository<br/>API client boundary"]
  node_api_config["API configuration<br/>endpoint config<br/>[api_config.dart]"]
  node_flutter_domain["Food and bill payloads<br/>domain models<br/>[bill.dart]"]
end

subgraph group_android["Native Android Client"]
  node_android_app["Compose Android app<br/>application entry<br/>[MainActivity.kt]"]
  node_android_ui["Main screen and state<br/>Compose UI"]
  node_android_repo["Data repository<br/>data boundary"]
end

node_dashboard -->|"HTTP requests"| node_api
node_api -->|"runs inference"| node_pipeline
node_secondary_api -.->|"may expose inference"| node_pipeline
node_cli -->|"invokes"| node_pipeline
node_pipeline -->|"loads detector"| node_yolo_weights
node_pipeline -->|"loads classifier"| node_classifier_weights
node_training -->|"produces/replaces"| node_classifier_weights
node_flutter_app -->|"hosts flow"| node_flutter_screens
node_flutter_screens -->|"scan state"| node_scanner_bloc
node_flutter_screens -->|"payment state"| node_payment_bloc
node_scanner_bloc -->|"submits image"| node_food_repo
node_food_repo -->|"uses endpoint"| node_api_config
node_food_repo -->|"prediction request"| node_api
node_food_repo -->|"maps response"| node_flutter_domain
node_flutter_domain -->|"bill state"| node_payment_bloc
node_android_app -->|"hosts"| node_android_ui
node_android_ui -->|"loads data"| node_android_repo

click node_api "https://github.com/sud747/vizualai/blob/main/backend/food_app.py"
click node_secondary_api "https://github.com/sud747/vizualai/blob/main/backend/app.py"
click node_pipeline "https://github.com/sud747/vizualai/blob/main/backend/yolo_pipeline.py"
click node_cli "https://github.com/sud747/vizualai/blob/main/backend/detect_food.py"
click node_dashboard "https://github.com/sud747/vizualai/blob/main/backend/static/food_ui.html"
click node_yolo_weights "https://github.com/sud747/vizualai/blob/main/models/yolov8n.pt"
click node_classifier_weights "https://github.com/sud747/vizualai/blob/main/models/best_food_classifier.pth"
click node_training "https://github.com/sud747/vizualai/blob/main/backend/train_classifier.py"
click node_flutter_app "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/main.dart"
click node_flutter_screens "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/screens/scanner_screen.dart"
click node_scanner_bloc "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/blocs/scanner/scanner_bloc.dart"
click node_payment_bloc "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/blocs/payment/payment_bloc.dart"
click node_food_repo "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/repositories/food_repository.dart"
click node_api_config "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/config/api_config.dart"
click node_flutter_domain "https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/models/bill.dart"
click node_android_app "https://github.com/sud747/vizualai/blob/main/apps/android/app/src/main/java/com/example/foodsight/MainActivity.kt"

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_api,node_secondary_api,node_pipeline,node_cli,node_dashboard toneBlue
class node_yolo_weights,node_classifier_weights,node_training toneAmber
class node_flutter_app,node_flutter_screens,node_scanner_bloc,node_payment_bloc,node_food_repo,node_api_config,node_flutter_domain toneMint
class node_android_app,node_android_ui,node_android_repo toneRose
```

## Components

### Python Inference Service

- [FastAPI service](https://github.com/sud747/vizualai/blob/main/backend/food_app.py): HTTP API · REST upload and billing inference service on port 8001. · `backend/food_app.py`
- [Second backend module](https://github.com/sud747/vizualai/blob/main/backend/app.py): Python module · Separate application module to assess before startup consolidation. · `backend/app.py`
- [Food recognition pipeline](https://github.com/sud747/vizualai/blob/main/backend/yolo_pipeline.py): vision pipeline · Detects, crops, classifies, deduplicates, and prices foods. · `backend/yolo_pipeline.py`
- [CLI detection](https://github.com/sud747/vizualai/blob/main/backend/detect_food.py): CLI entry · `backend/detect_food.py`
- [Static dashboard](https://github.com/sud747/vizualai/blob/main/backend/static/food_ui.html): browser UI · `backend/static/food_ui.html`

### Model Lifecycle

- [YOLOv8 weights](https://github.com/sud747/vizualai/blob/main/models/yolov8n.pt): model artifact · `models/yolov8n.pt`
- [Food classifier weights](https://github.com/sud747/vizualai/blob/main/models/best_food_classifier.pth): model artifact · Fine-tuned classifier consumed by serving. · `models/best_food_classifier.pth`
- [Classifier training](https://github.com/sud747/vizualai/blob/main/backend/train_classifier.py): training job · Replacement weights must retain runtime label and pricing assumptions. · `backend/train_classifier.py`

### Flutter Client

- [Flutter app](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/main.dart): application entry · Cross-platform client for mobile, desktop, and web. · `apps/flutter/lib/main.dart`
- [Start, scan, bill UI](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/screens/scanner_screen.dart): screen flow · `apps/flutter/lib/screens/scanner_screen.dart`
- [Scanner BLoC](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/blocs/scanner/scanner_bloc.dart): state controller · `apps/flutter/lib/blocs/scanner/scanner_bloc.dart`
- [Payment BLoC](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/blocs/payment/payment_bloc.dart): state controller · `apps/flutter/lib/blocs/payment/payment_bloc.dart`
- [Food repository](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/repositories/food_repository.dart): API client boundary · `apps/flutter/lib/repositories/food_repository.dart`
- [API configuration](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/config/api_config.dart): endpoint config · `apps/flutter/lib/config/api_config.dart`
- [Food and bill payloads](https://github.com/sud747/vizualai/blob/main/apps/flutter/lib/models/bill.dart): domain models · `apps/flutter/lib/models/bill.dart`

### Native Android Client

- [Compose Android app](https://github.com/sud747/vizualai/blob/main/apps/android/app/src/main/java/com/example/foodsight/MainActivity.kt): application entry · Independent native Android client implementation. · `apps/android/app/src/main/java/com/example/foodsight/MainActivity.kt`
- **Main screen and state**: Compose UI
- **Data repository**: data boundary

## Connections

- Static dashboard → FastAPI service: HTTP requests
- FastAPI service → Food recognition pipeline: runs inference
- Second backend module → Food recognition pipeline: may expose inference
- CLI detection → Food recognition pipeline: invokes
- Food recognition pipeline → YOLOv8 weights: loads detector
- Food recognition pipeline → Food classifier weights: loads classifier
- Classifier training → Food classifier weights: produces/replaces
- Flutter app → Start, scan, bill UI: hosts flow
- Start, scan, bill UI → Scanner BLoC: scan state
- Start, scan, bill UI → Payment BLoC: payment state
- Scanner BLoC → Food repository: submits image
- Food repository → API configuration: uses endpoint
- Food repository → FastAPI service: prediction request
- Food repository → Food and bill payloads: maps response
- Food and bill payloads → Payment BLoC: bill state
- Compose Android app → Main screen and state: hosts
- Main screen and state → Data repository: loads data