# archi-mukh-64/aether-moil-prototype architecture

> Architecture diagram of the GitHub repository archi-mukh-64/aether-moil-prototype, 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/archi-mukh-64/aether-moil-prototype
- Repository: https://github.com/archi-mukh-64/aether-moil-prototype

## Overview

MOIL is a mining intelligence command center for mine operators and leadership. Its user workflow runs from selecting a mine or stress scenario in the React workspace, through alerting, risk analysis, forecasting and recommended operational response, to dashboards, decision records and reports. Separate branches cover equipment health, anomaly detection, exploration and reserve prospectivity, national mine comparisons, telemetry, and AI trust. The README documents the six engines and backend gateway; sampled excerpts confirm selected forecast, exploration, national-radar and composite-risk behavior. Unsampled route-to-service details are represented only at the documented gateway boundary.

Main entry points: [`frontend/src/App.jsx`](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/App.jsx) (Application shell), [`frontend/src/services/api/apiClient.js`](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/services/api/apiClient.js) (API client), [`backend/main.py`](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/main.py) (FastAPI gateway), [`backend/database/database.py`](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/database/database.py) (Operational database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Command Center"]
  node_app["Application shell<br/>[App.jsx]"]
  node_workspace["Mine workspace"]
  node_alert_ui["Alert center"]
  node_scenario_ui["Scenario lab"]
  node_earth_ui["Reserve radar"]
  node_reports_ui["Reports<br/>[ReportsPage.jsx]"]
  node_api_client["API client<br/>[apiClient.js]"]
end

subgraph group_api["API Gateway"]
  node_backend["FastAPI gateway<br/>[main.py]"]
  node_alert_route["Alert &amp; forecast APIs<br/>[alert.py]"]
  node_scenario_route["Scenario &amp; protocol APIs<br/>[scenarios.py]"]
  node_earth_route["Earth &amp; reserve APIs<br/>[reserve.py]"]
  node_report_route["Report APIs<br/>[reports.py]"]
end

subgraph group_operations["Operational Intelligence"]
  node_operational["Risk, forecast &amp; anomaly"]
  node_equipment["Equipment health"]
  node_scenario["Prescriptive response"]
end

subgraph group_earth["Earth &amp; Strategy"]
  node_exploration["Exploration targeting"]
  node_national["National mine radar"]
  node_reporting["PDF/PPT reporting"]
end

subgraph group_state["State &amp; Governance"]
  node_trust["AI trust governance<br/>[trust_engine.py]"]
  node_multirisk["Composite risk engine"]
  node_database[("Operational database<br/>[database.py]")]
end

node_operator(("Mine operator"))
node_telemetry(("Mine telemetry"))
node_earth_data(("Satellite &amp; geology data"))

node_operator -->|"uses"| node_app
node_app -->|"opens"| node_workspace
node_app -->|"navigates"| node_alert_ui
node_app -->|"navigates"| node_scenario_ui
node_app -->|"navigates"| node_earth_ui
node_app -->|"navigates"| node_reports_ui
node_workspace -->|"requests data"| node_api_client
node_alert_ui -->|"requests forecasts"| node_api_client
node_scenario_ui -->|"submits scenarios"| node_api_client
node_earth_ui -->|"requests targets"| node_api_client
node_reports_ui -->|"requests reports"| node_api_client
node_api_client -->|"REST requests"| node_backend
node_backend -->|"dispatches"| node_alert_route
node_backend -->|"dispatches"| node_scenario_route
node_backend -->|"dispatches"| node_earth_route
node_backend -->|"dispatches"| node_report_route
node_alert_route -->|"invokes"| node_operational
node_operational -->|"evaluates risk"| node_multirisk
node_multirisk -->|"calculates trust"| node_trust
node_scenario_route -->|"invokes"| node_scenario
node_earth_route -->|"invokes"| node_exploration
node_earth_route -->|"invokes"| node_national
node_report_route -->|"generates reports"| node_reporting
node_telemetry -.->|"supplies signals"| node_equipment
node_earth_data -.->|"informs targets"| node_exploration
node_operational -->|"reads/writes"| node_database
node_equipment -->|"reads/writes"| node_database
node_scenario -->|"reads/writes"| node_database
node_reporting -->|"reads records"| node_database

click node_app "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/App.jsx"
click node_workspace "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/CommandCenterPage.jsx"
click node_alert_ui "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/AlertEnginePage.jsx"
click node_scenario_ui "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/ScenarioLabPage.jsx"
click node_earth_ui "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/ReserveRadarPage.jsx"
click node_reports_ui "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/ReportsPage.jsx"
click node_api_client "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/services/api/apiClient.js"
click node_backend "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/main.py"
click node_alert_route "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/alert.py"
click node_scenario_route "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/scenarios.py"
click node_earth_route "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/reserve.py"
click node_report_route "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/reports.py"
click node_operational "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/forecast_service.py"
click node_equipment "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/equipment_service.py"
click node_scenario "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/protocol_service.py"
click node_exploration "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/exploration_engine.py"
click node_national "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/national_radar_engine.py"
click node_reporting "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/pdf_report_service.py"
click node_trust "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/models/trust/trust_engine.py"
click node_multirisk "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/models/common/multi_risk_engine.py"
click node_database "https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/database/database.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_app,node_workspace,node_alert_ui,node_scenario_ui,node_earth_ui,node_reports_ui,node_api_client toneBlue
class node_backend,node_alert_route,node_scenario_route,node_earth_route,node_report_route toneAmber
class node_operational,node_equipment,node_scenario toneMint
class node_exploration,node_national,node_reporting toneRose
class node_trust,node_multirisk,node_database,node_operator,node_telemetry,node_earth_data toneIndigo
```

## Components

### Command Center

- [Application shell](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Mine workspace](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/CommandCenterPage.jsx): `frontend/src/pages/CommandCenterPage.jsx`
- [Alert center](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/AlertEnginePage.jsx): `frontend/src/pages/AlertEnginePage.jsx`
- [Scenario lab](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/ScenarioLabPage.jsx): `frontend/src/pages/ScenarioLabPage.jsx`
- [Reserve radar](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/ReserveRadarPage.jsx): `frontend/src/pages/ReserveRadarPage.jsx`
- [Reports](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/pages/ReportsPage.jsx): `frontend/src/pages/ReportsPage.jsx`
- [API client](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/frontend/src/services/api/apiClient.js): `frontend/src/services/api/apiClient.js`

### API Gateway

- [FastAPI gateway](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/main.py): `backend/main.py`
- [Alert & forecast APIs](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/alert.py): `backend/routes/alert.py`
- [Scenario & protocol APIs](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/scenarios.py): `backend/routes/scenarios.py`
- [Earth & reserve APIs](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/reserve.py): `backend/routes/reserve.py`
- [Report APIs](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/routes/reports.py): `backend/routes/reports.py`

### Operational Intelligence

- [Risk, forecast & anomaly](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/forecast_service.py): `backend/services/forecast_service.py`
- [Equipment health](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/equipment_service.py): `backend/services/equipment_service.py`
- [Prescriptive response](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/protocol_service.py): `backend/services/protocol_service.py`

### Earth & Strategy

- [Exploration targeting](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/exploration_engine.py): `backend/services/exploration_engine.py`
- [National mine radar](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/national_radar_engine.py): `backend/services/national_radar_engine.py`
- [PDF/PPT reporting](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/services/pdf_report_service.py): `backend/services/pdf_report_service.py`

### State & Governance

- [AI trust governance](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/models/trust/trust_engine.py): `models/trust/trust_engine.py`
- [Composite risk engine](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/models/common/multi_risk_engine.py): `models/common/multi_risk_engine.py`
- [Operational database](https://github.com/archi-mukh-64/aether-moil-prototype/blob/main/backend/database/database.py): `backend/database/database.py`

### Other components

- **Mine operator**
- **Mine telemetry**
- **Satellite & geology data**

## Connections

- Mine operator → Application shell: uses
- Application shell → Mine workspace: opens
- Application shell → Alert center: navigates
- Application shell → Scenario lab: navigates
- Application shell → Reserve radar: navigates
- Application shell → Reports: navigates
- Mine workspace → API client: requests data
- Alert center → API client: requests forecasts
- Scenario lab → API client: submits scenarios
- Reserve radar → API client: requests targets
- Reports → API client: requests reports
- API client → FastAPI gateway: REST requests
- FastAPI gateway → Alert & forecast APIs: dispatches
- FastAPI gateway → Scenario & protocol APIs: dispatches
- FastAPI gateway → Earth & reserve APIs: dispatches
- FastAPI gateway → Report APIs: dispatches
- Alert & forecast APIs → Risk, forecast & anomaly: invokes
- Risk, forecast & anomaly → Composite risk engine: evaluates risk
- Composite risk engine → AI trust governance: calculates trust
- Scenario & protocol APIs → Prescriptive response: invokes
- Earth & reserve APIs → Exploration targeting: invokes
- Earth & reserve APIs → National mine radar: invokes
- Report APIs → PDF/PPT reporting: generates reports
- Mine telemetry → Equipment health: supplies signals
- Satellite & geology data → Exploration targeting: informs targets
- Risk, forecast & anomaly → Operational database: reads/writes
- Equipment health → Operational database: reads/writes
- Prescriptive response → Operational database: reads/writes
- PDF/PPT reporting → Operational database: reads records