How sruthikishore/carbon-footprint works
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: App.jsx Routes · main.py FastAPI app · api.js API client · predict.py Predict engine
Components 28
Frontend
React/Vite presentation layer and client-side state
- App shell · Wires routing, layout, and top-level app composition
frontend/src/main.jsx - Routes · Defines public and protected navigation across the app
frontend/src/App.jsx - Auth state · Holds session state and login/logout flow for the client
frontend/src/context/AuthContext.jsx - Route guard · Blocks unauthenticated access to private pages
frontend/src/components/ProtectedRoute.jsx - API client · Single network boundary used by the UI to talk to the backend
frontend/src/services/api.js - Dashboard · Visual summary of emissions and tracked activity
frontend/src/pages/Dashboard.jsx - Activity input · Captures user activity data for storage and analysis
frontend/src/pages/ActivityInput.jsx - Activity history · Displays stored activity records over time
frontend/src/pages/ActivityHistory.jsx - Prediction · Shows carbon estimation results from the backend ML path
frontend/src/pages/Prediction.jsx - Suggestions · Presents AI-generated recommendations to the user
frontend/src/pages/Suggestions.jsx - Goals · User goal tracking and progress view
frontend/src/pages/Goals.jsx
Backend
FastAPI application, routes, and shared server logic
- FastAPI app · Application entrypoint that assembles the backend
backend/app/main.py - Auth API · Authentication endpoints for login and signup
backend/app/routes/auth_routes.py - Activity API · CRUD-style activity capture and history endpoints
backend/app/routes/activity_routes.py - Dashboard API · Aggregates stored activity into summary metrics
backend/app/routes/dashboard_routes.py - Prediction API · Exposes carbon prediction endpoints backed by local ML
backend/app/routes/prediction_routes.py - Suggestions API · Serves recommendation endpoints using local and external AI
backend/app/routes/suggestions_routes.py - Goals API · Endpoints for storing and retrieving goals
backend/app/routes/goals_routes.py - Data model · Database entities for users, activities, and related records
backend/app/models.py - Contracts · Request and response validation for API payloads
backend/app/schemas.py - DB session · Database connection and session management
backend/app/database.py - Security · Password and token logic used by auth endpoints
backend/app/auth.py - Helpers · Common calculations and formatting used across routes
backend/app/utils.py
ML/AI
Local inference artifacts and suggestion generation
- Predict engine · Local carbon estimation logic and fallback calculation path
backend/ml/predict.py - Feature prep · Builds model inputs from activity data
backend/ml/features.py - Suggestion engine · Generates recommendations, including Groq-backed prompts
backend/ml/suggestion.py - Model artifact · Trained carbon prediction model used for local inference
backend/ml/carbon_model.pkl - Model columns · Expected feature column ordering for the predictor
backend/ml/model_columns.pkl
Connections 37
- 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