# aljayvee/capstone_server architecture

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

- Interactive diagram: https://gitdiagram.com/aljayvee/capstone_server
- Repository: https://github.com/aljayvee/capstone_server

## Overview

SUGO On-The-Go is a logistics and on-demand errand backend. Its central workflow accepts customer errands, supports dispatcher and rider lifecycle operations, and exposes operational results to client apps; the README also documents routing, fleet telemetry, pricing, OCR, reporting, and settlement capabilities. The sampled source confirms the errand and category-inference controller paths, plus routing and authentication internals. Several documented subsystems were not sampled, so their internal links are omitted or marked unverified.

Main entry points: [`src/routes/index.ts`](https://github.com/aljayvee/capstone_server/blob/main/src/routes/index.ts) (API routes), [`src/services/errandService.ts`](https://github.com/aljayvee/capstone_server/blob/main/src/services/errandService.ts) (Errand services), [`src/lib/prisma.ts`](https://github.com/aljayvee/capstone_server/blob/main/src/lib/prisma.ts) (Prisma data access), [`src/services/categoryInferenceService.ts`](https://github.com/aljayvee/capstone_server/blob/main/src/services/categoryInferenceService.ts) (Category inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and security"]
  node_api["HTTP API<br/>[index.ts]"]
  node_routes["API routes<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
end

subgraph group_operations["Errand operations"]
  node_errand["Errand lifecycle"]
  node_errandlogic["Errand services<br/>[errandService.ts]"]
  node_payments["Payments and settlement"]
  node_reports["Reports and exports<br/>[reportService.ts]"]
end

subgraph group_location["Location services"]
  node_tracking["Rider tracking<br/>[trackingService.ts]"]
  node_routing["Routing service"]
  node_routeproviders["Route providers<br/>[osrmProvider.ts]"]
  node_firebase["Firebase services<br/>[firebaseAdmin.ts]"]
end

subgraph group_intelligence["Decision support"]
  node_category["Category inference"]
  node_categoryapi["Category sidecar<br/>[app.py]"]
  node_placement["Item placement"]
  node_ocr["Receipt OCR"]
end

subgraph group_platform["Platform services"]
  node_prisma["Prisma data access<br/>[prisma.ts]"]
  node_database[("MariaDB")]
  node_sessions["Session management<br/>[sessionService.ts]"]
  node_presence["Rider presence"]
  node_notifications["Notifications"]
  node_jobs["Scheduled learning<br/>[dwellLearning.ts]"]
end

node_clients(("Client apps"))

node_clients -->|"calls"| node_api
node_api -->|"mounts"| node_routes
node_routes -->|"routes requests"| node_errand
node_routes -->|"routes requests"| node_category
node_routes -->|"protects routes"| node_auth
node_errand -->|"calls"| node_errandlogic
node_errandlogic -.->|"persists operations"| node_prisma
node_prisma -->|"reads and writes"| node_database
node_routes -->|"routes requests"| node_payments
node_routes -.->|"routes requests"| node_reports
node_routes -.->|"routes requests"| node_tracking
node_tracking -.->|"streams GPS"| node_firebase
node_errandlogic -.->|"uses for ETA"| node_routing
node_routing -->|"tries providers"| node_routeproviders
node_routes -->|"routes requests"| node_category
node_category -->|"requests predictions"| node_categoryapi
node_category -.->|"resolves active categories"| node_prisma
node_category -->|"suggests placements"| node_placement
node_errandlogic -.->|"verifies receipts"| node_ocr
node_auth -.->|"checks session tokens"| node_sessions
node_sessions -->|"stores sessions"| node_prisma
node_auth -.->|"uses identity services"| node_firebase
node_errandlogic -.->|"notifies participants"| node_notifications
node_jobs -.->|"learns from deliveries"| node_prisma
node_jobs -.->|"updates dwell estimates"| node_errandlogic
node_presence -->|"persists presence"| node_prisma

click node_api "https://github.com/aljayvee/capstone_server/blob/main/src/index.ts"
click node_routes "https://github.com/aljayvee/capstone_server/blob/main/src/routes/index.ts"
click node_auth "https://github.com/aljayvee/capstone_server/blob/main/src/middleware/auth.ts"
click node_errand "https://github.com/aljayvee/capstone_server/blob/main/src/controllers/errandController.ts"
click node_errandlogic "https://github.com/aljayvee/capstone_server/blob/main/src/services/errandService.ts"
click node_payments "https://github.com/aljayvee/capstone_server/blob/main/src/controllers/errandPaymentController.ts"
click node_reports "https://github.com/aljayvee/capstone_server/blob/main/src/services/reportService.ts"
click node_tracking "https://github.com/aljayvee/capstone_server/blob/main/src/services/trackingService.ts"
click node_routing "https://github.com/aljayvee/capstone_server/blob/main/src/lib/routing/resilientRoutingService.ts"
click node_routeproviders "https://github.com/aljayvee/capstone_server/blob/main/src/lib/routing/osrmProvider.ts"
click node_firebase "https://github.com/aljayvee/capstone_server/blob/main/src/lib/firebaseAdmin.ts"
click node_category "https://github.com/aljayvee/capstone_server/blob/main/src/services/categoryInferenceService.ts"
click node_categoryapi "https://github.com/aljayvee/capstone_server/blob/main/ml/app.py"
click node_placement "https://github.com/aljayvee/capstone_server/blob/main/src/services/itemPlacementService.ts"
click node_ocr "https://github.com/aljayvee/capstone_server/blob/main/src/lib/ocr/resilientOcrService.ts"
click node_prisma "https://github.com/aljayvee/capstone_server/blob/main/src/lib/prisma.ts"
click node_sessions "https://github.com/aljayvee/capstone_server/blob/main/src/services/sessionService.ts"
click node_presence "https://github.com/aljayvee/capstone_server/blob/main/src/services/riderPresenceService.ts"
click node_notifications "https://github.com/aljayvee/capstone_server/blob/main/src/lib/pushNotifications.ts"
click node_jobs "https://github.com/aljayvee/capstone_server/blob/main/src/jobs/dwellLearning.ts"

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_api,node_routes,node_auth,node_clients toneBlue
class node_errand,node_errandlogic,node_payments,node_reports toneAmber
class node_tracking,node_routing,node_routeproviders,node_firebase toneMint
class node_category,node_categoryapi,node_placement,node_ocr toneRose
class node_prisma,node_database,node_sessions,node_presence,node_notifications,node_jobs toneIndigo
```

## Components

### API and security

- [HTTP API](https://github.com/aljayvee/capstone_server/blob/main/src/index.ts): `src/index.ts`
- [API routes](https://github.com/aljayvee/capstone_server/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Authentication](https://github.com/aljayvee/capstone_server/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`

### Errand operations

- [Errand lifecycle](https://github.com/aljayvee/capstone_server/blob/main/src/controllers/errandController.ts): `src/controllers/errandController.ts`
- [Errand services](https://github.com/aljayvee/capstone_server/blob/main/src/services/errandService.ts): `src/services/errandService.ts`
- [Payments and settlement](https://github.com/aljayvee/capstone_server/blob/main/src/controllers/errandPaymentController.ts): `src/controllers/errandPaymentController.ts`
- [Reports and exports](https://github.com/aljayvee/capstone_server/blob/main/src/services/reportService.ts): `src/services/reportService.ts`

### Location services

- [Rider tracking](https://github.com/aljayvee/capstone_server/blob/main/src/services/trackingService.ts): `src/services/trackingService.ts`
- [Routing service](https://github.com/aljayvee/capstone_server/blob/main/src/lib/routing/resilientRoutingService.ts): `src/lib/routing/resilientRoutingService.ts`
- [Route providers](https://github.com/aljayvee/capstone_server/blob/main/src/lib/routing/osrmProvider.ts): `src/lib/routing/osrmProvider.ts`
- [Firebase services](https://github.com/aljayvee/capstone_server/blob/main/src/lib/firebaseAdmin.ts): `src/lib/firebaseAdmin.ts`

### Decision support

- [Category inference](https://github.com/aljayvee/capstone_server/blob/main/src/services/categoryInferenceService.ts): `src/services/categoryInferenceService.ts`
- [Category sidecar](https://github.com/aljayvee/capstone_server/blob/main/ml/app.py): `ml/app.py`
- [Item placement](https://github.com/aljayvee/capstone_server/blob/main/src/services/itemPlacementService.ts): `src/services/itemPlacementService.ts`
- [Receipt OCR](https://github.com/aljayvee/capstone_server/blob/main/src/lib/ocr/resilientOcrService.ts): `src/lib/ocr/resilientOcrService.ts`

### Platform services

- [Prisma data access](https://github.com/aljayvee/capstone_server/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- **MariaDB**
- [Session management](https://github.com/aljayvee/capstone_server/blob/main/src/services/sessionService.ts): `src/services/sessionService.ts`
- [Rider presence](https://github.com/aljayvee/capstone_server/blob/main/src/services/riderPresenceService.ts): `src/services/riderPresenceService.ts`
- [Notifications](https://github.com/aljayvee/capstone_server/blob/main/src/lib/pushNotifications.ts): `src/lib/pushNotifications.ts`
- [Scheduled learning](https://github.com/aljayvee/capstone_server/blob/main/src/jobs/dwellLearning.ts): `src/jobs/dwellLearning.ts`

### Other components

- **Client apps**

## Connections

- Client apps → HTTP API: calls (evidence: `README.md`)
- HTTP API → API routes: mounts (evidence: `src/index.ts`)
- API routes → Errand lifecycle: routes requests
- API routes → Category inference: routes requests
- API routes → Authentication: protects routes
- Errand lifecycle → Errand services: calls (evidence: `src/controllers/errandController.ts`)
- Errand services → Prisma data access: persists operations (evidence: `README.md`)
- Prisma data access → MariaDB: reads and writes (evidence: `README.md`)
- API routes → Payments and settlement: routes requests
- API routes → Reports and exports: routes requests (evidence: `README.md`)
- API routes → Rider tracking: routes requests (evidence: `README.md`)
- Rider tracking → Firebase services: streams GPS (evidence: `README.md`)
- Errand services → Routing service: uses for ETA (evidence: `README.md`)
- Routing service → Route providers: tries providers (evidence: `src/lib/routing/resilientRoutingService.ts`)
- API routes → Category inference: routes requests
- Category inference → Category sidecar: requests predictions (evidence: `src/services/categoryInferenceService.ts`)
- Category inference → Prisma data access: resolves active categories (evidence: `README.md`)
- Category inference → Item placement: suggests placements (evidence: `src/controllers/categoryInferenceController.ts`)
- Errand services → Receipt OCR: verifies receipts (evidence: `README.md`)
- Authentication → Session management: checks session tokens (evidence: `README.md`)
- Session management → Prisma data access: stores sessions (evidence: `src/services/sessionService.ts`)
- Authentication → Firebase services: uses identity services (evidence: `README.md`)
- Errand services → Notifications: notifies participants (evidence: `README.md`)
- Scheduled learning → Prisma data access: learns from deliveries (evidence: `README.md`)
- Scheduled learning → Errand services: updates dwell estimates (evidence: `README.md`)
- Rider presence → Prisma data access: persists presence (evidence: `src/services/riderPresenceService.ts`)
