# neptune-glitch/ecocycle_ai architecture

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

- Interactive diagram: https://gitdiagram.com/neptune-glitch/ecocycle_ai
- Repository: https://github.com/neptune-glitch/ecocycle_ai

## Overview

EcoCycle AI turns an uploaded waste photo into recycling and reuse advice. In the Streamlit workflow, optional user notes are checked for threats, then the image is identified, matching knowledge is retrieved, and advice is generated and displayed. A separate Google ADK agent registers security, identification, and retrieval tools. The knowledge base is built from the CSV into ChromaDB using Gemini embeddings. The README describes broader capabilities; the graph follows sampled code where it differs, and does not infer unsampled ADK runtime behavior.

Main entry points: [`streamlit_app.py`](https://github.com/neptune-glitch/ecocycle_ai/blob/main/streamlit_app.py) (Streamlit App), [`skills/retrieve.py`](https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/retrieve.py) (Knowledge Retrieval), [`build_db.py`](https://github.com/neptune-glitch/ecocycle_ai/blob/main/build_db.py) (Database Builder), [`skills/identify.py`](https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/identify.py) (Image Identification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_streamlit["Streamlit App<br/>[streamlit_app.py]"]
  node_result["Recommendations<br/>[streamlit_app.py]"]
end

subgraph group_agent["Agent Orchestration"]
  node_adk["ADK Agent<br/>[agent.py]"]
  node_cli["CLI Workflow<br/>[app.py]"]
end

subgraph group_workflow["Waste Analysis"]
  node_security["Input Security<br/>[security.py]"]
  node_identify["Image Identification<br/>[identify.py]"]
  node_advise["Advice Generation<br/>[advise.py]"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_retrieve["Knowledge Retrieval<br/>[retrieve.py]"]
  node_build["Database Builder<br/>[build_db.py]"]
  node_embed["Embedding Builder<br/>[embed.py]"]
  node_dataset["Waste Dataset"]
  node_chroma[("ChromaDB")]
end

node_user(("User"))
node_gemini{{"Gemini API"}}

node_user -->|"uploads image"| node_streamlit
node_streamlit -->|"checks note"| node_security
node_streamlit -->|"identifies image"| node_identify
node_streamlit -->|"requests knowledge"| node_retrieve
node_streamlit -->|"generates advice"| node_advise
node_streamlit -->|"displays response"| node_result
node_adk -->|"registers tool"| node_security
node_adk -->|"registers tool"| node_identify
node_adk -->|"registers tool"| node_retrieve
node_cli -->|"identifies image"| node_identify
node_cli -->|"requests knowledge"| node_retrieve
node_cli -->|"generates advice"| node_advise
node_identify -->|"analyzes image"| node_gemini
node_advise -->|"generates response"| node_gemini
node_retrieve -->|"creates query embedding"| node_gemini
node_retrieve -->|"queries vectors"| node_chroma
node_retrieve -->|"builds if absent"| node_build
node_build -->|"reads records"| node_dataset
node_build -->|"embeds records"| node_gemini
node_build -->|"stores vectors"| node_chroma
node_embed -->|"reads records"| node_dataset
node_embed -->|"embeds records"| node_gemini
node_embed -->|"stores vectors"| node_chroma

click node_streamlit "https://github.com/neptune-glitch/ecocycle_ai/blob/main/streamlit_app.py"
click node_result "https://github.com/neptune-glitch/ecocycle_ai/blob/main/streamlit_app.py"
click node_adk "https://github.com/neptune-glitch/ecocycle_ai/blob/main/agents/agent.py"
click node_cli "https://github.com/neptune-glitch/ecocycle_ai/blob/main/app.py"
click node_security "https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/security.py"
click node_identify "https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/identify.py"
click node_advise "https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/advise.py"
click node_retrieve "https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/retrieve.py"
click node_build "https://github.com/neptune-glitch/ecocycle_ai/blob/main/build_db.py"
click node_embed "https://github.com/neptune-glitch/ecocycle_ai/blob/main/rag/embed.py"
click node_dataset "https://github.com/neptune-glitch/ecocycle_ai/blob/main/data/waste_knowledge.csv"

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_streamlit,node_result,node_user toneBlue
class node_adk,node_cli toneAmber
class node_security,node_identify,node_advise,node_gemini toneMint
class node_retrieve,node_build,node_embed,node_dataset,node_chroma toneRose
```

## Components

### User Interface

- [Streamlit App](https://github.com/neptune-glitch/ecocycle_ai/blob/main/streamlit_app.py): `streamlit_app.py`
- [Recommendations](https://github.com/neptune-glitch/ecocycle_ai/blob/main/streamlit_app.py): `streamlit_app.py`

### Agent Orchestration

- [ADK Agent](https://github.com/neptune-glitch/ecocycle_ai/blob/main/agents/agent.py): `agents/agent.py`
- [CLI Workflow](https://github.com/neptune-glitch/ecocycle_ai/blob/main/app.py): `app.py`

### Waste Analysis

- [Input Security](https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/security.py): `skills/security.py`
- [Image Identification](https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/identify.py): `skills/identify.py`
- [Advice Generation](https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/advise.py): `skills/advise.py`

### Knowledge Retrieval

- [Knowledge Retrieval](https://github.com/neptune-glitch/ecocycle_ai/blob/main/skills/retrieve.py): `skills/retrieve.py`
- [Database Builder](https://github.com/neptune-glitch/ecocycle_ai/blob/main/build_db.py): `build_db.py`
- [Embedding Builder](https://github.com/neptune-glitch/ecocycle_ai/blob/main/rag/embed.py): `rag/embed.py`
- [Waste Dataset](https://github.com/neptune-glitch/ecocycle_ai/blob/main/data/waste_knowledge.csv): `data/waste_knowledge.csv`
- **ChromaDB**

### Other components

- **User**
- **Gemini API**

## Connections

- User → Streamlit App: uploads image (evidence: `README.md`)
- Streamlit App → Input Security: checks note (evidence: `streamlit_app.py`)
- Streamlit App → Image Identification: identifies image (evidence: `streamlit_app.py`)
- Streamlit App → Knowledge Retrieval: requests knowledge (evidence: `streamlit_app.py`)
- Streamlit App → Advice Generation: generates advice (evidence: `streamlit_app.py`)
- Streamlit App → Recommendations: displays response (evidence: `streamlit_app.py`)
- ADK Agent → Input Security: registers tool (evidence: `agents/agent.py`)
- ADK Agent → Image Identification: registers tool (evidence: `agents/agent.py`)
- ADK Agent → Knowledge Retrieval: registers tool (evidence: `agents/agent.py`)
- CLI Workflow → Image Identification: identifies image (evidence: `app.py`)
- CLI Workflow → Knowledge Retrieval: requests knowledge (evidence: `app.py`)
- CLI Workflow → Advice Generation: generates advice (evidence: `app.py`)
- Image Identification → Gemini API: analyzes image (evidence: `skills/identify.py`)
- Advice Generation → Gemini API: generates response (evidence: `skills/advise.py`)
- Knowledge Retrieval → Gemini API: creates query embedding (evidence: `skills/retrieve.py`)
- Knowledge Retrieval → ChromaDB: queries vectors (evidence: `skills/retrieve.py`)
- Knowledge Retrieval → Database Builder: builds if absent (evidence: `skills/retrieve.py`)
- Database Builder → Waste Dataset: reads records (evidence: `build_db.py`)
- Database Builder → Gemini API: embeds records (evidence: `build_db.py`)
- Database Builder → ChromaDB: stores vectors (evidence: `build_db.py`)
- Embedding Builder → Waste Dataset: reads records (evidence: `rag/embed.py`)
- Embedding Builder → Gemini API: embeds records (evidence: `rag/embed.py`)
- Embedding Builder → ChromaDB: stores vectors (evidence: `rag/embed.py`)
