# santhosh-i/neuro-stack_plastic-ledger architecture

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

- Interactive diagram: https://gitdiagram.com/santhosh-i/neuro-stack_plastic-ledger
- Repository: https://github.com/santhosh-i/neuro-stack_plastic-ledger

## Overview

Plastic-Ledger turns a selected coastal area and date into a marine-debris investigation: analysts configure and launch a run, the backend records its status and invokes the pipeline, and the dashboard supports review of detections, polymer classes, backtracks, attribution, hotspots, and reports. The seven-stage pipeline is documented as an ordered workflow; the excerpted runner confirms orchestration but does not expose every stage call. Frontend-to-API behavior and several dashboard capabilities are documented in the README, not verified from their unsampled implementations.

Main entry points: [`src/pipeline/run_pipeline.py`](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/run_pipeline.py) (Pipeline runner), [`frontend/src/lib/api.ts`](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/App.tsx`](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/App.tsx) (Application routes), [`src/pipeline/01_ingest.py`](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/01_ingest.py) (Satellite ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Analyst dashboard"]
  node_app["Application routes<br/>[App.tsx]"]
  node_tracking["Run tracking<br/>[TrackingPage.tsx]"]
  node_dashboard["Run dashboard<br/>[DashboardPage.tsx]"]
  node_detail["Run detail<br/>[RunDetailPage.tsx]"]
  node_hotspots["Hotspots<br/>[HotspotsPage.tsx]"]
  node_modelview["Model outputs<br/>[modelpage.jsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Run management API"]
  node_runs_api["Run API<br/>[views.py]"]
  node_run_model[("Run records<br/>[models.py]")]
  node_run_serializer["Run validation<br/>[serializers.py]"]
end

subgraph group_pipeline["Analysis pipeline"]
  node_orchestrator["Pipeline runner<br/>[run_pipeline.py]"]
  node_ingest["Satellite ingest<br/>[01_ingest.py]"]
  node_preprocess["Image preprocessing<br/>[02_preprocess.py]"]
  node_detect["Debris detection<br/>[03_detect.py]"]
  node_polymer["Polymer classification<br/>[04_polymer.py]"]
  node_backtrack["Particle backtracking<br/>[05_backtrack.py]"]
  node_attribute["Source attribution<br/>[06_attribute.py]"]
  node_report["Run reporting<br/>[07_report.py]"]
end

subgraph group_shared["Pipeline utilities"]
  node_cache["Stage caching<br/>[cache_utils.py]"]
  node_geo["Geospatial helpers<br/>[geo_utils.py]"]
  node_logs["Pipeline logging<br/>[logging_utils.py]"]
end

node_analyst(("Analyst"))
node_sentinel{{"Copernicus Sentinel-2"}}
node_environment{{"CMEMS and ERA5"}}

node_analyst -->|"configures run"| node_tracking
node_app -->|"routes to"| node_tracking
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_detail
node_app -->|"routes to"| node_hotspots
node_app -->|"routes to"| node_modelview
node_tracking -.->|"submits run"| node_api_client
node_dashboard -.->|"loads run data"| node_api_client
node_detail -.->|"loads run data"| node_api_client
node_hotspots -.->|"explores run data"| node_api_client
node_modelview -.->|"reads evaluation artifacts"| node_api_client
node_api_client -.->|"requests run data"| node_runs_api
node_runs_api -->|"validates and serializes"| node_run_serializer
node_run_serializer -->|"validates records"| node_run_model
node_runs_api -->|"creates and updates"| node_run_model
node_runs_api -->|"starts pipeline"| node_orchestrator
node_orchestrator -->|"runs stage 1"| node_ingest
node_orchestrator -->|"runs stage 2"| node_preprocess
node_orchestrator -->|"runs stage 3"| node_detect
node_orchestrator -->|"runs stage 4"| node_polymer
node_orchestrator -->|"runs stage 5"| node_backtrack
node_orchestrator -->|"runs stage 6"| node_attribute
node_orchestrator -->|"runs stage 7"| node_report
node_ingest -->|"passes imagery"| node_preprocess
node_preprocess -->|"passes image patches"| node_detect
node_detect -->|"passes detections"| node_polymer
node_polymer -->|"passes classified clusters"| node_backtrack
node_backtrack -->|"passes trajectories"| node_attribute
node_attribute -->|"passes attribution"| node_report
node_sentinel -->|"provides imagery"| node_ingest
node_environment -->|"provides currents and wind"| node_backtrack
node_ingest -->|"uses geospatial helpers"| node_geo
node_ingest -->|"uses cache helpers"| node_cache
node_attribute -->|"uses geospatial helpers"| node_geo
node_attribute -->|"uses cache helpers"| node_cache
node_report -->|"uses cache helpers"| node_cache
node_geo -->|"gets logger"| node_logs
node_cache -->|"gets logger"| node_logs

click node_app "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/App.tsx"
click node_tracking "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/TrackingPage.tsx"
click node_dashboard "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_detail "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/RunDetailPage.tsx"
click node_hotspots "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/HotspotsPage.tsx"
click node_modelview "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/modelpage.jsx"
click node_api_client "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/lib/api.ts"
click node_runs_api "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/server/api/views.py"
click node_run_model "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/server/api/models.py"
click node_run_serializer "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/server/api/serializers.py"
click node_orchestrator "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/run_pipeline.py"
click node_ingest "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/01_ingest.py"
click node_preprocess "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/02_preprocess.py"
click node_detect "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/03_detect.py"
click node_polymer "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/04_polymer.py"
click node_backtrack "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/05_backtrack.py"
click node_attribute "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/06_attribute.py"
click node_report "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/07_report.py"
click node_cache "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/utils/cache_utils.py"
click node_geo "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/utils/geo_utils.py"
click node_logs "https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/utils/logging_utils.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_tracking,node_dashboard,node_detail,node_hotspots,node_modelview,node_api_client toneBlue
class node_runs_api,node_run_model,node_run_serializer toneAmber
class node_orchestrator,node_ingest,node_preprocess,node_detect,node_polymer,node_backtrack,node_attribute,node_report toneMint
class node_cache,node_geo,node_logs toneRose
class node_analyst,node_sentinel,node_environment toneIndigo
```

## Components

### Analyst dashboard

- [Application routes](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Run tracking](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/TrackingPage.tsx): `frontend/src/pages/TrackingPage.tsx`
- [Run dashboard](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Run detail](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/RunDetailPage.tsx): `frontend/src/pages/RunDetailPage.tsx`
- [Hotspots](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/HotspotsPage.tsx): `frontend/src/pages/HotspotsPage.tsx`
- [Model outputs](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/pages/modelpage.jsx): `frontend/src/pages/modelpage.jsx`
- [API client](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Run management API

- [Run API](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/server/api/views.py): `server/api/views.py`
- [Run records](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/server/api/models.py): `server/api/models.py`
- [Run validation](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/server/api/serializers.py): `server/api/serializers.py`

### Analysis pipeline

- [Pipeline runner](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/run_pipeline.py): `src/pipeline/run_pipeline.py`
- [Satellite ingest](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/01_ingest.py): `src/pipeline/01_ingest.py`
- [Image preprocessing](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/02_preprocess.py): `src/pipeline/02_preprocess.py`
- [Debris detection](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/03_detect.py): `src/pipeline/03_detect.py`
- [Polymer classification](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/04_polymer.py): `src/pipeline/04_polymer.py`
- [Particle backtracking](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/05_backtrack.py): `src/pipeline/05_backtrack.py`
- [Source attribution](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/06_attribute.py): `src/pipeline/06_attribute.py`
- [Run reporting](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/07_report.py): `src/pipeline/07_report.py`

### Pipeline utilities

- [Stage caching](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/utils/cache_utils.py): `src/pipeline/utils/cache_utils.py`
- [Geospatial helpers](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/utils/geo_utils.py): `src/pipeline/utils/geo_utils.py`
- [Pipeline logging](https://github.com/santhosh-i/neuro-stack_plastic-ledger/blob/main/src/pipeline/utils/logging_utils.py): `src/pipeline/utils/logging_utils.py`

### Other components

- **Analyst**
- **Copernicus Sentinel-2**
- **CMEMS and ERA5**

## Connections

- Analyst → Run tracking: configures run (evidence: `README.md`)
- Application routes → Run tracking: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Run dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Run detail: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Hotspots: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Model outputs: routes to (evidence: `frontend/src/App.tsx`)
- Run tracking → API client: submits run
- Run dashboard → API client: loads run data
- Run detail → API client: loads run data
- Hotspots → API client: explores run data
- Model outputs → API client: reads evaluation artifacts
- API client → Run API: requests run data
- Run API → Run validation: validates and serializes (evidence: `server/api/views.py`)
- Run validation → Run records: validates records (evidence: `server/api/serializers.py`)
- Run API → Run records: creates and updates (evidence: `server/api/views.py`)
- Run API → Pipeline runner: starts pipeline (evidence: `server/api/views.py`)
- Pipeline runner → Satellite ingest: runs stage 1 (evidence: `README.md`)
- Pipeline runner → Image preprocessing: runs stage 2 (evidence: `src/pipeline/run_pipeline.py`)
- Pipeline runner → Debris detection: runs stage 3 (evidence: `README.md`)
- Pipeline runner → Polymer classification: runs stage 4 (evidence: `src/pipeline/run_pipeline.py`)
- Pipeline runner → Particle backtracking: runs stage 5 (evidence: `README.md`)
- Pipeline runner → Source attribution: runs stage 6 (evidence: `README.md`)
- Pipeline runner → Run reporting: runs stage 7 (evidence: `src/pipeline/run_pipeline.py`)
- Satellite ingest → Image preprocessing: passes imagery (evidence: `README.md`)
- Image preprocessing → Debris detection: passes image patches (evidence: `README.md`)
- Debris detection → Polymer classification: passes detections (evidence: `README.md`)
- Polymer classification → Particle backtracking: passes classified clusters (evidence: `README.md`)
- Particle backtracking → Source attribution: passes trajectories (evidence: `README.md`)
- Source attribution → Run reporting: passes attribution (evidence: `README.md`)
- Copernicus Sentinel-2 → Satellite ingest: provides imagery (evidence: `README.md`)
- CMEMS and ERA5 → Particle backtracking: provides currents and wind (evidence: `README.md`)
- Satellite ingest → Geospatial helpers: uses geospatial helpers (evidence: `src/pipeline/01_ingest.py`)
- Satellite ingest → Stage caching: uses cache helpers (evidence: `src/pipeline/01_ingest.py`)
- Source attribution → Geospatial helpers: uses geospatial helpers (evidence: `src/pipeline/06_attribute.py`)
- Source attribution → Stage caching: uses cache helpers (evidence: `src/pipeline/06_attribute.py`)
- Run reporting → Stage caching: uses cache helpers (evidence: `src/pipeline/07_report.py`)
- Geospatial helpers → Pipeline logging: gets logger (evidence: `src/pipeline/utils/geo_utils.py`)
- Stage caching → Pipeline logging: gets logger (evidence: `src/pipeline/utils/cache_utils.py`)
