# coolclimatenetwork/tnc architecture

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

- Interactive diagram: https://gitdiagram.com/coolclimatenetwork/tnc
- Repository: https://github.com/coolclimatenetwork/tnc

## Overview

##### Project Type and Purpose
- This is a single‐page React frontend application (built with Create React App) that implements the Cool Climate Carbon Calculator UI (TNC version).
- It relies on an external “calculator-api” service (a sibling project) for all emissions calculations.

##### File Structure Analysis
- Top‐level:
- public/ – static HTML and manifest
- src/ – React application code
- tests/ – Jest/React Testing Library tests
- src/Container.js – root component holding global state (React hooks) and all API calls.
- src/components/ – UI subfolders:
- CalcPages/ – individual step‐by‐step pages (Started, Home, Food, Travel, Shopping, Results)
- CustomAssets/ – reusable controls (Dropdown, Range, Switch)
- CarbonCalculator.js – wrapper that loads CalcPages steps
- CCgraph.js – live graph next to the form
- Intro.js – initial text
- ResultsChart.js – full‐screen results overlay

##### Key Insights from README
- Container.js is the single source of truth for state and triggers to the API.
- Child pages consume setter functions (e.g. setInputSize) to update global state and automatically trigger new calculations.
- ResultsChart overlays the main UI when toggled.
- CCgraph updates in real time alongside user inputs.

a. Main Components
- Browser / User Agent
- React SPA (index.html → index.js → top‐level Container)
- Container (global state & API client)
- CarbonCalculator (stepper controller)
- CalcPages (Started, Home, Food, Travel, Shopping, Results)
- CustomAssets library (Dropdown, Range, Switch)
- CCgraph (in‐page graph)
- ResultsChart (overlay chart)
- External calculator-api service (HTTP REST)
- Static assets (public/)
b. Relationships & Data Flow
1. User interacts with UI (CalcPages & CustomAssets) → calls setter hooks provided by Container.
2. Container updates internal state → invokes API client to send HTTP request to calculator-api.
3. External service returns emissions data → Container updates result state.
4. Updated state is propagated to CCgraph (live update) and ResultsChart (when toggled).
5. CarbonCalculator routes between CalcPages based on current step.
c. Architectural Patterns & Principles
- Single‐page application (SPA) with client‐side routing of steps
- Unidirectional data flow via React hooks and props
- Separation of concerns: Container (state/API), presentation components (CalcPages, graphs), and custom UI controls
d. Key Technologies & Frameworks
- React (functional components + hooks)
- Create React App (Webpack, Babel under the hood)
- SCSS for styling (Container.scss, component‐specific .scss files)
- Jest + React Testing Library for tests

##### Charting Elements
- Use clear labels: e.g. “Container (global state + API client)”
- from User → CalcPages / CustomAssets
- from CalcPages → Container (setter calls)
- Container → calculator-api (HTTP request)
- calculator-api → Container (HTTP response)
- Container → CCgraph / ResultsChart (state updates)
- Blue rectangles for React components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    Browser["Browser/User"]:::external

    %% React SPA Boundary
    subgraph "React SPA"
        direction TB
        IndexJS["src/index.js"]:::component
        Container["Container\n(global state + API client)"]:::component
        click Container "https://github.com/coolclimatenetwork/tnc/blob/main/src/Container.js"
        click Container "https://github.com/coolclimatenetwork/tnc/blob/main/src/Container.scss"
        click IndexJS "https://github.com/coolclimatenetwork/tnc/blob/main/src/index.js"

        %% Presentation and Visualization Columns
        subgraph "Presentation Components"
            direction TB
            CarbonCalc["CarbonCalculator"]:::component
            click CarbonCalc "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CarbonCalculator.js"

            subgraph "CalcPages"
                direction TB
                Started["Started"]:::component
                click Started "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CalcPages/Started.js"
                Home["Home"]:::component
                click Home "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CalcPages/Home.js"
                Food["Food"]:::component
                click Food "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CalcPages/Food.js"
                Travel["Travel"]:::component
                click Travel "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CalcPages/Travel.js"
                Shopping["Shopping"]:::component
                click Shopping "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CalcPages/Shopping.js"
                ResultsPage["Results"]:::component
                click ResultsPage "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CalcPages/Results.js"
            end

            subgraph "CustomAssets"
                direction TB
                Dropdown["Dropdown"]:::component
                click Dropdown "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CustomAssets/Dropdown.js"
                Range["Range"]:::component
                click Range "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CustomAssets/Range.js"
                Switch["Switch"]:::component
                click Switch "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/CustomAssets/Switch.js"
            end

            Intro["Intro"]:::component
            click Intro "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/Intro.js"
        end

        subgraph "Visualization Components"
            direction TB
            CCgraph["CCgraph"]:::component
            click CCgraph "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/Ccgraph.js"
            ResultsChart["ResultsChart"]:::component
            click ResultsChart "https://github.com/coolclimatenetwork/tnc/blob/main/src/components/ResultsChart.js"
        end
    end

    %% External API Service
    CalculatorAPI["calculator-api (REST)"]:::api

    %% Static Assets
    Public["public/"]:::static
    click Public "https://github.com/coolclimatenetwork/tnc/tree/main/public/"

    %% Tests
    subgraph "Tests"
        AppTest["App.test.js"]:::test
        click AppTest "https://github.com/coolclimatenetwork/tnc/blob/main/tests/App.test.js"
        SetupTests["setupTests.js"]:::test
        click SetupTests "https://github.com/coolclimatenetwork/tnc/blob/main/tests/setupTests.js"
    end

    %% Connections
    Browser -->|"interacts with"| Started
    Browser -->|"interacts with"| Dropdown
    Browser -->|"interacts with"| Range
    Browser -->|"interacts with"| Switch

    CarbonCalc -->|"routes steps"| Started
    CarbonCalc --> CalcPages

    Started -->|"setter calls"| Container
    Home -->|"setter calls"| Container
    Food -->|"setter calls"| Container
    Travel -->|"setter calls"| Container
    Shopping -->|"setter calls"| Container
    ResultsPage -->|"setter calls"| Container

    Dropdown -->|"updates via hooks"| Container
    Range --> Container
    Switch --> Container

    Container -->|"HTTP request"| CalculatorAPI
    CalculatorAPI -->|"HTTP response"| Container

    Container -->|"state updates"| CCgraph
    Container -->|"state updates"| ResultsChart

    Public -->|"serves index.html"| IndexJS

    Tests --> AppTest
    Tests --> SetupTests

    %% Styles
    classDef component fill:#E3F2FD,stroke:#64B5F6
    classDef api fill:#E8F5E9,stroke:#66BB6A
    classDef external fill:#FFF3E0,stroke:#FFA726
    classDef static fill:#ECEFF1,stroke:#90A4AE
    classDef test fill:#F3E5F5,stroke:#AB47BC
```
