# sruthikishore/carbon-footprint architecture

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

- Interactive diagram: https://gitdiagram.com/sruthikishore/carbon-footprint
- Repository: https://github.com/sruthikishore/carbon-footprint

## Overview

1. **Overall shape**
   - This is a two-tier full-stack app: a **React/Vite frontend** talks to a **FastAPI backend**.
   - The backend persists user/activity data in **MySQL via SQLAlchemy**, and also calls into a small **ML/AI layer** for predictions and suggestions.

2. **Frontend boundary**
   - The frontend lives under `frontend/src` and is organized by **pages**, **shared components**, **context**, and a single **API service** layer.
   - `src/services/api.js` is the main network boundary; the UI should not talk to the backend directly anywhere else.

3. **Client-side routing and session control**
   - `App.jsx`, `main.jsx`, `ProtectedRoute.jsx`, and `AuthContext.jsx` define the app shell, route protection, and auth state management.
   - This indicates a clear separation between public pages like **Landing/Login/Signup** and authenticated pages like **Dashboard, Activity History, Prediction, Suggestions, Goals**.

4. **Primary user workflows**
   - The UI appears centered around four flows: **login/signup**, **activity entry**, **dashboard visualization**, and **AI-driven recommendations/predictions**.
   - Activity data is entered through `ActivityInput.jsx`, reviewed in `ActivityHistory.jsx`, summarized in `Dashboard.jsx`, and fed into `Prediction.jsx` and `Suggestions.jsx`.

5. **Backend entrypoint and API composition**
   - `backend/app/main.py` is the FastAPI bootstrap point and likely wires together routers from `backend/app/routes/*`.
   - The backend is split into route modules by feature, which is a strong signal that each subsystem is exposed as its own API boundary rather than one monolith handler.

6. **Backend feature modules**
   - `auth_routes.py` handles authentication endpoints.
   - `activity_routes.py` handles CRUD-like activity capture/history.
   - `dashboard_routes.py` likely aggregates user activity into chart-ready summaries.
   - `prediction_routes.py` and `suggestions_routes.py` expose ML/AI-backed endpoints.
   - `goals_routes.py` exists as a separate feature boundary, even if it is not emphasized in the README.

7. **Domain, persistence, and validation layer**
   - `models.py`, `schemas.py`, and `database.py` define the backend’s data model, request/response contracts, and database session setup.
   - `auth.py` is the security boundary, likely handling password/JWT logic.
   - `utils.py` likely contains shared calculation or formatting helpers used by multiple routes.

8. **Data flow for activity tracking**
   - User input originates in the frontend, goes through the API service, hits the activity endpoints, and is stored in MySQL.
   - Dashboard and history screens then read the stored activity records back through the backend, meaning the database is the source of truth for user behavior over time.

9. **Prediction and suggestion pipeline**
   - The `backend/ml` directory is a separate analytical subsystem from the core API.
   - `predict.py`, `features.py`, `suggestion.py`, and the serialized model files (`carbon_model.pkl`, `model_columns.pkl`) suggest a local inference path for carbon estimation plus an LLM-backed recommendation path.
   - The README notes a **fallback calculation** when the model’s expected features do not match the UI inputs, so prediction is resilient even when ML inference fails.

10. **External AI dependency**
   - Suggestions use the **Groq API with Llama 3.1**, which makes the suggestion flow depend on an external LLM service.
   - This is a separate integration boundary from the local ML model: one is local inference with pickle/joblib artifacts, the other is a remote API call.

11. **Visualization boundary**
   - The frontend mentions **Recharts**, so chart rendering happens client-side after the backend returns aggregated emission data.
   - That means the backend likely provides structured metrics rather than pre-rendered visuals, keeping presentation logic in the browser.

12. **Architectural separation to show in a diagram**
   - A useful diagram would show: **React UI → FastAPI routes → auth/database/ML services → MySQL / local model / Groq API**.
   - The key boundaries are: **presentation**, **API/auth**, **persistence**, **local ML inference**, and **external LLM service**.

