# skydenqqq/hkust-maie6000c-skyden-qiu architecture

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

- Interactive diagram: https://gitdiagram.com/skydenqqq/hkust-maie6000c-skyden-qiu
- Repository: https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu

## Overview

This starter demonstrates a case-triage workflow: a user submits a case through the API, which persists it and a pending job; the worker claims the job, calls the internal AI service, and saves the triage result for retrieval through the API. Shared schemas, configuration, and database-session code support the services. Health checks, structured logging, and metrics are exposed by the services. Worker-to-database and service-to-PostgreSQL links are based on the README workflow and database description; detailed deployment and migration wiring is outside this runtime view.

Main entry points: [`services/api/app/main.py`](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/api/app/main.py) (Case API), [`services/common/db.py`](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/db.py) (DB sessions), [`services/worker/app/main.py`](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/worker/app/main.py) (Job worker), [`services/common/models.py`](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/models.py) (Case and job models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_services["Runtime services"]
  node_api["Case API<br/>[main.py]"]
  node_worker["Job worker<br/>[main.py]"]
  node_ai["AI triage<br/>[main.py]"]
end

subgraph group_shared["Shared foundation"]
  node_schemas["Data schemas<br/>[schemas.py]"]
  node_config["Settings and logging<br/>[config.py]"]
end

subgraph group_persistence["Persistence"]
  node_dbsession["DB sessions<br/>[db.py]"]
  node_models["Case and job models<br/>[models.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]

node_user -->|"submits cases"| node_api
node_api -->|"creates and queries"| node_models
node_api -->|"gets sessions"| node_dbsession
node_api -->|"validates and returns"| node_schemas
node_api -->|"queues jobs for"| node_worker
node_worker -->|"gets sessions"| node_dbsession
node_worker -->|"claims and updates"| node_models
node_worker -->|"sends triage request"| node_ai
node_ai -->|"validates and returns"| node_schemas
node_api -->|"returns case state"| node_user
node_dbsession -->|"reads database settings"| node_config
node_models -->|"uses declarative base"| node_dbsession
node_schemas -->|"uses status enums"| node_models
node_dbsession -->|"connects to"| node_postgres

click node_api "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/api/app/main.py"
click node_worker "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/worker/app/main.py"
click node_ai "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/ai/app/main.py"
click node_schemas "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/schemas.py"
click node_config "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/config.py"
click node_dbsession "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/db.py"
click node_models "https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/models.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_api,node_worker,node_ai,node_user toneBlue
class node_schemas,node_config,node_postgres toneAmber
class node_dbsession,node_models toneMint
```

## Components

### Runtime services

- [Case API](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/api/app/main.py): `services/api/app/main.py`
- [Job worker](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/worker/app/main.py): `services/worker/app/main.py`
- [AI triage](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/ai/app/main.py): `services/ai/app/main.py`

### Shared foundation

- [Data schemas](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/schemas.py): `services/common/schemas.py`
- [Settings and logging](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/config.py): `services/common/config.py`

### Persistence

- [DB sessions](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/db.py): `services/common/db.py`
- [Case and job models](https://github.com/skydenqqq/hkust-maie6000c-skyden-qiu/blob/main/services/common/models.py): `services/common/models.py`

### Other components

- **User**
- **PostgreSQL**

## Connections

- User → Case API: submits cases (evidence: `README.md`)
- Case API → Case and job models: creates and queries (evidence: `services/api/app/main.py`)
- Case API → DB sessions: gets sessions (evidence: `services/api/app/main.py`)
- Case API → Data schemas: validates and returns (evidence: `services/api/app/main.py`)
- Case API → Job worker: queues jobs for (evidence: `README.md`)
- Job worker → DB sessions: gets sessions (evidence: `services/worker/app/main.py`)
- Job worker → Case and job models: claims and updates (evidence: `services/worker/app/main.py`)
- Job worker → AI triage: sends triage request (evidence: `services/worker/app/main.py`)
- AI triage → Data schemas: validates and returns (evidence: `services/ai/app/main.py`)
- Case API → User: returns case state (evidence: `README.md`)
- DB sessions → Settings and logging: reads database settings (evidence: `services/common/db.py`)
- Case and job models → DB sessions: uses declarative base (evidence: `services/common/models.py`)
- Data schemas → Case and job models: uses status enums (evidence: `services/common/schemas.py`)
- DB sessions → PostgreSQL: connects to (evidence: `README.md`)
