# sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system architecture

> Architecture diagram of the GitHub repository sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system
- Repository: https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system

## Overview

1. BioDose is split into three clear layers: a Django backend, a Next.js frontend, and a machine-learning/registry layer that supports offline scoring and model training. The backend owns the product-safety logic and persistence; the frontend owns scan/chat/dashboard flows; the ML artifacts and CSV/JSON assets provide local toxicology knowledge and predictive models.

2. The primary runtime backend is `backend/`, organized as a Django project (`biodose/`) with three domain apps: `users`, `products`, and `analysis`. This is the main service boundary for authentication/profile management, product ingestion, and personalized risk analysis.

3. `users` handles account and profile data, including locked medical conditions and email OTP/auth-related flows. The models and migrations show a profile-centric design rather than a generic consumer account system.

4. `products` is the ingestion boundary for barcode and ingredient processing. Its services (`barcode.py`, `extractor.py`) suggest a pipeline that takes scanned product data or raw ingredient text, normalizes it, and turns it into additive candidates for downstream matching.

5. `analysis` is the core decision engine. It contains the matcher, scorer, and report services, plus views/serializers/urls for exposing scan and chat-related endpoints. The analysis migrations also show evolving persisted state for scan history and chat context, which means the app logs user-product interactions and reuses that context later.

6. The scoring path is centered around domain utilities in `backend/models/` and `backend/utils/`. `semantic_normalizer.py`, `predictor.py`, `condition_registry.py`, `cleaner.py`, and `loader.py` form the shared domain layer that maps raw ingredient text and medical-condition codes into canonical forms the scorer can evaluate.

7. The knowledge base is mostly local and file-backed. `backend/data/` contains CSVs for additive aliases, toxicological metadata, interactions, and training data, while `backend/models/ebm_model.pkl` is the serialized inference artifact. That means the system can do substantial analysis without depending only on live external calls.

8. There is a distinct model-training pipeline in `backend/ml/` plus a separate top-level `ml/` package. The files there (`build_features.py`, `generate_labels.py`, `train_ebm.py`, `train.py`, `inference.py`, `shadow_trainer.py`, `model_registry.py`) indicate an offline training/evaluation loop and a parallel “shadow” model lifecycle alongside the main rule-based scorer.

9. The frontend has two codebases. `frontend-next/` is the main app, built with Next.js App Router and organized into pages for login/signup, profile setup, scan, search, dashboard, chat, history, and terms; `src/lib/api.ts` is the API boundary to the backend. The separate `frontend/` directory looks like an older or alternate client, with Supabase auth hooks, so it should be treated as a secondary/legacy UI unless proven otherwise.

10. The application flow is user-centric: a user authenticates, sets a locked profile, scans or searches a product, the backend extracts ingredients and matches them against the local toxicology registry, then the scorer generates a personalized safety report. Chat/context features reuse the same profile and product state, so the analysis subsystem is both a scanner and a conversational advisor.

11. External integrations are part of the architecture but sit outside the core repo boundary. The README indicates optional calls to product and LLM services such as OpenFoodFacts and Groq for product lookup and chat responses; the codebase structure also implies a fallback path when those services are unavailable.

12. Deployment and packaging are container-first. The backend has a Dockerfile, the ML service has its own Dockerfile, the root `docker-compose.yml` suggests local multi-service orchestration, `frontend-next/vercel.json` points to Vercel deployment for the Next.js client, and `.github/workflows/verify-build.yml` provides CI validation.

