# amanaakash/carbon-track architecture

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

- Interactive diagram: https://gitdiagram.com/amanaakash/carbon-track
- Repository: https://github.com/amanaakash/carbon-track

## Overview

##### Project Type and Purpose
- CarbonTrack is a full-stack web application built with Next.js (App Router), React, and TypeScript.
- Purpose: provide real-time air quality monitoring, historical data visualization, and AI-powered carbon reduction recommendations.

##### File Structure Analysis
- Top level
- package.json, next.config.ts, tsconfig.json, tailwind.config.ts, postcss.config.mjs – build & config
- src/
– app/ – Next.js App Router (layout.tsx, page.tsx, global CSS)
– components/ – reusable UI components (shadcn/ui Button, Card, Input)
– lib/ – utility functions, API wrappers (utils.ts)
- No dedicated “api” folder; data fetching occurs in server components or client components using fetch.
- No database folder: all data is fetched at runtime from external services.

##### README Insights
- External APIs:
- Open-Meteo Air Quality for pollutant data
- OpenStreetMap Nominatim for geocoding
- OpenRouter AI for GPT-powered insights
- Architecture patterns: server components (Next.js), client components, utility layer, static assets, environment variables.

##### Main Components
a. Client Layer
– Web Browser (user interface)
– Next.js client-side bundles (React components, CSS, charts)
b. Server Layer
– Next.js server (App Router) handling SSR/SSG and server components
– Utility module (src/lib/utils.ts) encapsulating fetch logic
c. External Services
– Air Quality API (Open-Meteo)
– Geocoding API (OpenStreetMap Nominatim)
– AI Recommendations API (OpenRouter → OpenAI GPT)
d. Static Assets & Build
– CDN or Vercel/Netlify hosting static assets (public/)
– Build pipeline (Turbopack) for dev & production

##### Relationships and Data Flow
- User enters a city in the UI → browser sends event to React component → component invokes Next.js fetch (in server/client component)
- Next.js server handles data requests:
- calls Geocoding API → gets coordinates
- calls Air Quality API → retrieves pollutant data
- optionally calls AI API → gets recommendations
- Next.js composes response (JSON + HTML) → sends to browser
- Browser renders charts (Recharts) and UI components (shadcn/ui)
- For subsequent interactions, client-side fetches may bypass SSR for faster updates

##### Architectural Patterns and Principles
- Single Page Application with hybrid SSR/CSR (Next.js App Router)
- Separation of concerns:
- UI layer (components/)
- Data layer (lib/utils.ts)
- Style layer (Tailwind CSS, globals.css)
- External service abstraction for maintainability
- No in-house database: relies on real-time APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Web Browser"]:::external
        ClientBundle["Next.js Client Bundles\n(React, CSS, Charts)"]:::internal
        subgraph "UI Components"
            Button["Button"]:::internal
            Card["Card"]:::internal
            Input["Input"]:::internal
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Server["Next.js Server\n(App Router)"]:::internal
        Utils["Utility Module\n(src/lib/utils.ts)"]:::internal
    end

    %% External Services
    subgraph "External Services"
        AQ["Open-Meteo Air Quality API"]:::external
        GEO["OpenStreetMap Nominatim API"]:::external
        AI["OpenRouter/OpenAI GPT API"]:::external
    end

    %% Build & Deploy
    subgraph "Build & Deploy"
        Build["Build Pipeline\n(Turbopack)"]:::config
        Static["Static Assets\n(public/)"]:::internal
        Host["Vercel/Netlify Hosting"]:::external
        NextConfig["next.config.ts"]:::config
        TailwindConfig["tailwind.config.ts"]:::config
        PostCSSConfig["postcss.config.mjs"]:::config
        TSConfig["tsconfig.json"]:::config
        PackageManifest["package.json"]:::config
        GlobalStyles["Global Styles\n(src/app/globals.css)"]:::internal
    end

    %% Runtime Data Flow
    Browser -->|"user input"| ClientBundle
    ClientBundle -->|"fetch data"| Server
    Server -->|"geocode request"| GEO
    Server -->|"air quality request"| AQ
    Server -.->|"optional AI recommendations"| AI
    Server -->|"compose response"| ClientBundle
    ClientBundle -->|"render UI & charts"| Browser

    %% UI Component Usage
    ClientBundle -->|"uses"| Button
    ClientBundle -->|"uses"| Card
    ClientBundle -->|"uses"| Input

    %% Build & Deploy Flow
    Build --> Host
    Build --> Static
    Build --> ClientBundle
    Build --> Server
    Host --> Browser
    Static --> Browser

    %% Click Events
    click Server "https://github.com/amanaakash/carbon-track/tree/main/src/app/"
    click Button "https://github.com/amanaakash/carbon-track/blob/main/src/components/ui/button.tsx"
    click Card "https://github.com/amanaakash/carbon-track/blob/main/src/components/ui/card.tsx"
    click Input "https://github.com/amanaakash/carbon-track/blob/main/src/components/ui/input.tsx"
    click Utils "https://github.com/amanaakash/carbon-track/blob/main/src/lib/utils.ts"
    click Static "https://github.com/amanaakash/carbon-track/tree/main/public/"
    click GlobalStyles "https://github.com/amanaakash/carbon-track/blob/main/src/app/globals.css"
    click NextConfig "https://github.com/amanaakash/carbon-track/blob/main/next.config.ts"
    click TailwindConfig "https://github.com/amanaakash/carbon-track/blob/main/tailwind.config.ts"
    click PostCSSConfig "https://github.com/amanaakash/carbon-track/blob/main/postcss.config.mjs"
    click TSConfig "https://github.com/amanaakash/carbon-track/blob/main/tsconfig.json"
    click PackageManifest "https://github.com/amanaakash/carbon-track/blob/main/package.json"

    %% Styling
    classDef internal fill:#D0E8FF,stroke:#0366D6,stroke-width:2px;
    classDef external fill:#DFFFD6,stroke:#228B22,stroke-width:2px;
    classDef config fill:#FFF4E5,stroke:#FF8C00,stroke-width:2px;
    class GlobalStyles,ClientBundle,Utils,Server,Button,Card,Input,Static internal
    class Browser,AQ,GEO,AI,Host external
    class Build,NextConfig,TailwindConfig,PostCSSConfig,TSConfig,PackageManifest config
```
