# pavaram/imperium-ticketing-system architecture

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

- Interactive diagram: https://gitdiagram.com/pavaram/imperium-ticketing-system
- Repository: https://github.com/pavaram/imperium-ticketing-system

## Overview

Imperium Ticketing is a self-hosted QR ticketing app for staff to issue full- or half-payment tickets and check guests in. The core flow is browser requests through FastAPI routes, ticket rules and persistence, then QR/email delivery; scanning validates entry against ticket state. Admin account management, event statistics, and safe database reset are distinct supporting capabilities. Edges reflect the README and source-index references or excerpts; unsampled implementation details are not inferred.

Main entry points: [`app/main.py`](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/main.py) (FastAPI app), [`app/templating.py`](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/templating.py) (Page rendering), [`app/models.py`](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/models.py) (Ticket & user models), [`app/routers/tickets.py`](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/tickets.py) (Ticket routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Web Runtime"]
  node_app["FastAPI app<br/>[main.py]"]
  node_ticket_routes["Ticket routes<br/>[tickets.py]"]
  node_scan_routes["Scan routes<br/>[scan.py]"]
  node_page_routes["Page routes<br/>[pages.py]"]
  node_scanner_ui["Scanner client<br/>[scan.js]"]
  node_templates["Page rendering<br/>[templating.py]"]
end

subgraph group_ticketing["Ticket Operations"]
  node_ticket_rules["Ticket rules<br/>[tickets.py]"]
  node_scan_logic["Check-in logic<br/>[scan.py]"]
  node_qr["QR generation<br/>[qr.py]"]
  node_delivery["Ticket delivery<br/>[delivery.py]"]
  node_stats["Event statistics<br/>[stats.py]"]
end

subgraph group_identity["Identity &amp; Admin"]
  node_auth_routes["Login routes<br/>[auth.py]"]
  node_users["User management<br/>[users.py]"]
  node_security["Session security<br/>[security.py]"]
  node_rate_limit["Login throttling<br/>[ratelimit.py]"]
  node_admin_routes["Admin routes<br/>[admin.py]"]
  node_reset["Safe reset<br/>[reset.py]"]
end

subgraph group_platform["Persistence &amp; Delivery"]
  node_models["Ticket &amp; user models<br/>[models.py]"]
  node_db["SQLite engine<br/>[db.py]"]
  node_database[("SQLite data<br/>[db.py]")]
  node_mailer["Mailer<br/>[mailer.py]"]
end

node_staff(("Staff browser"))
node_smtp["SMTP provider"]

node_staff -->|"uses"| node_app
node_app -->|"registers"| node_ticket_routes
node_app -->|"registers"| node_scan_routes
node_app -->|"registers"| node_page_routes
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_admin_routes
node_app -->|"creates engine"| node_db
node_app -->|"seeds admin"| node_users
node_app -->|"renders errors"| node_templates
node_app -->|"serves static"| node_scanner_ui
node_ticket_routes -->|"calls"| node_ticket_rules
node_ticket_routes -->|"calls"| node_delivery
node_ticket_routes -->|"calls"| node_qr
node_ticket_routes -->|"renders"| node_templates
node_scan_routes -->|"calls"| node_scan_logic
node_scan_routes -->|"renders"| node_templates
node_page_routes -->|"calls"| node_stats
node_page_routes -->|"renders"| node_templates
node_auth_routes -->|"authenticates"| node_users
node_auth_routes -->|"manages session"| node_security
node_auth_routes -->|"checks attempts"| node_rate_limit
node_auth_routes -->|"renders"| node_templates
node_admin_routes -->|"manages accounts"| node_users
node_admin_routes -->|"requests reset"| node_reset
node_admin_routes -->|"renders"| node_templates
node_scan_logic -->|"uses ticket rules"| node_ticket_rules
node_delivery -->|"sends messages"| node_mailer
node_delivery -->|"generates QR"| node_qr
node_mailer -.->|"sends mail"| node_smtp
node_ticket_rules -->|"reads &amp; writes"| node_models
node_scan_logic -->|"reads &amp; writes"| node_models
node_stats -->|"queries"| node_models
node_users -->|"reads &amp; writes"| node_models
node_security -->|"loads user"| node_models
node_db -->|"opens SQLite"| node_database
node_reset -->|"backs up &amp; resets"| node_database
node_db -->|"provides sessions"| node_models

click node_app "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/main.py"
click node_ticket_routes "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/tickets.py"
click node_scan_routes "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/scan.py"
click node_page_routes "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/pages.py"
click node_auth_routes "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/auth.py"
click node_ticket_rules "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/tickets.py"
click node_scan_logic "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/scan.py"
click node_qr "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/qr.py"
click node_delivery "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/delivery.py"
click node_stats "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/stats.py"
click node_scanner_ui "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/static/scan.js"
click node_templates "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/templating.py"
click node_users "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/users.py"
click node_security "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/security.py"
click node_rate_limit "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/ratelimit.py"
click node_admin_routes "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/admin.py"
click node_reset "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/reset.py"
click node_models "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/models.py"
click node_db "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/db.py"
click node_database "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/db.py"
click node_mailer "https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/mailer.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_app,node_ticket_routes,node_scan_routes,node_page_routes,node_scanner_ui,node_templates,node_staff toneBlue
class node_ticket_rules,node_scan_logic,node_qr,node_delivery,node_stats toneAmber
class node_auth_routes,node_users,node_security,node_rate_limit,node_admin_routes,node_reset toneMint
class node_models,node_db,node_database,node_mailer toneRose
class node_smtp toneIndigo
```

## Components

### Web Runtime

- [FastAPI app](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/main.py): `app/main.py`
- [Ticket routes](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/tickets.py): `app/routers/tickets.py`
- [Scan routes](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/scan.py): `app/routers/scan.py`
- [Page routes](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/pages.py): `app/routers/pages.py`
- [Scanner client](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/static/scan.js): `app/static/scan.js`
- [Page rendering](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/templating.py): `app/templating.py`

### Ticket Operations

- [Ticket rules](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/tickets.py): `app/services/tickets.py`
- [Check-in logic](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/scan.py): `app/services/scan.py`
- [QR generation](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/qr.py): `app/services/qr.py`
- [Ticket delivery](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/delivery.py): `app/services/delivery.py`
- [Event statistics](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/stats.py): `app/services/stats.py`

### Identity & Admin

- [Login routes](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [User management](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/users.py): `app/services/users.py`
- [Session security](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/security.py): `app/security.py`
- [Login throttling](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/ratelimit.py): `app/ratelimit.py`
- [Admin routes](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/routers/admin.py): `app/routers/admin.py`
- [Safe reset](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/reset.py): `app/services/reset.py`

### Persistence & Delivery

- [Ticket & user models](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/models.py): `app/models.py`
- [SQLite engine](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/db.py): `app/db.py`
- [SQLite data](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/db.py): `app/db.py`
- [Mailer](https://github.com/pavaram/imperium-ticketing-system/blob/main/app/services/mailer.py): `app/services/mailer.py`

### Other components

- **Staff browser**
- **SMTP provider**

## Connections

- Staff browser → FastAPI app: uses (evidence: `README.md`)
- FastAPI app → Ticket routes: registers (evidence: `app/main.py`)
- FastAPI app → Scan routes: registers (evidence: `app/main.py`)
- FastAPI app → Page routes: registers (evidence: `app/main.py`)
- FastAPI app → Login routes: registers (evidence: `app/main.py`)
- FastAPI app → Admin routes: registers (evidence: `app/main.py`)
- FastAPI app → SQLite engine: creates engine (evidence: `app/main.py`)
- FastAPI app → User management: seeds admin (evidence: `app/main.py`)
- FastAPI app → Page rendering: renders errors (evidence: `app/main.py`)
- FastAPI app → Scanner client: serves static (evidence: `app/main.py`)
- Ticket routes → Ticket rules: calls (evidence: `app/routers/tickets.py`)
- Ticket routes → Ticket delivery: calls (evidence: `app/routers/tickets.py`)
- Ticket routes → QR generation: calls (evidence: `app/routers/tickets.py`)
- Ticket routes → Page rendering: renders (evidence: `app/routers/tickets.py`)
- Scan routes → Check-in logic: calls (evidence: `app/routers/scan.py`)
- Scan routes → Page rendering: renders (evidence: `app/routers/scan.py`)
- Page routes → Event statistics: calls (evidence: `app/routers/pages.py`)
- Page routes → Page rendering: renders (evidence: `app/routers/pages.py`)
- Login routes → User management: authenticates (evidence: `app/routers/auth.py`)
- Login routes → Session security: manages session (evidence: `app/routers/auth.py`)
- Login routes → Login throttling: checks attempts (evidence: `app/routers/auth.py`)
- Login routes → Page rendering: renders (evidence: `app/routers/auth.py`)
- Admin routes → User management: manages accounts (evidence: `app/routers/admin.py`)
- Admin routes → Safe reset: requests reset (evidence: `app/routers/admin.py`)
- Admin routes → Page rendering: renders (evidence: `app/routers/admin.py`)
- Check-in logic → Ticket rules: uses ticket rules (evidence: `app/services/scan.py`)
- Ticket delivery → Mailer: sends messages (evidence: `app/services/delivery.py`)
- Ticket delivery → QR generation: generates QR (evidence: `app/services/delivery.py`)
- Mailer → SMTP provider: sends mail (evidence: `README.md`)
- Ticket rules → Ticket & user models: reads & writes (evidence: `app/services/tickets.py`)
- Check-in logic → Ticket & user models: reads & writes (evidence: `app/services/scan.py`)
- Event statistics → Ticket & user models: queries (evidence: `app/services/stats.py`)
- User management → Ticket & user models: reads & writes (evidence: `app/services/users.py`)
- Session security → Ticket & user models: loads user (evidence: `app/security.py`)
- SQLite engine → SQLite data: opens SQLite (evidence: `app/db.py`)
- Safe reset → SQLite data: backs up & resets (evidence: `app/services/reset.py`)
- SQLite engine → Ticket & user models: provides sessions (evidence: `app/db.py`)
