# adithya-charan/cube-04-returns-manager architecture

> Architecture diagram of the GitHub repository adithya-charan/cube-04-returns-manager, 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/adithya-charan/cube-04-returns-manager
- Repository: https://github.com/adithya-charan/cube-04-returns-manager

## Overview

CUBE Returns Manager is a local-first returns inspection prototype. An operator uses a dashboard to enter product/package identifiers, submit return images, and review the resulting inspection; the API stores media, gathers visual observations, applies deterministic identity, completeness, condition, and disposition rules, and persists a result that may require human resolution. QR verification is a separate binding lookup, not an input to inspection decisions. The graph covers both React clients and the backend’s documented capabilities; some backend call details and UI component internals were not sampled, so undocumented links are omitted.

Main entry points: [`src/main.py`](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py) (FastAPI routes), [`mobile/src/App.jsx`](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/mobile/src/App.jsx) (Mobile app), [`website/src/App.jsx`](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/App.jsx) (Website app), [`website/src/components/CaptureView.jsx`](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/CaptureView.jsx) (Photo capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Operator clients"]
  node_mobile_app["Mobile app<br/>[App.jsx]"]
  node_web_app["Website app<br/>[App.jsx]"]
  node_web_dashboard["Dashboard view<br/>[DashboardView.jsx]"]
  node_web_qr["QR entry<br/>[QRScanView.jsx]"]
  node_web_capture["Photo capture<br/>[CaptureView.jsx]"]
  node_web_detail["Inspection detail"]
end

subgraph group_api["API workflows"]
  node_api_routes["FastAPI routes<br/>[main.py]"]
  node_auth_binding["QR binding lookup<br/>[main.py]"]
  node_media_upload["Media handling<br/>[main.py]"]
  node_inspection_pipeline["Inspection orchestration<br/>[main.py]"]
  node_review_resolution["Review resolution<br/>[main.py]"]
end

subgraph group_inspection["Inspection logic"]
  node_vision_contract["Vision observations<br/>[vision.py]"]
  node_decision_rules["Decision rules<br/>[engine.py]"]
  node_domain_models["Domain models<br/>[models.py]"]
end

subgraph group_persistence["Persistence"]
  node_storage_adapter["Media storage<br/>[storage.py]"]
  node_return_repository["Return repository<br/>[repository.py]"]
  node_database_models[("Database tables<br/>[database.py]")]
end

subgraph group_integrations["Vision providers"]
  node_ollama_provider["Ollama vision<br/>[vision_ollama.py]"]
  node_yolo_provider["YOLO detector<br/>[vision_yolo.py]"]
end

node_operator(("Returns operator"))
node_external_ollama["Ollama service"]
node_object_store[("S3-compatible storage")]

node_operator -->|"uses"| node_mobile_app
node_operator -->|"uses"| node_web_app
node_web_app -->|"renders"| node_web_dashboard
node_web_app -->|"renders"| node_web_qr
node_web_app -->|"renders"| node_web_capture
node_web_app -->|"renders"| node_web_detail
node_web_dashboard -->|"loads reviews"| node_api_routes
node_web_qr -->|"verifies identifiers"| node_auth_binding
node_web_capture -->|"uploads images"| node_media_upload
node_web_capture -->|"submits inspection"| node_inspection_pipeline
node_web_detail -->|"loads record"| node_api_routes
node_web_detail -->|"resolves review"| node_review_resolution
node_mobile_app -->|"loads reviews"| node_api_routes
node_mobile_app -->|"verifies identifiers"| node_auth_binding
node_mobile_app -->|"uploads images"| node_media_upload
node_mobile_app -->|"submits inspection"| node_inspection_pipeline
node_api_routes -->|"routes binding"| node_auth_binding
node_api_routes -->|"routes media"| node_media_upload
node_api_routes -->|"routes inspection"| node_inspection_pipeline
node_api_routes -->|"routes reviews"| node_review_resolution
node_media_upload -->|"stores file"| node_storage_adapter
node_storage_adapter -.->|"uploads objects"| node_object_store
node_inspection_pipeline -->|"requests observations"| node_vision_contract
node_inspection_pipeline -->|"evaluates observations"| node_decision_rules
node_inspection_pipeline -->|"persists decision"| node_return_repository
node_vision_contract -->|"provider implementation"| node_ollama_provider
node_vision_contract -.->|"optional detector"| node_yolo_provider
node_ollama_provider -.->|"requests inference"| node_external_ollama
node_decision_rules -->|"uses types"| node_domain_models
node_return_repository -->|"queries and writes"| node_database_models
node_review_resolution -->|"loads return"| node_return_repository

click node_mobile_app "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/mobile/src/App.jsx"
click node_web_app "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/App.jsx"
click node_web_dashboard "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/DashboardView.jsx"
click node_web_qr "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/QRScanView.jsx"
click node_web_capture "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/CaptureView.jsx"
click node_web_detail "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/InspectionDetailView.jsx"
click node_api_routes "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py"
click node_auth_binding "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py"
click node_media_upload "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py"
click node_inspection_pipeline "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py"
click node_review_resolution "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py"
click node_vision_contract "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/vision.py"
click node_decision_rules "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/engine.py"
click node_domain_models "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/models.py"
click node_ollama_provider "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/vision_ollama.py"
click node_yolo_provider "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/vision_yolo.py"
click node_storage_adapter "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/storage.py"
click node_return_repository "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/repository.py"
click node_database_models "https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/database.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_mobile_app,node_web_app,node_web_dashboard,node_web_qr,node_web_capture,node_web_detail toneBlue
class node_api_routes,node_auth_binding,node_media_upload,node_inspection_pipeline,node_review_resolution,node_object_store toneAmber
class node_vision_contract,node_decision_rules,node_domain_models toneMint
class node_storage_adapter,node_return_repository,node_database_models toneRose
class node_ollama_provider,node_yolo_provider,node_operator,node_external_ollama toneIndigo
```

## Components

### Operator clients

- [Mobile app](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/mobile/src/App.jsx): `mobile/src/App.jsx`
- [Website app](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/App.jsx): `website/src/App.jsx`
- [Dashboard view](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/DashboardView.jsx): `website/src/components/DashboardView.jsx`
- [QR entry](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/QRScanView.jsx): `website/src/components/QRScanView.jsx`
- [Photo capture](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/CaptureView.jsx): `website/src/components/CaptureView.jsx`
- [Inspection detail](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/website/src/components/InspectionDetailView.jsx): `website/src/components/InspectionDetailView.jsx`

### API workflows

- [FastAPI routes](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py): `src/main.py`
- [QR binding lookup](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py): `src/main.py`
- [Media handling](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py): `src/main.py`
- [Inspection orchestration](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py): `src/main.py`
- [Review resolution](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/main.py): `src/main.py`

### Inspection logic

- [Vision observations](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/vision.py): `src/vision.py`
- [Decision rules](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/engine.py): `src/engine.py`
- [Domain models](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/models.py): `src/models.py`

### Persistence

- [Media storage](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/storage.py): `src/storage.py`
- [Return repository](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/repository.py): `src/repository.py`
- [Database tables](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/database.py): `src/database.py`

### Vision providers

- [Ollama vision](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/vision_ollama.py): `src/vision_ollama.py`
- [YOLO detector](https://github.com/adithya-charan/cube-04-returns-manager/blob/main/src/vision_yolo.py): `src/vision_yolo.py`

### Other components

- **Returns operator**
- **Ollama service**
- **S3-compatible storage**

## Connections

- Returns operator → Mobile app: uses (evidence: `README.md`)
- Returns operator → Website app: uses (evidence: `README.md`)
- Website app → Dashboard view: renders (evidence: `website/src/App.jsx`)
- Website app → QR entry: renders (evidence: `website/src/App.jsx`)
- Website app → Photo capture: renders (evidence: `website/src/App.jsx`)
- Website app → Inspection detail: renders (evidence: `website/src/App.jsx`)
- Dashboard view → FastAPI routes: loads reviews (evidence: `README.md`)
- QR entry → QR binding lookup: verifies identifiers (evidence: `README.md`)
- Photo capture → Media handling: uploads images (evidence: `website/src/components/CaptureView.jsx`)
- Photo capture → Inspection orchestration: submits inspection (evidence: `website/src/components/CaptureView.jsx`)
- Inspection detail → FastAPI routes: loads record (evidence: `README.md`)
- Inspection detail → Review resolution: resolves review (evidence: `README.md`)
- Mobile app → FastAPI routes: loads reviews (evidence: `mobile/src/App.jsx`)
- Mobile app → QR binding lookup: verifies identifiers (evidence: `mobile/src/App.jsx`)
- Mobile app → Media handling: uploads images (evidence: `mobile/src/App.jsx`)
- Mobile app → Inspection orchestration: submits inspection (evidence: `mobile/src/App.jsx`)
- FastAPI routes → QR binding lookup: routes binding (evidence: `src/main.py`)
- FastAPI routes → Media handling: routes media (evidence: `src/main.py`)
- FastAPI routes → Inspection orchestration: routes inspection (evidence: `src/main.py`)
- FastAPI routes → Review resolution: routes reviews (evidence: `src/main.py`)
- Media handling → Media storage: stores file (evidence: `src/main.py`)
- Media storage → S3-compatible storage: uploads objects (evidence: `src/storage.py`)
- Inspection orchestration → Vision observations: requests observations (evidence: `src/main.py`)
- Inspection orchestration → Decision rules: evaluates observations (evidence: `src/main.py`)
- Inspection orchestration → Return repository: persists decision (evidence: `src/main.py`)
- Vision observations → Ollama vision: provider implementation (evidence: `src/vision_ollama.py`)
- Vision observations → YOLO detector: optional detector (evidence: `src/vision_yolo.py`)
- Ollama vision → Ollama service: requests inference (evidence: `README.md`)
- Decision rules → Domain models: uses types (evidence: `src/engine.py`)
- Return repository → Database tables: queries and writes (evidence: `src/repository.py`)
- Review resolution → Return repository: loads return (evidence: `src/main.py`)