Main entry points: [`backend/biodose`](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/biodose) (Biodose), [`backend/apps/analysis`](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/analysis) (Analysis), [`ml`](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/ml) (ML pipeline), [`frontend-next/src/app`](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/frontend-next/src/app) (Next.js app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_project["Biodose<br/>Django project"]
  node_backend_users["Users<br/>domain app"]
  node_backend_products["Products<br/>domain app"]
  node_backend_analysis["Analysis<br/>decision app"]
  node_backend_domain_models[("Domain models<br/>shared domain")]
  node_backend_utils["Registry utils<br/>shared utilities"]
  node_backend_data[("Knowledge base<br/>csv/json assets")]
  node_backend_ebm_model[("EBM model<br/>serialized model<br/>[ebm_model.pkl]")]
  node_backend_ml_pkg["Backend ML<br/>training pipeline"]
end

subgraph group_frontend["Frontend"]
  node_frontend_next_app["Next.js app<br/>web client"]
  node_frontend_next_api["API client<br/>frontend lib<br/>[api.ts]"]
  node_frontend_legacy["Legacy UI<br/>secondary client"]
end

subgraph group_ml["ML / Registry"]
  node_ml_pipeline["ML pipeline<br/>offline training"]
  node_ml_registry["Model registry<br/>[model_registry.py]"]
  node_ml_inference["Inference<br/>runtime<br/>[inference.py]"]
  node_ml_shadow["Shadow trainer<br/>evaluation<br/>[shadow_trainer.py]"]
end

subgraph group_ops["Ops"]
  node_ops_compose{{"Compose<br/>deployment<br/>[docker-compose.yml]"}}
  node_ops_ci{{"CI check<br/>workflow<br/>[verify-build.yml]"}}
end

node_backend_project -->|"routes to"| node_backend_users
node_backend_project -->|"routes to"| node_backend_products
node_backend_project -->|"routes to"| node_backend_analysis
node_backend_users -->|"persists via"| node_backend_domain_models
node_backend_products -->|"normalizes with"| node_backend_utils
node_backend_products -->|"creates product data"| node_backend_domain_models
node_backend_analysis -->|"reads state"| node_backend_domain_models
node_backend_analysis -->|"scores with"| node_backend_utils
node_backend_analysis -->|"loads model"| node_backend_ebm_model
node_backend_analysis -->|"consults"| node_backend_data
node_backend_ml_pkg -->|"builds from"| node_backend_data
node_backend_ml_pkg -->|"produces"| node_backend_ebm_model
node_frontend_next_app -->|"calls"| node_frontend_next_api
node_frontend_next_api -->|"requests"| node_backend_project
node_frontend_next_app -->|"drives scan/chat"| node_backend_analysis
node_frontend_legacy -.->|"legacy integration"| node_backend_project
node_ml_pipeline -->|"publishes"| node_ml_registry
node_ml_pipeline -->|"feeds"| node_ml_inference
node_ml_pipeline -->|"compares"| node_ml_shadow
node_ops_compose -->|"orchestrates"| node_backend_project
node_ops_compose -->|"orchestrates"| node_ml_pipeline
node_ops_compose -->|"orchestrates"| node_frontend_next_app
node_ops_ci -->|"validates"| node_backend_project
node_ops_ci -->|"validates"| node_frontend_next_app
node_ops_ci -->|"validates"| node_ml_pipeline

click node_backend_project "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/biodose"
click node_backend_users "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/users"
click node_backend_products "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/products"
click node_backend_analysis "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/analysis"
click node_backend_domain_models "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/models"
click node_backend_utils "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/utils"
click node_backend_data "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/data"
click node_backend_ebm_model "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/backend/models/ebm_model.pkl"
click node_backend_ml_pkg "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/ml"
click node_frontend_next_app "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/frontend-next/src/app"
click node_frontend_next_api "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/frontend-next/src/lib/api.ts"
click node_frontend_legacy "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/frontend/src"
click node_ml_pipeline "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/ml"
click node_ml_registry "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/ml/model_registry.py"
click node_ml_inference "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/ml/inference.py"
click node_ml_shadow "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/ml/shadow_trainer.py"
click node_ops_compose "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/docker-compose.yml"
click node_ops_ci "https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/.github/workflows/verify-build.yml"

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_backend_project,node_backend_users,node_backend_products,node_backend_analysis,node_backend_domain_models,node_backend_utils,node_backend_data,node_backend_ebm_model,node_backend_ml_pkg toneBlue
class node_frontend_next_app,node_frontend_next_api,node_frontend_legacy toneAmber
class node_ml_pipeline,node_ml_registry,node_ml_inference,node_ml_shadow toneMint
class node_ops_compose,node_ops_ci toneRose
```

## Components

### Backend

Django service for auth, product ingestion, and analysis.

- [Biodose](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/biodose): Django project · Core backend settings and routing entrypoint. · `backend/biodose`
- [Users](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/users): domain app · Profiles, locked conditions, and OTP/auth flows. · `backend/apps/users`
- [Products](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/products): domain app · Barcode and ingredient ingestion pipeline. · `backend/apps/products`
- [Analysis](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/apps/analysis): decision app · Matcher, scorer, and report generation for scans and chat. · `backend/apps/analysis`
- [Domain models](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/models): shared domain · Canonical product, user, and analysis model layer. · `backend/models`
- [Registry utils](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/utils): shared utilities · Normalization, condition registry, loading, and cleaning helpers. · `backend/utils`
- [Knowledge base](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/data): csv/json assets · Local additive, toxicology, interaction, and training data. · `backend/data`
- [EBM model](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/backend/models/ebm_model.pkl): serialized model · Persisted inference artifact used by the backend scorer. · `backend/models/ebm_model.pkl`
- [Backend ML](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/backend/ml): training pipeline · Feature building and label generation for backend-side model preparation. · `backend/ml`

### Frontend

Primary Next.js client plus legacy UI.

- [Next.js app](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/frontend-next/src/app): web client · Primary user interface built with App Router. · `frontend-next/src/app`
- [API client](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/frontend-next/src/lib/api.ts): frontend lib · Backend request boundary for the primary client. · `frontend-next/src/lib/api.ts`
- [Legacy UI](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/frontend/src): secondary client · Older Supabase-based frontend kept as a separate app. · `frontend/src`

### ML / Registry

Offline model training, inference, and local knowledge artifacts.

- [ML pipeline](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/tree/main/ml): offline training · Standalone training, evaluation, and registry lifecycle. · `ml`
- [Model registry](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/ml/model_registry.py): registry · Stores and promotes model versions for inference and shadow training. · `ml/model_registry.py`
- [Inference](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/ml/inference.py): runtime · Standalone prediction entrypoint used outside the Django app. · `ml/inference.py`
- [Shadow trainer](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/ml/shadow_trainer.py): evaluation · Parallel model lifecycle for comparison and monitoring. · `ml/shadow_trainer.py`

### Ops

Containerization and CI validation.

- [Compose](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/docker-compose.yml): deployment · Local multi-service orchestration boundary. · `docker-compose.yml`
- [CI check](https://github.com/sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system/blob/main/.github/workflows/verify-build.yml): workflow · Build and verification workflow. · `.github/workflows/verify-build.yml`

## Connections

- Biodose → Users: routes to · Project wires user endpoints into the Django app boundary.
- Biodose → Products: routes to · Project wires product ingestion endpoints.
- Biodose → Analysis: routes to · Project wires scan and chat analysis endpoints.
- Users → Domain models: persists via · Profile and auth state are stored through shared models.
- Products → Registry utils: normalizes with · Barcode and ingredient extraction depend on shared cleaners and registries.
- Products → Domain models: creates product data · Ingestion produces canonical product records and candidates.
- Analysis → Domain models: reads state · Scoring uses persisted user, product, and analysis state.
- Analysis → Registry utils: scores with · Matcher and scorer rely on normalization and condition mapping.
- Analysis → EBM model: loads model · Analysis can invoke the persisted EBM artifact for prediction.
- Analysis → Knowledge base: consults · Uses local toxicology and interaction datasets as knowledge base.
- Backend ML → Knowledge base: builds from · Training features and labels are derived from local datasets.
- Backend ML → EBM model: produces · Backend-side training can refresh the serialized model artifact.
- Next.js app → API client: calls · UI pages use the API client to reach backend services.
- API client → Biodose: requests · Primary client talks to the Django backend boundary.
- Next.js app → Analysis: drives scan/chat · User flows surface personalized analysis results.
- Legacy UI → Biodose: legacy integration · Older client likely connects to the same backend services.
- ML pipeline → Model registry: publishes · Training outputs are managed through the registry.
- ML pipeline → Inference: feeds · Offline training supports the inference runtime.
- ML pipeline → Shadow trainer: compares · Shadow trainer evaluates candidate models alongside production.
- Compose → Biodose: orchestrates · Compose starts the backend service locally.
- Compose → ML pipeline: orchestrates · Compose includes the ML service boundary.
- Compose → Next.js app: orchestrates · Compose supports the primary client in local environments.
- CI check → Biodose: validates · Workflow checks backend build health.
- CI check → Next.js app: validates · Workflow checks frontend build health.
- CI check → ML pipeline: validates · Workflow checks ML-related build paths.