# danielmreen/wastegrab architecture

> Architecture diagram of the GitHub repository danielmreen/wastegrab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielmreen/wastegrab
- Repository: https://github.com/danielmreen/wastegrab

## Overview

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.

Main entry points: [`apps/backend`](https://github.com/danielmreen/wastegrab/tree/main/apps/backend) (Backend), [`apps/frontend`](https://github.com/danielmreen/wastegrab/tree/main/apps/frontend) (Frontend), [`libs/shared/types/src/lib/types`](https://github.com/danielmreen/wastegrab/tree/main/libs/shared/types/src/lib/types) (Shared types), [`docker-compose.yml`](https://github.com/danielmreen/wastegrab/blob/main/docker-compose.yml) (Docker stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_monorepo["WasteGrab<br/>Nx monorepo"]
end

subgraph group_runtime["Runtime Apps"]
  node_frontend["Frontend<br/>Angular app"]
  node_fe_pages["Pages<br/>route screens"]
  node_fe_services["UI services<br/>API clients"]
  node_fe_ui["UI kit<br/>components"]
  node_backend["Backend<br/>Express API"]
  node_be_routes["Routes<br/>HTTP API"]
  node_be_services["Services<br/>business logic"]
  node_be_middleware["Middleware<br/>cross-cutting"]
  node_be_prisma[("Persistence<br/>Prisma + SQL")]
  node_e2e["E2E tests<br/>Playwright suite"]
end

subgraph group_contract["Shared Contract"]
  node_shared_types["Shared types<br/>domain models"]
end

subgraph group_ops["Ops & Delivery"]
  node_docker_stack["Docker stack<br/>container deploy<br/>[docker-compose.yml]"]
  node_ci["CI workflow<br/>GitHub Actions<br/>[ci.yml]"]
  node_graphify["Graphify<br/>tooling"]
  node_wa_notifier["WA notifier<br/>automation tool"]
end

node_monorepo -->|"contains"| node_frontend
node_monorepo -->|"contains"| node_backend
node_monorepo -->|"contains"| node_e2e
node_monorepo -->|"contains"| node_shared_types
node_frontend -->|"organizes"| node_fe_pages
node_frontend -->|"uses"| node_fe_services
node_frontend -->|"renders with"| node_fe_ui
node_fe_services -->|"typed by"| node_shared_types
node_backend -->|"exposes"| node_be_routes
node_backend -->|"orchestrates"| node_be_services
node_backend -->|"guards"| node_be_middleware
node_backend -->|"persists to"| node_be_prisma
node_be_routes -->|"typed by"| node_shared_types
node_be_services -->|"typed by"| node_shared_types
node_frontend -->|"calls"| node_backend
node_backend -->|"shares contracts"| node_shared_types
node_e2e -->|"drives"| node_frontend
node_e2e -->|"verifies"| node_backend
node_docker_stack -->|"runs"| node_backend
node_docker_stack -->|"serves"| node_frontend
node_docker_stack -->|"boots"| node_be_prisma
node_ci -->|"checks"| node_e2e
node_ci -->|"builds"| node_docker_stack
node_graphify -.->|"analyzes"| node_monorepo
node_wa_notifier -.->|"supports"| node_ci

click node_frontend "https://github.com/danielmreen/wastegrab/tree/main/apps/frontend"
click node_fe_pages "https://github.com/danielmreen/wastegrab/tree/main/apps/frontend/src/app/pages"
click node_fe_services "https://github.com/danielmreen/wastegrab/tree/main/apps/frontend/src/app/services"
click node_fe_ui "https://github.com/danielmreen/wastegrab/tree/main/apps/frontend/src/app/ui"
click node_backend "https://github.com/danielmreen/wastegrab/tree/main/apps/backend"
click node_be_routes "https://github.com/danielmreen/wastegrab/tree/main/apps/backend/src/routes"
click node_be_services "https://github.com/danielmreen/wastegrab/tree/main/apps/backend/src/services"
click node_be_middleware "https://github.com/danielmreen/wastegrab/tree/main/apps/backend/src/middleware"
click node_be_prisma "https://github.com/danielmreen/wastegrab/tree/main/apps/backend/prisma"
click node_shared_types "https://github.com/danielmreen/wastegrab/tree/main/libs/shared/types/src/lib/types"
click node_e2e "https://github.com/danielmreen/wastegrab/tree/main/apps/e2e"
click node_docker_stack "https://github.com/danielmreen/wastegrab/blob/main/docker-compose.yml"
click node_ci "https://github.com/danielmreen/wastegrab/blob/main/.github/workflows/ci.yml"
click node_graphify "https://github.com/danielmreen/wastegrab/tree/main/tools/graphify"
click node_wa_notifier "https://github.com/danielmreen/wastegrab/tree/main/tools/wa-notifier"

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_monorepo toneBlue
class node_frontend,node_fe_pages,node_fe_services,node_fe_ui,node_backend,node_be_routes,node_be_services,node_be_middleware,node_be_prisma,node_e2e toneAmber
class node_shared_types toneMint
class node_docker_stack,node_ci,node_graphify,node_wa_notifier toneRose
```

## Components

### Repository

Nx monorepo and supporting automation

- **WasteGrab**: Nx monorepo · Top-level workspace boundary for all apps, libraries, and tooling

### Runtime Apps

User-facing app, API, and end-to-end tests

- [Frontend](https://github.com/danielmreen/wastegrab/tree/main/apps/frontend): Angular app · User-facing UI and workflow orchestration · `apps/frontend`
- [Pages](https://github.com/danielmreen/wastegrab/tree/main/apps/frontend/src/app/pages): route screens · Role- and workflow-specific screens for customer, collector, admin, auth, home, and pickup detail · `apps/frontend/src/app/pages`
- [UI services](https://github.com/danielmreen/wastegrab/tree/main/apps/frontend/src/app/services): API clients · Frontend service layer for auth, pickups, users, locations, notifications, and AI analysis · `apps/frontend/src/app/services`
- [UI kit](https://github.com/danielmreen/wastegrab/tree/main/apps/frontend/src/app/ui): components · Reusable visual primitives, header/nav, maps, and Zard component system · `apps/frontend/src/app/ui`
- [Backend](https://github.com/danielmreen/wastegrab/tree/main/apps/backend): Express API · Application and integration layer for domain operations and external services · `apps/backend`
- [Routes](https://github.com/danielmreen/wastegrab/tree/main/apps/backend/src/routes): HTTP API · Feature and role-based route tree for auth, pickups, addresses, notifications, places, AI, and admin/customer/collector flows · `apps/backend/src/routes`
- [Services](https://github.com/danielmreen/wastegrab/tree/main/apps/backend/src/services): business logic · Backend orchestration for auth, addresses, achievements, notifications, places, and storage · `apps/backend/src/services`
- [Middleware](https://github.com/danielmreen/wastegrab/tree/main/apps/backend/src/middleware): cross-cutting · Auth and error-handling boundaries for request processing · `apps/backend/src/middleware`
- [Persistence](https://github.com/danielmreen/wastegrab/tree/main/apps/backend/prisma): Prisma + SQL · Database schema ownership and local schema bootstrap for MySQL/MariaDB · `apps/backend/prisma`
- [E2E tests](https://github.com/danielmreen/wastegrab/tree/main/apps/e2e): Playwright suite · Customer, collector, admin, and platform verification flows · `apps/e2e`

### Shared Contract

Typed domain models shared across runtime layers

- [Shared types](https://github.com/danielmreen/wastegrab/tree/main/libs/shared/types/src/lib/types): domain models · Common request/response and domain contracts shared by frontend and backend · `libs/shared/types/src/lib/types`

### Ops & Delivery

Build, test, Docker, and repository automation

- [Docker stack](https://github.com/danielmreen/wastegrab/blob/main/docker-compose.yml): container deploy · MariaDB, schema sync, backend API, and frontend/Nginx deployment shape · `docker-compose.yml`
- [CI workflow](https://github.com/danielmreen/wastegrab/blob/main/.github/workflows/ci.yml): GitHub Actions · Repository build, test, and release checks · `.github/workflows/ci.yml`
- [Graphify](https://github.com/danielmreen/wastegrab/tree/main/tools/graphify): tooling · Codebase graph generation and repository architecture tooling · `tools/graphify`
- [WA notifier](https://github.com/danielmreen/wastegrab/tree/main/tools/wa-notifier): automation tool · Auxiliary WhatsApp notification helper under tools · `tools/wa-notifier`

## Connections

- WasteGrab → Frontend: contains · Workspace includes the Angular frontend
- WasteGrab → Backend: contains · Workspace includes the Express backend
- WasteGrab → E2E tests: contains · Workspace includes end-to-end tests
- WasteGrab → Shared types: contains · Workspace includes shared domain contracts
- Frontend → Pages: organizes · Feature screens are grouped by persona and workflow
- Frontend → UI services: uses · UI composes state through service clients
- Frontend → UI kit: renders with · UI uses shared visual primitives and custom components
- UI services → Shared types: typed by · Frontend requests and responses use shared models
- Backend → Routes: exposes · HTTP API surface is defined by route modules
- Backend → Services: orchestrates · Business logic is concentrated in service modules
- Backend → Middleware: guards · Middleware handles auth and failures
- Backend → Persistence: persists to · Backend owns database access and schema
- Routes → Shared types: typed by · API shapes are aligned with shared contracts
- Services → Shared types: typed by · Domain operations use shared models
- Frontend → Backend: calls · Angular app consumes the backend API
- Backend → Shared types: shares contracts · Backend and frontend share the same domain boundary
- E2E tests → Frontend: drives · Playwright validates user-facing workflows
- E2E tests → Backend: verifies · API and role flows are exercised against the backend
- Docker stack → Backend: runs · Container stack deploys the API service
- Docker stack → Frontend: serves · Frontend is served through Nginx in Docker
- Docker stack → Persistence: boots · Database schema sync and storage are part of the stack
- CI workflow → E2E tests: checks · CI runs test and validation workflows
- CI workflow → Docker stack: builds · CI supports containerized delivery and release checks
- Graphify → WasteGrab: analyzes · Graphify tooling documents repository structure
- WA notifier → CI workflow: supports · Auxiliary automation can notify on operational events