# shashank101-aiml/maritime-control-tower architecture

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

- Interactive diagram: https://gitdiagram.com/shashank101-aiml/maritime-control-tower
- Repository: https://github.com/shashank101-aiml/maritime-control-tower

## Overview

Maritime Agentic Control System is a governed maritime logistics control tower. Operators use the React console to monitor vessels and events, analyze corridor risk, compare routes, and review recommendations; the backend workflow coordinates agents from ingestion through risk and routing to decisions and explanations. Human review, authorization, execution traces, and audit are governance capabilities alongside the main workflow. Separate capabilities cover fleet tracking, congestion, delay, fuel, and disruption simulation. The README documents these responsibilities; sampled source excerpts are partial, so the graph omits uncertain implementation-level links.

Main entry points: [`backend/app/workflows/maritime_workflow.py`](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/workflows/maritime_workflow.py) (Workflow coordinator), [`backend/app/agents/ingestion/ingestion_agent.py`](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/ingestion_agent.py) (Live ingestion), [`backend/app/agents/fleet/fleet_monitor_agent.py`](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/fleet/fleet_monitor_agent.py) (Fleet monitoring), [`backend/app/governance/core.py`](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/governance/core.py) (Agent governance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operator console"]
  node_console_app["React console<br/>[App.jsx]"]
  node_route_ui["Route planning"]
  node_route_client["Route service<br/>[routeService.js]"]
end

subgraph group_api["API and workflow"]
  node_api_main["FastAPI app<br/>[main.py]"]
  node_workflow_api["Workflow endpoint<br/>[workflow.py]"]
  node_maritime_workflow["Workflow coordinator"]
end

subgraph group_agents["Maritime analysis"]
  node_ingestion["Live ingestion<br/>[ingestion_agent.py]"]
  node_live_conditions["Sea conditions"]
  node_ais["AIS positions<br/>[ais_client.py]"]
  node_risk["Risk scoring<br/>[risk_agent.py]"]
  node_route["Route optimization<br/>[route_agent.py]"]
  node_decision["Recommendation<br/>[decision_agent.py]"]
  node_explanation["Explanation"]
  node_event_understanding["News understanding"]
  node_simulation["What-if simulation"]
end

subgraph group_operations["Fleet and estimates"]
  node_congestion["Port congestion"]
  node_delay["Shipment delay<br/>[delay_agent.py]"]
  node_fuel["Fuel and emissions<br/>[fuel_agent.py]"]
  node_fleet["Fleet monitoring"]
  node_twin["Digital twin<br/>[digital_twin.py]"]
end

subgraph group_state["State and governance"]
  node_governance["Agent governance<br/>[core.py]"]
  node_audit["Audit and trace<br/>[audit.py]"]
  node_database[("Application database<br/>[session.py]")]
end

node_operator(("Operator"))
node_weather_service{{"Weather feed"}}
node_ais_service{{"AIS feed"}}
node_human_reviewer(("Human reviewer"))

node_operator -->|"uses"| node_console_app
node_console_app -->|"opens planning"| node_route_ui
node_route_ui -->|"requests options"| node_route_client
node_route_client -->|"calls API"| node_api_main
node_api_main -->|"dispatches routes"| node_workflow_api
node_workflow_api -->|"runs workflow"| node_maritime_workflow
node_maritime_workflow -->|"collects inputs"| node_ingestion
node_ingestion -->|"fetches conditions"| node_live_conditions
node_live_conditions -.->|"reads feed"| node_weather_service
node_maritime_workflow -->|"scores hazards"| node_risk
node_maritime_workflow -->|"ranks routes"| node_route
node_maritime_workflow -->|"forms recommendation"| node_decision
node_maritime_workflow -->|"explains result"| node_explanation
node_ingestion -.->|"collects positions"| node_ais
node_ais -.->|"reads positions"| node_ais_service
node_operator -->|"submits news"| node_event_understanding
node_operator -->|"requests scenario"| node_simulation
node_operator -->|"requests analysis"| node_congestion
node_operator -->|"requests estimate"| node_delay
node_operator -->|"requests estimate"| node_fuel
node_operator -->|"registers vessels"| node_fleet
node_fleet -.->|"tracks ships"| node_ais
node_route -->|"routes over"| node_twin
node_operator -->|"reviews action"| node_human_reviewer
node_human_reviewer -->|"approves or rejects"| node_governance
node_governance -->|"records execution"| node_audit
node_governance -->|"persists records"| node_database
node_fleet -->|"stores fleet data"| node_database

click node_console_app "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/frontend/src/App.jsx"
click node_route_ui "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/frontend/src/pages/RouteRecommendations.jsx"
click node_route_client "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/frontend/src/services/routeService.js"
click node_api_main "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/main.py"
click node_workflow_api "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/api/routes/workflow.py"
click node_maritime_workflow "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/workflows/maritime_workflow.py"
click node_ingestion "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/ingestion_agent.py"
click node_live_conditions "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/live_conditions_client.py"
click node_ais "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/ais_client.py"
click node_risk "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/risk/risk_agent.py"
click node_route "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/route/route_agent.py"
click node_decision "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/decision/decision_agent.py"
click node_explanation "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/explanation/explanation_agent.py"
click node_event_understanding "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/understanding/event_understanding_agent.py"
click node_simulation "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/simulation/simulation_agent.py"
click node_congestion "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/congestion/congestion_agent.py"
click node_delay "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/delay/delay_agent.py"
click node_fuel "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/fuel/fuel_agent.py"
click node_fleet "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/fleet/fleet_monitor_agent.py"
click node_twin "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/twin/digital_twin.py"
click node_governance "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/governance/core.py"
click node_audit "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/governance/audit.py"
click node_database "https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/database/session.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_console_app,node_route_ui,node_route_client,node_human_reviewer toneBlue
class node_api_main,node_workflow_api,node_maritime_workflow toneAmber
class node_ingestion,node_live_conditions,node_ais,node_risk,node_route,node_decision,node_explanation,node_event_understanding,node_simulation toneMint
class node_congestion,node_delay,node_fuel,node_fleet,node_twin toneRose
class node_governance,node_audit,node_database,node_operator,node_weather_service,node_ais_service toneIndigo
```

## Components

### Operator console

- [React console](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Route planning](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/frontend/src/pages/RouteRecommendations.jsx): `frontend/src/pages/RouteRecommendations.jsx`
- [Route service](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/frontend/src/services/routeService.js): `frontend/src/services/routeService.js`

### API and workflow

- [FastAPI app](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/main.py): `backend/app/main.py`
- [Workflow endpoint](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/api/routes/workflow.py): `backend/app/api/routes/workflow.py`
- [Workflow coordinator](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/workflows/maritime_workflow.py): `backend/app/workflows/maritime_workflow.py`

### Maritime analysis

- [Live ingestion](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/ingestion_agent.py): `backend/app/agents/ingestion/ingestion_agent.py`
- [Sea conditions](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/live_conditions_client.py): `backend/app/agents/ingestion/live_conditions_client.py`
- [AIS positions](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/ingestion/ais_client.py): `backend/app/agents/ingestion/ais_client.py`
- [Risk scoring](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/risk/risk_agent.py): `backend/app/agents/risk/risk_agent.py`
- [Route optimization](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/route/route_agent.py): `backend/app/agents/route/route_agent.py`
- [Recommendation](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/decision/decision_agent.py): `backend/app/agents/decision/decision_agent.py`
- [Explanation](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/explanation/explanation_agent.py): `backend/app/agents/explanation/explanation_agent.py`
- [News understanding](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/understanding/event_understanding_agent.py): `backend/app/agents/understanding/event_understanding_agent.py`
- [What-if simulation](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/simulation/simulation_agent.py): `backend/app/agents/simulation/simulation_agent.py`

### Fleet and estimates

- [Port congestion](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/congestion/congestion_agent.py): `backend/app/agents/congestion/congestion_agent.py`
- [Shipment delay](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/delay/delay_agent.py): `backend/app/agents/delay/delay_agent.py`
- [Fuel and emissions](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/fuel/fuel_agent.py): `backend/app/agents/fuel/fuel_agent.py`
- [Fleet monitoring](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/agents/fleet/fleet_monitor_agent.py): `backend/app/agents/fleet/fleet_monitor_agent.py`
- [Digital twin](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/twin/digital_twin.py): `backend/app/twin/digital_twin.py`

### State and governance

- [Agent governance](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/governance/core.py): `backend/app/governance/core.py`
- [Audit and trace](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/governance/audit.py): `backend/app/governance/audit.py`
- [Application database](https://github.com/shashank101-aiml/maritime-control-tower/blob/main/backend/app/database/session.py): `backend/app/database/session.py`

### Other components

- **Operator**
- **Weather feed**
- **AIS feed**
- **Human reviewer**

## Connections

- Operator → React console: uses
- React console → Route planning: opens planning
- Route planning → Route service: requests options
- Route service → FastAPI app: calls API
- FastAPI app → Workflow endpoint: dispatches routes
- Workflow endpoint → Workflow coordinator: runs workflow
- Workflow coordinator → Live ingestion: collects inputs
- Live ingestion → Sea conditions: fetches conditions
- Sea conditions → Weather feed: reads feed
- Workflow coordinator → Risk scoring: scores hazards
- Workflow coordinator → Route optimization: ranks routes
- Workflow coordinator → Recommendation: forms recommendation
- Workflow coordinator → Explanation: explains result
- Live ingestion → AIS positions: collects positions
- AIS positions → AIS feed: reads positions
- Operator → News understanding: submits news
- Operator → What-if simulation: requests scenario
- Operator → Port congestion: requests analysis
- Operator → Shipment delay: requests estimate
- Operator → Fuel and emissions: requests estimate
- Operator → Fleet monitoring: registers vessels
- Fleet monitoring → AIS positions: tracks ships
- Route optimization → Digital twin: routes over
- Operator → Human reviewer: reviews action
- Human reviewer → Agent governance: approves or rejects
- Agent governance → Audit and trace: records execution
- Agent governance → Application database: persists records
- Fleet monitoring → Application database: stores fleet data