# qdcv0272/baloambule architecture

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

- Interactive diagram: https://gitdiagram.com/qdcv0272/baloambule
- Repository: https://github.com/qdcv0272/baloambule

## Overview

Baloambule is a multi-role ambulance dispatch and emergency-hospital discovery app, with user, hospital, ambulance, and administrator experiences. A user searches nearby hospitals, creates a vehicle request, and can follow its trip; ambulance staff manage vehicles and accept calls, while hospitals and administrators have separate operational tools. The graph also shows registration/authentication, server-verified identity and payments, and persistent data. Search-service excerpts and README flows support the external search and verification links; unsampled service wiring is intentionally omitted.

Main entry points: [`src/lib/api-client.ts`](https://github.com/qdcv0272/baloambule/blob/master/src/lib/api-client.ts) (API Client), [`app/user/main.tsx`](https://github.com/qdcv0272/baloambule/blob/master/app/user/main.tsx) (User App), [`backend/src/prisma.service.ts`](https://github.com/qdcv0272/baloambule/blob/master/backend/src/prisma.service.ts) (PostgreSQL), [`backend/src/auth/auth.service.ts`](https://github.com/qdcv0272/baloambule/blob/master/backend/src/auth/auth.service.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mobile and Web App"]
  node_user_app["User App<br/>[main.tsx]"]
  node_user_search["Hospital Search UI"]
  node_user_dispatch["Dispatch UI<br/>[useUserDispatch.ts]"]
  node_role_auth["Role Login and Registration<br/>[login.tsx]"]
  node_api_client["API Client<br/>[api-client.ts]"]
  node_dispatch_api["Dispatch API Client<br/>[dispatch-api.ts]"]
  node_hospital_api["Hospital API Client<br/>[hospital-api.ts]"]
end

subgraph group_domains["Backend Domains"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_dispatch["Dispatch and Trips"]
  node_hospital_search["Hospital Search"]
  node_hospital_ops["Hospital Operations"]
  node_ambulance_ops["Ambulance Operations"]
  node_identity["Identity Verification"]
  node_payment["Payment<br/>[payment.service.ts]"]
  node_admin["Administration<br/>[admin.service.ts]"]
  node_notices["Notices<br/>[notice.service.ts]"]
end

subgraph group_operations["Operations Portals"]
  node_hospital_portal["Hospital Portal<br/>[main.tsx]"]
  node_ambulance_portal["Ambulance Portal<br/>[main.tsx]"]
  node_admin_portal["Admin Portal<br/>[index.tsx]"]
end

subgraph group_integrations["External Services"]
  node_gov_hospital["Government Hospital Data"]
  node_kakao["Kakao Search and Maps"]
  node_portone["PortOne"]
  node_toss["Toss Payments"]
  node_sms["SMS Provider"]
end

subgraph group_state["Application State"]
  node_db[("PostgreSQL<br/>[prisma.service.ts]")]
  node_token_storage["Role Token Storage<br/>[tokenStorage.ts]"]
end

node_user(("User"))
node_staff(("Hospital and Ambulance Staff"))
node_admin_actor(("Administrator"))

node_user -->|"uses"| node_user_app
node_user_app -->|"searches with"| node_user_search
node_user_search -->|"requests results"| node_hospital_api
node_hospital_api -->|"queries"| node_hospital_search
node_hospital_search -->|"fetches hospital data"| node_gov_hospital
node_hospital_search -->|"geocodes and searches"| node_kakao
node_user_app -->|"creates and tracks calls"| node_user_dispatch
node_user_dispatch -->|"sends trip requests"| node_dispatch_api
node_dispatch_api -->|"calls dispatch endpoints"| node_dispatch
node_staff -->|"signs in or registers"| node_role_auth
node_role_auth -->|"sends auth requests"| node_api_client
node_api_client -->|"calls authentication endpoints"| node_auth
node_auth -->|"sends verification codes"| node_sms
node_auth -->|"reads and writes accounts"| node_db
node_hospital_portal -->|"requests portal data"| node_api_client
node_api_client -->|"calls hospital endpoints"| node_hospital_ops
node_ambulance_portal -->|"manages calls and vehicles"| node_dispatch_api
node_ambulance_portal -->|"manages staff and revenue"| node_api_client
node_dispatch -->|"reads and writes requests and trips"| node_db
node_hospital_ops -->|"reads and writes hospital records"| node_db
node_ambulance_ops -->|"reads and writes staff records"| node_db
node_admin_actor -->|"manages platform"| node_admin_portal
node_admin_portal -->|"requests admin actions"| node_api_client
node_api_client -->|"calls admin endpoints"| node_admin
node_admin -->|"backs up and restores"| node_db
node_user_app -->|"starts verification"| node_identity
node_identity -->|"verifies identity"| node_portone
node_identity -->|"stores verification and registration"| node_db
node_user_app -->|"starts payment"| node_payment
node_payment -->|"prepares and confirms payment"| node_toss
node_payment -->|"stores payment records"| node_db
node_user_app -->|"stores role tokens"| node_token_storage
node_hospital_portal -.->|"views notices"| node_notices

click node_user_app "https://github.com/qdcv0272/baloambule/blob/master/app/user/main.tsx"
click node_user_search "https://github.com/qdcv0272/baloambule/blob/master/src/hooks/useUserMainSearch.ts"
click node_user_dispatch "https://github.com/qdcv0272/baloambule/blob/master/src/hooks/useUserDispatch.ts"
click node_role_auth "https://github.com/qdcv0272/baloambule/blob/master/app/ambulance/login.tsx"
click node_hospital_portal "https://github.com/qdcv0272/baloambule/blob/master/app/hospital/main.tsx"
click node_ambulance_portal "https://github.com/qdcv0272/baloambule/blob/master/app/ambulance/main.tsx"
click node_admin_portal "https://github.com/qdcv0272/baloambule/blob/master/app/admin/index.tsx"
click node_api_client "https://github.com/qdcv0272/baloambule/blob/master/src/lib/api-client.ts"
click node_dispatch_api "https://github.com/qdcv0272/baloambule/blob/master/src/lib/dispatch-api.ts"
click node_hospital_api "https://github.com/qdcv0272/baloambule/blob/master/src/lib/hospital-api.ts"
click node_auth "https://github.com/qdcv0272/baloambule/blob/master/backend/src/auth/auth.service.ts"
click node_dispatch "https://github.com/qdcv0272/baloambule/blob/master/backend/src/dispatch/dispatch.service.ts"
click node_hospital_search "https://github.com/qdcv0272/baloambule/blob/master/backend/src/hospital/hospital-search.service.ts"
click node_hospital_ops "https://github.com/qdcv0272/baloambule/blob/master/backend/src/hospital/hospital.service.ts"
click node_ambulance_ops "https://github.com/qdcv0272/baloambule/blob/master/backend/src/ambulance/ambulance.service.ts"
click node_identity "https://github.com/qdcv0272/baloambule/blob/master/backend/src/identity/identity.service.ts"
click node_payment "https://github.com/qdcv0272/baloambule/blob/master/backend/src/payment/payment.service.ts"
click node_admin "https://github.com/qdcv0272/baloambule/blob/master/backend/src/admin/admin.service.ts"
click node_notices "https://github.com/qdcv0272/baloambule/blob/master/backend/src/notice/notice.service.ts"
click node_db "https://github.com/qdcv0272/baloambule/blob/master/backend/src/prisma.service.ts"
click node_token_storage "https://github.com/qdcv0272/baloambule/blob/master/src/stores/tokenStorage.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_user_app,node_user_search,node_user_dispatch,node_role_auth,node_api_client,node_dispatch_api,node_hospital_api,node_user toneBlue
class node_auth,node_dispatch,node_hospital_search,node_hospital_ops,node_ambulance_ops,node_identity,node_payment,node_admin,node_notices toneAmber
class node_hospital_portal,node_ambulance_portal,node_admin_portal toneMint
class node_gov_hospital,node_kakao,node_portone,node_toss,node_sms toneRose
class node_db,node_token_storage,node_staff,node_admin_actor toneIndigo
```

## Components

### Mobile and Web App

- [User App](https://github.com/qdcv0272/baloambule/blob/master/app/user/main.tsx): `app/user/main.tsx`
- [Hospital Search UI](https://github.com/qdcv0272/baloambule/blob/master/src/hooks/useUserMainSearch.ts): `src/hooks/useUserMainSearch.ts`
- [Dispatch UI](https://github.com/qdcv0272/baloambule/blob/master/src/hooks/useUserDispatch.ts): `src/hooks/useUserDispatch.ts`
- [Role Login and Registration](https://github.com/qdcv0272/baloambule/blob/master/app/ambulance/login.tsx): `app/ambulance/login.tsx`
- [API Client](https://github.com/qdcv0272/baloambule/blob/master/src/lib/api-client.ts): `src/lib/api-client.ts`
- [Dispatch API Client](https://github.com/qdcv0272/baloambule/blob/master/src/lib/dispatch-api.ts): `src/lib/dispatch-api.ts`
- [Hospital API Client](https://github.com/qdcv0272/baloambule/blob/master/src/lib/hospital-api.ts): `src/lib/hospital-api.ts`

### Backend Domains

- [Authentication](https://github.com/qdcv0272/baloambule/blob/master/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [Dispatch and Trips](https://github.com/qdcv0272/baloambule/blob/master/backend/src/dispatch/dispatch.service.ts): `backend/src/dispatch/dispatch.service.ts`
- [Hospital Search](https://github.com/qdcv0272/baloambule/blob/master/backend/src/hospital/hospital-search.service.ts): `backend/src/hospital/hospital-search.service.ts`
- [Hospital Operations](https://github.com/qdcv0272/baloambule/blob/master/backend/src/hospital/hospital.service.ts): `backend/src/hospital/hospital.service.ts`
- [Ambulance Operations](https://github.com/qdcv0272/baloambule/blob/master/backend/src/ambulance/ambulance.service.ts): `backend/src/ambulance/ambulance.service.ts`
- [Identity Verification](https://github.com/qdcv0272/baloambule/blob/master/backend/src/identity/identity.service.ts): `backend/src/identity/identity.service.ts`
- [Payment](https://github.com/qdcv0272/baloambule/blob/master/backend/src/payment/payment.service.ts): `backend/src/payment/payment.service.ts`
- [Administration](https://github.com/qdcv0272/baloambule/blob/master/backend/src/admin/admin.service.ts): `backend/src/admin/admin.service.ts`
- [Notices](https://github.com/qdcv0272/baloambule/blob/master/backend/src/notice/notice.service.ts): `backend/src/notice/notice.service.ts`

### Operations Portals

- [Hospital Portal](https://github.com/qdcv0272/baloambule/blob/master/app/hospital/main.tsx): `app/hospital/main.tsx`
- [Ambulance Portal](https://github.com/qdcv0272/baloambule/blob/master/app/ambulance/main.tsx): `app/ambulance/main.tsx`
- [Admin Portal](https://github.com/qdcv0272/baloambule/blob/master/app/admin/index.tsx): `app/admin/index.tsx`

### External Services

- **Government Hospital Data**
- **Kakao Search and Maps**
- **PortOne**
- **Toss Payments**
- **SMS Provider**

### Application State

- [PostgreSQL](https://github.com/qdcv0272/baloambule/blob/master/backend/src/prisma.service.ts): `backend/src/prisma.service.ts`
- [Role Token Storage](https://github.com/qdcv0272/baloambule/blob/master/src/stores/tokenStorage.ts): `src/stores/tokenStorage.ts`

### Other components

- **User**
- **Hospital and Ambulance Staff**
- **Administrator**

## Connections

- User → User App: uses
- User App → Hospital Search UI: searches with
- Hospital Search UI → Hospital API Client: requests results
- Hospital API Client → Hospital Search: queries
- Hospital Search → Government Hospital Data: fetches hospital data
- Hospital Search → Kakao Search and Maps: geocodes and searches
- User App → Dispatch UI: creates and tracks calls
- Dispatch UI → Dispatch API Client: sends trip requests
- Dispatch API Client → Dispatch and Trips: calls dispatch endpoints
- Hospital and Ambulance Staff → Role Login and Registration: signs in or registers
- Role Login and Registration → API Client: sends auth requests
- API Client → Authentication: calls authentication endpoints
- Authentication → SMS Provider: sends verification codes
- Authentication → PostgreSQL: reads and writes accounts
- Hospital Portal → API Client: requests portal data
- API Client → Hospital Operations: calls hospital endpoints
- Ambulance Portal → Dispatch API Client: manages calls and vehicles
- Ambulance Portal → API Client: manages staff and revenue
- Dispatch and Trips → PostgreSQL: reads and writes requests and trips
- Hospital Operations → PostgreSQL: reads and writes hospital records
- Ambulance Operations → PostgreSQL: reads and writes staff records
- Administrator → Admin Portal: manages platform
- Admin Portal → API Client: requests admin actions
- API Client → Administration: calls admin endpoints
- Administration → PostgreSQL: backs up and restores
- User App → Identity Verification: starts verification
- Identity Verification → PortOne: verifies identity
- Identity Verification → PostgreSQL: stores verification and registration
- User App → Payment: starts payment
- Payment → Toss Payments: prepares and confirms payment
- Payment → PostgreSQL: stores payment records
- User App → Role Token Storage: stores role tokens
- Hospital Portal → Notices: views notices