# arunkumar-codec/skip-line architecture

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

- Interactive diagram: https://gitdiagram.com/arunkumar-codec/skip-line
- Repository: https://github.com/arunkumar-codec/skip-line

## Overview

Skip Line is a FastAPI digital queue and virtual-token platform for customers, walk-ins, employees, and organization operators. Its central flow is booking: customers check service availability, reserve a token, then track queue progress and receive turn notifications; staff operate counters and advance tokens. The product also includes organization administration, payments, multi-stage workflows, kiosk/display access, and an optional AI booking assistant. The graph reflects documented capabilities and indexed references; unsampled router and service implementations limit some call-level evidence.

Main entry points: [`app/main.py`](https://github.com/arunkumar-codec/skip-line/blob/main/app/main.py) (FastAPI app), [`app/database.py`](https://github.com/arunkumar-codec/skip-line/blob/main/app/database.py) (SQL database), [`app/services/token_service.py`](https://github.com/arunkumar-codec/skip-line/blob/main/app/services/token_service.py) (Token lifecycle), [`app/services/schedule_service.py`](https://github.com/arunkumar-codec/skip-line/blob/main/app/services/schedule_service.py) (Availability and slots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_public["Public booking<br/>[public.py]"]
  node_token_api["Token endpoints<br/>[tokens.py]"]
end

subgraph group_booking["Booking and queue"]
  node_availability["Availability and slots"]
  node_booking_engine["Token lifecycle<br/>[token_service.py]"]
  node_token_store[("Token records<br/>[token.py]")]
  node_schedule_store[("Schedule and capacity<br/>[weekly_schedule.py]")]
end

subgraph group_operations["Organization operations"]
  node_org_admin["Organization management<br/>[org.py]"]
  node_employee_ops["Employee and shifts<br/>[shift_service.py]"]
  node_admin["Admin oversight<br/>[admin.py]"]
  node_workflow["Service workflows<br/>[workflow.py]"]
  node_payments["Payments<br/>[payments.py]"]
end

subgraph group_engagement["Customer engagement"]
  node_ai["AI booking assistant<br/>[ai.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
  node_websocket["Live queue updates<br/>[websocket.py]"]
  node_display["Display and kiosk<br/>[public.py]"]
end

subgraph group_platform["Platform services"]
  node_db[("SQL database<br/>[database.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
  node_ws_manager["WebSocket delivery<br/>[manager.py]"]
end

node_customer(("Customer / kiosk"))

node_customer -->|"uses"| node_app
node_app -->|"registers"| node_auth
node_app -->|"registers"| node_public
node_app -->|"registers"| node_token_api
node_app -->|"registers"| node_org_admin
node_app -->|"registers"| node_admin
node_app -->|"registers"| node_payments
node_app -->|"registers"| node_notifications
node_app -->|"registers"| node_websocket
node_token_api -.->|"dispatches"| node_booking_engine
node_public -.->|"checks availability"| node_availability
node_booking_engine -->|"checks slots"| node_availability
node_booking_engine -->|"creates and updates"| node_token_store
node_availability -->|"resolves hours"| node_schedule_store
node_availability -->|"queries"| node_db
node_booking_engine -->|"persists bookings"| node_db
node_auth -->|"uses sessions"| node_db
node_org_admin -->|"manages organization"| node_db
node_employee_ops -->|"updates shifts"| node_db
node_admin -.->|"manages records"| node_db
node_workflow -.->|"tracks stages"| node_db
node_payments -.->|"records payments"| node_db
node_ai -.->|"assists booking"| node_customer
node_booking_engine -.->|"triggers notices"| node_notifications
node_booking_engine -.->|"broadcasts queue state"| node_ws_manager
node_websocket -.->|"serves connections"| node_ws_manager
node_display -.->|"shows queue"| node_customer
node_app -->|"loads settings"| node_config
node_db -->|"configures engine"| node_config
node_ws_manager -->|"reads settings"| node_config

click node_app "https://github.com/arunkumar-codec/skip-line/blob/main/app/main.py"
click node_auth "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/auth.py"
click node_public "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/public.py"
click node_token_api "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/tokens.py"
click node_availability "https://github.com/arunkumar-codec/skip-line/blob/main/app/services/schedule_service.py"
click node_booking_engine "https://github.com/arunkumar-codec/skip-line/blob/main/app/services/token_service.py"
click node_token_store "https://github.com/arunkumar-codec/skip-line/blob/main/models/token.py"
click node_schedule_store "https://github.com/arunkumar-codec/skip-line/blob/main/models/weekly_schedule.py"
click node_org_admin "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/org.py"
click node_employee_ops "https://github.com/arunkumar-codec/skip-line/blob/main/app/services/shift_service.py"
click node_admin "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/admin.py"
click node_workflow "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/workflow.py"
click node_payments "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/payments.py"
click node_ai "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/ai.py"
click node_notifications "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/notifications.py"
click node_websocket "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/websocket.py"
click node_display "https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/public.py"
click node_db "https://github.com/arunkumar-codec/skip-line/blob/main/app/database.py"
click node_config "https://github.com/arunkumar-codec/skip-line/blob/main/app/config.py"
click node_ws_manager "https://github.com/arunkumar-codec/skip-line/blob/main/app/websocket/manager.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_auth,node_public,node_token_api toneBlue
class node_availability,node_booking_engine,node_token_store,node_schedule_store toneAmber
class node_org_admin,node_employee_ops,node_admin,node_workflow,node_payments toneMint
class node_ai,node_notifications,node_websocket,node_display toneRose
class node_db,node_config,node_ws_manager,node_customer toneIndigo
```

## Components

### Application entry

- [FastAPI app](https://github.com/arunkumar-codec/skip-line/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Public booking](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/public.py): `app/routers/public.py`
- [Token endpoints](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/tokens.py): `app/routers/tokens.py`

### Booking and queue

- [Availability and slots](https://github.com/arunkumar-codec/skip-line/blob/main/app/services/schedule_service.py): `app/services/schedule_service.py`
- [Token lifecycle](https://github.com/arunkumar-codec/skip-line/blob/main/app/services/token_service.py): `app/services/token_service.py`
- [Token records](https://github.com/arunkumar-codec/skip-line/blob/main/models/token.py): `models/token.py`
- [Schedule and capacity](https://github.com/arunkumar-codec/skip-line/blob/main/models/weekly_schedule.py): `models/weekly_schedule.py`

### Organization operations

- [Organization management](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/org.py): `app/routers/org.py`
- [Employee and shifts](https://github.com/arunkumar-codec/skip-line/blob/main/app/services/shift_service.py): `app/services/shift_service.py`
- [Admin oversight](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/admin.py): `app/routers/admin.py`
- [Service workflows](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/workflow.py): `app/routers/workflow.py`
- [Payments](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/payments.py): `app/routers/payments.py`

### Customer engagement

- [AI booking assistant](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/ai.py): `app/routers/ai.py`
- [Notifications](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/notifications.py): `app/routers/notifications.py`
- [Live queue updates](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/websocket.py): `app/routers/websocket.py`
- [Display and kiosk](https://github.com/arunkumar-codec/skip-line/blob/main/app/routers/public.py): `app/routers/public.py`

### Platform services

- [SQL database](https://github.com/arunkumar-codec/skip-line/blob/main/app/database.py): `app/database.py`
- [Runtime configuration](https://github.com/arunkumar-codec/skip-line/blob/main/app/config.py): `app/config.py`
- [WebSocket delivery](https://github.com/arunkumar-codec/skip-line/blob/main/app/websocket/manager.py): `app/websocket/manager.py`

### Other components

- **Customer / kiosk**

## Connections

- Customer / kiosk → FastAPI app: uses (evidence: `README.md`)
- FastAPI app → Authentication: registers (evidence: `app/main.py`)
- FastAPI app → Public booking: registers (evidence: `app/main.py`)
- FastAPI app → Token endpoints: registers (evidence: `app/main.py`)
- FastAPI app → Organization management: registers (evidence: `app/main.py`)
- FastAPI app → Admin oversight: registers (evidence: `app/main.py`)
- FastAPI app → Payments: registers (evidence: `app/main.py`)
- FastAPI app → Notifications: registers (evidence: `app/main.py`)
- FastAPI app → Live queue updates: registers (evidence: `app/main.py`)
- Token endpoints → Token lifecycle: dispatches
- Public booking → Availability and slots: checks availability
- Token lifecycle → Availability and slots: checks slots (evidence: `app/services/token_service.py`)
- Token lifecycle → Token records: creates and updates (evidence: `app/services/token_service.py`)
- Availability and slots → Schedule and capacity: resolves hours (evidence: `app/services/schedule_service.py`)
- Availability and slots → SQL database: queries (evidence: `app/services/schedule_service.py`)
- Token lifecycle → SQL database: persists bookings (evidence: `app/services/token_service.py`)
- Authentication → SQL database: uses sessions (evidence: `app/routers/auth.py`)
- Organization management → SQL database: manages organization (evidence: `app/routers/org.py`)
- Employee and shifts → SQL database: updates shifts (evidence: `app/services/shift_service.py`)
- Admin oversight → SQL database: manages records
- Service workflows → SQL database: tracks stages
- Payments → SQL database: records payments
- AI booking assistant → Customer / kiosk: assists booking (evidence: `README.md`)
- Token lifecycle → Notifications: triggers notices
- Token lifecycle → WebSocket delivery: broadcasts queue state (evidence: `app/services/token_service.py`)
- Live queue updates → WebSocket delivery: serves connections
- Display and kiosk → Customer / kiosk: shows queue (evidence: `README.md`)
- FastAPI app → Runtime configuration: loads settings (evidence: `app/main.py`)
- SQL database → Runtime configuration: configures engine (evidence: `app/database.py`)
- WebSocket delivery → Runtime configuration: reads settings (evidence: `app/websocket/manager.py`)