# fahad3235/green-factory-ai architecture

> Architecture diagram of the GitHub repository fahad3235/green-factory-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fahad3235/green-factory-ai
- Repository: https://github.com/fahad3235/green-factory-ai

## Overview

Green Factory Brain AI is a simulated-factory energy intelligence product: factory staff inspect telemetry, explore deterministic energy and carbon calculations, review proposed mitigations, and make the approval decision before any simulated state change. Its major capabilities include the dashboard and digital twin, scenario simulation, agent workflows, carbon forecasting and reporting, and an optional LLM copilot. The backend API and browser-side simulation are both represented. Some frontend and agent internals were not sampled, so relationships beyond documented behavior are omitted.

Main entry points: [`src/api/routes.py`](https://github.com/fahad3235/green-factory-ai/blob/main/src/api/routes.py) (API routes), [`src/agents/copilot_agent.py`](https://github.com/fahad3235/green-factory-ai/blob/main/src/agents/copilot_agent.py) (AI copilot), [`src/api/main.py`](https://github.com/fahad3235/green-factory-ai/blob/main/src/api/main.py) (FastAPI application), [`preview/index.html`](https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html) (Dashboard and views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Factory Experience"]
  node_dashboard["Dashboard and views<br/>[index.html]"]
  node_twin["3D digital twin<br/>[digital-twin.html]"]
  node_simulator_view["Simulator view<br/>[simulation.html]"]
  node_manager_gate["Manager confirmation gate<br/>[index.html]"]
end

subgraph group_simulation["Simulation and Metrics"]
  node_browser_engine["Seeded simulation engine<br/>[calculations.mjs]"]
  node_ts_engine["Typed calculation engine<br/>[calculations.ts]"]
end

subgraph group_backend["API and Agents"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_contracts["API contracts<br/>[schemas.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_workflow["Mitigation workflow<br/>[copilot_agent.py]"]
  node_copilot["AI copilot<br/>[copilot_agent.py]"]
end

subgraph group_reporting["Carbon and Reporting"]
  node_python_metrics["Energy and carbon formulas<br/>[calculations.py]"]
  node_forecast["Carbon credit forecast<br/>[calculations.py]"]
  node_reports["Carbon and savings reports<br/>[index.html]"]
end

node_staff(("Factory staff"))
node_groq{{"Groq API"}}
node_gemini{{"Gemini API"}}

node_staff -->|"uses"| node_dashboard
node_staff -->|"inspects"| node_twin
node_staff -->|"runs scenarios"| node_simulator_view
node_simulator_view -->|"simulates telemetry"| node_browser_engine
node_browser_engine -->|"typed parity"| node_ts_engine
node_api_app -->|"includes router"| node_api_routes
node_api_app -->|"loads settings"| node_settings
node_api_app -->|"serves UI"| node_dashboard
node_api_routes -->|"validates payloads"| node_contracts
node_api_routes -->|"reads settings"| node_settings
node_api_routes -->|"runs copilot"| node_copilot
node_api_routes -->|"evaluates scenario"| node_workflow
node_api_routes -->|"calculates telemetry"| node_python_metrics
node_api_routes -->|"calculates forecast"| node_forecast
node_copilot -->|"uses provider keys"| node_settings
node_copilot -.->|"requests completion"| node_groq
node_copilot -.->|"requests completion"| node_gemini
node_workflow -->|"requires approval"| node_manager_gate
node_staff -->|"approves or rejects"| node_manager_gate
node_dashboard -->|"opens reports"| node_reports
node_python_metrics -.->|"feeds calculations"| node_forecast

click node_dashboard "https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html"
click node_twin "https://github.com/fahad3235/green-factory-ai/blob/main/preview/digital-twin.html"
click node_simulator_view "https://github.com/fahad3235/green-factory-ai/blob/main/preview/simulation.html"
click node_browser_engine "https://github.com/fahad3235/green-factory-ai/blob/main/preview/src/domain/calculations.mjs"
click node_ts_engine "https://github.com/fahad3235/green-factory-ai/blob/main/preview/src/domain/calculations.ts"
click node_api_app "https://github.com/fahad3235/green-factory-ai/blob/main/src/api/main.py"
click node_api_routes "https://github.com/fahad3235/green-factory-ai/blob/main/src/api/routes.py"
click node_contracts "https://github.com/fahad3235/green-factory-ai/blob/main/src/models/schemas.py"
click node_settings "https://github.com/fahad3235/green-factory-ai/blob/main/src/core/config.py"
click node_workflow "https://github.com/fahad3235/green-factory-ai/blob/main/src/agents/copilot_agent.py"
click node_copilot "https://github.com/fahad3235/green-factory-ai/blob/main/src/agents/copilot_agent.py"
click node_python_metrics "https://github.com/fahad3235/green-factory-ai/blob/main/src/core/calculations.py"
click node_forecast "https://github.com/fahad3235/green-factory-ai/blob/main/src/core/calculations.py"
click node_reports "https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html"
click node_manager_gate "https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html"

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_dashboard,node_twin,node_simulator_view,node_manager_gate toneBlue
class node_browser_engine,node_ts_engine toneAmber
class node_api_app,node_api_routes,node_contracts,node_settings,node_workflow,node_copilot,node_groq,node_gemini toneMint
class node_python_metrics,node_forecast,node_reports toneRose
class node_staff toneIndigo
```

## Components

### Factory Experience

- [Dashboard and views](https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html): `preview/index.html`
- [3D digital twin](https://github.com/fahad3235/green-factory-ai/blob/main/preview/digital-twin.html): `preview/digital-twin.html`
- [Simulator view](https://github.com/fahad3235/green-factory-ai/blob/main/preview/simulation.html): `preview/simulation.html`
- [Manager confirmation gate](https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html): `preview/index.html`

### Simulation and Metrics

- [Seeded simulation engine](https://github.com/fahad3235/green-factory-ai/blob/main/preview/src/domain/calculations.mjs): `preview/src/domain/calculations.mjs`
- [Typed calculation engine](https://github.com/fahad3235/green-factory-ai/blob/main/preview/src/domain/calculations.ts): `preview/src/domain/calculations.ts`

### API and Agents

- [FastAPI application](https://github.com/fahad3235/green-factory-ai/blob/main/src/api/main.py): `src/api/main.py`
- [API routes](https://github.com/fahad3235/green-factory-ai/blob/main/src/api/routes.py): `src/api/routes.py`
- [API contracts](https://github.com/fahad3235/green-factory-ai/blob/main/src/models/schemas.py): `src/models/schemas.py`
- [Runtime settings](https://github.com/fahad3235/green-factory-ai/blob/main/src/core/config.py): `src/core/config.py`
- [Mitigation workflow](https://github.com/fahad3235/green-factory-ai/blob/main/src/agents/copilot_agent.py): `src/agents/copilot_agent.py`
- [AI copilot](https://github.com/fahad3235/green-factory-ai/blob/main/src/agents/copilot_agent.py): `src/agents/copilot_agent.py`

### Carbon and Reporting

- [Energy and carbon formulas](https://github.com/fahad3235/green-factory-ai/blob/main/src/core/calculations.py): `src/core/calculations.py`
- [Carbon credit forecast](https://github.com/fahad3235/green-factory-ai/blob/main/src/core/calculations.py): `src/core/calculations.py`
- [Carbon and savings reports](https://github.com/fahad3235/green-factory-ai/blob/main/preview/index.html): `preview/index.html`

### Other components

- **Factory staff**
- **Groq API**
- **Gemini API**

## Connections

- Factory staff → Dashboard and views: uses (evidence: `README.md`)
- Factory staff → 3D digital twin: inspects (evidence: `README.md`)
- Factory staff → Simulator view: runs scenarios (evidence: `README.md`)
- Simulator view → Seeded simulation engine: simulates telemetry (evidence: `README.md`)
- Seeded simulation engine → Typed calculation engine: typed parity (evidence: `preview/src/domain/calculations.ts`)
- FastAPI application → API routes: includes router (evidence: `src/api/main.py`)
- FastAPI application → Runtime settings: loads settings (evidence: `src/api/main.py`)
- FastAPI application → Dashboard and views: serves UI (evidence: `src/api/main.py`)
- API routes → API contracts: validates payloads (evidence: `src/api/routes.py`)
- API routes → Runtime settings: reads settings (evidence: `src/api/routes.py`)
- API routes → AI copilot: runs copilot (evidence: `src/api/routes.py`)
- API routes → Mitigation workflow: evaluates scenario (evidence: `src/api/routes.py`)
- API routes → Energy and carbon formulas: calculates telemetry (evidence: `src/api/routes.py`)
- API routes → Carbon credit forecast: calculates forecast (evidence: `src/api/routes.py`)
- AI copilot → Runtime settings: uses provider keys (evidence: `src/agents/copilot_agent.py`)
- AI copilot → Groq API: requests completion (evidence: `src/agents/copilot_agent.py`)
- AI copilot → Gemini API: requests completion (evidence: `src/agents/copilot_agent.py`)
- Mitigation workflow → Manager confirmation gate: requires approval (evidence: `README.md`)
- Factory staff → Manager confirmation gate: approves or rejects (evidence: `README.md`)
- Dashboard and views → Carbon and savings reports: opens reports (evidence: `README.md`)
- Energy and carbon formulas → Carbon credit forecast: feeds calculations (evidence: `src/core/calculations.py`)
