# meetmendapara09/tracking_app architecture

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

- Interactive diagram: https://gitdiagram.com/meetmendapara09/tracking_app
- Repository: https://github.com/meetmendapara09/tracking_app

## Overview

#### Purpose and Runtime Shape
Real-Time Delivery Tracker is a two-process application: a Next.js frontend for customers and delivery personnel, and an Express + Socket.IO backend for order, location, and delivery updates. Root development entry is `scripts/dev-all.js`; frontend starts from `src/app/page.tsx`; backend boots through `backend/src/index.ts` and assembles middleware/routes in `backend/src/app.ts`.

#### Frontend Application
The Next.js App Router provides role-oriented flows:
- Customer tracking route: `src/app/customer/track/[orderId]/page.tsx`
- Delivery login and dashboard: `src/app/delivery/login/page.tsx`, `src/app/delivery/dashboard/page.tsx`
- Shared application shell and visual components: `src/app/layout.tsx`, `src/app/components/AntLayout.tsx`, `src/app/components/Map.tsx`

Ant Design is the primary UI framework. The frontend is a browser client rather than an API host.

#### Client API and Realtime Boundary
Frontend HTTP calls are centralized in `src/app/lib/api.ts`; Socket.IO client setup is in `src/app/lib/socket.ts` and consumed through `src/app/hooks/useSocket.ts`. Authentication state is handled by `src/app/hooks/useAuth.ts` and `src/app/utils/auth.ts`. This layer bridges browser UI state to backend REST endpoints and live location/order events.

#### Backend HTTP and Authentication Pipeline
Express controllers expose domain operations through route modules:
- API and delivery operations: `backend/src/routes/apiRoutes.ts`, `backend/src/controllers/apiController.ts`, `backend/src/controllers/deliveryController.ts`
- Authentication: `backend/src/routes/authRoutes.ts`, `backend/src/controllers/authController.ts`
- Orders and locations: `backend/src/routes/orderRoutes.ts`, `backend/src/routes/locationRoutes.ts`

Requests pass authentication and validation boundaries in `backend/src/middleware/auth.ts` and `backend/src/middleware/validators.ts` before controller logic. An OpenAPI contract is published at `backend/openapi.json`.

#### Domain and Persistence
The core persisted entities are users, orders, and location records, represented by `backend/src/models/User.ts`, `backend/src/models/Order.ts`, and `backend/src/models/Location.ts`. The repository retains MongoDB-oriented data access through `backend/src/services/db.ts`, while PostgreSQL/PostGIS support is represented by Prisma configuration in `backend/prisma/schema.prisma` and `backend/src/services/prisma.ts`. Migration paths are explicit in `backend/scripts/migrate-mongo-to-postgres.ts` and `backend/scripts/enable-postgis.ts`.

#### Live Location Processing
Socket.IO is hosted alongside the Express backend from `backend/src/index.ts`. Location-specific HTTP handling resides in `backend/src/controllers/locationController.ts`; asynchronous/background processing is isolated in `backend/src/workers/locationWorker.ts`. This boundary supports ingesting courier location updates, persisting or processing them, and broadcasting delivery-tracking state to subscribed clients.

#### Operations, Observability, and Deployment
The backend can run containerized via `backend/Dockerfile` and `backend/docker-compose.yml`. Prometheus metrics are exposed from `backend/src/metrics.ts`, with database and Bull-related metric collectors in `backend/src/metrics/postgres_stats.ts` and `backend/src/metrics/bull_poll.ts`. OpenTelemetry and Sentry integrations are isolated in `backend/src/services/opentelemetry.ts` and `backend/src/services/sentry.ts`; Grafana/Prometheus local monitoring assets live under `backend/grafana` and `backend/prometheus/prometheus.yml`. Kubernetes deployment is packaged as Helm resources under `deploy/helm/tracking-app/templates/deployment.yaml`, `deploy/helm/tracking-app/templates/service.yaml`, and `deploy/helm/tracking-app/templates/ingress.yaml`.

