# wissemkooli/m4_agentic_energy_planning architecture

> Architecture diagram of the GitHub repository wissemkooli/m4_agentic_energy_planning, 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/wissemkooli/m4_agentic_energy_planning
- Repository: https://github.com/wissemkooli/m4_agentic_energy_planning

## Overview

M4 is a human-in-the-loop energy planning and operations decision-support system. A planner submits a natural-language goal or operating problem through the web UI; the backend investigates data, prepares a scenario, checks and solves an optimization or simulation, and returns alternatives for review. The agent explains and recommends, while users approve assumptions and administrators record decisions—nothing is executed automatically. The graph preserves documented data integration, authentication, history and administration capabilities. Some router and agent internals were not sampled, so uncertain wiring is omitted or shown as unverified.

Main entry points: [`M4-Mahdi/m4/services.py`](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/services.py) (Application services), [`M4-Mahdi/m4/modeling/system.py`](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/system.py) (System inputs), [`frontend/src/api/client.ts`](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/api/client.ts) (REST client), [`M4-Mahdi/m4/api/app.py`](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/api/app.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web_agent["Planning agent UI<br/>[PlanningAgent.tsx]"]
  node_web_scenarios["Scenario builder"]
  node_web_results["Runs and results<br/>[StrategiesList.tsx]"]
  node_web_admin["Admin review<br/>[ReviewQueue.tsx]"]
  node_api_client["REST client<br/>[client.ts]"]
end

subgraph group_api["API and orchestration"]
  node_api_app["FastAPI application<br/>[app.py]"]
  node_services["Application services<br/>[services.py]"]
end

subgraph group_planning["Planning and operations"]
  node_agent["Agent workflow<br/>[graph.py]"]
  node_llm["LLM integration<br/>[llm.py]"]
  node_scenario["Scenario configuration<br/>[schema.py]"]
  node_system_inputs["System inputs<br/>[system.py]"]
  node_capacity_opt["Capacity optimization<br/>[engine.py]"]
  node_operations["Operational optimization<br/>[engine.py]"]
  node_simulation["Energy simulation<br/>[simulation.py]"]
  node_roadmap["Strategy roadmap<br/>[roadmap.py]"]
end

subgraph group_data["Energy data"]
  node_input_repo["Input repository<br/>[repository.py]"]
  node_adapters["Source adapters<br/>[adapters.py]"]
  node_demand["Demand pathways<br/>[demand.py]"]
end

subgraph group_governance["Identity and decisions"]
  node_auth["Authentication<br/>[security.py]"]
  node_db[("Persistent records<br/>[models.py]")]
  node_admin_router["Admin review API<br/>[admin.py]"]
end

node_planner(("Planner"))

node_planner -->|"submits goal"| node_web_agent
node_web_agent -->|"sends requests"| node_api_client
node_web_scenarios -->|"sends requests"| node_api_client
node_web_results -.->|"fetches results"| node_api_client
node_web_admin -.->|"reviews decisions"| node_api_client
node_api_client -->|"calls REST API"| node_api_app
node_api_app -->|"routes workflow"| node_services
node_api_app -->|"mounts router"| node_admin_router
node_services -->|"invokes agent"| node_agent
node_services -->|"runs planning"| node_capacity_opt
node_services -->|"runs operations"| node_operations
node_services -->|"runs simulation"| node_simulation
node_services -->|"persists runs"| node_db
node_agent -.->|"uses optional LLM"| node_llm
node_agent -.->|"forms scenario"| node_scenario
node_capacity_opt -->|"builds from"| node_system_inputs
node_operations -->|"builds from"| node_system_inputs
node_simulation -->|"uses shared inputs"| node_system_inputs
node_system_inputs -->|"loads inputs"| node_input_repo
node_input_repo -->|"loads source data"| node_adapters
node_system_inputs -->|"uses demand pathways"| node_demand
node_system_inputs -->|"applies scenario"| node_scenario
node_capacity_opt -.->|"informs strategies"| node_roadmap
node_planner -->|"authenticates"| node_auth
node_auth -->|"uses user records"| node_db
node_admin_router -.->|"records decisions"| node_db

click node_web_agent "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/PlanningAgent.tsx"
click node_web_scenarios "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/ScenarioBuilder.tsx"
click node_web_results "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/StrategiesList.tsx"
click node_web_admin "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/admin/ReviewQueue.tsx"
click node_api_client "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/api/client.ts"
click node_api_app "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/api/app.py"
click node_services "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/services.py"
click node_agent "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/agent/graph.py"
click node_llm "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/agent/llm.py"
click node_scenario "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/scenarios/schema.py"
click node_system_inputs "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/system.py"
click node_capacity_opt "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/optimization/engine.py"
click node_operations "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/operations/engine.py"
click node_simulation "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/simulation.py"
click node_roadmap "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/strategy/roadmap.py"
click node_input_repo "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/data_integration/repository.py"
click node_adapters "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/data_integration/adapters.py"
click node_demand "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/demand.py"
click node_auth "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/auth/security.py"
click node_db "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/db/models.py"
click node_admin_router "https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/api/routers/admin.py"

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_web_agent,node_web_scenarios,node_web_results,node_web_admin,node_api_client toneBlue
class node_api_app,node_services toneAmber
class node_agent,node_llm,node_scenario,node_system_inputs,node_capacity_opt,node_operations,node_simulation,node_roadmap toneMint
class node_input_repo,node_adapters,node_demand toneRose
class node_auth,node_db,node_admin_router,node_planner toneIndigo
```

## Components

### Web experience

- [Planning agent UI](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/PlanningAgent.tsx): `frontend/src/pages/PlanningAgent.tsx`
- [Scenario builder](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/ScenarioBuilder.tsx): `frontend/src/pages/ScenarioBuilder.tsx`
- [Runs and results](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/StrategiesList.tsx): `frontend/src/pages/StrategiesList.tsx`
- [Admin review](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/pages/admin/ReviewQueue.tsx): `frontend/src/pages/admin/ReviewQueue.tsx`
- [REST client](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and orchestration

- [FastAPI application](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/api/app.py): `M4-Mahdi/m4/api/app.py`
- [Application services](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/services.py): `M4-Mahdi/m4/services.py`

### Planning and operations

- [Agent workflow](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/agent/graph.py): `M4-Mahdi/m4/agent/graph.py`
- [LLM integration](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/agent/llm.py): `M4-Mahdi/m4/agent/llm.py`
- [Scenario configuration](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/scenarios/schema.py): `M4-Mahdi/m4/scenarios/schema.py`
- [System inputs](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/system.py): `M4-Mahdi/m4/modeling/system.py`
- [Capacity optimization](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/optimization/engine.py): `M4-Mahdi/m4/optimization/engine.py`
- [Operational optimization](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/operations/engine.py): `M4-Mahdi/m4/operations/engine.py`
- [Energy simulation](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/simulation.py): `M4-Mahdi/m4/modeling/simulation.py`
- [Strategy roadmap](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/strategy/roadmap.py): `M4-Mahdi/m4/strategy/roadmap.py`

### Energy data

- [Input repository](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/data_integration/repository.py): `M4-Mahdi/m4/data_integration/repository.py`
- [Source adapters](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/data_integration/adapters.py): `M4-Mahdi/m4/data_integration/adapters.py`
- [Demand pathways](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/modeling/demand.py): `M4-Mahdi/m4/modeling/demand.py`

### Identity and decisions

- [Authentication](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/auth/security.py): `M4-Mahdi/m4/auth/security.py`
- [Persistent records](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/db/models.py): `M4-Mahdi/m4/db/models.py`
- [Admin review API](https://github.com/wissemkooli/m4_agentic_energy_planning/blob/main/M4-Mahdi/m4/api/routers/admin.py): `M4-Mahdi/m4/api/routers/admin.py`

### Other components

- **Planner**

## Connections

- Planner → Planning agent UI: submits goal (evidence: `README.md`)
- Planning agent UI → REST client: sends requests (evidence: `frontend/src/pages/PlanningAgent.tsx`)
- Scenario builder → REST client: sends requests (evidence: `frontend/src/pages/ScenarioBuilder.tsx`)
- Runs and results → REST client: fetches results
- Admin review → REST client: reviews decisions
- REST client → FastAPI application: calls REST API (evidence: `README.md`)
- FastAPI application → Application services: routes workflow (evidence: `M4-Mahdi/m4/api/app.py`)
- FastAPI application → Admin review API: mounts router (evidence: `M4-Mahdi/m4/api/app.py`)
- Application services → Agent workflow: invokes agent (evidence: `M4-Mahdi/m4/services.py`)
- Application services → Capacity optimization: runs planning (evidence: `M4-Mahdi/m4/services.py`)
- Application services → Operational optimization: runs operations (evidence: `M4-Mahdi/m4/services.py`)
- Application services → Energy simulation: runs simulation (evidence: `M4-Mahdi/m4/services.py`)
- Application services → Persistent records: persists runs (evidence: `M4-Mahdi/m4/services.py`)
- Agent workflow → LLM integration: uses optional LLM (evidence: `README.md`)
- Agent workflow → Scenario configuration: forms scenario (evidence: `README.md`)
- Capacity optimization → System inputs: builds from (evidence: `M4-Mahdi/m4/optimization/engine.py`)
- Operational optimization → System inputs: builds from (evidence: `M4-Mahdi/m4/operations/engine.py`)
- Energy simulation → System inputs: uses shared inputs (evidence: `M4-Mahdi/m4/modeling/system.py`)
- System inputs → Input repository: loads inputs (evidence: `M4-Mahdi/m4/modeling/system.py`)
- Input repository → Source adapters: loads source data (evidence: `M4-Mahdi/m4/data_integration/repository.py`)
- System inputs → Demand pathways: uses demand pathways (evidence: `M4-Mahdi/m4/modeling/system.py`)
- System inputs → Scenario configuration: applies scenario (evidence: `M4-Mahdi/m4/modeling/system.py`)
- Capacity optimization → Strategy roadmap: informs strategies
- Planner → Authentication: authenticates (evidence: `README.md`)
- Authentication → Persistent records: uses user records (evidence: `M4-Mahdi/m4/auth/security.py`)
- Admin review API → Persistent records: records decisions
