# komal-2108/aurora architecture

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

- Interactive diagram: https://gitdiagram.com/komal-2108/aurora
- Repository: https://github.com/komal-2108/aurora

## Overview

AURORA is a smart energy management prototype for polar research stations. The main user workflow is to select a station and view live dashboard data, forecasts, alerts, battery and fuel status, then request a dispatch optimization or apply a scenario. The React app communicates with FastAPI; forecasting combines station history with load and renewable models, and optimization uses that forecast with MILP when available or a heuristic fallback. The README documents additional reporting and monitoring capabilities. Route handlers and several services were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`backend/app/services/optimization_service.py`](https://github.com/komal-2108/aurora/blob/main/backend/app/services/optimization_service.py) (Optimization service), [`frontend/src/App.jsx`](https://github.com/komal-2108/aurora/blob/main/frontend/src/App.jsx) (AURORA app), [`backend/app/services/forecast_service.py`](https://github.com/komal-2108/aurora/blob/main/backend/app/services/forecast_service.py) (Forecast service), [`frontend/src/services/api.js`](https://github.com/komal-2108/aurora/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["AURORA app<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_views["Product views"]
  node_app_shell["App shell<br/>[AppShell.jsx]"]
  node_reporting["Reports and analytics<br/>[ModulePages.jsx]"]
end

subgraph group_api["Application API"]
  node_fastapi["FastAPI entry<br/>[main.py]"]
  node_routes["API routes"]
  node_alerts["Alerts and events<br/>[alerts.py]"]
  node_energy_services["Energy services"]
end

subgraph group_forecast["Forecasting"]
  node_forecast_route["Forecast service"]
  node_simulator["Station simulator<br/>[simulator.py]"]
  node_load_model["Load forecasting"]
  node_renewable_model["Renewable forecasting"]
end

subgraph group_dispatch["Dispatch and state"]
  node_optimization["Optimization service"]
  node_dispatch_engine["Dispatch engine<br/>[dispatch.py]"]
  node_state["Station state<br/>[state_service.py]"]
  node_store[("Run history store<br/>[database.py]")]
  node_weather["Weather service<br/>[weather_service.py]"]
end

node_operator(("Station operator"))
node_weather_provider(("Open-Meteo"))

node_operator -->|"uses"| node_app
node_app -->|"requests data"| node_api_client
node_app -->|"renders"| node_views
node_app -->|"wraps views"| node_app_shell
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"registers routers"| node_routes
node_optimization -->|"requests forecast"| node_forecast_route
node_forecast_route -->|"reads station history"| node_simulator
node_forecast_route -->|"predicts load"| node_load_model
node_forecast_route -->|"predicts renewables"| node_renewable_model
node_optimization -->|"optimizes dispatch"| node_dispatch_engine
node_optimization -->|"reads and updates state"| node_state
node_optimization -->|"writes run history"| node_store
node_optimization -->|"reads run history"| node_store
node_weather -.->|"fetches conditions"| node_weather_provider
node_routes -->|"serves alerts"| node_alerts
node_views -->|"includes reports"| node_reporting

click node_app "https://github.com/komal-2108/aurora/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/komal-2108/aurora/blob/main/frontend/src/services/api.js"
click node_views "https://github.com/komal-2108/aurora/tree/main/frontend/src/pages"
click node_app_shell "https://github.com/komal-2108/aurora/blob/main/frontend/src/components/layout/AppShell.jsx"
click node_fastapi "https://github.com/komal-2108/aurora/blob/main/backend/app/main.py"
click node_routes "https://github.com/komal-2108/aurora/tree/main/backend/app/api/routes"
click node_forecast_route "https://github.com/komal-2108/aurora/blob/main/backend/app/services/forecast_service.py"
click node_simulator "https://github.com/komal-2108/aurora/blob/main/simulation/simulator.py"
click node_load_model "https://github.com/komal-2108/aurora/tree/main/ml/load_forecasting"
click node_renewable_model "https://github.com/komal-2108/aurora/tree/main/ml/renewable_forecasting"
click node_optimization "https://github.com/komal-2108/aurora/blob/main/backend/app/services/optimization_service.py"
click node_dispatch_engine "https://github.com/komal-2108/aurora/blob/main/optimizer/dispatch.py"
click node_state "https://github.com/komal-2108/aurora/blob/main/backend/app/services/state_service.py"
click node_store "https://github.com/komal-2108/aurora/blob/main/backend/app/core/database.py"
click node_weather "https://github.com/komal-2108/aurora/blob/main/backend/app/services/weather_service.py"
click node_reporting "https://github.com/komal-2108/aurora/blob/main/frontend/src/pages/ModulePages.jsx"
click node_alerts "https://github.com/komal-2108/aurora/blob/main/backend/app/api/routes/alerts.py"
click node_energy_services "https://github.com/komal-2108/aurora/tree/main/backend/app/services"

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_app,node_api_client,node_views,node_app_shell,node_reporting toneBlue
class node_fastapi,node_routes,node_alerts,node_energy_services toneAmber
class node_forecast_route,node_simulator,node_load_model,node_renewable_model toneMint
class node_optimization,node_dispatch_engine,node_state,node_store,node_weather toneRose
class node_operator,node_weather_provider toneIndigo
```

## Components

### User interface

- [AURORA app](https://github.com/komal-2108/aurora/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/komal-2108/aurora/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Product views](https://github.com/komal-2108/aurora/tree/main/frontend/src/pages): `frontend/src/pages`
- [App shell](https://github.com/komal-2108/aurora/blob/main/frontend/src/components/layout/AppShell.jsx): `frontend/src/components/layout/AppShell.jsx`
- [Reports and analytics](https://github.com/komal-2108/aurora/blob/main/frontend/src/pages/ModulePages.jsx): `frontend/src/pages/ModulePages.jsx`

### Application API

- [FastAPI entry](https://github.com/komal-2108/aurora/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/komal-2108/aurora/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Alerts and events](https://github.com/komal-2108/aurora/blob/main/backend/app/api/routes/alerts.py): `backend/app/api/routes/alerts.py`
- [Energy services](https://github.com/komal-2108/aurora/tree/main/backend/app/services): `backend/app/services`

### Forecasting

- [Forecast service](https://github.com/komal-2108/aurora/blob/main/backend/app/services/forecast_service.py): `backend/app/services/forecast_service.py`
- [Station simulator](https://github.com/komal-2108/aurora/blob/main/simulation/simulator.py): `simulation/simulator.py`
- [Load forecasting](https://github.com/komal-2108/aurora/tree/main/ml/load_forecasting): `ml/load_forecasting`
- [Renewable forecasting](https://github.com/komal-2108/aurora/tree/main/ml/renewable_forecasting): `ml/renewable_forecasting`

### Dispatch and state

- [Optimization service](https://github.com/komal-2108/aurora/blob/main/backend/app/services/optimization_service.py): `backend/app/services/optimization_service.py`
- [Dispatch engine](https://github.com/komal-2108/aurora/blob/main/optimizer/dispatch.py): `optimizer/dispatch.py`
- [Station state](https://github.com/komal-2108/aurora/blob/main/backend/app/services/state_service.py): `backend/app/services/state_service.py`
- [Run history store](https://github.com/komal-2108/aurora/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Weather service](https://github.com/komal-2108/aurora/blob/main/backend/app/services/weather_service.py): `backend/app/services/weather_service.py`

### Other components

- **Station operator**
- **Open-Meteo**

## Connections

- Station operator → AURORA app: uses
- AURORA app → API client: requests data
- AURORA app → Product views: renders
- AURORA app → App shell: wraps views
- API client → FastAPI entry: HTTP requests
- FastAPI entry → API routes: registers routers
- Optimization service → Forecast service: requests forecast
- Forecast service → Station simulator: reads station history
- Forecast service → Load forecasting: predicts load
- Forecast service → Renewable forecasting: predicts renewables
- Optimization service → Dispatch engine: optimizes dispatch
- Optimization service → Station state: reads and updates state
- Optimization service → Run history store: writes run history
- Optimization service → Run history store: reads run history
- Weather service → Open-Meteo: fetches conditions
- API routes → Alerts and events: serves alerts
- Product views → Reports and analytics: includes reports