danielmreen/wastegrab

1. Monorepo boundary

WasteGrab is an Nx monorepo with three runtime apps and one shared library: an Angular frontend (apps/frontend), an Express/Prisma backend (apps/backend), Playwright/API tests (apps/e2e), and shared TypeScript domain types (libs/shared/types). That shared library is the main contract boundary between UI and API.

2. Frontend as the user-facing orchestration layer

The Angular app is organized by role and workflow, not by generic widgets. It has route/page areas for customer, collector, admin, auth, pickup detail, onboarding, and home. The frontend mostly composes UI state and calls backend services under src/app/services, while reusable visual primitives live in src/app/ui and the custom Zard component system.

3. Backend as the application and integration layer

The backend is an Express API with routes split by feature and role: auth, addresses, pickups, notifications, places, waste categories, Roboflow AI, and role-specific subtrees for admin/customer/collector. Business logic is pushed into src/services, while middleware handles cross-cutting concerns like auth and error handling. This makes the backend the central orchestration point for database, external APIs, and notification delivery.

4. Shared API/domain model

libs/shared/types defines the common request/response shapes and domain models for addresses, pickups, users, locations, vouchers, waste categories, transactions, notifications, places, and AI analysis. This reduces drift between Angular and Express and is the main interface for architecture diagrams that show typed contracts crossing the frontend/backend boundary.

5. Role-specific workflows

The product is split into three operational personas:

- Customers create pickup requests, upload images, review AI suggestions, manage addresses, track progress, and redeem vouchers.

- Collectors accept and process pickups, verify actual waste data, and use map-based route planning.

- Admins maintain operational data such as users, locations, pickups, vouchers, notifications, and waste categories.

These are reflected both in frontend page structure and backend route grouping.

6. Pickup lifecycle as the core domain flow

The central business process is a pickup request moving through states such as Pending, Accepted, Arrived, Verified, Completed, and Cancelled. Customer-facing pages create and track the request; collector pages update status and verify actual weight; admin pages can inspect and manage the same objects. The pickup domain is therefore the main shared data flow through the system.

7. Rewards and redemption subsystem

Reward points are tracked as a ledger-like transaction flow rather than just a display value. Customers accumulate points from verified pickups and spend them on vouchers; admins manage voucher definitions; both customer and admin UIs expose this rewards layer. The shared transaction model suggests that rewards are a first-class domain boundary, not an incidental UI feature.

8. AI-assisted image analysis and file handling

Waste image analysis is integrated through Roboflow. The customer flow uploads images, the backend invokes analysis to estimate waste category, weight, and reward points, and the frontend allows manual adjustment before final submission. Image storage is separated through Supabase Storage, while the backend also contains upload-related assets and scripts, indicating a split between persistent object storage and local/dev handling.

9. Maps and location services

Location search and route planning are major integration points. The backend exposes places-related services and routes, while the frontend includes a route-map UI and Google-place-input component. The README also mentions Google Places API for search/autocomplete, MapLibre for rendering, and OSRM for route previews, so the map subsystem spans both client rendering and server-assisted lookup/routing.

10. Notifications and live updates

Notifications are handled as a dedicated subsystem with three delivery modes: in-app notifications, a server-sent events notification stream, and web push support. The backend has notification routes and a notification-stream.service, while the frontend has notification services and header UI elements for surfacing updates. This is a distinct asynchronous channel separate from the main request/response API.

11. Persistence and schema ownership

Prisma is the main data-access layer, backed by MySQL/MariaDB. The backend owns the Prisma schema in apps/backend/prisma/schema.prisma, with generated client code also checked into backend/src/generated/prisma. There is also raw SQL schema support in apps/backend/sql/schema.sql, which matters for local sync/bootstrap and diagramming the persistence boundary.

12. API surface and deployment shape

In development, the Angular app proxies /api traffic to the backend. In Docker, the stack is split into MariaDB, a schema-sync container, the backend API, and the frontend served by Nginx. This means the deployment architecture is a classic split-tier web app with a separate database, not a serverless or single-process design.

13. Testing and operational confidence

The apps/e2e project contains Playwright tests plus API operation specs for customer, collector, admin, and platform flows. CI is run through GitHub Actions, with Docker image publishing and deployment-related checks. For an architecture diagram, these testing layers sit alongside the runtime apps as verification and release boundaries rather than part of the request path.

14. Tooling and auxiliary automation

The repo includes Graphify codebase graph tooling and a WhatsApp notifier helper under tools/, plus agent/CI monitoring artifacts under .agents, .github, and .codex. These are supporting operations tools, not product features, but they show the repository is managed as an automation-friendly platform with repository-level workflow support.