Main entry points: [`frontend/src/App.jsx`](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/App.jsx) (Routes), [`backend/app/main.py`](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/services/api.js`](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/services/api.js) (API client), [`backend/ml/predict.py`](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/predict.py) (Predict engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_main["App shell<br/>react bootstrap<br/>[main.jsx]"]
  node_frontend_app["Routes<br/>react router<br/>[App.jsx]"]
  node_frontend_auth["Auth state<br/>context<br/>[AuthContext.jsx]"]
  node_frontend_guard["Route guard<br/>protected route<br/>[ProtectedRoute.jsx]"]
  node_frontend_api["API client<br/>http service<br/>[api.js]"]
  node_frontend_dashboard["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_frontend_activity["Activity input<br/>page<br/>[ActivityInput.jsx]"]
  node_frontend_history["Activity history<br/>page"]
  node_frontend_prediction["Prediction<br/>page<br/>[Prediction.jsx]"]
  node_frontend_suggestions["Suggestions<br/>page<br/>[Suggestions.jsx]"]
  node_frontend_goals["Goals<br/>page<br/>[Goals.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_main["FastAPI app<br/>api bootstrap<br/>[main.py]"]
  node_backend_auth_routes["Auth API<br/>route module<br/>[auth_routes.py]"]
  node_backend_activity_routes["Activity API<br/>route module<br/>[activity_routes.py]"]
  node_backend_dashboard_routes["Dashboard API<br/>route module"]
  node_backend_prediction_routes["Prediction API<br/>route module"]
  node_backend_suggestions_routes["Suggestions API<br/>route module"]
  node_backend_goals_routes["Goals API<br/>route module<br/>[goals_routes.py]"]
  node_backend_models[("Data model<br/>orm models<br/>[models.py]")]
  node_backend_schemas["Contracts<br/>pydantic schemas<br/>[schemas.py]"]
  node_backend_database[("DB session<br/>sqlalchemy setup<br/>[database.py]")]
  node_backend_auth["Security<br/>auth helpers<br/>[auth.py]"]
  node_backend_utils["Helpers<br/>shared utils<br/>[utils.py]"]
end

subgraph group_ml["ML/AI"]
  node_ml_predict["Predict engine<br/>inference<br/>[predict.py]"]
  node_ml_features["Feature prep<br/>feature engineering<br/>[features.py]"]
  node_ml_suggestion["Suggestion engine<br/>llm integration<br/>[suggestion.py]"]
  node_ml_model["Model artifact<br/>serialized model<br/>[carbon_model.pkl]"]
  node_ml_columns["Model columns<br/>serialized metadata<br/>[model_columns.pkl]"]
end

node_frontend_main -->|"bootstraps"| node_frontend_app
node_frontend_app -->|"uses"| node_frontend_auth
node_frontend_app -->|"protects"| node_frontend_guard
node_frontend_app -->|"routes"| node_frontend_dashboard
node_frontend_app -->|"routes"| node_frontend_activity
node_frontend_app -->|"routes"| node_frontend_history
node_frontend_app -->|"routes"| node_frontend_prediction
node_frontend_app -->|"routes"| node_frontend_suggestions
node_frontend_app -->|"routes"| node_frontend_goals
node_frontend_dashboard -->|"fetches"| node_frontend_api
node_frontend_activity -->|"submits"| node_frontend_api
node_frontend_history -->|"loads"| node_frontend_api
node_frontend_prediction -->|"requests"| node_frontend_api
node_frontend_suggestions -->|"requests"| node_frontend_api
node_frontend_goals -->|"syncs"| node_frontend_api
node_frontend_api -->|"HTTP"| node_backend_main
node_backend_main -->|"mounts"| node_backend_auth_routes
node_backend_main -->|"mounts"| node_backend_activity_routes
node_backend_main -->|"mounts"| node_backend_dashboard_routes
node_backend_main -->|"mounts"| node_backend_prediction_routes
node_backend_main -->|"mounts"| node_backend_suggestions_routes
node_backend_main -->|"mounts"| node_backend_goals_routes
node_backend_auth_routes -->|"uses"| node_backend_auth
node_backend_auth_routes -->|"persists"| node_backend_models
node_backend_activity_routes -->|"persists"| node_backend_models
node_backend_activity_routes -->|"validates"| node_backend_schemas
node_backend_dashboard_routes -->|"queries"| node_backend_database
node_backend_dashboard_routes -->|"summarizes"| node_backend_utils
node_backend_prediction_routes -->|"calls"| node_ml_predict
node_backend_prediction_routes -->|"validates"| node_backend_schemas
node_backend_schemas -->|"maps"| node_backend_models
node_backend_models -->|"uses"| node_backend_database
node_backend_suggestions_routes -->|"calls"| node_ml_suggestion
node_ml_predict -->|"prepares"| node_ml_features
node_ml_predict -->|"loads"| node_ml_model
node_ml_predict -->|"checks"| node_ml_columns
node_ml_suggestion -->|"uses"| node_ml_features

click node_frontend_main "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/main.jsx"
click node_frontend_app "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/App.jsx"
click node_frontend_auth "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_guard "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_frontend_api "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/services/api.js"
click node_frontend_dashboard "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Dashboard.jsx"
click node_frontend_activity "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/ActivityInput.jsx"
click node_frontend_history "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/ActivityHistory.jsx"
click node_frontend_prediction "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Prediction.jsx"
click node_frontend_suggestions "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Suggestions.jsx"
click node_frontend_goals "https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Goals.jsx"
click node_backend_main "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/main.py"
click node_backend_auth_routes "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/auth_routes.py"
click node_backend_activity_routes "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/activity_routes.py"
click node_backend_dashboard_routes "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/dashboard_routes.py"
click node_backend_prediction_routes "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/prediction_routes.py"
click node_backend_suggestions_routes "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/suggestions_routes.py"
click node_backend_goals_routes "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/goals_routes.py"
click node_backend_models "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/models.py"
click node_backend_schemas "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/schemas.py"
click node_backend_database "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/database.py"
click node_backend_auth "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/auth.py"
click node_backend_utils "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/utils.py"
click node_ml_predict "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/predict.py"
click node_ml_features "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/features.py"
click node_ml_suggestion "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/suggestion.py"
click node_ml_model "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/carbon_model.pkl"
click node_ml_columns "https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/model_columns.pkl"

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_main,node_frontend_app,node_frontend_auth,node_frontend_guard,node_frontend_api,node_frontend_dashboard,node_frontend_activity,node_frontend_history,node_frontend_prediction,node_frontend_suggestions,node_frontend_goals toneBlue
class node_backend_main,node_backend_auth_routes,node_backend_activity_routes,node_backend_dashboard_routes,node_backend_prediction_routes,node_backend_suggestions_routes,node_backend_goals_routes,node_backend_models,node_backend_schemas,node_backend_database,node_backend_auth,node_backend_utils toneAmber
class node_ml_predict,node_ml_features,node_ml_suggestion,node_ml_model,node_ml_columns toneMint
```

## Components

### Frontend

React/Vite presentation layer and client-side state

- [App shell](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/main.jsx): react bootstrap · Wires routing, layout, and top-level app composition · `frontend/src/main.jsx`
- [Routes](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/App.jsx): react router · Defines public and protected navigation across the app · `frontend/src/App.jsx`
- [Auth state](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/context/AuthContext.jsx): context · Holds session state and login/logout flow for the client · `frontend/src/context/AuthContext.jsx`
- [Route guard](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/components/ProtectedRoute.jsx): protected route · Blocks unauthenticated access to private pages · `frontend/src/components/ProtectedRoute.jsx`
- [API client](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/services/api.js): http service · Single network boundary used by the UI to talk to the backend · `frontend/src/services/api.js`
- [Dashboard](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Dashboard.jsx): page · Visual summary of emissions and tracked activity · `frontend/src/pages/Dashboard.jsx`
- [Activity input](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/ActivityInput.jsx): page · Captures user activity data for storage and analysis · `frontend/src/pages/ActivityInput.jsx`
- [Activity history](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/ActivityHistory.jsx): page · Displays stored activity records over time · `frontend/src/pages/ActivityHistory.jsx`
- [Prediction](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Prediction.jsx): page · Shows carbon estimation results from the backend ML path · `frontend/src/pages/Prediction.jsx`
- [Suggestions](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Suggestions.jsx): page · Presents AI-generated recommendations to the user · `frontend/src/pages/Suggestions.jsx`
- [Goals](https://github.com/sruthikishore/carbon-footprint/blob/main/frontend/src/pages/Goals.jsx): page · User goal tracking and progress view · `frontend/src/pages/Goals.jsx`

### Backend

FastAPI application, routes, and shared server logic

- [FastAPI app](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/main.py): api bootstrap · Application entrypoint that assembles the backend · `backend/app/main.py`
- [Auth API](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/auth_routes.py): route module · Authentication endpoints for login and signup · `backend/app/routes/auth_routes.py`
- [Activity API](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/activity_routes.py): route module · CRUD-style activity capture and history endpoints · `backend/app/routes/activity_routes.py`
- [Dashboard API](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/dashboard_routes.py): route module · Aggregates stored activity into summary metrics · `backend/app/routes/dashboard_routes.py`
- [Prediction API](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/prediction_routes.py): route module · Exposes carbon prediction endpoints backed by local ML · `backend/app/routes/prediction_routes.py`
- [Suggestions API](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/suggestions_routes.py): route module · Serves recommendation endpoints using local and external AI · `backend/app/routes/suggestions_routes.py`
- [Goals API](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/routes/goals_routes.py): route module · Endpoints for storing and retrieving goals · `backend/app/routes/goals_routes.py`
- [Data model](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/models.py): orm models · Database entities for users, activities, and related records · `backend/app/models.py`
- [Contracts](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/schemas.py): pydantic schemas · Request and response validation for API payloads · `backend/app/schemas.py`
- [DB session](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/database.py): sqlalchemy setup · Database connection and session management · `backend/app/database.py`
- [Security](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/auth.py): auth helpers · Password and token logic used by auth endpoints · `backend/app/auth.py`
- [Helpers](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/app/utils.py): shared utils · Common calculations and formatting used across routes · `backend/app/utils.py`

### ML/AI

Local inference artifacts and suggestion generation

- [Predict engine](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/predict.py): inference · Local carbon estimation logic and fallback calculation path · `backend/ml/predict.py`
- [Feature prep](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/features.py): feature engineering · Builds model inputs from activity data · `backend/ml/features.py`
- [Suggestion engine](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/suggestion.py): llm integration · Generates recommendations, including Groq-backed prompts · `backend/ml/suggestion.py`
- [Model artifact](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/carbon_model.pkl): serialized model · Trained carbon prediction model used for local inference · `backend/ml/carbon_model.pkl`
- [Model columns](https://github.com/sruthikishore/carbon-footprint/blob/main/backend/ml/model_columns.pkl): serialized metadata · Expected feature column ordering for the predictor · `backend/ml/model_columns.pkl`

## Connections

- App shell → Routes: bootstraps · App entry renders the route structure
- Routes → Auth state: uses · Routes depend on client auth state
- Routes → Route guard: protects · Private pages are wrapped by the guard
- Routes → Dashboard: routes · Authenticated dashboard page
- Routes → Activity input: routes · Activity entry page
- Routes → Activity history: routes · Activity history page
- Routes → Prediction: routes · Prediction page
- Routes → Suggestions: routes · Suggestions page
- Routes → Goals: routes · Goals page
- Dashboard → API client: fetches · Requests summaries from the backend
- Activity input → API client: submits · Sends user activity to the API layer
- Activity history → API client: loads · Reads stored activity records from the API
- Prediction → API client: requests · Calls prediction endpoints
- Suggestions → API client: requests · Calls suggestion endpoints
- Goals → API client: syncs · Reads and updates goal data through the API
- API client → FastAPI app: HTTP · Frontend network traffic enters the FastAPI app
- FastAPI app → Auth API: mounts · Registers auth endpoints
- FastAPI app → Activity API: mounts · Registers activity endpoints
- FastAPI app → Dashboard API: mounts · Registers dashboard endpoints
- FastAPI app → Prediction API: mounts · Registers prediction endpoints
- FastAPI app → Suggestions API: mounts · Registers suggestion endpoints
- FastAPI app → Goals API: mounts · Registers goals endpoints
- Auth API → Security: uses · Authentication endpoints depend on security helpers
- Auth API → Data model: persists · Auth data maps to stored user records
- Activity API → Data model: persists · Activity endpoints read and write database entities
- Activity API → Contracts: validates · Input and output payloads are typed by schemas
- Dashboard API → DB session: queries · Aggregations are built from persisted activity data
- Dashboard API → Helpers: summarizes · Shared calculations help assemble dashboard metrics
- Prediction API → Predict engine: calls · Prediction API delegates to local inference
- Prediction API → Contracts: validates · Prediction request and response contracts
- Contracts → Data model: maps · Schemas mirror persistence entities
- Data model → DB session: uses · ORM models rely on the database session
- Suggestions API → Suggestion engine: calls · Suggestion API delegates to the recommendation engine
- Predict engine → Feature prep: prepares · Prediction logic derives model inputs from activity data
- Predict engine → Model artifact: loads · Uses the serialized carbon model when available
- Predict engine → Model columns: checks · Validates expected input columns for fallback handling
- Suggestion engine → Feature prep: uses · Recommendations may reuse feature extraction
