# lavanya0613/ambulance architecture

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

- Interactive diagram: https://gitdiagram.com/lavanya0613/ambulance
- Repository: https://github.com/lavanya0613/ambulance

## Overview

This repository is an ambulance booking and tracking product with a Java/Spring backend and a React web client; the README also documents a Flutter patient/driver app, whose runtime feature code is not present in this tree. The patient workflow runs from booking and payment through dispatch/queue processing to live tracking, while separate admin and dispatcher workflows cover monitoring, request management and audit/DLQ operations. Edges are limited to relationships visible in excerpts or the README; mobile internals and unsampled backend wiring are not inferred.

Main entry points: [`web/src/App.tsx`](https://github.com/lavanya0613/ambulance/blob/main/web/src/App.tsx) (Web router), [`backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java`](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java) (Dispatch service), [`backend-java/src/main/java/com/callhealth/ambulance/queue/service/RedisQueueService.java`](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/service/RedisQueueService.java) (Redis queue), [`backend-java/src/main/java/com/callhealth/ambulance/repository/AmbulanceRequestRepository.java`](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/repository/AmbulanceRequestRepository.java) (Request repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portals"]
  node_webapp["Web router<br/>[App.tsx]"]
  node_patientpages["Patient pages"]
  node_adminpages["Admin pages"]
  node_mobile["Mobile clients"]
end

subgraph group_booking["Booking and payment"]
  node_patientapi["Patient API"]
  node_requestservice["Request and payment"]
  node_requests[("Booking records")]
  node_requestrepo["Request repository"]
end

subgraph group_dispatch["Dispatch and tracking"]
  node_dispatchercontroller["Dispatcher API"]
  node_dispatchservice["Dispatch service"]
  node_queue["Redis queue"]
  node_bookingworker["Booking worker"]
  node_trackingworker["Tracking worker"]
  node_trackingdata[("Tracking positions")]
  node_gateway["WebSocket gateway"]
  node_socketclients(("Realtime clients"))
end

subgraph group_operations["Administration"]
  node_admincontroller["Admin API"]
  node_adminservice["Admin service<br/>[AdminService.java]"]
  node_auditdata[("Audit logs")]
  node_dlqservice["Failed job recovery<br/>[DlqService.java]"]
  node_dlqdata[("Dead letter jobs<br/>[DlqJob.java]")]
  node_vendorapi["Vendor API"]
end

node_patient(("Patient"))
node_dispatcher(("Dispatcher"))
node_admin(("Administrator"))

node_patient -->|"opens portal"| node_webapp
node_dispatcher -->|"opens portal"| node_webapp
node_admin -->|"opens portal"| node_webapp
node_webapp -->|"routes to"| node_patientpages
node_webapp -->|"routes to"| node_adminpages
node_patientpages -.->|"uses API"| node_patientapi
node_adminpages -.->|"uses API"| node_admincontroller
node_mobile -.->|"uses API"| node_patientapi
node_mobile -.->|"realtime updates"| node_gateway
node_patientapi -->|"delegates"| node_requestservice
node_requestservice -->|"reads and writes"| node_requestrepo
node_requestrepo -->|"persists"| node_requests
node_dispatchercontroller -.->|"delegates"| node_dispatchservice
node_dispatchservice -->|"queries"| node_requestrepo
node_dispatchservice -->|"enqueues tracking"| node_queue
node_queue -.->|"dispatches jobs"| node_bookingworker
node_queue -.->|"dispatches jobs"| node_trackingworker
node_dispatchservice -->|"emits location"| node_gateway
node_gateway -.->|"pushes updates"| node_socketclients
node_trackingworker -.->|"records positions"| node_trackingdata
node_admincontroller -.->|"delegates"| node_adminservice
node_adminservice -->|"queries bookings"| node_requestrepo
node_adminservice -->|"reads audit logs"| node_auditdata
node_dlqservice -->|"stores and retries"| node_dlqdata
node_dlqservice -->|"requeues jobs"| node_queue
node_dlqservice -->|"records recovery"| node_auditdata
node_vendorapi -.->|"vendor workflow"| node_requests

click node_webapp "https://github.com/lavanya0613/ambulance/blob/main/web/src/App.tsx"
click node_patientpages "https://github.com/lavanya0613/ambulance/tree/main/web/src/pages"
click node_adminpages "https://github.com/lavanya0613/ambulance/tree/main/web/src/pages"
click node_mobile "https://github.com/lavanya0613/ambulance/tree/main/mobile"
click node_patientapi "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/PatientRequestController.java"
click node_requestservice "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/PatientRequestService.java"
click node_requests "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/AmbulanceRequest.java"
click node_requestrepo "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/repository/AmbulanceRequestRepository.java"
click node_dispatchercontroller "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/DispatcherController.java"
click node_dispatchservice "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java"
click node_queue "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/service/RedisQueueService.java"
click node_bookingworker "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/worker/BookingQueueWorker.java"
click node_trackingworker "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/worker/TrackingQueueWorker.java"
click node_trackingdata "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/TrackingPosition.java"
click node_gateway "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/gateway/WebSocketGateway.java"
click node_admincontroller "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/AdminController.java"
click node_adminservice "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/AdminService.java"
click node_auditdata "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/SystemAuditLog.java"
click node_dlqservice "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/DlqService.java"
click node_dlqdata "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/DlqJob.java"
click node_vendorapi "https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/VendorController.java"

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_webapp,node_patientpages,node_adminpages,node_mobile toneBlue
class node_patientapi,node_requestservice,node_requests,node_requestrepo toneAmber
class node_dispatchercontroller,node_dispatchservice,node_queue,node_bookingworker,node_trackingworker,node_trackingdata,node_gateway,node_socketclients toneMint
class node_admincontroller,node_adminservice,node_auditdata,node_dlqservice,node_dlqdata,node_vendorapi toneRose
class node_patient,node_dispatcher,node_admin toneIndigo
```

## Components

### Web portals

- [Web router](https://github.com/lavanya0613/ambulance/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Patient pages](https://github.com/lavanya0613/ambulance/tree/main/web/src/pages): `web/src/pages`
- [Admin pages](https://github.com/lavanya0613/ambulance/tree/main/web/src/pages): `web/src/pages`
- [Mobile clients](https://github.com/lavanya0613/ambulance/tree/main/mobile): `mobile`

### Booking and payment

- [Patient API](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/PatientRequestController.java): `backend-java/src/main/java/com/callhealth/ambulance/controller/PatientRequestController.java`
- [Request and payment](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/PatientRequestService.java): `backend-java/src/main/java/com/callhealth/ambulance/service/PatientRequestService.java`
- [Booking records](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/AmbulanceRequest.java): `backend-java/src/main/java/com/callhealth/ambulance/model/entity/AmbulanceRequest.java`
- [Request repository](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/repository/AmbulanceRequestRepository.java): `backend-java/src/main/java/com/callhealth/ambulance/repository/AmbulanceRequestRepository.java`

### Dispatch and tracking

- [Dispatcher API](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/DispatcherController.java): `backend-java/src/main/java/com/callhealth/ambulance/controller/DispatcherController.java`
- [Dispatch service](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java): `backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java`
- [Redis queue](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/service/RedisQueueService.java): `backend-java/src/main/java/com/callhealth/ambulance/queue/service/RedisQueueService.java`
- [Booking worker](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/worker/BookingQueueWorker.java): `backend-java/src/main/java/com/callhealth/ambulance/queue/worker/BookingQueueWorker.java`
- [Tracking worker](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/queue/worker/TrackingQueueWorker.java): `backend-java/src/main/java/com/callhealth/ambulance/queue/worker/TrackingQueueWorker.java`
- [Tracking positions](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/TrackingPosition.java): `backend-java/src/main/java/com/callhealth/ambulance/model/entity/TrackingPosition.java`
- [WebSocket gateway](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/gateway/WebSocketGateway.java): `backend-java/src/main/java/com/callhealth/ambulance/gateway/WebSocketGateway.java`
- **Realtime clients**

### Administration

- [Admin API](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/AdminController.java): `backend-java/src/main/java/com/callhealth/ambulance/controller/AdminController.java`
- [Admin service](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/AdminService.java): `backend-java/src/main/java/com/callhealth/ambulance/service/AdminService.java`
- [Audit logs](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/SystemAuditLog.java): `backend-java/src/main/java/com/callhealth/ambulance/model/entity/SystemAuditLog.java`
- [Failed job recovery](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/service/DlqService.java): `backend-java/src/main/java/com/callhealth/ambulance/service/DlqService.java`
- [Dead letter jobs](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/model/entity/DlqJob.java): `backend-java/src/main/java/com/callhealth/ambulance/model/entity/DlqJob.java`
- [Vendor API](https://github.com/lavanya0613/ambulance/blob/main/backend-java/src/main/java/com/callhealth/ambulance/controller/VendorController.java): `backend-java/src/main/java/com/callhealth/ambulance/controller/VendorController.java`

### Other components

- **Patient**
- **Dispatcher**
- **Administrator**

## Connections

- Patient → Web router: opens portal (evidence: `web/src/App.tsx`)
- Dispatcher → Web router: opens portal (evidence: `web/src/App.tsx`)
- Administrator → Web router: opens portal (evidence: `web/src/App.tsx`)
- Web router → Patient pages: routes to (evidence: `web/src/App.tsx`)
- Web router → Admin pages: routes to (evidence: `web/src/App.tsx`)
- Patient pages → Patient API: uses API
- Admin pages → Admin API: uses API
- Mobile clients → Patient API: uses API
- Mobile clients → WebSocket gateway: realtime updates
- Patient API → Request and payment: delegates (evidence: `backend-java/src/main/java/com/callhealth/ambulance/controller/PatientRequestController.java`)
- Request and payment → Request repository: reads and writes (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/PatientRequestService.java`)
- Request repository → Booking records: persists (evidence: `backend-java/src/main/java/com/callhealth/ambulance/repository/AmbulanceRequestRepository.java`)
- Dispatcher API → Dispatch service: delegates
- Dispatch service → Request repository: queries (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java`)
- Dispatch service → Redis queue: enqueues tracking (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java`)
- Redis queue → Booking worker: dispatches jobs
- Redis queue → Tracking worker: dispatches jobs (evidence: `backend-java/src/main/java/com/callhealth/ambulance/queue/worker/TrackingQueueWorker.java`)
- Dispatch service → WebSocket gateway: emits location (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/DispatcherService.java`)
- WebSocket gateway → Realtime clients: pushes updates
- Tracking worker → Tracking positions: records positions (evidence: `backend-java/src/main/java/com/callhealth/ambulance/queue/worker/TrackingQueueWorker.java`)
- Admin API → Admin service: delegates
- Admin service → Request repository: queries bookings (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/AdminService.java`)
- Admin service → Audit logs: reads audit logs (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/AdminService.java`)
- Failed job recovery → Dead letter jobs: stores and retries (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/DlqService.java`)
- Failed job recovery → Redis queue: requeues jobs (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/DlqService.java`)
- Failed job recovery → Audit logs: records recovery (evidence: `backend-java/src/main/java/com/callhealth/ambulance/service/DlqService.java`)
- Vendor API → Booking records: vendor workflow
