# lordmarss/shipment-navigator architecture

> Architecture diagram of the GitHub repository lordmarss/shipment-navigator, 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/lordmarss/shipment-navigator
- Repository: https://github.com/lordmarss/shipment-navigator

## Overview

Shipment Navigator is a shipment operations web app: users create and manage shipment records, review documents and status history, and monitor fleet movement, alerts, and analytics. Its runtime has grown beyond the README’s initial manual-tracking specification: the source index identifies AIS ingestion and automated lifecycle decisions as substantial capabilities. The graph separates the UI, shipment lifecycle, fleet intelligence, and persistence/integration layers. Some route and automation internals are unsampled; only documented or indexed relationships are shown.

Main entry points: [`src/lib/api.ts`](https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/api.ts) (Data Access), [`src/routes/map.tsx`](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/map.tsx) (Fleet Map), [`src/routes/index.tsx`](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/index.tsx) (Dashboard), [`src/components/maritime/useFleet.ts`](https://github.com/lordmarss/shipment-navigator/blob/main/src/components/maritime/useFleet.ts) (Fleet Queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_dashboard["Dashboard<br/>[index.tsx]"]
  node_shell["App Shell<br/>[AppShell.tsx]"]
  node_analytics["Analytics<br/>[analytics.tsx]"]
  node_settings["Settings<br/>[settings.tsx]"]
end

subgraph group_shipments["Shipment Lifecycle"]
  node_shipment_detail["Shipment Detail<br/>[shipments.$id.tsx]"]
  node_new_shipment["New Shipment Form"]
  node_documents["Documents<br/>[documents.tsx]"]
  node_alerts["Alerts<br/>[alerts.tsx]"]
end

subgraph group_fleet["Fleet Intelligence"]
  node_map["Fleet Map<br/>[map.tsx]"]
  node_vessels["Vessels<br/>[vessels.tsx]"]
  node_fleet_hook["Fleet Queries<br/>[useFleet.ts]"]
  node_monitoring_config["Monitoring Config"]
  node_lifecycle["Lifecycle Rules<br/>[lifecycle.ts]"]
  node_ais_decisions["AIS Decisions<br/>[aisAutomation.ts]"]
  node_position_hook["AIS Position Ingest"]
end

subgraph group_data["Data and Integrations"]
  node_position_hook_route["AIS Position Hook<br/>[ais-position.ts]"]
  node_automation_route["Automation Hook<br/>[automation-run.ts]"]
  node_automation_runner["Automation Runner"]
  node_api["Data Access<br/>[api.ts]"]
  node_supabase["Supabase<br/>[client.ts]"]
  node_database[("Supabase Database")]
end

node_operator(("Operator"))
node_marine_traffic["MarineTraffic Embed"]

node_operator -->|"opens"| node_dashboard
node_operator -->|"reviews"| node_shipment_detail
node_operator -->|"tracks vessels"| node_map
node_operator -->|"views alerts"| node_alerts
node_dashboard -->|"opens form"| node_new_shipment
node_dashboard -->|"loads events"| node_api
node_shipment_detail -->|"saves details"| node_api
node_documents -->|"loads documents"| node_api
node_map -->|"loads fleet data"| node_fleet_hook
node_vessels -->|"loads fleet data"| node_fleet_hook
node_fleet_hook -->|"queries records"| node_api
node_monitoring_config -->|"loads settings"| node_api
node_monitoring_config -->|"uses defaults"| node_lifecycle
node_map -->|"uses AIS rules"| node_ais_decisions
node_position_hook_route -->|"routes position data"| node_position_hook
node_position_hook_route -->|"invokes webhook handler"| node_ais_decisions
node_ais_decisions -->|"applies decisions"| node_api
node_automation_route -->|"runs automation"| node_automation_runner
node_automation_runner -.->|"uses data access"| node_api
node_api -->|"queries"| node_supabase
node_supabase -->|"reads and writes"| node_database
node_map -->|"embeds map"| node_marine_traffic

click node_dashboard "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/index.tsx"
click node_shell "https://github.com/lordmarss/shipment-navigator/blob/main/src/components/AppShell.tsx"
click node_shipment_detail "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/shipments.%24id.tsx"
click node_new_shipment "https://github.com/lordmarss/shipment-navigator/blob/main/src/components/NewShipmentForm.tsx"
click node_documents "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/documents.tsx"
click node_alerts "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/alerts.tsx"
click node_analytics "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/analytics.tsx"
click node_settings "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/settings.tsx"
click node_map "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/map.tsx"
click node_vessels "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/vessels.tsx"
click node_fleet_hook "https://github.com/lordmarss/shipment-navigator/blob/main/src/components/maritime/useFleet.ts"
click node_monitoring_config "https://github.com/lordmarss/shipment-navigator/blob/main/src/hooks/useMonitoringConfig.ts"
click node_lifecycle "https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/lifecycle.ts"
click node_ais_decisions "https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/aisAutomation.ts"
click node_position_hook "https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/aisPositionIngest.ts"
click node_position_hook_route "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/api/public/hooks/ais-position.ts"
click node_automation_route "https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/api/public/hooks/automation-run.ts"
click node_automation_runner "https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/automation.server.ts"
click node_api "https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/api.ts"
click node_supabase "https://github.com/lordmarss/shipment-navigator/blob/main/src/integrations/supabase/client.ts"

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_dashboard,node_shell,node_analytics,node_settings toneBlue
class node_shipment_detail,node_new_shipment,node_documents,node_alerts toneAmber
class node_map,node_vessels,node_fleet_hook,node_monitoring_config,node_lifecycle,node_ais_decisions,node_position_hook toneMint
class node_position_hook_route,node_automation_route,node_automation_runner,node_api,node_supabase,node_database toneRose
class node_operator,node_marine_traffic toneIndigo
```

## Components

### Workspace UI

- [Dashboard](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [App Shell](https://github.com/lordmarss/shipment-navigator/blob/main/src/components/AppShell.tsx): `src/components/AppShell.tsx`
- [Analytics](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/analytics.tsx): `src/routes/analytics.tsx`
- [Settings](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/settings.tsx): `src/routes/settings.tsx`

### Shipment Lifecycle

- [Shipment Detail](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/shipments.%24id.tsx): `src/routes/shipments.$id.tsx`
- [New Shipment Form](https://github.com/lordmarss/shipment-navigator/blob/main/src/components/NewShipmentForm.tsx): `src/components/NewShipmentForm.tsx`
- [Documents](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/documents.tsx): `src/routes/documents.tsx`
- [Alerts](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/alerts.tsx): `src/routes/alerts.tsx`

### Fleet Intelligence

- [Fleet Map](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/map.tsx): `src/routes/map.tsx`
- [Vessels](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/vessels.tsx): `src/routes/vessels.tsx`
- [Fleet Queries](https://github.com/lordmarss/shipment-navigator/blob/main/src/components/maritime/useFleet.ts): `src/components/maritime/useFleet.ts`
- [Monitoring Config](https://github.com/lordmarss/shipment-navigator/blob/main/src/hooks/useMonitoringConfig.ts): `src/hooks/useMonitoringConfig.ts`
- [Lifecycle Rules](https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/lifecycle.ts): `src/lib/lifecycle.ts`
- [AIS Decisions](https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/aisAutomation.ts): `src/lib/aisAutomation.ts`
- [AIS Position Ingest](https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/aisPositionIngest.ts): `src/lib/aisPositionIngest.ts`

### Data and Integrations

- [AIS Position Hook](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/api/public/hooks/ais-position.ts): `src/routes/api/public/hooks/ais-position.ts`
- [Automation Hook](https://github.com/lordmarss/shipment-navigator/blob/main/src/routes/api/public/hooks/automation-run.ts): `src/routes/api/public/hooks/automation-run.ts`
- [Automation Runner](https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/automation.server.ts): `src/lib/automation.server.ts`
- [Data Access](https://github.com/lordmarss/shipment-navigator/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Supabase](https://github.com/lordmarss/shipment-navigator/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`
- **Supabase Database**

### Other components

- **Operator**
- **MarineTraffic Embed**

## Connections

- Operator → Dashboard: opens (evidence: `README.md`)
- Operator → Shipment Detail: reviews (evidence: `README.md`)
- Operator → Fleet Map: tracks vessels (evidence: `README.md`)
- Operator → Alerts: views alerts (evidence: `README.md`)
- Dashboard → New Shipment Form: opens form (evidence: `src/routes/index.tsx`)
- Dashboard → Data Access: loads events (evidence: `src/routes/index.tsx`)
- Shipment Detail → Data Access: saves details (evidence: `src/routes/shipments.$id.tsx`)
- Documents → Data Access: loads documents (evidence: `src/routes/documents.tsx`)
- Fleet Map → Fleet Queries: loads fleet data (evidence: `src/routes/map.tsx`)
- Vessels → Fleet Queries: loads fleet data (evidence: `src/routes/vessels.tsx`)
- Fleet Queries → Data Access: queries records (evidence: `src/components/maritime/useFleet.ts`)
- Monitoring Config → Data Access: loads settings (evidence: `src/hooks/useMonitoringConfig.ts`)
- Monitoring Config → Lifecycle Rules: uses defaults (evidence: `src/hooks/useMonitoringConfig.ts`)
- Fleet Map → AIS Decisions: uses AIS rules (evidence: `src/routes/map.tsx`)
- AIS Position Hook → AIS Position Ingest: routes position data (evidence: `src/routes/api/public/hooks/ais-position.ts`)
- AIS Position Hook → AIS Decisions: invokes webhook handler
- AIS Decisions → Data Access: applies decisions (evidence: `src/lib/aisAutomation.ts`)
- Automation Hook → Automation Runner: runs automation (evidence: `src/routes/api/public/hooks/automation-run.ts`)
- Automation Runner → Data Access: uses data access
- Data Access → Supabase: queries (evidence: `src/lib/api.ts`)
- Supabase → Supabase Database: reads and writes
- Fleet Map → MarineTraffic Embed: embeds map (evidence: `README.md`)