# nitin020305/nutritrack architecture

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

- Interactive diagram: https://gitdiagram.com/nitin020305/nutritrack
- Repository: https://github.com/nitin020305/nutritrack

## Overview

1. **Overall shape**
   - NutriTrack is a Flask-backed full-stack app with a browser UI on the frontend and a REST API on the backend.
   - The backend owns all business logic, authentication, persistence, and third-party integrations; the frontend is a thin client that renders one HTML page and calls API endpoints.

2. **Request flow**
   - A user interacts with `frontend/templates/index.html` plus static CSS/JS.
   - The JS client talks to `/api/...` endpoints exposed by Flask blueprints.
   - Responses drive dashboard views for profile, food logging, analytics, and admin operations.

3. **Backend entry and configuration**
   - `backend/run.py` is the application entry point.
   - `backend/config.py` centralizes environment-driven settings, including secrets and service credentials, with values expected from `infra/.env`.
   - The backend uses a local SQLite database at `backend/instance/nutritrack.db` for persistence.

4. **API boundary and route grouping**
   - The backend is organized around blueprints in `backend/app/routes/`:
     - `auth.py` for registration, login, verification, password reset, token refresh, and account lifecycle.
     - `user.py` for profile management and prediction.
     - `food.py` for food search, logging, and log deletion.
     - `analytics.py` for daily, weekly, and monthly summaries.
     - `admin.py` for bootstrap, user management, stats, and log access.
   - This routing layer is the main architectural boundary between HTTP and domain logic.

5. **Authentication and access control**
   - Authentication is JWT-based.
   - Email verification is a separate gate for actions that require a verified account, especially food logging and analytics.
   - Admin routes are role-protected; the README shows a bootstrap path for establishing the first admin user.
   - Shared auth checks and token helpers live in `backend/app/utils/auth_helpers.py`.

6. **Core domain model**
   - The primary persisted entities are in `backend/app/models/`:
     - `user.py` for account/profile/admin state.
     - `food_log.py` for logged meals/items and dates.
     - `nutrient.py` for nutrient-related caching or lookup data.
   - The database schema in `database/schema.sql` serves as the structural reference, while `database/seed.py` creates initial users for setup.

7. **Food and nutrition pipeline**
   - Food lookup and logging are not just CRUD; they pass through service logic in `backend/app/services/food_parser.py` and `usda_api.py`.
   - The app integrates with an external USDA nutrition API for nutrient search and enrichment.
   - `backend/app/utils/unit_converter.py` suggests inputs are normalized before storage or calculation, so food entries likely move through parsing, unit conversion, then persistence.

8. **Analytics and chart generation**
   - Analytics endpoints aggregate logged food data into daily, weekly, and monthly summaries.
   - `backend/app/utils/chart_generator.py` indicates the backend produces chart-ready output or server-generated visualizations for the dashboard.
   - This is a distinct reporting layer built on top of stored food logs rather than a separate analytics service.

9. **Prediction and personalized user features**
   - `backend/app/services/prediction.py` provides a weight prediction or similar user-specific inference function exposed through the user API.
   - This sits beside profile management, implying the app combines static account data with computed health insights.

10. **Notifications and email workflows**
   - `backend/app/services/mail_service.py` handles transactional email flows such as verification, resend-verification, password reset, and likely account-related notifications.
   - The README specifies Gmail app-password setup, so email delivery is an external SMTP dependency rather than an in-app queue.

11. **Operational/admin layer**
   - Admin endpoints expose platform-level visibility: user lists, user status updates, stats, and access to all food logs.
   - This makes admin a separate operational subsystem with elevated privileges over the same underlying user and log tables.

12. **Frontend deployment model**
   - The `frontend/` directory contains a single-page-style browser app implemented with vanilla HTML/CSS/JS, not a separate frontend framework.
   - It likely consumes the Flask API directly and handles session/auth token usage on the client side.

13. **Infrastructure and packaging**
   - `infra/docker-compose.yml` and `infra/Dockerfile` indicate the project can be containerized for local or deployment environments.
   - `backend/requirements.txt` and the README’s matplotlib note suggest the backend has both standard web dependencies and chart/visualization support.
   - The architecture is therefore a monolith with clear internal layers, externalized config, and optional containerized runtime.

14. **Key architectural boundaries to draw**
   - Client/browser boundary: static frontend versus API backend.
   - HTTP/API boundary: blueprints separating auth, user, food, analytics, admin.
   - Service boundary: business logic and external integrations isolated from routes.
   - Persistence boundary: SQLAlchemy models and SQLite database.
   - External dependency boundary: USDA API, SMTP email, and environment-managed secrets.

