# hemnath-kandasamyk/calorie-tracker architecture

> Architecture diagram of the GitHub repository hemnath-kandasamyk/calorie-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hemnath-kandasamyk/calorie-tracker
- Repository: https://github.com/hemnath-kandasamyk/calorie-tracker

## Overview

This repository is an AI diet recommendation system with a FastAPI interface. Its main user flow accepts body metrics and activity level, calculates BMI/BMR/TDEE and daily macronutrient targets, then returns ranked foods; a separate endpoint can produce a meal plan. Recommendation code also supports goal-based filtering, macro matching, ranking, and an offline-trained model capability. The graph follows documented routes and capabilities plus the source index; unsampled implementation details are not treated as verified call relationships.

Main entry points: [`backend/app.py`](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/backend/app.py) (FastAPI routes), [`src/recommendation/recommendation.py`](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/recommendation.py) (Recommendation engine), [`src/recommendation/recommendation_utils.py`](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/recommendation_utils.py) (Recommendation utilities), [`datasets/processed/processed_food_dataset.csv`](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/datasets/processed/processed_food_dataset.csv) (Processed food dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api["FastAPI routes<br/>[app.py]"]
  node_config["Backend configuration<br/>[config.py]"]
end

subgraph group_health["Health calculations"]
  node_bmi["BMI calculator<br/>[bmi.py]"]
  node_bmr["BMR calculator<br/>[bmr.py]"]
  node_tdee["TDEE calculator<br/>[tdee.py]"]
  node_nutrition["Macro targets<br/>[nutrition.py]"]
end

subgraph group_recommend["Food recommendations"]
  node_engine["Recommendation engine<br/>[recommendation.py]"]
  node_filter["Goal food filters<br/>[food_filter.py]"]
  node_matching["Nutrition matching<br/>[nutrition_match.py]"]
  node_ranking["Food ranking<br/>[ranking.py]"]
  node_meal["Meal planner<br/>[meal_planner.py]"]
  node_utils["Recommendation utilities"]
  node_predictor["Density predictor<br/>[predictor.py]"]
end

subgraph group_data["Nutrition data and models"]
  node_fooddata[("Processed food dataset")]
  node_models[("Trained regression models")]
end

node_user(("User"))

node_user -->|"submits profile"| node_api
node_api -->|"calculates BMI"| node_bmi
node_api -->|"calculates BMR"| node_bmr
node_api -->|"calculates TDEE"| node_tdee
node_api -->|"gets macro targets"| node_nutrition
node_api -->|"requests recommendations"| node_engine
node_api -->|"requests meal plan"| node_meal
node_api -->|"loads food data"| node_fooddata
node_config -->|"sets dataset path"| node_fooddata
node_config -->|"sets model directory"| node_models
node_engine -->|"filters foods"| node_filter
node_engine -->|"scores macro fit"| node_matching
node_engine -->|"ranks foods"| node_ranking
node_engine -->|"uses food records"| node_fooddata
node_meal -->|"uses shared helpers"| node_utils
node_filter -->|"uses shared helpers"| node_utils
node_matching -->|"uses shared helpers"| node_utils
node_ranking -->|"uses shared helpers"| node_utils
node_predictor -->|"loads model"| node_models

click node_api "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/backend/app.py"
click node_config "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/backend/config.py"
click node_bmi "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/bmi.py"
click node_bmr "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/bmr.py"
click node_tdee "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/tdee.py"
click node_nutrition "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/nutrition.py"
click node_engine "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/recommendation.py"
click node_filter "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/food_filter.py"
click node_matching "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/nutrition_match.py"
click node_ranking "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/ranking.py"
click node_meal "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/meal_planner.py"
click node_utils "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/recommendation_utils.py"
click node_predictor "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/predictor.py"
click node_fooddata "https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/datasets/processed/processed_food_dataset.csv"
click node_models "https://github.com/hemnath-kandasamyk/calorie-tracker/tree/main/trained_models"

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_config,node_user toneBlue
class node_bmi,node_bmr,node_tdee,node_nutrition toneAmber
class node_engine,node_filter,node_matching,node_ranking,node_meal,node_utils,node_predictor toneMint
class node_fooddata,node_models toneRose
```

## Components

### API and orchestration

- [FastAPI routes](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/backend/app.py): `backend/app.py`
- [Backend configuration](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/backend/config.py): `backend/config.py`

### Health calculations

- [BMI calculator](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/bmi.py): `src/health/bmi.py`
- [BMR calculator](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/bmr.py): `src/health/bmr.py`
- [TDEE calculator](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/tdee.py): `src/health/tdee.py`
- [Macro targets](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/health/nutrition.py): `src/health/nutrition.py`

### Food recommendations

- [Recommendation engine](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/recommendation.py): `src/recommendation/recommendation.py`
- [Goal food filters](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/food_filter.py): `src/recommendation/food_filter.py`
- [Nutrition matching](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/nutrition_match.py): `src/recommendation/nutrition_match.py`
- [Food ranking](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/ranking.py): `src/recommendation/ranking.py`
- [Meal planner](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/meal_planner.py): `src/recommendation/meal_planner.py`
- [Recommendation utilities](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/recommendation_utils.py): `src/recommendation/recommendation_utils.py`
- [Density predictor](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/src/recommendation/predictor.py): `src/recommendation/predictor.py`

### Nutrition data and models

- [Processed food dataset](https://github.com/hemnath-kandasamyk/calorie-tracker/blob/main/datasets/processed/processed_food_dataset.csv): `datasets/processed/processed_food_dataset.csv`
- [Trained regression models](https://github.com/hemnath-kandasamyk/calorie-tracker/tree/main/trained_models): `trained_models`

### Other components

- **User**

## Connections

- User → FastAPI routes: submits profile (evidence: `README.md`)
- FastAPI routes → BMI calculator: calculates BMI (evidence: `README.md`)
- FastAPI routes → BMR calculator: calculates BMR (evidence: `backend/app.py`)
- FastAPI routes → TDEE calculator: calculates TDEE (evidence: `backend/app.py`)
- FastAPI routes → Macro targets: gets macro targets (evidence: `backend/app.py`)
- FastAPI routes → Recommendation engine: requests recommendations (evidence: `README.md`)
- FastAPI routes → Meal planner: requests meal plan (evidence: `backend/app.py`)
- FastAPI routes → Processed food dataset: loads food data (evidence: `backend/app.py`)
- Backend configuration → Processed food dataset: sets dataset path (evidence: `backend/config.py`)
- Backend configuration → Trained regression models: sets model directory (evidence: `backend/config.py`)
- Recommendation engine → Goal food filters: filters foods (evidence: `README.md`)
- Recommendation engine → Nutrition matching: scores macro fit (evidence: `README.md`)
- Recommendation engine → Food ranking: ranks foods (evidence: `README.md`)
- Recommendation engine → Processed food dataset: uses food records (evidence: `README.md`)
- Meal planner → Recommendation utilities: uses shared helpers (evidence: `src/recommendation/meal_planner.py`)
- Goal food filters → Recommendation utilities: uses shared helpers (evidence: `src/recommendation/food_filter.py`)
- Nutrition matching → Recommendation utilities: uses shared helpers (evidence: `src/recommendation/nutrition_match.py`)
- Food ranking → Recommendation utilities: uses shared helpers (evidence: `src/recommendation/ranking.py`)
- Density predictor → Trained regression models: loads model (evidence: `src/recommendation/predictor.py`)
