# tiwariraman884/deepsee architecture

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

- Interactive diagram: https://gitdiagram.com/tiwariraman884/deepsee
- Repository: https://github.com/tiwariraman884/deepsee

## Overview

DeepSea Guardian is an ocean-monitoring and mission-control platform. Sensor readings enter through the ESP32 gateway or other sensor clients, are analyzed for anomalies, and can trigger drone dispatch and an inspection; the dashboard presents live monitoring, alerts, maps, and forecasts. The backend also supports camera-based inspection evidence, species classification, reporting, and user accounts. The README documents the product workflow; source excerpts show pipeline orchestration, persistence, and live event delivery, but do not expose every route-to-worker connection.

Main entry points: [`backend/src/lib/sensorPipeline.ts`](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/sensorPipeline.ts) (Pipeline Orchestrator), [`backend/src/lib/pipeline/droneDispatcher.ts`](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/droneDispatcher.ts) (Drone Dispatcher), [`backend/src/lib/pipeline/inspectionSimulator.ts`](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/inspectionSimulator.ts) (Inspection Simulator), [`backend/src/server.ts`](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/server.ts) (API Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_field["Field Monitoring"]
  node_esp32["ESP32 Gateway<br/>[main.cpp]"]
  node_api_client["Device API Client<br/>[ApiClient.h]"]
end

subgraph group_backend["Backend Processing"]
  node_sensor_api["Sensor API<br/>[sensors.ts]"]
  node_pipeline["Pipeline Orchestrator<br/>[sensorPipeline.ts]"]
  node_consumer["Sensor Consumer<br/>[sensorConsumer.ts]"]
  node_event_bus["Event Bus<br/>[eventBus.ts]"]
  node_db[("Telemetry Database<br/>[index.ts]")]
  node_dispatcher["Drone Dispatcher<br/>[droneDispatcher.ts]"]
  node_inspection["Inspection Simulator"]
  node_reports["Incident Reports<br/>[reports.ts]"]
  node_auth["Account Access<br/>[auth.ts]"]
  node_server["API Server<br/>[server.ts]"]
  node_sse["Live Event Push<br/>[sseManager.ts]"]
end

subgraph group_intelligence["AI &amp; Inspection"]
  node_ml_worker["Anomaly Worker<br/>[mlWorker.ts]"]
  node_python["Python Inference<br/>[python.ts]"]
  node_vision["Vision Pipeline<br/>[pipeline.ts]"]
  node_vision_storage[("Frame Storage<br/>[storage.ts]")]
  node_species["Species Inference<br/>[speciesWorker.ts]"]
end

subgraph group_experience["Mission Control"]
  node_dashboard["Mission Dashboard<br/>[page.tsx]"]
  node_map["Ocean Map<br/>[page.tsx]"]
  node_species_ui["Species Classifier UI<br/>[page.tsx]"]
  node_ai_ui["AI Insights<br/>[page.tsx]"]
end

node_operator(("Ocean Operator"))

node_operator -->|"uses"| node_dashboard
node_esp32 -->|"sends readings"| node_api_client
node_api_client -->|"posts telemetry"| node_sensor_api
node_sensor_api -.->|"feeds readings"| node_pipeline
node_server -->|"registers route"| node_sensor_api
node_pipeline -->|"starts"| node_consumer
node_pipeline -->|"starts"| node_dispatcher
node_pipeline -->|"starts"| node_inspection
node_consumer -.->|"requests inference"| node_ml_worker
node_ml_worker -->|"spawns process"| node_python
node_consumer -.->|"persists readings"| node_db
node_dispatcher -->|"records missions"| node_db
node_dispatcher -.->|"signals inspection"| node_inspection
node_inspection -->|"uses camera analysis"| node_vision
node_vision -->|"stores evidence"| node_db
node_vision -->|"stores frames"| node_vision_storage
node_inspection -->|"streams findings"| node_sse
node_dispatcher -->|"pushes updates"| node_sse
node_species_ui -.->|"classifies species"| node_species
node_operator -->|"signs in"| node_auth
node_dashboard -->|"uses REST and SSE"| node_server
node_dashboard -.->|"receives live events"| node_sse
node_map -.->|"requests monitoring data"| node_server
node_ai_ui -.->|"views insights"| node_server
node_reports -.->|"reads inspection data"| node_db

click node_esp32 "https://github.com/tiwariraman884/deepsee/blob/main/hardware/esp32/src/main.cpp"
click node_api_client "https://github.com/tiwariraman884/deepsee/blob/main/hardware/esp32/src/transport/ApiClient.h"
click node_sensor_api "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/routes/sensors.ts"
click node_pipeline "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/sensorPipeline.ts"
click node_consumer "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/sensorConsumer.ts"
click node_event_bus "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/eventBus.ts"
click node_ml_worker "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/mlWorker.ts"
click node_python "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/python.ts"
click node_db "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/db/index.ts"
click node_dispatcher "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/droneDispatcher.ts"
click node_inspection "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/inspectionSimulator.ts"
click node_vision "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/vision/pipeline.ts"
click node_vision_storage "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/vision/storage.ts"
click node_species "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/speciesWorker.ts"
click node_reports "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/routes/reports.ts"
click node_auth "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/routes/auth.ts"
click node_server "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/server.ts"
click node_sse "https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/sseManager.ts"
click node_dashboard "https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/dashboard/page.tsx"
click node_map "https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/map/page.tsx"
click node_species_ui "https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/species/page.tsx"
click node_ai_ui "https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/system-intelligence/page.tsx"

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_esp32,node_api_client toneBlue
class node_sensor_api,node_pipeline,node_consumer,node_event_bus,node_db,node_dispatcher,node_inspection,node_reports,node_auth,node_server,node_sse toneAmber
class node_ml_worker,node_python,node_vision,node_vision_storage,node_species toneMint
class node_dashboard,node_map,node_species_ui,node_ai_ui toneRose
class node_operator toneIndigo
```

## Components

### Field Monitoring

- [ESP32 Gateway](https://github.com/tiwariraman884/deepsee/blob/main/hardware/esp32/src/main.cpp): `hardware/esp32/src/main.cpp`
- [Device API Client](https://github.com/tiwariraman884/deepsee/blob/main/hardware/esp32/src/transport/ApiClient.h): `hardware/esp32/src/transport/ApiClient.h`

### Backend Processing

- [Sensor API](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/routes/sensors.ts): `backend/src/routes/sensors.ts`
- [Pipeline Orchestrator](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/sensorPipeline.ts): `backend/src/lib/sensorPipeline.ts`
- [Sensor Consumer](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/sensorConsumer.ts): `backend/src/lib/pipeline/sensorConsumer.ts`
- [Event Bus](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/eventBus.ts): `backend/src/lib/eventBus.ts`
- [Telemetry Database](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/db/index.ts): `backend/src/db/index.ts`
- [Drone Dispatcher](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/droneDispatcher.ts): `backend/src/lib/pipeline/droneDispatcher.ts`
- [Inspection Simulator](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/pipeline/inspectionSimulator.ts): `backend/src/lib/pipeline/inspectionSimulator.ts`
- [Incident Reports](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/routes/reports.ts): `backend/src/routes/reports.ts`
- [Account Access](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [API Server](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Live Event Push](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/sseManager.ts): `backend/src/lib/sseManager.ts`

### AI & Inspection

- [Anomaly Worker](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/mlWorker.ts): `backend/src/lib/mlWorker.ts`
- [Python Inference](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/python.ts): `backend/src/lib/python.ts`
- [Vision Pipeline](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/vision/pipeline.ts): `backend/src/lib/vision/pipeline.ts`
- [Frame Storage](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/vision/storage.ts): `backend/src/lib/vision/storage.ts`
- [Species Inference](https://github.com/tiwariraman884/deepsee/blob/main/backend/src/lib/speciesWorker.ts): `backend/src/lib/speciesWorker.ts`

### Mission Control

- [Mission Dashboard](https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/dashboard/page.tsx): `frontend/src/app/dashboard/page.tsx`
- [Ocean Map](https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/map/page.tsx): `frontend/src/app/map/page.tsx`
- [Species Classifier UI](https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/species/page.tsx): `frontend/src/app/species/page.tsx`
- [AI Insights](https://github.com/tiwariraman884/deepsee/blob/main/frontend/src/app/system-intelligence/page.tsx): `frontend/src/app/system-intelligence/page.tsx`

### Other components

- **Ocean Operator**

## Connections

- Ocean Operator → Mission Dashboard: uses
- ESP32 Gateway → Device API Client: sends readings (evidence: `hardware/esp32/src/main.cpp`)
- Device API Client → Sensor API: posts telemetry (evidence: `hardware/esp32/src/transport/ApiClient.h`)
- Sensor API → Pipeline Orchestrator: feeds readings
- API Server → Sensor API: registers route (evidence: `backend/src/server.ts`)
- Pipeline Orchestrator → Sensor Consumer: starts (evidence: `backend/src/lib/sensorPipeline.ts`)
- Pipeline Orchestrator → Drone Dispatcher: starts (evidence: `backend/src/lib/sensorPipeline.ts`)
- Pipeline Orchestrator → Inspection Simulator: starts (evidence: `backend/src/lib/sensorPipeline.ts`)
- Sensor Consumer → Anomaly Worker: requests inference (evidence: `backend/src/lib/pipeline/sensorConsumer.ts`)
- Anomaly Worker → Python Inference: spawns process (evidence: `backend/src/lib/mlWorker.ts`)
- Sensor Consumer → Telemetry Database: persists readings (evidence: `backend/src/lib/pipeline/sensorConsumer.ts`)
- Drone Dispatcher → Telemetry Database: records missions (evidence: `backend/src/lib/pipeline/droneDispatcher.ts`)
- Drone Dispatcher → Inspection Simulator: signals inspection
- Inspection Simulator → Vision Pipeline: uses camera analysis (evidence: `backend/src/lib/pipeline/inspectionSimulator.ts`)
- Vision Pipeline → Telemetry Database: stores evidence (evidence: `backend/src/lib/vision/pipeline.ts`)
- Vision Pipeline → Frame Storage: stores frames (evidence: `backend/src/lib/vision/pipeline.ts`)
- Inspection Simulator → Live Event Push: streams findings (evidence: `backend/src/lib/pipeline/inspectionSimulator.ts`)
- Drone Dispatcher → Live Event Push: pushes updates (evidence: `backend/src/lib/pipeline/droneDispatcher.ts`)
- Species Classifier UI → Species Inference: classifies species
- Ocean Operator → Account Access: signs in (evidence: `backend/src/routes/auth.ts`)
- Mission Dashboard → API Server: uses REST and SSE
- Mission Dashboard → Live Event Push: receives live events
- Ocean Map → API Server: requests monitoring data
- AI Insights → API Server: views insights
- Incident Reports → Telemetry Database: reads inspection data