# nikatsg/mpc architecture

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

## Overview

MPC is a browser-based maritime maintenance planner and communicator. Users monitor fleet condition and position, add vessels, review AI-assisted fault or document intake, approve supplier-order drafts, and plan repair-port routing. The graph separates dashboard workflows, maritime planning, API orchestration, domain services, and persistence/integrations. Edges are limited to relationships visible in excerpts or documented by the README; unsampled routes and component internals are represented without asserting their wiring.

Main entry points: [`client/src/components/ShipDashboard.tsx`](https://github.com/nikatsg/mpc/blob/main/client/src/components/ShipDashboard.tsx) (Ship dashboard), [`server/src/services/intake.service.ts`](https://github.com/nikatsg/mpc/blob/main/server/src/services/intake.service.ts) (Reviewed intake), [`server/src/services/order.service.ts`](https://github.com/nikatsg/mpc/blob/main/server/src/services/order.service.ts) (Procurement orders), [`server/prisma/db.ts`](https://github.com/nikatsg/mpc/blob/main/server/prisma/db.ts) (Database client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_fleet["Fleet dashboard"]
  node_dashboard["Ship dashboard<br/>[ShipDashboard.tsx]"]
  node_map["Live fleet map<br/>[LiveMap.tsx]"]
  node_model["Ship health model<br/>[shipModel.tsx]"]
  node_vessel_hook["Vessel state<br/>[useVessel.ts]"]
  node_order_hook["Order state<br/>[useOrder.ts]"]
  node_ai_chat["AI chat<br/>[AiChat.tsx]"]
  node_pdf_workflow["PDF intake UI<br/>[AiPdfWorkflow.tsx]"]
  node_settings["AI settings"]
end

subgraph group_planning["Repair planning"]
  node_port_calls["Port conditions<br/>[portCalls.ts]"]
  node_sea_router["Sea routing<br/>[seaRouter.ts]"]
  node_weather_hook["Port weather<br/>[usePortWeather.ts]"]
end

subgraph group_backend["API and domain"]
  node_api["MPC API client<br/>[mpcApi.ts]"]
  node_routes["API route registry<br/>[index.ts]"]
  node_vessel_controller["Vessel endpoints"]
  node_vessel_service["Fleet and health<br/>[vessel.service.ts]"]
  node_order_service["Procurement orders<br/>[order.service.ts]"]
  node_report_service["Fault reports<br/>[report.service.ts]"]
  node_intake_service["Reviewed intake<br/>[intake.service.ts]"]
  node_ai_routes["AI API workflows<br/>[ai.route.ts]"]
end

subgraph group_assist["AI and communications"]
  node_provider["AI providers<br/>[aiProvider.ts]"]
  node_document_reader["Document reader<br/>[documentReader.ts]"]
  node_order_agent["Supplier draft agent<br/>[orderAgent.ts]"]
  node_email["Email delivery<br/>[nodemailer.ts]"]
end

subgraph group_storage["Persistence"]
  node_db_client["Database client<br/>[db.ts]"]
  node_sqlite[("SQLite store<br/>[databasePath.ts]")]
end

node_user(("Fleet user"))
node_ai_services{{"AI services"}}
node_mail_system{{"Mail systems"}}
node_weather_service{{"Marine conditions service"}}

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_map
node_dashboard -->|"uses"| node_model
node_dashboard -->|"uses"| node_vessel_hook
node_dashboard -->|"uses"| node_order_hook
node_dashboard -->|"renders"| node_ai_chat
node_dashboard -->|"renders"| node_pdf_workflow
node_dashboard -->|"renders"| node_settings
node_vessel_hook -->|"requests fleet"| node_api
node_order_hook -->|"requests orders"| node_api
node_map -->|"loads vessel data"| node_api
node_map -->|"routes vessels"| node_sea_router
node_map -->|"gets port calls"| node_port_calls
node_weather_hook -->|"gets conditions"| node_port_calls
node_port_calls -->|"uses port routes"| node_sea_router
node_port_calls -.->|"fetches conditions"| node_weather_service
node_api -.->|"calls API"| node_routes
node_routes -->|"mounts endpoints"| node_vessel_controller
node_vessel_controller -->|"delegates fleet work"| node_vessel_service
node_vessel_service -->|"reads and writes"| node_db_client
node_ai_routes -->|"requests AI"| node_provider
node_ai_routes -->|"handles reviewed intake"| node_intake_service
node_ai_routes -->|"generates drafts"| node_order_service
node_ai_routes -->|"processes reports"| node_report_service
node_intake_service -->|"extracts documents"| node_document_reader
node_intake_service -->|"prepares orders"| node_order_service
node_intake_service -->|"applies fault damage"| node_vessel_service
node_order_service -->|"drafts supplier emails"| node_order_agent
node_order_agent -.->|"requests AI"| node_provider
node_provider -->|"calls provider"| node_ai_services
node_document_reader -.->|"uses AI extraction"| node_provider
node_order_service -.->|"dispatches drafts"| node_email
node_email -.->|"sends mail"| node_mail_system
node_intake_service -->|"stores reviews"| node_db_client
node_order_service -->|"stores orders"| node_db_client
node_report_service -.->|"uses persistence"| node_db_client
node_db_client -->|"opens database"| node_sqlite

click node_dashboard "https://github.com/nikatsg/mpc/blob/main/client/src/components/ShipDashboard.tsx"
click node_map "https://github.com/nikatsg/mpc/blob/main/client/src/components/LiveMap.tsx"
click node_model "https://github.com/nikatsg/mpc/blob/main/client/src/components/shipModel.tsx"
click node_vessel_hook "https://github.com/nikatsg/mpc/blob/main/client/src/hooks/useVessel.ts"
click node_order_hook "https://github.com/nikatsg/mpc/blob/main/client/src/hooks/useOrder.ts"
click node_ai_chat "https://github.com/nikatsg/mpc/blob/main/client/src/components/AiChat.tsx"
click node_pdf_workflow "https://github.com/nikatsg/mpc/blob/main/client/src/components/AiPdfWorkflow.tsx"
click node_settings "https://github.com/nikatsg/mpc/blob/main/client/src/components/AiSettingsPanel.tsx"
click node_api "https://github.com/nikatsg/mpc/blob/main/client/src/api/mpcApi.ts"
click node_port_calls "https://github.com/nikatsg/mpc/blob/main/client/src/utils/portCalls.ts"
click node_sea_router "https://github.com/nikatsg/mpc/blob/main/client/src/utils/seaRouter.ts"
click node_weather_hook "https://github.com/nikatsg/mpc/blob/main/client/src/hooks/usePortWeather.ts"
click node_routes "https://github.com/nikatsg/mpc/blob/main/server/src/routes/index.ts"
click node_vessel_controller "https://github.com/nikatsg/mpc/blob/main/server/src/controllers/vessel.controller.ts"
click node_vessel_service "https://github.com/nikatsg/mpc/blob/main/server/src/services/vessel.service.ts"
click node_order_service "https://github.com/nikatsg/mpc/blob/main/server/src/services/order.service.ts"
click node_report_service "https://github.com/nikatsg/mpc/blob/main/server/src/services/report.service.ts"
click node_intake_service "https://github.com/nikatsg/mpc/blob/main/server/src/services/intake.service.ts"
click node_ai_routes "https://github.com/nikatsg/mpc/blob/main/server/src/routes/ai.route.ts"
click node_provider "https://github.com/nikatsg/mpc/blob/main/server/src/integrations/ai/aiProvider.ts"
click node_document_reader "https://github.com/nikatsg/mpc/blob/main/server/src/integrations/ai/documentReader.ts"
click node_order_agent "https://github.com/nikatsg/mpc/blob/main/server/src/integrations/ai/orderAgent.ts"
click node_email "https://github.com/nikatsg/mpc/blob/main/server/src/integrations/email/nodemailer.ts"
click node_db_client "https://github.com/nikatsg/mpc/blob/main/server/prisma/db.ts"
click node_sqlite "https://github.com/nikatsg/mpc/blob/main/server/prisma/databasePath.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_map,node_model,node_vessel_hook,node_order_hook,node_ai_chat,node_pdf_workflow,node_settings,node_user toneBlue
class node_port_calls,node_sea_router,node_weather_hook toneAmber
class node_api,node_routes,node_vessel_controller,node_vessel_service,node_order_service,node_report_service,node_intake_service,node_ai_routes toneMint
class node_provider,node_document_reader,node_order_agent,node_email toneRose
class node_db_client,node_sqlite,node_ai_services,node_mail_system,node_weather_service toneIndigo
```

## Components

### Fleet dashboard

- [Ship dashboard](https://github.com/nikatsg/mpc/blob/main/client/src/components/ShipDashboard.tsx): `client/src/components/ShipDashboard.tsx`
- [Live fleet map](https://github.com/nikatsg/mpc/blob/main/client/src/components/LiveMap.tsx): `client/src/components/LiveMap.tsx`
- [Ship health model](https://github.com/nikatsg/mpc/blob/main/client/src/components/shipModel.tsx): `client/src/components/shipModel.tsx`
- [Vessel state](https://github.com/nikatsg/mpc/blob/main/client/src/hooks/useVessel.ts): `client/src/hooks/useVessel.ts`
- [Order state](https://github.com/nikatsg/mpc/blob/main/client/src/hooks/useOrder.ts): `client/src/hooks/useOrder.ts`
- [AI chat](https://github.com/nikatsg/mpc/blob/main/client/src/components/AiChat.tsx): `client/src/components/AiChat.tsx`
- [PDF intake UI](https://github.com/nikatsg/mpc/blob/main/client/src/components/AiPdfWorkflow.tsx): `client/src/components/AiPdfWorkflow.tsx`
- [AI settings](https://github.com/nikatsg/mpc/blob/main/client/src/components/AiSettingsPanel.tsx): `client/src/components/AiSettingsPanel.tsx`

### Repair planning

- [Port conditions](https://github.com/nikatsg/mpc/blob/main/client/src/utils/portCalls.ts): `client/src/utils/portCalls.ts`
- [Sea routing](https://github.com/nikatsg/mpc/blob/main/client/src/utils/seaRouter.ts): `client/src/utils/seaRouter.ts`
- [Port weather](https://github.com/nikatsg/mpc/blob/main/client/src/hooks/usePortWeather.ts): `client/src/hooks/usePortWeather.ts`

### API and domain

- [MPC API client](https://github.com/nikatsg/mpc/blob/main/client/src/api/mpcApi.ts): `client/src/api/mpcApi.ts`
- [API route registry](https://github.com/nikatsg/mpc/blob/main/server/src/routes/index.ts): `server/src/routes/index.ts`
- [Vessel endpoints](https://github.com/nikatsg/mpc/blob/main/server/src/controllers/vessel.controller.ts): `server/src/controllers/vessel.controller.ts`
- [Fleet and health](https://github.com/nikatsg/mpc/blob/main/server/src/services/vessel.service.ts): `server/src/services/vessel.service.ts`
- [Procurement orders](https://github.com/nikatsg/mpc/blob/main/server/src/services/order.service.ts): `server/src/services/order.service.ts`
- [Fault reports](https://github.com/nikatsg/mpc/blob/main/server/src/services/report.service.ts): `server/src/services/report.service.ts`
- [Reviewed intake](https://github.com/nikatsg/mpc/blob/main/server/src/services/intake.service.ts): `server/src/services/intake.service.ts`
- [AI API workflows](https://github.com/nikatsg/mpc/blob/main/server/src/routes/ai.route.ts): `server/src/routes/ai.route.ts`

### AI and communications

- [AI providers](https://github.com/nikatsg/mpc/blob/main/server/src/integrations/ai/aiProvider.ts): `server/src/integrations/ai/aiProvider.ts`
- [Document reader](https://github.com/nikatsg/mpc/blob/main/server/src/integrations/ai/documentReader.ts): `server/src/integrations/ai/documentReader.ts`
- [Supplier draft agent](https://github.com/nikatsg/mpc/blob/main/server/src/integrations/ai/orderAgent.ts): `server/src/integrations/ai/orderAgent.ts`
- [Email delivery](https://github.com/nikatsg/mpc/blob/main/server/src/integrations/email/nodemailer.ts): `server/src/integrations/email/nodemailer.ts`

### Persistence

- [Database client](https://github.com/nikatsg/mpc/blob/main/server/prisma/db.ts): `server/prisma/db.ts`
- [SQLite store](https://github.com/nikatsg/mpc/blob/main/server/prisma/databasePath.ts): `server/prisma/databasePath.ts`

### Other components

- **Fleet user**
- **AI services**
- **Mail systems**
- **Marine conditions service**

## Connections

- Fleet user → Ship dashboard: uses (evidence: `README.md`)
- Ship dashboard → Live fleet map: renders (evidence: `client/src/components/ShipDashboard.tsx`)
- Ship dashboard → Ship health model: uses (evidence: `client/src/components/ShipDashboard.tsx`)
- Ship dashboard → Vessel state: uses (evidence: `client/src/components/ShipDashboard.tsx`)
- Ship dashboard → Order state: uses (evidence: `client/src/components/ShipDashboard.tsx`)
- Ship dashboard → AI chat: renders (evidence: `client/src/components/ShipDashboard.tsx`)
- Ship dashboard → PDF intake UI: renders (evidence: `client/src/components/ShipDashboard.tsx`)
- Ship dashboard → AI settings: renders (evidence: `client/src/components/ShipDashboard.tsx`)
- Vessel state → MPC API client: requests fleet (evidence: `client/src/hooks/useVessel.ts`)
- Order state → MPC API client: requests orders (evidence: `client/src/components/ShipDashboard.tsx`)
- Live fleet map → MPC API client: loads vessel data (evidence: `client/src/components/LiveMap.tsx`)
- Live fleet map → Sea routing: routes vessels (evidence: `client/src/components/LiveMap.tsx`)
- Live fleet map → Port conditions: gets port calls (evidence: `client/src/components/LiveMap.tsx`)
- Port weather → Port conditions: gets conditions (evidence: `client/src/hooks/usePortWeather.ts`)
- Port conditions → Sea routing: uses port routes (evidence: `client/src/utils/portCalls.ts`)
- Port conditions → Marine conditions service: fetches conditions
- MPC API client → API route registry: calls API
- API route registry → Vessel endpoints: mounts endpoints (evidence: `server/src/routes/index.ts`)
- Vessel endpoints → Fleet and health: delegates fleet work (evidence: `server/src/controllers/vessel.controller.ts`)
- Fleet and health → Database client: reads and writes (evidence: `server/src/services/vessel.service.ts`)
- AI API workflows → AI providers: requests AI (evidence: `server/src/app.ts`)
- AI API workflows → Reviewed intake: handles reviewed intake (evidence: `server/src/app.ts`)
- AI API workflows → Procurement orders: generates drafts (evidence: `server/src/app.ts`)
- AI API workflows → Fault reports: processes reports (evidence: `server/src/app.ts`)
- Reviewed intake → Document reader: extracts documents (evidence: `server/src/services/intake.service.ts`)
- Reviewed intake → Procurement orders: prepares orders (evidence: `server/src/services/intake.service.ts`)
- Reviewed intake → Fleet and health: applies fault damage (evidence: `server/src/services/intake.service.ts`)
- Procurement orders → Supplier draft agent: drafts supplier emails (evidence: `server/src/services/order.service.ts`)
- Supplier draft agent → AI providers: requests AI (evidence: `server/src/integrations/ai/orderAgent.ts`)
- AI providers → AI services: calls provider (evidence: `server/src/integrations/ai/aiProvider.ts`)
- Document reader → AI providers: uses AI extraction (evidence: `server/src/integrations/ai/documentReader.ts`)
- Procurement orders → Email delivery: dispatches drafts
- Email delivery → Mail systems: sends mail
- Reviewed intake → Database client: stores reviews (evidence: `server/src/services/intake.service.ts`)
- Procurement orders → Database client: stores orders (evidence: `server/src/services/order.service.ts`)
- Fault reports → Database client: uses persistence (evidence: `server/src/services/report.service.ts`)
- Database client → SQLite store: opens database (evidence: `server/prisma/db.ts`)
