# aryan-puranik/ticket_router architecture

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

- Interactive diagram: https://gitdiagram.com/aryan-puranik/ticket_router
- Repository: https://github.com/aryan-puranik/ticket_router

## Overview

Customer Support Ticket Router serves staff and customers through a Streamlit UI and FastAPI backend. Customers create tickets; staff can search, assign, prioritize, and move tickets through lifecycle stages. The service routes work using role, skill, capacity, priority, and SLA rules, while serving board and queue views and maintaining a tamper-evident audit trail. PostgreSQL is durable storage; the service rebuilds in-memory indexes and heaps at startup and persists each request as a transaction. The graph follows documented and indexed relationships; some subsystem internals were not sampled.

Main entry points: [`service.py`](https://github.com/aryan-puranik/ticket_router/blob/main/service.py) (Ticket Router), [`seed.py`](https://github.com/aryan-puranik/ticket_router/blob/main/seed.py) (Demo Data Seeder), [`app.py`](https://github.com/aryan-puranik/ticket_router/blob/main/app.py) (Streamlit UI), [`main.py`](https://github.com/aryan-puranik/ticket_router/blob/main/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interface"]
  node_ui["Streamlit UI<br/>[app.py]"]
end

subgraph group_domain["Routing and Domain"]
  node_api["HTTP API<br/>[main.py]"]
  node_router["Ticket Router<br/>[service.py]"]
  node_search["Ticket Search<br/>[service.py]"]
  node_domain_rules["Lifecycle and Roles<br/>[models.py]"]
  node_audit["Audit Hash Chain<br/>[audit.py]"]
  node_settings["Runtime Settings<br/>[config.py]"]
end

subgraph group_memory["In-Memory Structures"]
  node_btree["B+ Trees<br/>[bplus_tree.py]"]
  node_heap["Indexed Heaps<br/>[indexed_heap.py]"]
end

subgraph group_storage["Persistence"]
  node_database_adapter["Database Adapter<br/>[db.py]"]
  node_postgres[("PostgreSQL")]
  node_seeder["Demo Data Seeder<br/>[seed.py]"]
end

node_users(("Customers and Staff"))

node_users -->|"use"| node_ui
node_ui -->|"HTTP requests"| node_api
node_api -->|"dispatches"| node_router
node_router -->|"indexes and searches"| node_search
node_router -->|"uses rules"| node_domain_rules
node_router -->|"creates and verifies"| node_audit
node_router -->|"uses indexes"| node_btree
node_router -->|"uses queues"| node_heap
node_router -->|"loads and persists"| node_database_adapter
node_database_adapter -->|"reads and writes"| node_postgres
node_api -->|"uses configuration"| node_settings
node_ui -->|"uses API defaults"| node_settings
node_seeder -->|"bulk loads data"| node_database_adapter
node_seeder -->|"builds audit entries"| node_audit
node_seeder -->|"uses domain values"| node_domain_rules

click node_ui "https://github.com/aryan-puranik/ticket_router/blob/main/app.py"
click node_api "https://github.com/aryan-puranik/ticket_router/blob/main/main.py"
click node_router "https://github.com/aryan-puranik/ticket_router/blob/main/service.py"
click node_search "https://github.com/aryan-puranik/ticket_router/blob/main/service.py"
click node_domain_rules "https://github.com/aryan-puranik/ticket_router/blob/main/models.py"
click node_audit "https://github.com/aryan-puranik/ticket_router/blob/main/audit.py"
click node_btree "https://github.com/aryan-puranik/ticket_router/blob/main/bplus_tree.py"
click node_heap "https://github.com/aryan-puranik/ticket_router/blob/main/indexed_heap.py"
click node_database_adapter "https://github.com/aryan-puranik/ticket_router/blob/main/db.py"
click node_settings "https://github.com/aryan-puranik/ticket_router/blob/main/config.py"
click node_seeder "https://github.com/aryan-puranik/ticket_router/blob/main/seed.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_ui toneBlue
class node_api,node_router,node_search,node_domain_rules,node_audit,node_settings toneAmber
class node_btree,node_heap toneMint
class node_database_adapter,node_postgres,node_seeder toneRose
class node_users toneIndigo
```

## Components

### User Interface

- [Streamlit UI](https://github.com/aryan-puranik/ticket_router/blob/main/app.py): `app.py`

### Routing and Domain

- [HTTP API](https://github.com/aryan-puranik/ticket_router/blob/main/main.py): `main.py`
- [Ticket Router](https://github.com/aryan-puranik/ticket_router/blob/main/service.py): `service.py`
- [Ticket Search](https://github.com/aryan-puranik/ticket_router/blob/main/service.py): `service.py`
- [Lifecycle and Roles](https://github.com/aryan-puranik/ticket_router/blob/main/models.py): `models.py`
- [Audit Hash Chain](https://github.com/aryan-puranik/ticket_router/blob/main/audit.py): `audit.py`
- [Runtime Settings](https://github.com/aryan-puranik/ticket_router/blob/main/config.py): `config.py`

### In-Memory Structures

- [B+ Trees](https://github.com/aryan-puranik/ticket_router/blob/main/bplus_tree.py): `bplus_tree.py`
- [Indexed Heaps](https://github.com/aryan-puranik/ticket_router/blob/main/indexed_heap.py): `indexed_heap.py`

### Persistence

- [Database Adapter](https://github.com/aryan-puranik/ticket_router/blob/main/db.py): `db.py`
- **PostgreSQL**
- [Demo Data Seeder](https://github.com/aryan-puranik/ticket_router/blob/main/seed.py): `seed.py`

### Other components

- **Customers and Staff**

## Connections

- Customers and Staff → Streamlit UI: use (evidence: `README.md`)
- Streamlit UI → HTTP API: HTTP requests (evidence: `README.md`)
- HTTP API → Ticket Router: dispatches (evidence: `main.py`)
- Ticket Router → Ticket Search: indexes and searches (evidence: `service.py`)
- Ticket Router → Lifecycle and Roles: uses rules (evidence: `service.py`)
- Ticket Router → Audit Hash Chain: creates and verifies (evidence: `service.py`)
- Ticket Router → B+ Trees: uses indexes (evidence: `service.py`)
- Ticket Router → Indexed Heaps: uses queues (evidence: `service.py`)
- Ticket Router → Database Adapter: loads and persists (evidence: `README.md`)
- Database Adapter → PostgreSQL: reads and writes (evidence: `db.py`)
- HTTP API → Runtime Settings: uses configuration (evidence: `main.py`)
- Streamlit UI → Runtime Settings: uses API defaults (evidence: `app.py`)
- Demo Data Seeder → Database Adapter: bulk loads data (evidence: `seed.py`)
- Demo Data Seeder → Audit Hash Chain: builds audit entries (evidence: `seed.py`)
- Demo Data Seeder → Lifecycle and Roles: uses domain values (evidence: `seed.py`)
