# chacha0044/cft architecture

> Architecture diagram of the GitHub repository chacha0044/cft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chacha0044/cft
- Repository: https://github.com/chacha0044/cft

## Overview

##### Project Type and Purpose
- This is a full-stack MERN application (“Carbon Footprint Tracker”) that lets users log monthly lifestyle data (food, transport, electricity, waste), calculates CO₂ emissions, generates personalized suggestions, and shows community leaderboards.
- Frontend: React + TailwindCSS + Framer Motion, hosted on Vercel.
- Backend: Node.js + Express + Mongoose, hosted on Render.
- Database: MongoDB Atlas.
- Integrations: Nodemailer (SMTP), IMAP polling for email verification, GitHub Actions for CI/CD.

##### File Structure
- Top level:
- client/ → React SPA (public assets, src/components, src/api, src/context, src/hooks, src/utils)
- middleware/ → Express authentication and error‐handling middleware
- models/ → Mongoose schemas (User, CarbonEntry)
- routes/ → REST endpoints (/api/auth, /api/footprint)
- utils/ → core business logic (emission calculator, email templates, IMAP poller, mail sender)
- server.js → Express app bootstrap
- vercel.json, .github/workflows → CI/CD and hosting configs
- Key patterns:
- REST API layer (routes → controllers → services/util functions → models)
- Middleware chain (authentication, input sanitization, rate limiting)
- React component tree (Auth, Dashboard, Footprint, History, Leaderboard)

##### Extract Architecture Details from the README
- Authentication flows: registration, verification via email, secure HTTP-only cookies, JWT/session fallback
- Emission calculation engine with validation and caps
- Data visualization: pie charts, bar charts, animated UX
- Security: Helmet, CORS, DOMPurify, bcrypt, rate-limiting
- Deployment: Vercel (client), Render (server), MongoDB Atlas (DB)

##### Main Components
a. Frontend (React SPA on Vercel)
- Auth pages (Login, Register, VerifyEmail)
- Dashboard & Charts (ChartPage.js, Dashboard.js)
- Footprint modules (EditFootprintForm, History)
- Shared utilities (API client wrapper, loading/context hooks)
b. Backend (Express Monolith on Render)
- HTTP server (server.js)
- Middleware layer (authmiddleware.js, rate limiter, Helmet, CORS)
- Route handlers (/api/auth, /api/footprint)
- Business logic (utils/calculateEmissions.js, emailTemplate.js, imapPoller.js, sendEmail.js)
- Data layer (Mongoose models: User, CarbonEntry)
c. Database (MongoDB Atlas)
- Collections: users, carbonentries
d. External Services
- SMTP provider for Nodemailer
- IMAP server for inbound email polling
- GitHub Actions for CI/CD
e. Hosting/Deployment
- Vercel (frontend)
- Render (backend)
- Environment variables (MONGO_URI, JWT_SECRET, SMTP creds)

##### Relationships and Data Flow
- User’s browser → HTTPS → React SPA → fetch() calls → Express API endpoints
- Express middleware → route handlers → utils (validation, emission calculation) → Mongoose → MongoDB Atlas
- Email flows: backend → Nodemailer → user inbox → user clicks verification link → Express GET /api/auth/verify/:token
- CI/CD: GitHub Actions triggers tests and automatic deploys to Vercel/Render

##### Architectural Patterns and Design Principles
- Layered architecture: Presentation → API → Business logic → Data access
- RESTful design for API endpoints
- Modular code organization: routes, middleware, models, utils
- Secure-by-default: HTTP‐only cookies, Helmet, input sanitization
- Single Page Application separated from API (“decoupled full-stack”)

##### Detail without Overthinking
- Break the system into as many logical components as needed to reflect the file tree and README
- Keep it modular: future features (e.g., new categories, gamification) can slot into existing layers

## Diagram (Mermaid)

