# rynrindesu/portpilot architecture

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

- Interactive diagram: https://gitdiagram.com/rynrindesu/portpilot
- Repository: https://github.com/rynrindesu/portpilot

## Overview

PortPilot combines two independent operational services with a React console: one monitors arrivals and coordinates berth, pilot, and tug assignments; the other extracts vessel documents and manages compliance, risk, and inspection progression. The console presents both workflows and can use live APIs or deterministic demo data. The README documents the operating lifecycle and domain stages; source excerpts and the SOURCE INDEX confirm selected wiring, but several route and scheduling internals were not sampled, so uncertain links are omitted.

Main entry points: [`rescheduling_agent/src/PortPilot/monitoring/monitor_service.py`](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/monitor_service.py) (Arrival monitoring), [`frontend/src/pages`](https://github.com/rynrindesu/portpilot/tree/main/frontend/src/pages) (Operations screens), [`port_ops_agent/src/PortPilot/workflow/orchestrator.py`](https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/workflow/orchestrator.py) (Port-call workflow), [`frontend/src/App.tsx`](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/App.tsx) (Console routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operations console"]
  node_app["Console routes<br/>[App.tsx]"]
  node_console_data["Console data store<br/>[store.tsx]"]
  node_console_api["Console API client<br/>[api.ts]"]
  node_ops_views["Operations screens"]
  node_format["Time and value formatting<br/>[format.ts]"]
  node_ui["Shared UI components<br/>[ui.tsx]"]
  node_timeline["Berth timeline<br/>[BerthTimeline.tsx]"]
end

subgraph group_reschedule["Arrival rescheduling"]
  node_oceans["OCEANS-X arrivals<br/>[oceans.py]"]
  node_monitor["Arrival monitoring<br/>[monitor_service.py]"]
  node_scheduler["Operating-day scheduler<br/>[scheduler.py]"]
  node_lifecycle["Lifecycle recovery<br/>[lifecycle.py]"]
  node_schedule_agent["Rescheduling agent<br/>[graph.py]"]
  node_options["Scheduling options and rules"]
  node_postgres[("Operations database<br/>[postgres.py]")]
end

subgraph group_portops["Port-call compliance"]
  node_doc_processing["Document extraction and validation"]
  node_compliance_route["Compliance and port-call routes"]
  node_workflow["Port-call workflow<br/>[orchestrator.py]"]
  node_compliance["Compliance checks<br/>[engine.py]"]
  node_risk_inspection["Risk and inspection decisions"]
  node_port_state["Port-call state<br/>[state.py]"]
  node_port_agent["Port-ops agent<br/>[agent.py]"]
end

subgraph group_shared["Service APIs"]
  node_res_api["Rescheduling API"]
  node_port_api["Port-ops API"]
end

node_operator(("Port operator"))

node_operator -->|"uses"| node_app
node_app -->|"routes to"| node_ops_views
node_app -->|"provides data"| node_console_data
node_console_data -->|"fetches"| node_console_api
node_ops_views -->|"reads"| node_console_data
node_ops_views -->|"renders"| node_ui
node_ops_views -->|"formats with"| node_format
node_ops_views -->|"renders"| node_timeline
node_console_api -.->|"requests"| node_res_api
node_console_api -.->|"requests"| node_port_api
node_res_api -->|"routes monitoring"| node_monitor
node_port_api -.->|"routes workflow"| node_workflow
node_scheduler -->|"runs lifecycle polls"| node_monitor
node_scheduler -.->|"schedules stages"| node_lifecycle
node_monitor -->|"fetches arrivals"| node_oceans
node_monitor -->|"reads and writes"| node_postgres
node_monitor -->|"requests rescheduling"| node_schedule_agent
node_monitor -->|"generates options"| node_options
node_workflow -->|"runs checks"| node_compliance
node_workflow -->|"evaluates decisions"| node_risk_inspection
node_workflow -.->|"updates state"| node_port_state
node_port_agent -->|"invokes workflow"| node_workflow
node_compliance_route -->|"runs checks"| node_compliance
node_compliance_route -.->|"accepts documents"| node_doc_processing
node_doc_processing -.->|"supplies extracted data"| node_compliance

click node_app "https://github.com/rynrindesu/portpilot/blob/main/frontend/src/App.tsx"
click node_console_data "https://github.com/rynrindesu/portpilot/blob/main/frontend/src/lib/store.tsx"
click node_console_api "https://github.com/rynrindesu/portpilot/blob/main/frontend/src/lib/api.ts"
click node_ops_views "https://github.com/rynrindesu/portpilot/tree/main/frontend/src/pages"
click node_format "https://github.com/rynrindesu/portpilot/blob/main/frontend/src/lib/format.ts"
click node_ui "https://github.com/rynrindesu/portpilot/blob/main/frontend/src/components/ui.tsx"
click node_timeline "https://github.com/rynrindesu/portpilot/blob/main/frontend/src/components/BerthTimeline.tsx"
click node_res_api "https://github.com/rynrindesu/portpilot/tree/main/rescheduling_agent/src/PortPilot/api/routes"
click node_port_api "https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/api/routes"
click node_oceans "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/integration/oceans.py"
click node_monitor "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/monitor_service.py"
click node_scheduler "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/scheduler.py"
click node_lifecycle "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/lifecycle.py"
click node_schedule_agent "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/agent/graph.py"
click node_options "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/agent/schedule_option_generator.py"
click node_postgres "https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/database/postgres.py"
click node_doc_processing "https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/documents"
click node_compliance_route "https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/api/routes"
click node_workflow "https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/workflow/orchestrator.py"
click node_compliance "https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/compliance/engine.py"
click node_risk_inspection "https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/compliance"
click node_port_state "https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/workflow/state.py"
click node_port_agent "https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/agent/agent.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_console_data,node_console_api,node_ops_views,node_format,node_ui,node_timeline toneBlue
class node_oceans,node_monitor,node_scheduler,node_lifecycle,node_schedule_agent,node_options,node_postgres toneAmber
class node_doc_processing,node_compliance_route,node_workflow,node_compliance,node_risk_inspection,node_port_state,node_port_agent toneMint
class node_res_api,node_port_api toneRose
class node_operator toneIndigo
```

## Components

### Operations console

- [Console routes](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Console data store](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/lib/store.tsx): `frontend/src/lib/store.tsx`
- [Console API client](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Operations screens](https://github.com/rynrindesu/portpilot/tree/main/frontend/src/pages): `frontend/src/pages`
- [Time and value formatting](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/lib/format.ts): `frontend/src/lib/format.ts`
- [Shared UI components](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/components/ui.tsx): `frontend/src/components/ui.tsx`
- [Berth timeline](https://github.com/rynrindesu/portpilot/blob/main/frontend/src/components/BerthTimeline.tsx): `frontend/src/components/BerthTimeline.tsx`

### Arrival rescheduling

- [OCEANS-X arrivals](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/integration/oceans.py): `rescheduling_agent/src/PortPilot/integration/oceans.py`
- [Arrival monitoring](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/monitor_service.py): `rescheduling_agent/src/PortPilot/monitoring/monitor_service.py`
- [Operating-day scheduler](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/scheduler.py): `rescheduling_agent/src/PortPilot/monitoring/scheduler.py`
- [Lifecycle recovery](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/monitoring/lifecycle.py): `rescheduling_agent/src/PortPilot/monitoring/lifecycle.py`
- [Rescheduling agent](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/agent/graph.py): `rescheduling_agent/src/PortPilot/agent/graph.py`
- [Scheduling options and rules](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/agent/schedule_option_generator.py): `rescheduling_agent/src/PortPilot/agent/schedule_option_generator.py`
- [Operations database](https://github.com/rynrindesu/portpilot/blob/main/rescheduling_agent/src/PortPilot/database/postgres.py): `rescheduling_agent/src/PortPilot/database/postgres.py`

### Port-call compliance

- [Document extraction and validation](https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/documents): `port_ops_agent/src/PortPilot/documents`
- [Compliance and port-call routes](https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/api/routes): `port_ops_agent/src/PortPilot/api/routes`
- [Port-call workflow](https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/workflow/orchestrator.py): `port_ops_agent/src/PortPilot/workflow/orchestrator.py`
- [Compliance checks](https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/compliance/engine.py): `port_ops_agent/src/PortPilot/compliance/engine.py`
- [Risk and inspection decisions](https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/compliance): `port_ops_agent/src/PortPilot/compliance`
- [Port-call state](https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/workflow/state.py): `port_ops_agent/src/PortPilot/workflow/state.py`
- [Port-ops agent](https://github.com/rynrindesu/portpilot/blob/main/port_ops_agent/src/PortPilot/agent/agent.py): `port_ops_agent/src/PortPilot/agent/agent.py`

### Service APIs

- [Rescheduling API](https://github.com/rynrindesu/portpilot/tree/main/rescheduling_agent/src/PortPilot/api/routes): `rescheduling_agent/src/PortPilot/api/routes`
- [Port-ops API](https://github.com/rynrindesu/portpilot/tree/main/port_ops_agent/src/PortPilot/api/routes): `port_ops_agent/src/PortPilot/api/routes`

### Other components

- **Port operator**

## Connections

- Port operator → Console routes: uses (evidence: `README.md`)
- Console routes → Operations screens: routes to (evidence: `frontend/src/App.tsx`)
- Console routes → Console data store: provides data (evidence: `frontend/src/App.tsx`)
- Console data store → Console API client: fetches (evidence: `frontend/src/lib/store.tsx`)
- Operations screens → Console data store: reads (evidence: `frontend/src/pages/PortCallDetail.tsx`)
- Operations screens → Shared UI components: renders (evidence: `frontend/src/pages/PortCallDetail.tsx`)
- Operations screens → Time and value formatting: formats with (evidence: `frontend/src/pages/PortCallDetail.tsx`)
- Operations screens → Berth timeline: renders (evidence: `frontend/src/pages/Overview.tsx`)
- Console API client → Rescheduling API: requests
- Console API client → Port-ops API: requests
- Rescheduling API → Arrival monitoring: routes monitoring (evidence: `rescheduling_agent/src/PortPilot/api/routes/monitoring.py`)
- Port-ops API → Port-call workflow: routes workflow
- Operating-day scheduler → Arrival monitoring: runs lifecycle polls (evidence: `README.md`)
- Operating-day scheduler → Lifecycle recovery: schedules stages
- Arrival monitoring → OCEANS-X arrivals: fetches arrivals (evidence: `rescheduling_agent/src/PortPilot/monitoring/monitor_service.py`)
- Arrival monitoring → Operations database: reads and writes (evidence: `rescheduling_agent/src/PortPilot/monitoring/monitor_service.py`)
- Arrival monitoring → Rescheduling agent: requests rescheduling (evidence: `README.md`)
- Arrival monitoring → Scheduling options and rules: generates options (evidence: `README.md`)
- Port-call workflow → Compliance checks: runs checks (evidence: `port_ops_agent/src/PortPilot/workflow/orchestrator.py`)
- Port-call workflow → Risk and inspection decisions: evaluates decisions (evidence: `port_ops_agent/src/PortPilot/workflow/orchestrator.py`)
- Port-call workflow → Port-call state: updates state (evidence: `port_ops_agent/src/PortPilot/workflow/orchestrator.py`)
- Port-ops agent → Port-call workflow: invokes workflow
- Compliance and port-call routes → Compliance checks: runs checks (evidence: `port_ops_agent/src/PortPilot/api/routes/compliance_demo.py`)
- Compliance and port-call routes → Document extraction and validation: accepts documents
- Document extraction and validation → Compliance checks: supplies extracted data