# ashrafabid078/cloudcamp_hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/ashrafabid078/cloudcamp_hackathon
- Repository: https://github.com/ashrafabid078/cloudcamp_hackathon

## Overview

Meridian Grid is a Bangladesh-focused energy-planning application: users authenticate, inspect source-labelled regional forecasts, generate and review optimized industrial/battery schedules, and optionally save plans or apply schedule overrides. The Next.js workspace uses a FastAPI backend; the backend also provides role-controlled history, an admin-published public showcase, and read-only Copilot tools with optional Gemini and a separate local MCP server. The graph follows documented capabilities and visible imports/calls; unsampled subsystem links are omitted where their runtime wiring cannot be verified.

Main entry points: [`backend/dispatch/api.py`](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/api.py) (Dispatch routes), [`frontend/src/app/(dashboard)/dispatch/page.tsx`](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/app/(dashboard)/dispatch/page.tsx) (Next.js workspace), [`backend/forecasting/router.py`](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/router.py) (Forecast service), [`backend/agent/tools.py`](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/tools.py) (Read-only planning tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_workspace["Next.js workspace<br/>[page.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_api_services["API services<br/>[services.ts]"]
end

subgraph group_identity["Identity and persistence"]
  node_auth["Authentication routes<br/>[router.py]"]
  node_auth_security["JWT and role checks<br/>[utils.py]"]
  node_database[("Application database<br/>[database.py]")]
  node_models["User and plan records<br/>[models.py]"]
end

subgraph group_forecast["Forecasting"]
  node_forecast_routes["Forecast service<br/>[router.py]"]
  node_forecast_sources["Live weather and carbon<br/>[live_sources.py]"]
  node_forecast_models["Forecast models<br/>[base.py]"]
end

subgraph group_planning["Dispatch planning"]
  node_dispatch_api["Dispatch routes<br/>[api.py]"]
  node_asset_adapters["Asset adapters<br/>[adapters.py]"]
  node_planner["Portfolio planner<br/>[planner.py]"]
  node_solver["PuLP solver<br/>[solver.py]"]
  node_history["Saved plans and decisions<br/>[api.py]"]
end

subgraph group_assist["Copilot and publishing"]
  node_copilot_routes["Copilot routes<br/>[router.py]"]
  node_copilot_service["Copilot reasoning<br/>[copilot_service.py]"]
  node_copilot_tools["Read-only planning tools<br/>[tools.py]"]
  node_mcp["Local stdio MCP<br/>[mcp_server.py]"]
  node_showcase["Showcase publishing<br/>[router.py]"]
  node_admin_plugins["Showcase plugins<br/>[plugins.py]"]
end

node_user(("Planner or admin"))
node_weather(("Open-Meteo"))
node_carbon_api(("Electricity Maps"))
node_gemini(("Gemini"))

node_user -->|"uses"| node_workspace
node_workspace -->|"requests product data"| node_api_services
node_api_services -->|"calls"| node_api_client
node_api_client -->|"sends API requests"| node_auth
node_auth -->|"validates credentials"| node_auth_security
node_auth -->|"reads and writes"| node_database
node_database -->|"creates tables"| node_models
node_forecast_routes -->|"gets live inputs"| node_forecast_sources
node_forecast_sources -->|"fetches weather"| node_weather
node_forecast_sources -->|"fetches carbon data"| node_carbon_api
node_forecast_routes -->|"selects forecaster"| node_forecast_models
node_dispatch_api -->|"gets forecast"| node_forecast_routes
node_dispatch_api -->|"adapts custom assets"| node_asset_adapters
node_dispatch_api -->|"requests schedule"| node_planner
node_planner -->|"uses adapters"| node_asset_adapters
node_planner -->|"solves schedule"| node_solver
node_dispatch_api -->|"saves and lists plans"| node_history
node_history -->|"persists records"| node_database
node_copilot_routes -->|"handles chat"| node_copilot_service
node_copilot_service -->|"executes tool calls"| node_copilot_tools
node_copilot_tools -->|"queries forecasts"| node_forecast_routes
node_copilot_tools -->|"previews schedules"| node_dispatch_api
node_copilot_service -.->|"optionally requests reasoning"| node_gemini
node_mcp -->|"exposes tools"| node_copilot_tools
node_showcase -->|"returns plugin snapshots"| node_admin_plugins
node_showcase -->|"stores publishing state"| node_database
node_workspace -->|"uses planning endpoints"| node_dispatch_api
node_workspace -->|"administers and views showcase"| node_showcase

click node_workspace "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/app/(dashboard)/dispatch/page.tsx"
click node_api_client "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/lib/api/client.ts"
click node_api_services "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/lib/api/services.ts"
click node_auth "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/auth/router.py"
click node_auth_security "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/auth/utils.py"
click node_database "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/db/database.py"
click node_models "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/db/models.py"
click node_forecast_routes "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/router.py"
click node_forecast_sources "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/live_sources.py"
click node_forecast_models "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/models/base.py"
click node_dispatch_api "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/api.py"
click node_asset_adapters "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/adapters.py"
click node_planner "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/planner.py"
click node_solver "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/solver.py"
click node_history "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/api.py"
click node_copilot_routes "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/router.py"
click node_copilot_service "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/copilot_service.py"
click node_copilot_tools "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/tools.py"
click node_mcp "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/mcp_server.py"
click node_showcase "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/showcase/router.py"
click node_admin_plugins "https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/showcase/plugins.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_workspace,node_api_client,node_api_services toneBlue
class node_auth,node_auth_security,node_database,node_models toneAmber
class node_forecast_routes,node_forecast_sources,node_forecast_models toneMint
class node_dispatch_api,node_asset_adapters,node_planner,node_solver,node_history toneRose
class node_copilot_routes,node_copilot_service,node_copilot_tools,node_mcp,node_showcase,node_admin_plugins,node_user,node_weather,node_carbon_api,node_gemini toneIndigo
```

## Components

### User experience

- [Next.js workspace](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/app/(dashboard)/dispatch/page.tsx): `frontend/src/app/(dashboard)/dispatch/page.tsx`
- [API client](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`
- [API services](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/frontend/src/lib/api/services.ts): `frontend/src/lib/api/services.ts`

### Identity and persistence

- [Authentication routes](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/auth/router.py): `backend/auth/router.py`
- [JWT and role checks](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/auth/utils.py): `backend/auth/utils.py`
- [Application database](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/db/database.py): `backend/db/database.py`
- [User and plan records](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/db/models.py): `backend/db/models.py`

### Forecasting

- [Forecast service](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/router.py): `backend/forecasting/router.py`
- [Live weather and carbon](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/live_sources.py): `backend/forecasting/live_sources.py`
- [Forecast models](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/forecasting/models/base.py): `backend/forecasting/models/base.py`

### Dispatch planning

- [Dispatch routes](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/api.py): `backend/dispatch/api.py`
- [Asset adapters](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/adapters.py): `backend/dispatch/adapters.py`
- [Portfolio planner](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/planner.py): `backend/dispatch/planner.py`
- [PuLP solver](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/solver.py): `backend/dispatch/solver.py`
- [Saved plans and decisions](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/dispatch/api.py): `backend/dispatch/api.py`

### Copilot and publishing

- [Copilot routes](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/router.py): `backend/agent/router.py`
- [Copilot reasoning](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/copilot_service.py): `backend/agent/copilot_service.py`
- [Read-only planning tools](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/tools.py): `backend/agent/tools.py`
- [Local stdio MCP](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/agent/mcp_server.py): `backend/agent/mcp_server.py`
- [Showcase publishing](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/showcase/router.py): `backend/showcase/router.py`
- [Showcase plugins](https://github.com/ashrafabid078/cloudcamp_hackathon/blob/main/backend/showcase/plugins.py): `backend/showcase/plugins.py`

### Other components

- **Planner or admin**
- **Open-Meteo**
- **Electricity Maps**
- **Gemini**

## Connections

- Planner or admin → Next.js workspace: uses (evidence: `README.md`)
- Next.js workspace → API services: requests product data (evidence: `README.md`)
- API services → API client: calls (evidence: `frontend/src/lib/api/services.ts`)
- API client → Authentication routes: sends API requests (evidence: `README.md`)
- Authentication routes → JWT and role checks: validates credentials (evidence: `backend/auth/router.py`)
- Authentication routes → Application database: reads and writes (evidence: `backend/auth/router.py`)
- Application database → User and plan records: creates tables (evidence: `backend/db/database.py`)
- Forecast service → Live weather and carbon: gets live inputs (evidence: `backend/forecasting/router.py`)
- Live weather and carbon → Open-Meteo: fetches weather (evidence: `README.md`)
- Live weather and carbon → Electricity Maps: fetches carbon data (evidence: `README.md`)
- Forecast service → Forecast models: selects forecaster (evidence: `backend/forecasting/router.py`)
- Dispatch routes → Forecast service: gets forecast (evidence: `backend/dispatch/api.py`)
- Dispatch routes → Asset adapters: adapts custom assets (evidence: `backend/dispatch/api.py`)
- Dispatch routes → Portfolio planner: requests schedule (evidence: `backend/dispatch/api.py`)
- Portfolio planner → Asset adapters: uses adapters (evidence: `backend/dispatch/planner.py`)
- Portfolio planner → PuLP solver: solves schedule (evidence: `backend/dispatch/planner.py`)
- Dispatch routes → Saved plans and decisions: saves and lists plans (evidence: `backend/dispatch/api.py`)
- Saved plans and decisions → Application database: persists records (evidence: `backend/dispatch/api.py`)
- Copilot routes → Copilot reasoning: handles chat (evidence: `backend/agent/router.py`)
- Copilot reasoning → Read-only planning tools: executes tool calls (evidence: `backend/agent/copilot_service.py`)
- Read-only planning tools → Forecast service: queries forecasts (evidence: `backend/agent/tools.py`)
- Read-only planning tools → Dispatch routes: previews schedules (evidence: `backend/agent/tools.py`)
- Copilot reasoning → Gemini: optionally requests reasoning (evidence: `backend/agent/copilot_service.py`)
- Local stdio MCP → Read-only planning tools: exposes tools (evidence: `README.md`)
- Showcase publishing → Showcase plugins: returns plugin snapshots (evidence: `backend/showcase/router.py`)
- Showcase publishing → Application database: stores publishing state (evidence: `backend/showcase/router.py`)
- Next.js workspace → Dispatch routes: uses planning endpoints (evidence: `README.md`)
- Next.js workspace → Showcase publishing: administers and views showcase (evidence: `README.md`)