Main entry points: [`backend/run.py`](https://github.com/nitin020305/nutritrack/blob/main/backend/run.py) (App Entry), [`frontend/static/js/main.js`](https://github.com/nitin020305/nutritrack/blob/main/frontend/static/js/main.js) (Client JS), [`backend/app/routes/food.py`](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/food.py) (Food API), [`backend/app/routes/admin.py`](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/admin.py) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_index["Browser UI<br/>static SPA<br/>[index.html]"]
  node_frontend_js["Client JS<br/>ui controller<br/>[main.js]"]
  node_frontend_css["Styles<br/>ui styling<br/>[main.css]"]
end

subgraph group_backend_api["API Layer"]
  node_backend_run["App Entry<br/>Flask startup<br/>[run.py]"]
  node_backend_config["Config<br/>env settings<br/>[config.py]"]
  node_route_auth["Auth API<br/>blueprint<br/>[auth.py]"]
  node_route_user["User API<br/>blueprint<br/>[user.py]"]
  node_route_food["Food API<br/>blueprint<br/>[food.py]"]
  node_route_analytics["Analytics API<br/>blueprint<br/>[analytics.py]"]
  node_route_admin["Admin API<br/>blueprint<br/>[admin.py]"]
end

subgraph group_backend_core["Backend Core"]
  node_auth_helpers["Auth Helpers<br/>jwt utilities<br/>[auth_helpers.py]"]
  node_food_service["Food Parser<br/>[food_parser.py]"]
  node_usda_api["USDA API<br/>external integration<br/>[usda_api.py]"]
  node_mail_service["Mail Service<br/>smtp service<br/>[mail_service.py]"]
  node_prediction_service["Prediction<br/>inference service<br/>[prediction.py]"]
  node_chart_utils["Chart Generator<br/>reporting utils<br/>[chart_generator.py]"]
  node_unit_converter["Unit Converter<br/>normalization utils<br/>[unit_converter.py]"]
end

subgraph group_data["Data"]
  node_model_user[("User<br/>persisted model<br/>[user.py]")]
  node_model_food_log[("Food Log<br/>persisted model<br/>[food_log.py]")]
  node_model_nutrient[("Nutrient<br/>lookup model<br/>[nutrient.py]")]
  node_schema_seed["Schema/Seed<br/>db setup<br/>[schema.sql]"]
  node_sqlite_db[("SQLite DB<br/>local database<br/>[nutritrack.db]")]
end

subgraph group_ops["Ops"]
  node_docker_stack["Docker Stack<br/>containerization<br/>[docker-compose.yml]"]
end

node_frontend_index -->|"loads"| node_frontend_js
node_frontend_index -->|"styles"| node_frontend_css
node_frontend_js -->|"calls"| node_route_auth
node_frontend_js -->|"calls"| node_route_user
node_frontend_js -->|"calls"| node_route_food
node_frontend_js -->|"calls"| node_route_analytics
node_frontend_js -->|"calls"| node_route_admin
node_backend_run -->|"reads"| node_backend_config
node_backend_run -->|"registers"| node_route_auth
node_backend_run -->|"registers"| node_route_user
node_backend_run -->|"registers"| node_route_food
node_backend_run -->|"registers"| node_route_analytics
node_backend_run -->|"registers"| node_route_admin
node_route_auth -->|"uses"| node_auth_helpers
node_route_auth -->|"sends"| node_mail_service
node_route_user -->|"uses"| node_prediction_service
node_route_food -->|"uses"| node_food_service
node_route_food -->|"normalizes"| node_unit_converter
node_food_service -->|"queries"| node_usda_api
node_route_analytics -->|"builds"| node_chart_utils
node_route_admin -->|"protects"| node_auth_helpers
node_route_admin -->|"manages"| node_model_user
node_route_admin -->|"reads"| node_model_food_log
node_route_user -->|"reads/writes"| node_model_user
node_route_food -->|"writes"| node_model_food_log
node_route_food -->|"looks up"| node_model_nutrient
node_route_analytics -->|"aggregates"| node_model_food_log
node_model_user -->|"persists"| node_sqlite_db
node_model_food_log -->|"persists"| node_sqlite_db
node_model_nutrient -->|"persists"| node_sqlite_db
node_schema_seed -->|"initializes"| node_sqlite_db
node_docker_stack -->|"runs"| node_backend_run
node_docker_stack -->|"serves"| node_frontend_index

click node_frontend_index "https://github.com/nitin020305/nutritrack/blob/main/frontend/templates/index.html"
click node_frontend_js "https://github.com/nitin020305/nutritrack/blob/main/frontend/static/js/main.js"
click node_frontend_css "https://github.com/nitin020305/nutritrack/blob/main/frontend/static/css/main.css"
click node_backend_run "https://github.com/nitin020305/nutritrack/blob/main/backend/run.py"
click node_backend_config "https://github.com/nitin020305/nutritrack/blob/main/backend/config.py"
click node_route_auth "https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/auth.py"
click node_route_user "https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/user.py"
click node_route_food "https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/food.py"
click node_route_analytics "https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/analytics.py"
click node_route_admin "https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/admin.py"
click node_auth_helpers "https://github.com/nitin020305/nutritrack/blob/main/backend/app/utils/auth_helpers.py"
click node_food_service "https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/food_parser.py"
click node_usda_api "https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/usda_api.py"
click node_mail_service "https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/mail_service.py"
click node_prediction_service "https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/prediction.py"
click node_chart_utils "https://github.com/nitin020305/nutritrack/blob/main/backend/app/utils/chart_generator.py"
click node_unit_converter "https://github.com/nitin020305/nutritrack/blob/main/backend/app/utils/unit_converter.py"
click node_model_user "https://github.com/nitin020305/nutritrack/blob/main/backend/app/models/user.py"
click node_model_food_log "https://github.com/nitin020305/nutritrack/blob/main/backend/app/models/food_log.py"
click node_model_nutrient "https://github.com/nitin020305/nutritrack/blob/main/backend/app/models/nutrient.py"
click node_schema_seed "https://github.com/nitin020305/nutritrack/blob/main/database/schema.sql"
click node_sqlite_db "https://github.com/nitin020305/nutritrack/blob/main/backend/instance/nutritrack.db"
click node_docker_stack "https://github.com/nitin020305/nutritrack/blob/main/infra/docker-compose.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_frontend_index,node_frontend_js,node_frontend_css toneBlue
class node_backend_run,node_backend_config,node_route_auth,node_route_user,node_route_food,node_route_analytics,node_route_admin toneAmber
class node_auth_helpers,node_food_service,node_usda_api,node_mail_service,node_prediction_service,node_chart_utils,node_unit_converter toneMint
class node_model_user,node_model_food_log,node_model_nutrient,node_schema_seed,node_sqlite_db toneRose
class node_docker_stack toneIndigo
```

## Components

### Frontend

Single-page browser client and assets

- [Browser UI](https://github.com/nitin020305/nutritrack/blob/main/frontend/templates/index.html): static SPA · Single-page HTML client with CSS/JS · `frontend/templates/index.html`
- [Client JS](https://github.com/nitin020305/nutritrack/blob/main/frontend/static/js/main.js): ui controller · Calls API endpoints and updates dashboard views · `frontend/static/js/main.js`
- [Styles](https://github.com/nitin020305/nutritrack/blob/main/frontend/static/css/main.css): ui styling · Presentation layer for the browser app · `frontend/static/css/main.css`

### API Layer

Flask entrypoint and route blueprints

- [App Entry](https://github.com/nitin020305/nutritrack/blob/main/backend/run.py): Flask startup · Application launch point · `backend/run.py`
- [Config](https://github.com/nitin020305/nutritrack/blob/main/backend/config.py): env settings · Central environment-driven settings and secrets · `backend/config.py`
- [Auth API](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/auth.py): blueprint · Registration, login, verification, reset, refresh · `backend/app/routes/auth.py`
- [User API](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/user.py): blueprint · Profile management and prediction endpoints · `backend/app/routes/user.py`
- [Food API](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/food.py): blueprint · Search, logging, and log deletion · `backend/app/routes/food.py`
- [Analytics API](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/analytics.py): blueprint · Daily, weekly, and monthly summaries · `backend/app/routes/analytics.py`
- [Admin API](https://github.com/nitin020305/nutritrack/blob/main/backend/app/routes/admin.py): blueprint · Bootstrap, user management, stats, and log access · `backend/app/routes/admin.py`

### Backend Core

Shared utilities and business services

- [Auth Helpers](https://github.com/nitin020305/nutritrack/blob/main/backend/app/utils/auth_helpers.py): jwt utilities · Shared token and access-control checks · `backend/app/utils/auth_helpers.py`
- [Food Parser](https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/food_parser.py): service · Parses and normalizes food input · `backend/app/services/food_parser.py`
- [USDA API](https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/usda_api.py): external integration · Nutrition search and enrichment source · `backend/app/services/usda_api.py`
- [Mail Service](https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/mail_service.py): smtp service · Verification and password-reset email delivery · `backend/app/services/mail_service.py`
- [Prediction](https://github.com/nitin020305/nutritrack/blob/main/backend/app/services/prediction.py): inference service · User-specific weight or health prediction · `backend/app/services/prediction.py`
- [Chart Generator](https://github.com/nitin020305/nutritrack/blob/main/backend/app/utils/chart_generator.py): reporting utils · Builds chart-ready analytics output · `backend/app/utils/chart_generator.py`
- [Unit Converter](https://github.com/nitin020305/nutritrack/blob/main/backend/app/utils/unit_converter.py): normalization utils · Normalizes food quantities before storage or calculation · `backend/app/utils/unit_converter.py`

### Data

Models and database artifacts

- [User](https://github.com/nitin020305/nutritrack/blob/main/backend/app/models/user.py): persisted model · Account, profile, verification, and admin state · `backend/app/models/user.py`
- [Food Log](https://github.com/nitin020305/nutritrack/blob/main/backend/app/models/food_log.py): persisted model · Logged meals, items, and dates · `backend/app/models/food_log.py`
- [Nutrient](https://github.com/nitin020305/nutritrack/blob/main/backend/app/models/nutrient.py): lookup model · Nutrient cache or reference data · `backend/app/models/nutrient.py`
- [Schema/Seed](https://github.com/nitin020305/nutritrack/blob/main/database/schema.sql): db setup · Database structure and initial user seeding · `database/schema.sql`
- [SQLite DB](https://github.com/nitin020305/nutritrack/blob/main/backend/instance/nutritrack.db): local database · Persistent storage for NutriTrack · `backend/instance/nutritrack.db`

### Ops

Containerization and packaging

- [Docker Stack](https://github.com/nitin020305/nutritrack/blob/main/infra/docker-compose.yml): containerization · Compose and image packaging for runtime · `infra/docker-compose.yml`

## Connections

- Browser UI → Client JS: loads · The browser page is driven by client JavaScript
- Browser UI → Styles: styles · The page uses static CSS for presentation
- Client JS → Auth API: calls · Client requests auth endpoints
- Client JS → User API: calls · Client requests profile and prediction endpoints
- Client JS → Food API: calls · Client submits food searches and logs
- Client JS → Analytics API: calls · Client fetches summary data
- Client JS → Admin API: calls · Client accesses admin operations when permitted
- App Entry → Config: reads · Startup uses environment-driven configuration
- App Entry → Auth API: registers · Flask application wires in blueprints
- App Entry → User API: registers · Flask application wires in blueprints
- App Entry → Food API: registers · Flask application wires in blueprints
- App Entry → Analytics API: registers · Flask application wires in blueprints
- App Entry → Admin API: registers · Flask application wires in blueprints
- Auth API → Auth Helpers: uses · Routes rely on shared JWT and auth checks
- Auth API → Mail Service: sends · Verification and reset emails are triggered here
- User API → Prediction: uses · Profile API exposes prediction features
- Food API → Food Parser: uses · Food API parses and normalizes entries
- Food API → Unit Converter: normalizes · Quantities are converted before persistence
- Food Parser → USDA API: queries · Food enrichment uses external USDA data
- Analytics API → Chart Generator: builds · Analytics endpoints produce chart-ready summaries
- Admin API → Auth Helpers: protects · Admin routes are role-gated
- Admin API → User: manages · Admin operations act on users
- Admin API → Food Log: reads · Admin operations inspect food logs
- User API → User: reads/writes · Profile data is stored in the user model
- Food API → Food Log: writes · Food logging persists meal records
- Food API → Nutrient: looks up · Food flows consult nutrient reference data
- Analytics API → Food Log: aggregates · Summaries are computed from food logs
- User → SQLite DB: persists · User data is stored in SQLite
- Food Log → SQLite DB: persists · Food logs are stored in SQLite
- Nutrient → SQLite DB: persists · Nutrient data is stored in SQLite
- Schema/Seed → SQLite DB: initializes · Schema and seed data define the database state
- Docker Stack → App Entry: runs · Container image starts the backend app
- Docker Stack → Browser UI: serves · Containerized deployment includes the browser assets