# anh-08/penumbra architecture

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

- Interactive diagram: https://gitdiagram.com/anh-08/penumbra
- Repository: https://github.com/anh-08/penumbra

## Overview

Penumbra is a satellite mission-operations simulator: an incident produces telemetry and alerts, an AI agent diagnoses and proposes recovery plans, physics checks plans across plausible faults, and flight rules or an operator authorize execution. The API streams the evolving fleet state and decision trace to an interactive operations UI. The graph retains documented orbit, voice, anatomy, Monte Carlo, replay, and scheduling capabilities. Some subsystem links are documented in the README rather than visible in sampled implementation; those are marked accordingly.

Main entry points: [`backend/agent/dispatcher.py`](https://github.com/anh-08/penumbra/blob/main/backend/agent/dispatcher.py) (Tool Dispatcher), [`backend/api/app.py`](https://github.com/anh-08/penumbra/blob/main/backend/api/app.py) (FastAPI and WebSocket), [`backend/fleet/scenarios.py`](https://github.com/anh-08/penumbra/blob/main/backend/fleet/scenarios.py) (Incident Scenarios), [`backend/agent/session.py`](https://github.com/anh-08/penumbra/blob/main/backend/agent/session.py) (Recorded Agent Run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_world["Orbit and Simulation"]
  node_incident["Incident Scenarios<br/>[scenarios.py]"]
  node_orbits["Orbit Environment<br/>[eclipse.py]"]
  node_eps["Power Simulation<br/>[truth.py]"]
  node_faults["Fault Models<br/>[faults.py]"]
end

subgraph group_ops["Fleet Operations"]
  node_detect["Detection and Triage<br/>[detect.py]"]
  node_fleet["Fleet Backend<br/>[backend.py]"]
  node_scheduler["Uplink Scheduler<br/>[scheduler.py]"]
  node_approval["Flight Rules and Approval<br/>[flight_rules.py]"]
end

subgraph group_agent["Agent and Verification"]
  node_agentloop["Agent Loop<br/>[loop.py]"]
  node_dispatcher["Tool Dispatcher<br/>[dispatcher.py]"]
  node_gemini["Gemini Model<br/>[gemini.py]"]
  node_safety["Safety Checks<br/>[safety.py]"]
  node_planning["Plan Model<br/>[planning.py]"]
  node_verifier["Monte Carlo Verifier<br/>[verifier.py]"]
  node_scoring["Hypothesis Scoring<br/>[scoring.py]"]
end

subgraph group_service["API and Flight Records"]
  node_recorder[("Flight Recorder and Replay<br/>[flight.py]")]
  node_session["Recorded Agent Run<br/>[session.py]"]
  node_api["FastAPI and WebSocket<br/>[app.py]"]
  node_storm["Fault-Storm Director<br/>[storm.py]"]
  node_voice["Voice Commands<br/>[voice_command.py]"]
end

subgraph group_ui["Operator Interface"]
  node_frontend["Operations Dashboard<br/>[App.jsx]"]
  node_matrix["Plan Matrix<br/>[Matrix.jsx]"]
  node_anatomy["Satellite Anatomy<br/>[AnatomyView.jsx]"]
  node_mcview["Monte Carlo View"]
end

node_operator(("Mission Operator"))

node_operator -->|"starts incident"| node_api
node_api -->|"creates scenario"| node_incident
node_incident -->|"builds environment"| node_orbits
node_incident -->|"initializes world"| node_eps
node_incident -->|"supplies faults"| node_faults
node_eps -.->|"provides telemetry"| node_fleet
node_fleet -.->|"supports triage"| node_detect
node_detect -->|"initiates diagnosis"| node_agentloop
node_agentloop -->|"queries model"| node_gemini
node_agentloop -->|"dispatches tools"| node_dispatcher
node_dispatcher -->|"checks actions"| node_safety
node_dispatcher -->|"scores causes"| node_scoring
node_dispatcher -->|"builds plans"| node_planning
node_dispatcher -.->|"simulates plans"| node_verifier
node_verifier -->|"evaluates plans"| node_planning
node_dispatcher -->|"books uplinks"| node_scheduler
node_dispatcher -.->|"requests approval"| node_approval
node_operator -->|"approves plan"| node_approval
node_session -->|"runs agent"| node_agentloop
node_session -->|"provides dispatcher"| node_dispatcher
node_session -->|"records events"| node_recorder
node_api -->|"starts storm"| node_storm
node_storm -->|"runs agent"| node_session
node_api -->|"handles voice request"| node_voice
node_voice -->|"resolves incident"| node_incident
node_api -->|"streams fleet state"| node_frontend
node_frontend -->|"renders plans"| node_matrix
node_frontend -->|"renders anatomy"| node_anatomy
node_frontend -.->|"shows simulations"| node_mcview
node_recorder -->|"replays runs"| node_session

click node_incident "https://github.com/anh-08/penumbra/blob/main/backend/fleet/scenarios.py"
click node_orbits "https://github.com/anh-08/penumbra/blob/main/backend/orbit/eclipse.py"
click node_eps "https://github.com/anh-08/penumbra/blob/main/backend/eps/truth.py"
click node_faults "https://github.com/anh-08/penumbra/blob/main/backend/eps/faults.py"
click node_detect "https://github.com/anh-08/penumbra/blob/main/backend/fleet/detect.py"
click node_fleet "https://github.com/anh-08/penumbra/blob/main/backend/fleet/backend.py"
click node_agentloop "https://github.com/anh-08/penumbra/blob/main/backend/agent/loop.py"
click node_dispatcher "https://github.com/anh-08/penumbra/blob/main/backend/agent/dispatcher.py"
click node_gemini "https://github.com/anh-08/penumbra/blob/main/backend/agent/gemini.py"
click node_safety "https://github.com/anh-08/penumbra/blob/main/backend/agent/safety.py"
click node_planning "https://github.com/anh-08/penumbra/blob/main/backend/eps/planning.py"
click node_verifier "https://github.com/anh-08/penumbra/blob/main/backend/verify/verifier.py"
click node_scoring "https://github.com/anh-08/penumbra/blob/main/backend/verify/scoring.py"
click node_scheduler "https://github.com/anh-08/penumbra/blob/main/backend/sched/scheduler.py"
click node_approval "https://github.com/anh-08/penumbra/blob/main/backend/fleet/flight_rules.py"
click node_recorder "https://github.com/anh-08/penumbra/blob/main/backend/recorder/flight.py"
click node_session "https://github.com/anh-08/penumbra/blob/main/backend/agent/session.py"
click node_api "https://github.com/anh-08/penumbra/blob/main/backend/api/app.py"
click node_storm "https://github.com/anh-08/penumbra/blob/main/backend/api/storm.py"
click node_voice "https://github.com/anh-08/penumbra/blob/main/backend/api/voice_command.py"
click node_frontend "https://github.com/anh-08/penumbra/blob/main/frontend/src/App.jsx"
click node_matrix "https://github.com/anh-08/penumbra/blob/main/frontend/src/Matrix.jsx"
click node_anatomy "https://github.com/anh-08/penumbra/blob/main/frontend/src/anatomy/AnatomyView.jsx"
click node_mcview "https://github.com/anh-08/penumbra/blob/main/frontend/src/montecarlo/MonteCarloOverlay.jsx"

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_incident,node_orbits,node_eps,node_faults toneBlue
class node_detect,node_fleet,node_scheduler,node_approval toneAmber
class node_agentloop,node_dispatcher,node_gemini,node_safety,node_planning,node_verifier,node_scoring toneMint
class node_recorder,node_session,node_api,node_storm,node_voice toneRose
class node_frontend,node_matrix,node_anatomy,node_mcview,node_operator toneIndigo
```

## Components

### Orbit and Simulation

- [Incident Scenarios](https://github.com/anh-08/penumbra/blob/main/backend/fleet/scenarios.py): `backend/fleet/scenarios.py`
- [Orbit Environment](https://github.com/anh-08/penumbra/blob/main/backend/orbit/eclipse.py): `backend/orbit/eclipse.py`
- [Power Simulation](https://github.com/anh-08/penumbra/blob/main/backend/eps/truth.py): `backend/eps/truth.py`
- [Fault Models](https://github.com/anh-08/penumbra/blob/main/backend/eps/faults.py): `backend/eps/faults.py`

### Fleet Operations

- [Detection and Triage](https://github.com/anh-08/penumbra/blob/main/backend/fleet/detect.py): `backend/fleet/detect.py`
- [Fleet Backend](https://github.com/anh-08/penumbra/blob/main/backend/fleet/backend.py): `backend/fleet/backend.py`
- [Uplink Scheduler](https://github.com/anh-08/penumbra/blob/main/backend/sched/scheduler.py): `backend/sched/scheduler.py`
- [Flight Rules and Approval](https://github.com/anh-08/penumbra/blob/main/backend/fleet/flight_rules.py): `backend/fleet/flight_rules.py`

### Agent and Verification

- [Agent Loop](https://github.com/anh-08/penumbra/blob/main/backend/agent/loop.py): `backend/agent/loop.py`
- [Tool Dispatcher](https://github.com/anh-08/penumbra/blob/main/backend/agent/dispatcher.py): `backend/agent/dispatcher.py`
- [Gemini Model](https://github.com/anh-08/penumbra/blob/main/backend/agent/gemini.py): `backend/agent/gemini.py`
- [Safety Checks](https://github.com/anh-08/penumbra/blob/main/backend/agent/safety.py): `backend/agent/safety.py`
- [Plan Model](https://github.com/anh-08/penumbra/blob/main/backend/eps/planning.py): `backend/eps/planning.py`
- [Monte Carlo Verifier](https://github.com/anh-08/penumbra/blob/main/backend/verify/verifier.py): `backend/verify/verifier.py`
- [Hypothesis Scoring](https://github.com/anh-08/penumbra/blob/main/backend/verify/scoring.py): `backend/verify/scoring.py`

### API and Flight Records

- [Flight Recorder and Replay](https://github.com/anh-08/penumbra/blob/main/backend/recorder/flight.py): `backend/recorder/flight.py`
- [Recorded Agent Run](https://github.com/anh-08/penumbra/blob/main/backend/agent/session.py): `backend/agent/session.py`
- [FastAPI and WebSocket](https://github.com/anh-08/penumbra/blob/main/backend/api/app.py): `backend/api/app.py`
- [Fault-Storm Director](https://github.com/anh-08/penumbra/blob/main/backend/api/storm.py): `backend/api/storm.py`
- [Voice Commands](https://github.com/anh-08/penumbra/blob/main/backend/api/voice_command.py): `backend/api/voice_command.py`

### Operator Interface

- [Operations Dashboard](https://github.com/anh-08/penumbra/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Plan Matrix](https://github.com/anh-08/penumbra/blob/main/frontend/src/Matrix.jsx): `frontend/src/Matrix.jsx`
- [Satellite Anatomy](https://github.com/anh-08/penumbra/blob/main/frontend/src/anatomy/AnatomyView.jsx): `frontend/src/anatomy/AnatomyView.jsx`
- [Monte Carlo View](https://github.com/anh-08/penumbra/blob/main/frontend/src/montecarlo/MonteCarloOverlay.jsx): `frontend/src/montecarlo/MonteCarloOverlay.jsx`

### Other components

- **Mission Operator**

## Connections

- Mission Operator → FastAPI and WebSocket: starts incident (evidence: `README.md`)
- FastAPI and WebSocket → Incident Scenarios: creates scenario (evidence: `backend/api/app.py`)
- Incident Scenarios → Orbit Environment: builds environment (evidence: `backend/fleet/scenarios.py`)
- Incident Scenarios → Power Simulation: initializes world (evidence: `backend/fleet/scenarios.py`)
- Incident Scenarios → Fault Models: supplies faults (evidence: `backend/fleet/scenarios.py`)
- Power Simulation → Fleet Backend: provides telemetry
- Fleet Backend → Detection and Triage: supports triage
- Detection and Triage → Agent Loop: initiates diagnosis (evidence: `README.md`)
- Agent Loop → Gemini Model: queries model (evidence: `backend/agent/loop.py`)
- Agent Loop → Tool Dispatcher: dispatches tools (evidence: `backend/agent/loop.py`)
- Tool Dispatcher → Safety Checks: checks actions (evidence: `backend/agent/dispatcher.py`)
- Tool Dispatcher → Hypothesis Scoring: scores causes (evidence: `backend/agent/dispatcher.py`)
- Tool Dispatcher → Plan Model: builds plans (evidence: `backend/agent/dispatcher.py`)
- Tool Dispatcher → Monte Carlo Verifier: simulates plans
- Monte Carlo Verifier → Plan Model: evaluates plans (evidence: `backend/verify/verifier.py`)
- Tool Dispatcher → Uplink Scheduler: books uplinks (evidence: `README.md`)
- Tool Dispatcher → Flight Rules and Approval: requests approval
- Mission Operator → Flight Rules and Approval: approves plan (evidence: `README.md`)
- Recorded Agent Run → Agent Loop: runs agent (evidence: `backend/agent/session.py`)
- Recorded Agent Run → Tool Dispatcher: provides dispatcher (evidence: `backend/agent/session.py`)
- Recorded Agent Run → Flight Recorder and Replay: records events (evidence: `backend/agent/session.py`)
- FastAPI and WebSocket → Fault-Storm Director: starts storm (evidence: `backend/api/app.py`)
- Fault-Storm Director → Recorded Agent Run: runs agent (evidence: `backend/api/storm.py`)
- FastAPI and WebSocket → Voice Commands: handles voice request (evidence: `backend/api/app.py`)
- Voice Commands → Incident Scenarios: resolves incident (evidence: `backend/api/voice_command.py`)
- FastAPI and WebSocket → Operations Dashboard: streams fleet state (evidence: `README.md`)
- Operations Dashboard → Plan Matrix: renders plans (evidence: `frontend/src/App.jsx`)
- Operations Dashboard → Satellite Anatomy: renders anatomy (evidence: `frontend/src/App.jsx`)
- Operations Dashboard → Monte Carlo View: shows simulations (evidence: `frontend/src/App.jsx`)
- Flight Recorder and Replay → Recorded Agent Run: replays runs (evidence: `backend/recorder/flight.py`)
