# e-waste-recycle-guru/recycleguru architecture

> Architecture diagram of the GitHub repository e-waste-recycle-guru/recycleguru, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e-waste-recycle-guru/recycleguru
- Repository: https://github.com/e-waste-recycle-guru/recycleguru

## Overview

RECYCLEGURU is a multi-channel e-waste collection and reverse-logistics platform, with public and role-specific web/mobile experiences, a Payload CMS, and a FastAPI domain backend. The principal workflow is a customer or business initiating a pickup, followed by operational dispatch and collection, then compliance/certificate handling and material traceability. The graph preserves documented CMS, analytics/intelligence, finance, security, and offline-sync capabilities. Many portal-to-backend integrations are unsampled, so those links are shown as unverified rather than asserted.

Main entry points: [`backend/reloopx/api/app.py`](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/api/app.py) (FastAPI API), [`backend/reloopx/models`](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/models) (Domain models), [`packages/api-client/src/client.ts`](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/packages/api-client/src/client.ts) (Typed API client), [`backend/reloopx/ai/decision_engine.py`](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/decision_engine.py) (Capacity recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["User channels"]
  node_customers["Customer portal"]
  node_business["Business portal"]
  node_collectors["Collector mobile"]
  node_partners["Partner portals"]
  node_recyclers["Recycler portal"]
  node_admin["Operations admin"]
  node_marketing["Public website"]
end

subgraph group_interfaces["API interfaces"]
  node_api_client["Typed API client<br/>[client.ts]"]
  node_backend_api["FastAPI API<br/>[app.py]"]
  node_web_v1["API v1 entry<br/>[route.ts]"]
  node_offline_queue["Offline mutation queue<br/>[queue.ts]"]
  node_sync_engine["Offline sync<br/>[sync-engine.ts]"]
end

subgraph group_operations["Collection operations"]
  node_pickup["Pickup booking<br/>[actions.ts]"]
  node_dispatch["Dispatch optimization"]
  node_logistics["Logistics operations"]
  node_traceability["Material traceability"]
end

subgraph group_governance["Governance and intelligence"]
  node_compliance["Eligibility checks"]
  node_certificates["Certificate handling<br/>[route.ts]"]
  node_decision_engine["Capacity recommendations<br/>[decision_engine.py]"]
  node_capacity_forecast["Capacity forecasts"]
  node_recommendations["Recommendations"]
  node_policy["Access policy<br/>[policy_engine.py]"]
end

subgraph group_data["Content and domain data"]
  node_domain_models[("Domain models")]
  node_payload[("Payload CMS<br/>[payload.config.ts]")]
end

node_user(("Platform users"))
node_fastapi_service["FastAPI service"]

node_user -.->|"books pickups"| node_customers
node_user -.->|"requests collections"| node_business
node_user -.->|"handles jobs"| node_collectors
node_customers -.->|"submits booking"| node_pickup
node_pickup -.->|"uses client"| node_api_client
node_business -.->|"uses client"| node_api_client
node_partners -.->|"uses client"| node_api_client
node_recyclers -.->|"uses client"| node_api_client
node_collectors -.->|"queues mutations"| node_offline_queue
node_sync_engine -->|"reads and updates"| node_offline_queue
node_sync_engine -->|"replays mutations"| node_api_client
node_backend_api -.->|"serves API"| node_fastapi_service
node_web_v1 -->|"identifies target"| node_fastapi_service
node_backend_api -.->|"uses domain data"| node_domain_models
node_dispatch -.->|"uses dispatch records"| node_domain_models
node_logistics -.->|"uses operations records"| node_domain_models
node_traceability -.->|"uses material records"| node_domain_models
node_compliance -->|"reads partner and hold data"| node_domain_models
node_decision_engine -->|"requests forecasts"| node_capacity_forecast
node_decision_engine -->|"creates proposals"| node_recommendations
node_policy -->|"records decisions"| node_domain_models
node_admin -.->|"generates certificates"| node_certificates
node_certificates -->|"reads pickups; creates certificates"| node_payload
node_marketing -.->|"publishes CMS content"| node_payload
node_backend_api -.->|"routes domain requests"| node_dispatch
node_backend_api -.->|"routes domain requests"| node_compliance
node_backend_api -.->|"routes domain requests"| node_traceability
node_backend_api -.->|"routes intelligence requests"| node_decision_engine

click node_customers "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/customer/src"
click node_business "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/business/src"
click node_collectors "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/mobile/app"
click node_partners "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/supplier/src"
click node_recyclers "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/recycler/src"
click node_admin "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/admin/src"
click node_marketing "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/web/src/app/(marketing)"
click node_api_client "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/packages/api-client/src/client.ts"
click node_backend_api "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/api/app.py"
click node_web_v1 "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/web/src/app/api/v1/route.ts"
click node_pickup "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/customer/src/features/pickup/actions.ts"
click node_dispatch "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/dispatch/optimization_engine.py"
click node_logistics "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/logistics"
click node_traceability "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/traceability"
click node_compliance "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/compliance/eligibility_engine.py"
click node_certificates "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/admin/src/app/api/operations/certificates/route.ts"
click node_decision_engine "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/decision_engine.py"
click node_capacity_forecast "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/forecasting/capacity_forecast.py"
click node_recommendations "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/recommendation_service.py"
click node_policy "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/security/policy_engine.py"
click node_offline_queue "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/mobile/src/offline/queue.ts"
click node_sync_engine "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/mobile/src/offline/sync-engine.ts"
click node_domain_models "https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/models"
click node_payload "https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/web/payload.config.ts"

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_customers,node_business,node_collectors,node_partners,node_recyclers,node_admin,node_marketing,node_user toneBlue
class node_api_client,node_backend_api,node_web_v1,node_offline_queue,node_sync_engine toneAmber
class node_pickup,node_dispatch,node_logistics,node_traceability,node_fastapi_service toneMint
class node_compliance,node_certificates,node_decision_engine,node_capacity_forecast,node_recommendations,node_policy toneRose
class node_domain_models,node_payload toneIndigo
```

## Components

### User channels

- [Customer portal](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/customer/src): `apps/customer/src`
- [Business portal](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/business/src): `apps/business/src`
- [Collector mobile](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/mobile/app): `apps/mobile/app`
- [Partner portals](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/supplier/src): `apps/supplier/src`
- [Recycler portal](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/recycler/src): `apps/recycler/src`
- [Operations admin](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/admin/src): `apps/admin/src`
- [Public website](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/apps/web/src/app/(marketing)): `apps/web/src/app/(marketing)`

### API interfaces

- [Typed API client](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/packages/api-client/src/client.ts): `packages/api-client/src/client.ts`
- [FastAPI API](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/api/app.py): `backend/reloopx/api/app.py`
- [API v1 entry](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/web/src/app/api/v1/route.ts): `apps/web/src/app/api/v1/route.ts`
- [Offline mutation queue](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/mobile/src/offline/queue.ts): `apps/mobile/src/offline/queue.ts`
- [Offline sync](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/mobile/src/offline/sync-engine.ts): `apps/mobile/src/offline/sync-engine.ts`

### Collection operations

- [Pickup booking](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/customer/src/features/pickup/actions.ts): `apps/customer/src/features/pickup/actions.ts`
- [Dispatch optimization](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/dispatch/optimization_engine.py): `backend/reloopx/dispatch/optimization_engine.py`
- [Logistics operations](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/logistics): `backend/reloopx/logistics`
- [Material traceability](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/traceability): `backend/reloopx/traceability`

### Governance and intelligence

- [Eligibility checks](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/compliance/eligibility_engine.py): `backend/reloopx/compliance/eligibility_engine.py`
- [Certificate handling](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/admin/src/app/api/operations/certificates/route.ts): `apps/admin/src/app/api/operations/certificates/route.ts`
- [Capacity recommendations](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/decision_engine.py): `backend/reloopx/ai/decision_engine.py`
- [Capacity forecasts](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/forecasting/capacity_forecast.py): `backend/reloopx/ai/forecasting/capacity_forecast.py`
- [Recommendations](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/ai/recommendation_service.py): `backend/reloopx/ai/recommendation_service.py`
- [Access policy](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/backend/reloopx/security/policy_engine.py): `backend/reloopx/security/policy_engine.py`

### Content and domain data

- [Domain models](https://github.com/e-waste-recycle-guru/recycleguru/tree/main/backend/reloopx/models): `backend/reloopx/models`
- [Payload CMS](https://github.com/e-waste-recycle-guru/recycleguru/blob/main/apps/web/payload.config.ts): `apps/web/payload.config.ts`

### Other components

- **Platform users**
- **FastAPI service**

## Connections

- Platform users → Customer portal: books pickups
- Platform users → Business portal: requests collections
- Platform users → Collector mobile: handles jobs
- Customer portal → Pickup booking: submits booking
- Pickup booking → Typed API client: uses client
- Business portal → Typed API client: uses client
- Partner portals → Typed API client: uses client
- Recycler portal → Typed API client: uses client
- Collector mobile → Offline mutation queue: queues mutations
- Offline sync → Offline mutation queue: reads and updates (evidence: `apps/mobile/src/offline/sync-engine.ts`)
- Offline sync → Typed API client: replays mutations (evidence: `apps/mobile/src/offline/sync-engine.ts`)
- FastAPI API → FastAPI service: serves API
- API v1 entry → FastAPI service: identifies target (evidence: `apps/web/src/app/api/v1/route.ts`)
- FastAPI API → Domain models: uses domain data
- Dispatch optimization → Domain models: uses dispatch records
- Logistics operations → Domain models: uses operations records
- Material traceability → Domain models: uses material records
- Eligibility checks → Domain models: reads partner and hold data (evidence: `backend/reloopx/compliance/eligibility_engine.py`)
- Capacity recommendations → Capacity forecasts: requests forecasts (evidence: `backend/reloopx/ai/decision_engine.py`)
- Capacity recommendations → Recommendations: creates proposals (evidence: `backend/reloopx/ai/decision_engine.py`)
- Access policy → Domain models: records decisions (evidence: `backend/reloopx/security/policy_engine.py`)
- Operations admin → Certificate handling: generates certificates
- Certificate handling → Payload CMS: reads pickups; creates certificates (evidence: `apps/admin/src/app/api/operations/certificates/route.ts`)
- Public website → Payload CMS: publishes CMS content
- FastAPI API → Dispatch optimization: routes domain requests
- FastAPI API → Eligibility checks: routes domain requests
- FastAPI API → Material traceability: routes domain requests
- FastAPI API → Capacity recommendations: routes intelligence requests