# nus-mtechse-hawkerflow/hawkerflow-service-hawker architecture

> Architecture diagram of the GitHub repository nus-mtechse-hawkerflow/hawkerflow-service-hawker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker
- Repository: https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker

## Overview

HawkerFlow’s Hawker service is a FastAPI API for registering hawkers and stalls, publishing stall menus, and looking up a hawker’s stall. Requests enter through the registered routes, pass through the service layer, and reach the repository and shared database; startup configures that runtime and creates the tables. The graph preserves the documented PostgreSQL/SQLite driver options and health endpoint. Some driver selection and health-route internals were not excerpted, so uncertain links are omitted.

Main entry points: [`src/lifecycle/lifespan.py`](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/lifecycle/lifespan.py) (Startup lifecycle), [`src/repository/hawker_repository.py`](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/repository/hawker_repository.py) (Hawker repository), [`src/endpoints/hawker_routes.py`](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/endpoints/hawker_routes.py) (Hawker routes), [`src/hawker_service/hawker_service.py`](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/hawker_service/hawker_service.py) (Hawker service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_main["FastAPI app<br/>[main.py]"]
  node_routes["Hawker routes<br/>[hawker_routes.py]"]
  node_health["Health route<br/>[health_routes.py]"]
end

subgraph group_domain["Hawker domain"]
  node_request_model["Hawker request model<br/>[hawker_details.py]"]
  node_service["Hawker service<br/>[hawker_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Hawker repository"]
  node_stalls[("Stalls table<br/>[stalls.py]")]
  node_menu[("Stall menu table<br/>[stall_menu.py]")]
  node_owner[("Stall owner table<br/>[stall_owner.py]")]
  node_session["DB session<br/>[db_session.py]"]
  node_db_factory["Database factory"]
  node_driver_factory["Driver factory<br/>[driver_factory.py]"]
  node_driver["Database driver base<br/>[driver.py]"]
  node_postgres["PostgreSQL driver<br/>[postgres_driver.py]"]
  node_sqlite["SQLite driver<br/>[sqlite_driver.py]"]
end

subgraph group_setup["Configuration and startup"]
  node_config["App configuration<br/>[app_config.py]"]
  node_settings["Service settings<br/>[config.yml]"]
  node_lifespan["Startup lifecycle<br/>[lifespan.py]"]
end

node_hawker(("Hawker owner"))
node_diner(("Diner"))
node_database[("Shared hawkerflow database")]

node_main -->|"registers"| node_routes
node_main -->|"registers"| node_health
node_main -->|"configures startup"| node_lifespan
node_hawker -->|"submits requests"| node_routes
node_diner -->|"lists stalls"| node_routes
node_routes -->|"accepts payload"| node_request_model
node_routes -->|"calls"| node_service
node_lifespan -->|"loads"| node_config
node_config -->|"reads settings"| node_settings
node_lifespan -->|"creates"| node_session
node_lifespan -->|"creates"| node_repository
node_lifespan -->|"creates"| node_service
node_lifespan -->|"creates tables"| node_stalls
node_lifespan -->|"creates tables"| node_menu
node_lifespan -->|"creates tables"| node_owner
node_service -->|"delegates"| node_repository
node_service -->|"uses input"| node_request_model
node_repository -->|"reads and writes"| node_stalls
node_repository -->|"reads and writes"| node_menu
node_repository -->|"reads and writes"| node_owner
node_repository -->|"maps input"| node_request_model
node_repository -->|"persists records"| node_database
node_session -->|"requests driver"| node_db_factory
node_db_factory -->|"inherits"| node_driver_factory
node_postgres -->|"implements"| node_driver
node_sqlite -->|"implements"| node_driver
node_postgres -->|"uses settings"| node_config
node_sqlite -->|"uses settings"| node_config

click node_main "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/main.py"
click node_routes "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/endpoints/hawker_routes.py"
click node_health "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/endpoints/health_routes.py"
click node_request_model "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/models/hawker_details.py"
click node_service "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/hawker_service/hawker_service.py"
click node_repository "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/repository/hawker_repository.py"
click node_stalls "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/entities/stalls.py"
click node_menu "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/entities/stall_menu.py"
click node_owner "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/entities/stall_owner.py"
click node_session "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/session/db_session.py"
click node_db_factory "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/factory/database_factory.py"
click node_driver_factory "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/factory/driver_factory.py"
click node_driver "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/drivers/driver.py"
click node_postgres "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/drivers/postgres_driver.py"
click node_sqlite "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/drivers/sqlite_driver.py"
click node_config "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/configurations/app_config.py"
click node_settings "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/resources/config.yml"
click node_lifespan "https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/lifecycle/lifespan.py"

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_main,node_routes,node_health toneBlue
class node_request_model,node_service,node_database toneAmber
class node_repository,node_stalls,node_menu,node_owner,node_session,node_db_factory,node_driver_factory,node_driver,node_postgres,node_sqlite toneMint
class node_config,node_settings,node_lifespan toneRose
class node_hawker,node_diner toneIndigo
```

## Components

### API runtime

- [FastAPI app](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/main.py): `src/main.py`
- [Hawker routes](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/endpoints/hawker_routes.py): `src/endpoints/hawker_routes.py`
- [Health route](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/endpoints/health_routes.py): `src/endpoints/health_routes.py`

### Hawker domain

- [Hawker request model](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/models/hawker_details.py): `src/models/hawker_details.py`
- [Hawker service](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/hawker_service/hawker_service.py): `src/hawker_service/hawker_service.py`

### Persistence

- [Hawker repository](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/repository/hawker_repository.py): `src/repository/hawker_repository.py`
- [Stalls table](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/entities/stalls.py): `src/entities/stalls.py`
- [Stall menu table](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/entities/stall_menu.py): `src/entities/stall_menu.py`
- [Stall owner table](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/entities/stall_owner.py): `src/entities/stall_owner.py`
- [DB session](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/session/db_session.py): `src/session/db_session.py`
- [Database factory](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/factory/database_factory.py): `src/factory/database_factory.py`
- [Driver factory](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/factory/driver_factory.py): `src/factory/driver_factory.py`
- [Database driver base](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/drivers/driver.py): `src/drivers/driver.py`
- [PostgreSQL driver](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/drivers/postgres_driver.py): `src/drivers/postgres_driver.py`
- [SQLite driver](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/drivers/sqlite_driver.py): `src/drivers/sqlite_driver.py`

### Configuration and startup

- [App configuration](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/configurations/app_config.py): `src/configurations/app_config.py`
- [Service settings](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/resources/config.yml): `resources/config.yml`
- [Startup lifecycle](https://github.com/nus-mtechse-hawkerflow/hawkerflow-service-hawker/blob/release/src/lifecycle/lifespan.py): `src/lifecycle/lifespan.py`

### Other components

- **Hawker owner**
- **Diner**
- **Shared hawkerflow database**

## Connections

- FastAPI app → Hawker routes: registers (evidence: `src/main.py`)
- FastAPI app → Health route: registers (evidence: `src/main.py`)
- FastAPI app → Startup lifecycle: configures startup (evidence: `src/main.py`)
- Hawker owner → Hawker routes: submits requests (evidence: `README.md`)
- Diner → Hawker routes: lists stalls (evidence: `README.md`)
- Hawker routes → Hawker request model: accepts payload (evidence: `src/endpoints/hawker_routes.py`)
- Hawker routes → Hawker service: calls (evidence: `src/endpoints/hawker_routes.py`)
- Startup lifecycle → App configuration: loads (evidence: `src/lifecycle/lifespan.py`)
- App configuration → Service settings: reads settings (evidence: `README.md`)
- Startup lifecycle → DB session: creates (evidence: `src/lifecycle/lifespan.py`)
- Startup lifecycle → Hawker repository: creates (evidence: `src/lifecycle/lifespan.py`)
- Startup lifecycle → Hawker service: creates (evidence: `src/lifecycle/lifespan.py`)
- Startup lifecycle → Stalls table: creates tables (evidence: `src/lifecycle/lifespan.py`)
- Startup lifecycle → Stall menu table: creates tables (evidence: `src/lifecycle/lifespan.py`)
- Startup lifecycle → Stall owner table: creates tables (evidence: `src/lifecycle/lifespan.py`)
- Hawker service → Hawker repository: delegates (evidence: `src/hawker_service/hawker_service.py`)
- Hawker service → Hawker request model: uses input (evidence: `src/hawker_service/hawker_service.py`)
- Hawker repository → Stalls table: reads and writes (evidence: `src/repository/hawker_repository.py`)
- Hawker repository → Stall menu table: reads and writes (evidence: `src/repository/hawker_repository.py`)
- Hawker repository → Stall owner table: reads and writes (evidence: `src/repository/hawker_repository.py`)
- Hawker repository → Hawker request model: maps input (evidence: `src/repository/hawker_repository.py`)
- Hawker repository → Shared hawkerflow database: persists records (evidence: `README.md`)
- DB session → Database factory: requests driver (evidence: `src/session/db_session.py`)
- Database factory → Driver factory: inherits (evidence: `src/factory/database_factory.py`)
- PostgreSQL driver → Database driver base: implements (evidence: `src/drivers/postgres_driver.py`)
- SQLite driver → Database driver base: implements (evidence: `src/drivers/sqlite_driver.py`)
- PostgreSQL driver → App configuration: uses settings (evidence: `src/drivers/postgres_driver.py`)
- SQLite driver → App configuration: uses settings (evidence: `src/drivers/sqlite_driver.py`)