How sirikumar9106/biodose---intelligent-food-quality-consumer-safety-intelligence-system works
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: biodose Biodose · analysis Analysis · ml ML pipeline · app Next.js app
Components 18
Backend
Django service for auth, product ingestion, and analysis.
- Biodose · Core backend settings and routing entrypoint.
backend/biodose - Users · Profiles, locked conditions, and OTP/auth flows.
backend/apps/users - Products · Barcode and ingredient ingestion pipeline.
backend/apps/products - Analysis · Matcher, scorer, and report generation for scans and chat.
backend/apps/analysis - Domain models · Canonical product, user, and analysis model layer.
backend/models - Registry utils · Normalization, condition registry, loading, and cleaning helpers.
backend/utils - Knowledge base · Local additive, toxicology, interaction, and training data.
backend/data - EBM model · Persisted inference artifact used by the backend scorer.
backend/models/ebm_model.pkl - Backend ML · Feature building and label generation for backend-side model preparation.
backend/ml
Frontend
Primary Next.js client plus legacy UI.
- Next.js app · Primary user interface built with App Router.
frontend-next/src/app - API client · Backend request boundary for the primary client.
frontend-next/src/lib/api.ts - Legacy UI · Older Supabase-based frontend kept as a separate app.
frontend/src
ML / Registry
Offline model training, inference, and local knowledge artifacts.
- ML pipeline · Standalone training, evaluation, and registry lifecycle.
ml - Model registry · Stores and promotes model versions for inference and shadow training.
ml/model_registry.py - Inference · Standalone prediction entrypoint used outside the Django app.
ml/inference.py - Shadow trainer · Parallel model lifecycle for comparison and monitoring.
ml/shadow_trainer.py
Connections 25
- 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.