-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathexplanation.txt
More file actions
148 lines (94 loc) Β· 5.72 KB
/
explanation.txt
File metadata and controls
148 lines (94 loc) Β· 5.72 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
π§© ReBin Pro β Codebase Explained (Simplified & Technical)
π― What It Does
ReBin Pro helps users sort waste correctly.
You upload or take a photo of an item, and the app tells you whether it belongs in recycling, compost, or trash, along with a short explanation and eco-tip.
It uses computer vision to detect items and AI reasoning (via OpenRouter or Gemini) to explain the decision.
ποΈ Architecture Overview
Full-stack app with:
Frontend (React + TypeScript) β user interface
Backend (FastAPI) β handles AI calls and database
Cloudflare Worker β image preprocessing + routing
Supabase (PostgreSQL) β authentication and data storage
Mock CV Service β local test for object detection
Docker β containerized deployment for all services
π₯οΈ Frontend β React App
Purpose: The user-facing web app for uploading images, viewing results, and tracking impact.
Built with: React 18, TypeScript, React Query, TailwindCSS, Supabase JS SDK.
Key Files
File Description
frontend/src/App.tsx Main app entry point and route setup.
frontend/src/components/CameraUpload.tsx Lets users take/upload a photo and enter ZIP code; sends to backend for analysis.
frontend/src/components/ResultCard.tsx Displays AIβs classification (Recycle/Compost/Trash) with confidence, reasoning, and eco-tip.
frontend/src/components/StatsPanel.tsx Shows user progress and total COβ saved.
frontend/src/lib/api.ts Wrapper for backend HTTP requests (/infer, /explain, /event).
frontend/src/lib/supabase.ts Configures Supabase Auth + DB client.
frontend/src/types/index.ts Shared TypeScript interfaces (e.g., SortEvent, Item, Policy).
Frontend flow:
CameraUpload β calls api.infer() β backend returns detected items β calls api.explain() β shows in ResultCard β logs event to Supabase β updates StatsPanel.
βοΈ Backend β FastAPI Server
Purpose: Core logic and integration with AI services and the database.
Built with: FastAPI, Pydantic, httpx/aiohttp (async HTTP), Supabase Python Client.
Key Files
File Description
backend/main.py App entry point; includes CORS setup and route registration.
backend/routes/infer.py Receives photo, forwards to CV model (on Gradient or mock), returns detected items.
backend/routes/explain.py Sends detected items + ZIP policy to OpenRouter/Gemini; returns bin decision, rationale, and eco-tip.
backend/routes/event.py Logs the userβs sort event and COβ savings to Supabase.
backend/utils/openrouter_client.py Handles OpenRouter API requests and response parsing.
backend/utils/supabase_client.py Connects to Supabase for reading/writing data.
backend/schemas.py Pydantic models for validation (e.g., Item, ExplainRequest, SortEvent).
Backend flow:
Receive image β /infer detects items β /explain decides bin type β /event saves record β sends combined JSON back to frontend.
π Edge Layer β Cloudflare Worker
Purpose: Lightweight preprocessing & orchestration at the edge for faster responses.
File Description
cloudflare-worker/src/index.ts Resizes uploaded image, reads ZIP param, fetches local recycling policy from KV storage, then forwards data to the backend (/infer, /explain). Combines responses into one JSON reply.
This reduces backend load and latency for common ZIP lookups.
π§ AI Services
Component Description
Computer Vision (Model) Deployed on DigitalOcean Gradient (or local mock). Detects items and materials in the image.
OpenRouter / Gemini LLM used for reasoning β decides the correct bin and explains the logic in plain language.
ElevenLabs Voice Converts short text feedback into speech for accessibility and βwow factor.β
services/cv-mock/app.py A small mock CV API returning sample detections for testing without a real GPU model.
ποΈ Database β Supabase (PostgreSQL)
Stores all user data and statistics.
Tables
users: basic profile info (email, zip)
sort_events: one row per image processed (items, decision, COβ saved)
policies: recycling rules by ZIP code (cached in Cloudflare KV)
βοΈ Configuration & Infrastructure
File Description
frontend/vite.config.ts, tailwind.config.js, tsconfig.json Build, styling, and TypeScript configs.
backend/requirements.txt, backend/Dockerfile Python deps & container setup.
docker-compose.yml Runs frontend, backend, CV mock, and DB together.
.env.example (root + frontend + backend) Template for all API keys and URLs.
services/cv-mock/Dockerfile Container for mock CV service.
π Complete Data Flow
User uploads photo in browser.
Cloudflare Worker compresses & forwards to backend with ZIP code.
Backend /infer β CV model detects items.
Backend /explain β AI model decides bins + reasoning.
Backend /event β logs event + COβ impact to Supabase.
Frontend displays results and plays ElevenLabs audio.
StatsPanel updates total items sorted and emissions saved.
π§° Key Technologies
Frontend: React + TypeScript + TailwindCSS + React Query
Backend: FastAPI + Pydantic + httpx + Supabase Client
Edge: Cloudflare Workers + KV Storage
AI: OpenRouter / Gemini (reasoning), Gradient CV model (detection), ElevenLabs TTS
Database: Supabase (PostgreSQL)
Deployment: Docker Compose + GoDaddy Domain
βΆοΈ How to Run Locally
Copy .env.example β .env and fill in your API keys (Supabase, OpenRouter, ElevenLabs).
Run docker-compose up --build.
Visit http://localhost:5173
β upload a photo β watch classification + reasoning appear.
Check Supabase dashboard β see logged sort_events.
β
Summary
ReBin Pro is a full, modular AI application:
React frontend for user interaction
FastAPI backend for AI logic and DB I/O
Cloudflare edge for speed
Supabase database for persistent stats
OpenRouter + Gradient + ElevenLabs for the βAI magic.β
All services talk to each other through clear REST APIs, making it easy to extend or replace components later.