Main entry points: [`backend/src/index.ts`](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/index.ts) (Backend bootstrap), [`backend/src/middleware/auth.ts`](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/middleware/auth.ts) (Auth & validation), [`src/app/layout.tsx`](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/layout.tsx) (App shell & UI), [`src/app/customer/track/[orderId]/page.tsx`](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/customer/track/%5BorderId%5D/page.tsx) (Customer tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Frontend"]
  node_ui["App shell &amp; UI<br/>Next.js App Router<br/>[layout.tsx]"]
  node_customer["Customer tracking<br/>Tracking page<br/>[page.tsx]"]
  node_delivery["Delivery dashboard<br/>Delivery page<br/>[page.tsx]"]
  node_client_api["HTTP client<br/>API boundary<br/>[api.ts]"]
  node_client_socket["Realtime client<br/>Socket.IO client<br/>[socket.ts]"]
end

subgraph group_backend["Express + Socket.IO Backend"]
  node_server{{"Backend bootstrap<br/>Express + Socket.IO host<br/>[index.ts]"}}
  node_app["Express app<br/>Middleware assembly<br/>[app.ts]"]
  node_api_routes["Domain API routes<br/>Express routes<br/>[apiRoutes.ts]"]
  node_auth_routes["Authentication routes<br/>Express routes<br/>[authRoutes.ts]"]
  node_request_guard["Auth &amp; validation<br/>Express middleware<br/>[auth.ts]"]
  node_api_controller["Order &amp; delivery logic<br/>Controllers<br/>[apiController.ts]"]
  node_location_controller["Location ingest<br/>Location controller"]
  node_openapi["OpenAPI contract<br/>[openapi.json]"]
end

subgraph group_data["Data &amp; Processing"]
  node_location_worker["Location worker<br/>Background processing<br/>[locationWorker.ts]"]
  node_entities["Domain entities<br/>Mongo models<br/>[Order.ts]"]
  node_mongo[("MongoDB access<br/>Data service<br/>[db.ts]")]
  node_postgres[("PostgreSQL / PostGIS<br/>Prisma schema<br/>[schema.prisma]")]
end

subgraph group_ops["Operations"]
  node_observability["Metrics &amp; telemetry<br/>Observability<br/>[metrics.ts]"]
  node_container["Container runtime<br/>Docker deployment<br/>[docker-compose.yml]"]
  node_kubernetes["Kubernetes deployment<br/>Helm deployment<br/>[deployment.yaml]"]
end

node_dev["Dev launcher<br/>Node script<br/>[dev-all.js]"]

node_dev -->|"starts frontend"| node_ui
node_dev -->|"starts backend"| node_server
node_ui -->|"renders route"| node_customer
node_ui -->|"renders route"| node_delivery
node_customer -->|"queries order state"| node_client_api
node_delivery -->|"uses REST operations"| node_client_api
node_customer -->|"subscribes to updates"| node_client_socket
node_delivery -->|"publishes live location"| node_client_socket
node_client_api -->|"HTTP"| node_server
node_client_socket -->|"Socket.IO"| node_server
node_server -->|"hosts"| node_app
node_app -->|"mounts"| node_api_routes
node_app -->|"mounts"| node_auth_routes
node_api_routes -->|"passes through"| node_request_guard
node_auth_routes -->|"protects requests"| node_request_guard
node_request_guard -->|"authorizes"| node_api_controller
node_request_guard -->|"validates ingest"| node_location_controller
node_api_controller -->|"reads and writes"| node_entities
node_location_controller -->|"queues processing"| node_location_worker
node_location_worker -->|"persists locations"| node_entities
node_entities -->|"accesses"| node_mongo
node_api_controller -.->|"supports Prisma storage"| node_postgres
node_location_worker -->|"broadcasts tracking state"| node_server
node_server -.->|"publishes contract"| node_openapi
node_server -->|"emits metrics and telemetry"| node_observability
node_container -->|"runs"| node_server
node_kubernetes -->|"deploys image"| node_container

click node_dev "https://github.com/meetmendapara09/tracking_app/blob/main/scripts/dev-all.js"
click node_ui "https://github.com/meetmendapara09/tracking_app/blob/main/src/app/layout.tsx"
click node_customer "https://github.com/meetmendapara09/tracking_app/blob/main/src/app/customer/track/%5BorderId%5D/page.tsx"
click node_delivery "https://github.com/meetmendapara09/tracking_app/blob/main/src/app/delivery/dashboard/page.tsx"
click node_client_api "https://github.com/meetmendapara09/tracking_app/blob/main/src/app/lib/api.ts"
click node_client_socket "https://github.com/meetmendapara09/tracking_app/blob/main/src/app/lib/socket.ts"
click node_server "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/index.ts"
click node_app "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/app.ts"
click node_api_routes "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/routes/apiRoutes.ts"
click node_auth_routes "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/routes/authRoutes.ts"
click node_request_guard "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/middleware/auth.ts"
click node_api_controller "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/controllers/apiController.ts"
click node_location_controller "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/controllers/locationController.ts"
click node_location_worker "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/workers/locationWorker.ts"
click node_entities "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/models/Order.ts"
click node_mongo "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/services/db.ts"
click node_postgres "https://github.com/meetmendapara09/tracking_app/blob/main/backend/prisma/schema.prisma"
click node_openapi "https://github.com/meetmendapara09/tracking_app/blob/main/backend/openapi.json"
click node_observability "https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/metrics.ts"
click node_container "https://github.com/meetmendapara09/tracking_app/blob/main/backend/docker-compose.yml"
click node_kubernetes "https://github.com/meetmendapara09/tracking_app/blob/main/deploy/helm/tracking-app/templates/deployment.yaml"

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_ui,node_customer,node_delivery,node_client_api,node_client_socket toneBlue
class node_server,node_app,node_api_routes,node_auth_routes,node_request_guard,node_api_controller,node_location_controller,node_openapi toneAmber
class node_location_worker,node_entities,node_mongo,node_postgres toneMint
class node_observability,node_container,node_kubernetes toneRose
class node_dev toneNeutral
```

## Components

### Next.js Frontend

- [App shell & UI](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/layout.tsx): Next.js App Router · `src/app/layout.tsx`
- [Customer tracking](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/customer/track/%5BorderId%5D/page.tsx): Tracking page · `src/app/customer/track/[orderId]/page.tsx`
- [Delivery dashboard](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/delivery/dashboard/page.tsx): Delivery page · `src/app/delivery/dashboard/page.tsx`
- [HTTP client](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/lib/api.ts): API boundary · `src/app/lib/api.ts`
- [Realtime client](https://github.com/meetmendapara09/tracking_app/blob/main/src/app/lib/socket.ts): Socket.IO client · Socket setup consumed by the client hook. · `src/app/lib/socket.ts`

### Express + Socket.IO Backend

- [Backend bootstrap](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/index.ts): Express + Socket.IO host · `backend/src/index.ts`
- [Express app](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/app.ts): Middleware assembly · `backend/src/app.ts`
- [Domain API routes](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/routes/apiRoutes.ts): Express routes · `backend/src/routes/apiRoutes.ts`
- [Authentication routes](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/routes/authRoutes.ts): Express routes · `backend/src/routes/authRoutes.ts`
- [Auth & validation](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/middleware/auth.ts): Express middleware · `backend/src/middleware/auth.ts`
- [Order & delivery logic](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/controllers/apiController.ts): Controllers · `backend/src/controllers/apiController.ts`
- [Location ingest](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/controllers/locationController.ts): Location controller · `backend/src/controllers/locationController.ts`
- [OpenAPI contract](https://github.com/meetmendapara09/tracking_app/blob/main/backend/openapi.json): API contract · `backend/openapi.json`

### Data & Processing

- [Location worker](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/workers/locationWorker.ts): Background processing · `backend/src/workers/locationWorker.ts`
- [Domain entities](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/models/Order.ts): Mongo models · Users, orders, and locations. · `backend/src/models/Order.ts`
- [MongoDB access](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/services/db.ts): Data service · `backend/src/services/db.ts`
- [PostgreSQL / PostGIS](https://github.com/meetmendapara09/tracking_app/blob/main/backend/prisma/schema.prisma): Prisma schema · `backend/prisma/schema.prisma`

### Operations

- [Metrics & telemetry](https://github.com/meetmendapara09/tracking_app/blob/main/backend/src/metrics.ts): Observability · Prometheus metrics plus OpenTelemetry and Sentry integrations. · `backend/src/metrics.ts`
- [Container runtime](https://github.com/meetmendapara09/tracking_app/blob/main/backend/docker-compose.yml): Docker deployment · `backend/docker-compose.yml`
- [Kubernetes deployment](https://github.com/meetmendapara09/tracking_app/blob/main/deploy/helm/tracking-app/templates/deployment.yaml): Helm deployment · `deploy/helm/tracking-app/templates/deployment.yaml`

### Other components

- [Dev launcher](https://github.com/meetmendapara09/tracking_app/blob/main/scripts/dev-all.js): Node script · Starts both application processes. · `scripts/dev-all.js`

## Connections

- Dev launcher → App shell & UI: starts frontend
- Dev launcher → Backend bootstrap: starts backend
- App shell & UI → Customer tracking: renders route
- App shell & UI → Delivery dashboard: renders route
- Customer tracking → HTTP client: queries order state
- Delivery dashboard → HTTP client: uses REST operations
- Customer tracking → Realtime client: subscribes to updates
- Delivery dashboard → Realtime client: publishes live location
- HTTP client → Backend bootstrap: HTTP
- Realtime client → Backend bootstrap: Socket.IO
- Backend bootstrap → Express app: hosts
- Express app → Domain API routes: mounts
- Express app → Authentication routes: mounts
- Domain API routes → Auth & validation: passes through
- Authentication routes → Auth & validation: protects requests
- Auth & validation → Order & delivery logic: authorizes
- Auth & validation → Location ingest: validates ingest
- Order & delivery logic → Domain entities: reads and writes
- Location ingest → Location worker: queues processing
- Location worker → Domain entities: persists locations
- Domain entities → MongoDB access: accesses
- Order & delivery logic → PostgreSQL / PostGIS: supports Prisma storage
- Location worker → Backend bootstrap: broadcasts tracking state
- Backend bootstrap → OpenAPI contract: publishes contract
- Backend bootstrap → Metrics & telemetry: emits metrics and telemetry
- Container runtime → Backend bootstrap: runs
- Kubernetes deployment → Container runtime: deploys image