```mermaid
graph TB
  %% Client Layer
  subgraph "Client (React SPA on Vercel)" 
    direction TB
    ReactSPA["React SPA"]:::client
    subgraph "Auth Pages" 
      direction TB
      Login["Login Page"]:::client
      Register["Register Page"]:::client
      VerifyEmail["Email Verification Page"]:::client
    end
    subgraph "Dashboard & Charts" 
      direction TB
      Dashboard["Dashboard"]:::client
      ChartPage["Chart Page"]:::client
    end
    subgraph "Footprint Modules"
      direction TB
      EditForm["Edit Footprint Form"]:::client
      FootprintOverview["Footprint Overview"]:::client
      HistoryView["History View"]:::client
    end
    subgraph "Shared Frontend Utilities"
      direction TB
      APIClient["API Client Wrapper"]:::client
      LoadingContext["Global Loading Context"]:::client
      AuthHook["Auth Redirect Hook"]:::client
      NavigationLoader["NavigationLoader"]:::client
      PageLoader["PageLoader"]:::client
      PageWrapper["PageWrapper"]:::client
      ScrollToTop["ScrollToTop"]:::client
      FECalc["Frontend Emission Calculator"]:::client
      StylesUtil["Styling Utilities"]:::client
    end
  end

  %% Backend Layer
  subgraph "Backend (Express API on Render)"
    direction TB
    ServerJS["HTTP Server (server.js)"]:::backend
    subgraph "Middleware Layer"
      direction TB
      AuthMiddleware["Authentication Middleware"]:::backend
      HelmetCORS["Helmet & CORS"]:::backend
      RateLimit["Rate Limiter"]:::backend
    end
    subgraph "Route Handlers"
      direction TB
      AuthRoutes["Auth Routes"]:::backend
      FootprintRoutes["Footprint Routes"]:::backend
    end
    subgraph "Business Logic / Services"
      direction TB
      CalcEngine["Emission Calculation Engine"]:::backend
      EmailTemplate["Email Template Generator"]:::backend
      IMAPPoller["IMAP Poller"]:::backend
      EmailSender["Email Sender (Nodemailer)"]:::backend
    end
    subgraph "Data Layer (Mongoose Models)"
      direction TB
      UserModel["User Model"]:::backend
      CarbonModel["CarbonEntry Model"]:::backend
    end
  end

  %% Database
  subgraph "Database (MongoDB Atlas)"
    direction TB
    UsersCollection["Collection: users"]:::database
    EntriesCollection["Collection: carbonentries"]:::database
  end

  %% External Services
  subgraph "External Services" 
    direction TB
    SMTP["SMTP Provider"]:::external
    IMAPServer["IMAP Server"]:::external
    GitHubActions["GitHub Actions"]:::external
    VercelDeploy["Vercel Deploy"]:::external
    RenderDeploy["Render Deploy"]:::external
  end

  %% Connections
  Browser["User Browser"]:::external -->|"loads"| ReactSPA
  ReactSPA -->|"REST calls"| ServerJS
  ServerJS --> AuthMiddleware
  ServerJS --> HelmetCORS
  ServerJS --> RateLimit
  AuthMiddleware --> AuthRoutes
  RateLimit --> FootprintRoutes
  AuthRoutes --> CalcEngine
  FootprintRoutes --> CalcEngine
  CalcEngine --> UserModel
  CalcEngine --> CarbonModel
  UserModel --> UsersCollection
  CarbonModel --> EntriesCollection

  %% Email Flow
  AuthRoutes --> EmailSender
  EmailSender --> SMTP
  SMTP -->|"email to user"| Browser
  IMAPServer -->|"verification callback"| IMAPPoller
  IMAPPoller --> AuthRoutes

  %% CI/CD Flow
  GitHubActions --> VercelDeploy
  GitHubActions --> RenderDeploy

  %% Click Events
  click ReactSPA "https://github.com/chacha0044/cft/tree/main/client/"
  click Login "https://github.com/chacha0044/cft/blob/main/client/src/Components/Auth/Login/Login.js"
  click Register "https://github.com/chacha0044/cft/blob/main/client/src/Components/Auth/Register/Register.js"
  click VerifyEmail "https://github.com/chacha0044/cft/blob/main/client/src/Components/Auth/VerifyEmail.jsx"
  click Dashboard "https://github.com/chacha0044/cft/blob/main/client/src/Components/Dashboard/Dashboard.js"
  click ChartPage "https://github.com/chacha0044/cft/blob/main/client/src/Components/Dashboard/ChartPage.js"
  click EditForm "https://github.com/chacha0044/cft/blob/main/client/src/Components/Footprint/EditFootprintForm.js"
  click FootprintOverview "https://github.com/chacha0044/cft/blob/main/client/src/Components/Footprint/Footprint.js"
  click HistoryView "https://github.com/chacha0044/cft/blob/main/client/src/Components/Footprint/History.js"
  click APIClient "https://github.com/chacha0044/cft/blob/main/client/src/api/api.js"
  click LoadingContext "https://github.com/chacha0044/cft/blob/main/client/src/context/LoadingContext.js"
  click AuthHook "https://github.com/chacha0044/cft/blob/main/client/src/hooks/useAuthRedirect.js"
  click NavigationLoader "https://github.com/chacha0044/cft/blob/main/client/src/common/NavigationLoader.jsx"
  click PageLoader "https://github.com/chacha0044/cft/blob/main/client/src/common/PageLoader.jsx"
  click PageWrapper "https://github.com/chacha0044/cft/blob/main/client/src/common/PageWrapper.js"
  click ScrollToTop "https://github.com/chacha0044/cft/blob/main/client/src/common/ScrollToTop.js"
  click FECalc "https://github.com/chacha0044/cft/blob/main/client/src/utils/calculateEmissionsFrontend.js"
  click StylesUtil "https://github.com/chacha0044/cft/blob/main/client/src/utils/styles.js"
  click ServerJS "https://github.com/chacha0044/cft/blob/main/server.js"
  click AuthMiddleware "https://github.com/chacha0044/cft/blob/main/middleware/authmiddleware.js"
  click AuthRoutes "https://github.com/chacha0044/cft/blob/main/routes/auth.js"
  click FootprintRoutes "https://github.com/chacha0044/cft/blob/main/routes/footprint.js"
  click CalcEngine "https://github.com/chacha0044/cft/blob/main/utils/calculateEmissions.js"
  click EmailTemplate "https://github.com/chacha0044/cft/blob/main/utils/emailTemplate.js"
  click IMAPPoller "https://github.com/chacha0044/cft/blob/main/utils/imapPoller.js"
  click EmailSender "https://github.com/chacha0044/cft/blob/main/utils/sendEmail.js"
  click UserModel "https://github.com/chacha0044/cft/blob/main/models/user.js"
  click CarbonModel "https://github.com/chacha0044/cft/blob/main/models/CarbonEntry.js"
  click GitHubActions "https://github.com/chacha0044/cft/blob/main/.github/workflows/bump-version.yml"
  click VercelDeploy "https://github.com/chacha0044/cft/blob/main/vercel.json"
  click StylesUtil "https://github.com/chacha0044/cft/blob/main/client/tailwind.config.js"

  %% Styles
  classDef client fill:#e0f7fa,stroke:#006064,color:#004d40
  classDef backend fill:#e3f2fd,stroke:#0d47a1,color:#0d47a1
  classDef database fill:#fff3e0,stroke:#e65100,color:#bf360c
  classDef external fill:#eceff1,stroke:#607d8b,color:#37474f
```
