# mukundan-304/ecosort-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mukundan-304/ecosort-ai
- Repository: https://github.com/mukundan-304/ecosort-ai

## Overview

EcoSort is a waste-to-recovery platform: a worker submits a photo, the system identifies items, derives material and hazard guidance, recommends a compatible recovery facility, and presents instructions. Low-confidence or hazardous decisions can enter human review; corrections feed model retraining. The README also documents a classifier lifecycle with data preparation, benchmarking, evaluation gates, and promotion, plus hash-chained traceability and capacity forecasting. Runtime internals for the UI, pipeline, operations, and analytics were not sampled, so those connections reflect documented behavior rather than inspected calls.

Main entry points: [`src/ecosort/pipeline.py`](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/pipeline.py) (Item Pipeline), [`training/train.py`](https://github.com/mukundan-304/ecosort-ai/blob/main/training/train.py) (Classifier Training), [`src/ecosort/vision.py`](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/vision.py) (Detection & Classification), [`training/evaluate.py`](https://github.com/mukundan-304/ecosort-ai/blob/main/training/evaluate.py) (Quality Evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Photo Intake &amp; Guidance"]
  node_app["Photo UI<br/>[streamlit_app.py]"]
  node_orchestrator["Item Pipeline<br/>[pipeline.py]"]
  node_detection["Detection &amp; Classification<br/>[vision.py]"]
  node_knowledge["Waste Knowledge<br/>[knowledge.py]"]
  node_instructions["Worker Guidance<br/>[pipeline.py]"]
end

subgraph group_recovery["Recovery Operations"]
  node_router["Facility Router<br/>[routing.py]"]
  node_facilities["Facility Configuration<br/>[facilities.yaml]"]
end

subgraph group_audit["Review &amp; Traceability"]
  node_gate["Uncertainty Review Gate<br/>[ops.py]"]
  node_review["Human Review<br/>[streamlit_app.py]"]
  node_feedback["Review Feedback<br/>[feedback.jsonl]"]
  node_ledger[("Traceability Ledger<br/>[ledger.jsonl]")]
  node_analytics["Analytics &amp; Forecast<br/>[ops.py]"]
end

subgraph group_ml["Model Lifecycle"]
  node_prepare["Dataset Preparation<br/>[prepare.py]"]
  node_preprocess["Image Preprocessing<br/>[preprocess.py]"]
  node_train["Classifier Training<br/>[train.py]"]
  node_metrics["Evaluation Metrics<br/>[evalutils.py]"]
  node_evaluate["Quality Evaluation<br/>[evaluate.py]"]
  node_promote["Model Promotion<br/>[promote.py]"]
  node_models[("Deployed Models")]
end

node_worker(("Worker"))

node_worker -->|"uploads photo"| node_app
node_app -->|"submits image"| node_orchestrator
node_orchestrator -->|"detects items"| node_detection
node_detection -->|"uses item classes"| node_knowledge
node_detection -->|"preprocesses crops"| node_preprocess
node_orchestrator -->|"derives handling"| node_knowledge
node_orchestrator -->|"produces guidance"| node_instructions
node_orchestrator -->|"requests routing"| node_router
node_router -->|"loads facilities"| node_facilities
node_orchestrator -->|"checks uncertainty"| node_gate
node_gate -->|"queues review"| node_review
node_review -->|"writes corrections"| node_feedback
node_orchestrator -->|"records decisions"| node_ledger
node_ledger -->|"feeds analytics"| node_analytics
node_feedback -->|"feeds retraining"| node_prepare
node_prepare -->|"creates splits"| node_train
node_train -->|"uses transforms"| node_preprocess
node_train -->|"scores candidates"| node_metrics
node_train -->|"produces candidate"| node_evaluate
node_evaluate -->|"computes gate metrics"| node_metrics
node_evaluate -->|"gates promotion"| node_promote
node_promote -->|"copies approved model"| node_models
node_models -->|"loads deployed classifier"| node_detection

click node_app "https://github.com/mukundan-304/ecosort-ai/blob/main/app/streamlit_app.py"
click node_orchestrator "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/pipeline.py"
click node_detection "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/vision.py"
click node_knowledge "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/knowledge.py"
click node_instructions "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/pipeline.py"
click node_router "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/routing.py"
click node_facilities "https://github.com/mukundan-304/ecosort-ai/blob/main/configs/facilities.yaml"
click node_gate "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/ops.py"
click node_review "https://github.com/mukundan-304/ecosort-ai/blob/main/app/streamlit_app.py"
click node_feedback "https://github.com/mukundan-304/ecosort-ai/blob/main/data/feedback/feedback.jsonl"
click node_ledger "https://github.com/mukundan-304/ecosort-ai/blob/main/data/ledger.jsonl"
click node_analytics "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/ops.py"
click node_prepare "https://github.com/mukundan-304/ecosort-ai/blob/main/training/prepare.py"
click node_preprocess "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/preprocess.py"
click node_train "https://github.com/mukundan-304/ecosort-ai/blob/main/training/train.py"
click node_metrics "https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/evalutils.py"
click node_evaluate "https://github.com/mukundan-304/ecosort-ai/blob/main/training/evaluate.py"
click node_promote "https://github.com/mukundan-304/ecosort-ai/blob/main/training/promote.py"
click node_models "https://github.com/mukundan-304/ecosort-ai/tree/main/models"

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_orchestrator,node_detection,node_knowledge,node_instructions toneBlue
class node_router,node_facilities toneAmber
class node_gate,node_review,node_feedback,node_ledger,node_analytics toneMint
class node_prepare,node_preprocess,node_train,node_metrics,node_evaluate,node_promote,node_models,node_worker toneRose
```

## Components

### Photo Intake & Guidance

- [Photo UI](https://github.com/mukundan-304/ecosort-ai/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Item Pipeline](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/pipeline.py): `src/ecosort/pipeline.py`
- [Detection & Classification](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/vision.py): `src/ecosort/vision.py`
- [Waste Knowledge](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/knowledge.py): `src/ecosort/knowledge.py`
- [Worker Guidance](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/pipeline.py): `src/ecosort/pipeline.py`

### Recovery Operations

- [Facility Router](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/routing.py): `src/ecosort/routing.py`
- [Facility Configuration](https://github.com/mukundan-304/ecosort-ai/blob/main/configs/facilities.yaml): `configs/facilities.yaml`

### Review & Traceability

- [Uncertainty Review Gate](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/ops.py): `src/ecosort/ops.py`
- [Human Review](https://github.com/mukundan-304/ecosort-ai/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Review Feedback](https://github.com/mukundan-304/ecosort-ai/blob/main/data/feedback/feedback.jsonl): `data/feedback/feedback.jsonl`
- [Traceability Ledger](https://github.com/mukundan-304/ecosort-ai/blob/main/data/ledger.jsonl): `data/ledger.jsonl`
- [Analytics & Forecast](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/ops.py): `src/ecosort/ops.py`

### Model Lifecycle

- [Dataset Preparation](https://github.com/mukundan-304/ecosort-ai/blob/main/training/prepare.py): `training/prepare.py`
- [Image Preprocessing](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/preprocess.py): `src/ecosort/preprocess.py`
- [Classifier Training](https://github.com/mukundan-304/ecosort-ai/blob/main/training/train.py): `training/train.py`
- [Evaluation Metrics](https://github.com/mukundan-304/ecosort-ai/blob/main/src/ecosort/evalutils.py): `src/ecosort/evalutils.py`
- [Quality Evaluation](https://github.com/mukundan-304/ecosort-ai/blob/main/training/evaluate.py): `training/evaluate.py`
- [Model Promotion](https://github.com/mukundan-304/ecosort-ai/blob/main/training/promote.py): `training/promote.py`
- [Deployed Models](https://github.com/mukundan-304/ecosort-ai/tree/main/models): `models`

### Other components

- **Worker**

## Connections

- Worker → Photo UI: uploads photo (evidence: `README.md`)
- Photo UI → Item Pipeline: submits image (evidence: `README.md`)
- Item Pipeline → Detection & Classification: detects items (evidence: `README.md`)
- Detection & Classification → Waste Knowledge: uses item classes (evidence: `src/ecosort/vision.py`)
- Detection & Classification → Image Preprocessing: preprocesses crops (evidence: `src/ecosort/vision.py`)
- Item Pipeline → Waste Knowledge: derives handling (evidence: `README.md`)
- Item Pipeline → Worker Guidance: produces guidance (evidence: `README.md`)
- Item Pipeline → Facility Router: requests routing (evidence: `README.md`)
- Facility Router → Facility Configuration: loads facilities (evidence: `src/ecosort/routing.py`)
- Item Pipeline → Uncertainty Review Gate: checks uncertainty (evidence: `README.md`)
- Uncertainty Review Gate → Human Review: queues review (evidence: `README.md`)
- Human Review → Review Feedback: writes corrections (evidence: `README.md`)
- Item Pipeline → Traceability Ledger: records decisions (evidence: `README.md`)
- Traceability Ledger → Analytics & Forecast: feeds analytics (evidence: `README.md`)
- Review Feedback → Dataset Preparation: feeds retraining (evidence: `README.md`)
- Dataset Preparation → Classifier Training: creates splits (evidence: `README.md`)
- Classifier Training → Image Preprocessing: uses transforms (evidence: `training/train.py`)
- Classifier Training → Evaluation Metrics: scores candidates (evidence: `training/train.py`)
- Classifier Training → Quality Evaluation: produces candidate (evidence: `README.md`)
- Quality Evaluation → Evaluation Metrics: computes gate metrics (evidence: `training/evaluate.py`)
- Quality Evaluation → Model Promotion: gates promotion (evidence: `README.md`)
- Model Promotion → Deployed Models: copies approved model (evidence: `training/promote.py`)
- Deployed Models → Detection & Classification: loads deployed classifier (evidence: `README.md`)
