How adjoazzz/smartsort works
Purpose and topology
Smart Sort is a smart-waste-collection system with three deployable parts: a Vite/React operations UI, a Node/Express API backed by Prisma/PostgreSQL, and a Python ML inference service carrying Keras/TFLite bin models. The sparse README documents only frontend startup; the repository structure defines the broader product.
Frontend entry and application shell
The browser client starts at src/main.tsx, mounts its root/application shell through src/app/Root.tsx and src/app/App.tsx, and defines navigation in src/app/routes.tsx. It provides role-oriented operational screens: administrative dashboards, collection execution, device/bin management, alerts, analytics, users/collectors, and public/authentication/onboarding flows.
Client access, state, and failure boundaries
Route-level authorization is enforced by src/components/ProtectedRoute.tsx. API access is centralized in src/lib/apiService.ts and authenticated fetch behavior in src/lib/authFetch.ts; Supabase client integration is isolated in src/lib/supabaseClient.ts. Polling and real-time data are encapsulated in src/hooks/usePollingFetch.ts and src/hooks/useRealtimeData.ts, keeping page components such as src/pages/Dashboard/Dashboard.tsx and src/pages/CollectorDashboard/CollectorDashboard.tsx focused on presentation/workflow state. Error containment includes src/components/ErrorBoundary.tsx and src/components/RouteErrorBoundary.tsx; sentry.tsx indicates Sentry monitoring.
API server and request pipeline
smartsort-backend/server.js is the API process entry point; smartsort-backend/routes/index.js composes domain routers. Requests cross cross-cutting middleware for request identity, logging, authentication, validation, rate limiting, and centralized error handling, represented by smartsort-backend/middleware/requestId.js, smartsort-backend/middleware/auth.js, and smartsort-backend/middleware/errorHandler.js. smartsort-backend/instrument.js is an observability/instrumentation boundary.
Domain services and API layers
Routes/controllers expose bounded operational domains—authentication/users, devices/bins, collection jobs, alerts, dashboards/analytics, audit logs, and feedback. Controllers translate HTTP concerns into service calls; services own domain/data behavior. Representative verticals are smartsort-backend/routes/jobs.js → smartsort-backend/controllers/jobController.js → smartsort-backend/services/jobService.js, and corresponding device handling in smartsort-backend/routes/devices.js, smartsort-backend/controllers/deviceController.js, and smartsort-backend/services/deviceService.js. Audit functionality is a material cross-cutting domain via smartsort-backend/routes/auditLogs.js and smartsort-backend/services/auditService.js.
Persistence, identity, and operational data flow
The API uses Prisma, instantiated through smartsort-backend/lib/prisma.js, against a relational schema in smartsort-backend/prisma/schema.prisma; migrations establish its deployable database contract in smartsort-backend/prisma/migrations/20260615192157_init/migration.sql. Seed scripts (smartsort-backend/prisma/seed.js, smartsort-backend/seed_events.js) support initialized/demo operational data. The frontend’s Supabase integration and backend auth middleware imply authentication/session boundaries spanning client, Supabase, and API; exact token/provider mechanics require source inspection.
ML inference service and physical-device boundary
smartsort-ml/app.py is a separate Python service, containerized by smartsort-ml/Dockerfile, with dependencies in smartsort-ml/requirements.txt. It packages both smartsort-ml/smart_bin_model.keras and smartsort-ml/smart_bin_model.tflite, suggesting server and edge/mobile-compatible inference options. smartsort-ml/test_camera.py marks camera/image input as the hardware-facing boundary. The repository does not expose the API-to-ML integration path in the provided tree, so treat it as an independently deployed service until verified.
Components 18
Operations UI
Vite/React browser application.
- Operations users
- React entry and shell
src/main.tsx - Routes and role screens · Navigation covers operations, admin, collector, and public flows.
src/app/routes.tsx - Route authorization
src/components/ProtectedRoute.tsx - API, polling, and realtime · Centralizes authenticated API access and live updates.
src/lib/apiService.ts - Client failure monitoring · Contains UI failures and reports monitoring events.
src/components/ErrorBoundary.tsx - Supabase · Client-side authentication/session boundary.
src/lib/supabaseClient.ts
API Platform
Node/Express operational API.
- Express API server
smartsort-backend/server.js - Request middleware · Applies identity, logging, authentication, validation, rate limits, and error handling.
smartsort-backend/middleware/auth.js - Domain routers · Exposes auth, devices, jobs, alerts, dashboards, audit, and feedback domains.
smartsort-backend/routes/index.js - Collection jobs · Collection execution domain vertical.
smartsort-backend/services/jobService.js - Devices and bins · Device and bin management domain vertical.
smartsort-backend/services/deviceService.js - Audit logs · Cross-cutting operational audit domain.
smartsort-backend/services/auditService.js - Prisma data access
smartsort-backend/lib/prisma.js - PostgreSQL schema · Deployable operational data contract and migrations.
smartsort-backend/prisma/schema.prisma
ML Inference
Independently deployed Python inference service.
- Python inference service · Separate deployable bin-classification runtime.
smartsort-ml/app.py - Bin models · Supports server and edge/mobile-compatible inference artifacts.
smartsort-ml/smart_bin_model.keras - Camera/image input · Physical-device image capture boundary.
smartsort-ml/test_camera.py
Connections 18
- Operations users → React entry and shell: uses
- React entry and shell → Routes and role screens: renders
- Routes and role screens → Route authorization: protects routes
- Routes and role screens → API, polling, and realtime: loads operational data
- React entry and shell → Client failure monitoring: contains failures
- API, polling, and realtime → Supabase: uses session
- API, polling, and realtime → Express API server: authenticated HTTP
- Express API server → Request middleware: processes requests through
- Request middleware → Domain routers: authorizes and dispatches
- Domain routers → Collection jobs: collection jobs
- Domain routers → Devices and bins: devices and bins
- Domain routers → Audit logs: audit endpoints
- Collection jobs → Prisma data access: persists data
- Devices and bins → Prisma data access: persists data
- Audit logs → Prisma data access: records audits
- Prisma data access → PostgreSQL schema: queries
- Camera/image input → Python inference service: provides images
- Python inference service → Bin models: loads