# ronny-dev01/deepsight architecture

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

- Interactive diagram: https://gitdiagram.com/ronny-dev01/deepsight
- Repository: https://github.com/ronny-dev01/deepsight

## Overview

SIH 2026 Marine Sonar MVP processes real side-scan sonar through ingestion, frame analysis, evidence fusion and tracking, then exposes findings for human review and reporting. The API and database anchor job intake and persistent results; a worker runs the analysis pipeline. The README documents geolocation when metadata exists and provenance requirements. Several UI and backend subsystems are represented from the tree and index, but their unsampled implementations and some runtime wiring cannot be verified, so those connections are omitted or marked unverified.

Main entry points: [`services/worker/job_runner.py`](https://github.com/ronny-dev01/deepsight/blob/main/services/worker/job_runner.py) (Job runner), [`services/worker/pipeline.py`](https://github.com/ronny-dev01/deepsight/blob/main/services/worker/pipeline.py) (Frame pipeline), [`frontend/src/api/client.ts`](https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/api/client.ts) (API client), [`services/api/routes/ingestion.py`](https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/ingestion.py) (Ingestion routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Operator interface"]
  node_app["Workspace UI<br/>[App.tsx]"]
  node_jobdetail["Job detail<br/>[JobDetail.tsx]"]
  node_map["Operational map<br/>[OperationalMap.tsx]"]
  node_upload["Upload panel<br/>[UploadPanel.tsx]"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and ingestion"]
  node_api_entry["HTTP API<br/>[main.py]"]
  node_ingestion_route["Ingestion routes<br/>[ingestion.py]"]
  node_ingestion_service["Upload validation<br/>[ingestion.py]"]
end

subgraph group_processing["Sonar processing"]
  node_worker["Job worker<br/>[worker.py]"]
  node_job_runner["Job runner<br/>[job_runner.py]"]
  node_frame_pipeline["Frame pipeline<br/>[pipeline.py]"]
  node_quality["Image quality<br/>[assessor.py]"]
  node_detector["Object detector<br/>[detector.py]"]
  node_evidence["Acoustic evidence<br/>[extractor.py]"]
  node_fusion["Evidence fusion<br/>[fusion.py]"]
  node_tracking["Frame tracking<br/>[tracker.py]"]
end

subgraph group_persistence["Jobs and records"]
  node_database[("Authoritative database<br/>[db.py]")]
  node_domain["Domain records<br/>[domain.py]"]
end

subgraph group_outcomes["Review and reporting"]
  node_review_route["Review routes<br/>[review.py]"]
  node_report_route["Report routes<br/>[report.py]"]
  node_reports["Reports<br/>[report.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_app
node_app -.->|"presents"| node_upload
node_jobdetail -->|"requests data"| node_client
node_jobdetail -->|"renders"| node_map
node_upload -.->|"submits job"| node_client
node_client -->|"HTTP requests"| node_ingestion_route
node_client -->|"HTTP requests"| node_review_route
node_client -->|"HTTP requests"| node_report_route
node_api_entry -->|"registers"| node_ingestion_route
node_api_entry -->|"registers"| node_review_route
node_api_entry -->|"registers"| node_report_route
node_ingestion_route -->|"validates uploads"| node_ingestion_service
node_ingestion_route -->|"writes job data"| node_database
node_ingestion_route -->|"creates records"| node_domain
node_worker -->|"runs jobs"| node_job_runner
node_job_runner -->|"processes frames"| node_frame_pipeline
node_frame_pipeline -->|"assesses image"| node_quality
node_frame_pipeline -->|"predicts objects"| node_detector
node_frame_pipeline -->|"extracts evidence"| node_evidence
node_frame_pipeline -->|"fuses scores"| node_fusion
node_job_runner -.->|"tracks frames"| node_tracking
node_job_runner -->|"persists results"| node_database
node_job_runner -->|"uses records"| node_domain
node_review_route -->|"reads and updates"| node_database
node_review_route -->|"queries findings"| node_domain
node_report_route -->|"reads results"| node_database
node_report_route -->|"queries records"| node_domain
node_report_route -.->|"formats response"| node_reports

click node_app "https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/App.tsx"
click node_jobdetail "https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/components/JobDetail.tsx"
click node_map "https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/components/OperationalMap.tsx"
click node_upload "https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/components/UploadPanel.tsx"
click node_client "https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/api/client.ts"
click node_api_entry "https://github.com/ronny-dev01/deepsight/blob/main/services/api/main.py"
click node_ingestion_route "https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/ingestion.py"
click node_ingestion_service "https://github.com/ronny-dev01/deepsight/blob/main/services/api/services/ingestion.py"
click node_worker "https://github.com/ronny-dev01/deepsight/blob/main/services/worker/worker.py"
click node_job_runner "https://github.com/ronny-dev01/deepsight/blob/main/services/worker/job_runner.py"
click node_frame_pipeline "https://github.com/ronny-dev01/deepsight/blob/main/services/worker/pipeline.py"
click node_quality "https://github.com/ronny-dev01/deepsight/blob/main/ml/quality/assessor.py"
click node_detector "https://github.com/ronny-dev01/deepsight/blob/main/ml/inference/detector.py"
click node_evidence "https://github.com/ronny-dev01/deepsight/blob/main/ml/evidence/extractor.py"
click node_fusion "https://github.com/ronny-dev01/deepsight/blob/main/ml/evidence/fusion.py"
click node_tracking "https://github.com/ronny-dev01/deepsight/blob/main/ml/tracking/tracker.py"
click node_database "https://github.com/ronny-dev01/deepsight/blob/main/services/api/db.py"
click node_domain "https://github.com/ronny-dev01/deepsight/blob/main/services/api/models/domain.py"
click node_review_route "https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/review.py"
click node_report_route "https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/report.py"
click node_reports "https://github.com/ronny-dev01/deepsight/blob/main/services/api/schemas/report.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_jobdetail,node_map,node_upload,node_client toneBlue
class node_api_entry,node_ingestion_route,node_ingestion_service toneAmber
class node_worker,node_job_runner,node_frame_pipeline,node_quality,node_detector,node_evidence,node_fusion,node_tracking toneMint
class node_database,node_domain toneRose
class node_review_route,node_report_route,node_reports,node_operator toneIndigo
```

## Components

### Operator interface

- [Workspace UI](https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Job detail](https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/components/JobDetail.tsx): `frontend/src/components/JobDetail.tsx`
- [Operational map](https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/components/OperationalMap.tsx): `frontend/src/components/OperationalMap.tsx`
- [Upload panel](https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/components/UploadPanel.tsx): `frontend/src/components/UploadPanel.tsx`
- [API client](https://github.com/ronny-dev01/deepsight/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and ingestion

- [HTTP API](https://github.com/ronny-dev01/deepsight/blob/main/services/api/main.py): `services/api/main.py`
- [Ingestion routes](https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/ingestion.py): `services/api/routes/ingestion.py`
- [Upload validation](https://github.com/ronny-dev01/deepsight/blob/main/services/api/services/ingestion.py): `services/api/services/ingestion.py`

### Sonar processing

- [Job worker](https://github.com/ronny-dev01/deepsight/blob/main/services/worker/worker.py): `services/worker/worker.py`
- [Job runner](https://github.com/ronny-dev01/deepsight/blob/main/services/worker/job_runner.py): `services/worker/job_runner.py`
- [Frame pipeline](https://github.com/ronny-dev01/deepsight/blob/main/services/worker/pipeline.py): `services/worker/pipeline.py`
- [Image quality](https://github.com/ronny-dev01/deepsight/blob/main/ml/quality/assessor.py): `ml/quality/assessor.py`
- [Object detector](https://github.com/ronny-dev01/deepsight/blob/main/ml/inference/detector.py): `ml/inference/detector.py`
- [Acoustic evidence](https://github.com/ronny-dev01/deepsight/blob/main/ml/evidence/extractor.py): `ml/evidence/extractor.py`
- [Evidence fusion](https://github.com/ronny-dev01/deepsight/blob/main/ml/evidence/fusion.py): `ml/evidence/fusion.py`
- [Frame tracking](https://github.com/ronny-dev01/deepsight/blob/main/ml/tracking/tracker.py): `ml/tracking/tracker.py`

### Jobs and records

- [Authoritative database](https://github.com/ronny-dev01/deepsight/blob/main/services/api/db.py): `services/api/db.py`
- [Domain records](https://github.com/ronny-dev01/deepsight/blob/main/services/api/models/domain.py): `services/api/models/domain.py`

### Review and reporting

- [Review routes](https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/review.py): `services/api/routes/review.py`
- [Report routes](https://github.com/ronny-dev01/deepsight/blob/main/services/api/routes/report.py): `services/api/routes/report.py`
- [Reports](https://github.com/ronny-dev01/deepsight/blob/main/services/api/schemas/report.py): `services/api/schemas/report.py`

### Other components

- **Operator**

## Connections

- Operator → Workspace UI: uses (evidence: `frontend/src/App.tsx`)
- Workspace UI → Upload panel: presents
- Job detail → API client: requests data (evidence: `frontend/src/components/JobDetail.tsx`)
- Job detail → Operational map: renders (evidence: `frontend/src/components/JobDetail.tsx`)
- Upload panel → API client: submits job
- API client → Ingestion routes: HTTP requests (evidence: `frontend/src/api/client.ts`)
- API client → Review routes: HTTP requests (evidence: `frontend/src/api/client.ts`)
- API client → Report routes: HTTP requests (evidence: `frontend/src/api/client.ts`)
- HTTP API → Ingestion routes: registers (evidence: `services/api/main.py`)
- HTTP API → Review routes: registers (evidence: `services/api/main.py`)
- HTTP API → Report routes: registers (evidence: `services/api/main.py`)
- Ingestion routes → Upload validation: validates uploads (evidence: `services/api/routes/ingestion.py`)
- Ingestion routes → Authoritative database: writes job data (evidence: `services/api/routes/ingestion.py`)
- Ingestion routes → Domain records: creates records (evidence: `services/api/routes/ingestion.py`)
- Job worker → Job runner: runs jobs (evidence: `services/worker/worker.py`)
- Job runner → Frame pipeline: processes frames (evidence: `services/worker/job_runner.py`)
- Frame pipeline → Image quality: assesses image (evidence: `services/worker/pipeline.py`)
- Frame pipeline → Object detector: predicts objects (evidence: `services/worker/pipeline.py`)
- Frame pipeline → Acoustic evidence: extracts evidence (evidence: `services/worker/pipeline.py`)
- Frame pipeline → Evidence fusion: fuses scores (evidence: `services/worker/pipeline.py`)
- Job runner → Frame tracking: tracks frames
- Job runner → Authoritative database: persists results (evidence: `services/worker/job_runner.py`)
- Job runner → Domain records: uses records (evidence: `services/worker/job_runner.py`)
- Review routes → Authoritative database: reads and updates (evidence: `services/api/routes/review.py`)
- Review routes → Domain records: queries findings (evidence: `services/api/routes/review.py`)
- Report routes → Authoritative database: reads results (evidence: `services/api/routes/report.py`)
- Report routes → Domain records: queries records (evidence: `services/api/routes/report.py`)
- Report routes → Reports: formats response (evidence: `services/api/routes/report.py`)
