# joydeep-bhattacharjee/token-sesh architecture

> Architecture diagram of the GitHub repository joydeep-bhattacharjee/token-sesh, 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/joydeep-bhattacharjee/token-sesh
- Repository: https://github.com/joydeep-bhattacharjee/token-sesh

## Overview

CoWork is a multi-tenant coworking-room booking REST API. Members register or authenticate, browse rooms, create and manage bookings, and retrieve availability; admins manage rooms and access usage reports and CSV exports. The main request path is FastAPI’s application entry point into endpoint routers, which apply domain rules and use SQLAlchemy-backed models. Booking creation and cancellation also invoke rate limiting, reference-code, refund, statistics, notification, and cache services. The graph follows documented endpoints and shown calls; unsampled modules are included where the README or source index establishes their role, without guessing their internal wiring.

Main entry points: [`app/routers/bookings.py`](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/bookings.py) (Booking Endpoints), [`app/models.py`](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/models.py) (Domain Models), [`app/main.py`](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/main.py) (FastAPI App), [`app/routers/rooms.py`](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/rooms.py) (Room Endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Routing"]
  node_app["FastAPI App<br/>[main.py]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
  node_errors["API Error Handling<br/>[errors.py]"]
  node_health["Health Endpoint<br/>[health.py]"]
end

subgraph group_identity["Identity &amp; Tenancy"]
  node_auth_routes["Auth Endpoints<br/>[auth.py]"]
  node_auth["Token &amp; Password Auth<br/>[auth.py]"]
end

subgraph group_booking["Booking Lifecycle"]
  node_booking_routes["Booking Endpoints<br/>[bookings.py]"]
  node_serializers["Booking Serialization<br/>[serializers.py]"]
  node_ratelimit["Booking Rate Limit<br/>[ratelimit.py]"]
  node_reference["Reference Codes<br/>[reference.py]"]
  node_refunds["Refund Processing<br/>[refunds.py]"]
  node_notifications["Booking Notifications<br/>[notifications.py]"]
end

subgraph group_rooms["Rooms &amp; Reporting"]
  node_stats["Room Statistics<br/>[stats.py]"]
  node_rooms_routes["Room Endpoints<br/>[rooms.py]"]
  node_admin_routes["Admin Reports &amp; Export<br/>[admin.py]"]
  node_export["CSV Export<br/>[export.py]"]
end

subgraph group_core["Runtime Core"]
  node_models["Domain Models<br/>[models.py]"]
  node_database[("SQLAlchemy Database<br/>[database.py]")]
  node_config["Runtime Config<br/>[config.py]"]
  node_cache["Response Cache<br/>[cache.py]"]
  node_timeutils["UTC Time Utilities<br/>[timeutils.py]"]
end

node_caller(("API Client"))

node_caller -->|"sends requests"| node_app
node_app -->|"creates schema"| node_database
node_app -->|"registers handler"| node_errors
node_app -->|"registers routes"| node_auth_routes
node_app -->|"registers routes"| node_booking_routes
node_app -->|"registers routes"| node_rooms_routes
node_app -->|"registers routes"| node_admin_routes
node_app -->|"registers routes"| node_health
node_auth_routes -->|"issues and verifies"| node_auth
node_auth_routes -->|"reads and writes"| node_models
node_auth_routes -->|"gets sessions"| node_database
node_auth_routes -->|"validates requests"| node_schemas
node_auth -->|"uses token settings"| node_config
node_auth -->|"gets sessions"| node_database
node_auth -->|"loads users"| node_models
node_models -->|"uses declarative base"| node_database
node_database -->|"loads database URL"| node_config
node_booking_routes -->|"requires user"| node_auth
node_booking_routes -->|"gets sessions"| node_database
node_booking_routes -->|"queries and writes"| node_models
node_booking_routes -->|"validates requests"| node_schemas
node_booking_routes -->|"checks request limit"| node_ratelimit
node_booking_routes -->|"allocates code"| node_reference
node_booking_routes -->|"calculates and logs"| node_refunds
node_booking_routes -->|"sends notifications"| node_notifications
node_booking_routes -->|"invalidates entries"| node_cache
node_booking_routes -->|"serializes bookings"| node_serializers
node_serializers -->|"reads booking fields"| node_models
node_serializers -->|"formats timestamps"| node_timeutils
node_reference -->|"checks references"| node_models
node_refunds -->|"creates refund logs"| node_models
node_ratelimit -->|"raises limit error"| node_errors
node_rooms_routes -->|"requires user or admin"| node_auth
node_rooms_routes -->|"gets sessions"| node_database
node_rooms_routes -->|"queries rooms and bookings"| node_models
node_rooms_routes -->|"validates room input"| node_schemas
node_rooms_routes -->|"gets room totals"| node_stats
node_rooms_routes -->|"reads and writes availability"| node_cache
node_rooms_routes -->|"formats intervals"| node_timeutils
node_stats -->|"queries bookings"| node_models
node_admin_routes -->|"requires admin"| node_auth
node_admin_routes -->|"gets sessions"| node_database
node_admin_routes -->|"queries report data"| node_models
node_admin_routes -->|"generates CSV"| node_export
node_admin_routes -->|"reads and writes reports"| node_cache
node_admin_routes -->|"parses date range"| node_timeutils
node_export -->|"queries bookings"| node_models
node_export -->|"formats timestamps"| node_timeutils

click node_app "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/main.py"
click node_auth_routes "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/auth.py"
click node_auth "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/auth.py"
click node_models "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/models.py"
click node_database "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/database.py"
click node_config "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/config.py"
click node_schemas "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/schemas.py"
click node_errors "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/errors.py"
click node_booking_routes "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/bookings.py"
click node_serializers "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/serializers.py"
click node_ratelimit "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/ratelimit.py"
click node_reference "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/reference.py"
click node_refunds "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/refunds.py"
click node_notifications "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/notifications.py"
click node_stats "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/stats.py"
click node_rooms_routes "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/rooms.py"
click node_admin_routes "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/admin.py"
click node_export "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/export.py"
click node_cache "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/cache.py"
click node_timeutils "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/timeutils.py"
click node_health "https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/health.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_schemas,node_errors,node_health,node_caller toneBlue
class node_auth_routes,node_auth toneAmber
class node_booking_routes,node_serializers,node_ratelimit,node_reference,node_refunds,node_notifications toneMint
class node_stats,node_rooms_routes,node_admin_routes,node_export toneRose
class node_models,node_database,node_config,node_cache,node_timeutils toneIndigo
```

## Components

### API Routing

- [FastAPI App](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/main.py): `app/main.py`
- [Request Schemas](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/schemas.py): `app/schemas.py`
- [API Error Handling](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/errors.py): `app/errors.py`
- [Health Endpoint](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/health.py): `app/routers/health.py`

### Identity & Tenancy

- [Auth Endpoints](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Token & Password Auth](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/auth.py): `app/auth.py`

### Booking Lifecycle

- [Booking Endpoints](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/bookings.py): `app/routers/bookings.py`
- [Booking Serialization](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/serializers.py): `app/serializers.py`
- [Booking Rate Limit](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/ratelimit.py): `app/services/ratelimit.py`
- [Reference Codes](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/reference.py): `app/services/reference.py`
- [Refund Processing](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/refunds.py): `app/services/refunds.py`
- [Booking Notifications](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/notifications.py): `app/services/notifications.py`

### Rooms & Reporting

- [Room Statistics](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/stats.py): `app/services/stats.py`
- [Room Endpoints](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/rooms.py): `app/routers/rooms.py`
- [Admin Reports & Export](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/routers/admin.py): `app/routers/admin.py`
- [CSV Export](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/services/export.py): `app/services/export.py`

### Runtime Core

- [Domain Models](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/models.py): `app/models.py`
- [SQLAlchemy Database](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/database.py): `app/database.py`
- [Runtime Config](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/config.py): `app/config.py`
- [Response Cache](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/cache.py): `app/cache.py`
- [UTC Time Utilities](https://github.com/joydeep-bhattacharjee/token-sesh/blob/main/app/timeutils.py): `app/timeutils.py`

### Other components

- **API Client**

## Connections

- API Client → FastAPI App: sends requests (evidence: `README.md`)
- FastAPI App → SQLAlchemy Database: creates schema (evidence: `app/main.py`)
- FastAPI App → API Error Handling: registers handler (evidence: `app/main.py`)
- FastAPI App → Auth Endpoints: registers routes (evidence: `app/main.py`)
- FastAPI App → Booking Endpoints: registers routes (evidence: `app/main.py`)
- FastAPI App → Room Endpoints: registers routes (evidence: `app/main.py`)
- FastAPI App → Admin Reports & Export: registers routes (evidence: `app/main.py`)
- FastAPI App → Health Endpoint: registers routes (evidence: `app/main.py`)
- Auth Endpoints → Token & Password Auth: issues and verifies (evidence: `app/routers/auth.py`)
- Auth Endpoints → Domain Models: reads and writes (evidence: `app/routers/auth.py`)
- Auth Endpoints → SQLAlchemy Database: gets sessions (evidence: `app/routers/auth.py`)
- Auth Endpoints → Request Schemas: validates requests (evidence: `app/routers/auth.py`)
- Token & Password Auth → Runtime Config: uses token settings (evidence: `app/auth.py`)
- Token & Password Auth → SQLAlchemy Database: gets sessions (evidence: `app/auth.py`)
- Token & Password Auth → Domain Models: loads users (evidence: `app/auth.py`)
- Domain Models → SQLAlchemy Database: uses declarative base (evidence: `app/models.py`)
- SQLAlchemy Database → Runtime Config: loads database URL (evidence: `app/database.py`)
- Booking Endpoints → Token & Password Auth: requires user (evidence: `app/routers/bookings.py`)
- Booking Endpoints → SQLAlchemy Database: gets sessions (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Domain Models: queries and writes (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Request Schemas: validates requests (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Booking Rate Limit: checks request limit (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Reference Codes: allocates code (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Refund Processing: calculates and logs (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Booking Notifications: sends notifications (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Response Cache: invalidates entries (evidence: `app/routers/bookings.py`)
- Booking Endpoints → Booking Serialization: serializes bookings (evidence: `app/routers/bookings.py`)
- Booking Serialization → Domain Models: reads booking fields (evidence: `app/serializers.py`)
- Booking Serialization → UTC Time Utilities: formats timestamps (evidence: `app/serializers.py`)
- Reference Codes → Domain Models: checks references (evidence: `app/services/reference.py`)
- Refund Processing → Domain Models: creates refund logs (evidence: `app/services/refunds.py`)
- Booking Rate Limit → API Error Handling: raises limit error (evidence: `app/services/ratelimit.py`)
- Room Endpoints → Token & Password Auth: requires user or admin (evidence: `app/routers/rooms.py`)
- Room Endpoints → SQLAlchemy Database: gets sessions (evidence: `app/routers/rooms.py`)
- Room Endpoints → Domain Models: queries rooms and bookings (evidence: `app/routers/rooms.py`)
- Room Endpoints → Request Schemas: validates room input (evidence: `app/routers/rooms.py`)
- Room Endpoints → Room Statistics: gets room totals (evidence: `app/routers/rooms.py`)
- Room Endpoints → Response Cache: reads and writes availability (evidence: `app/routers/rooms.py`)
- Room Endpoints → UTC Time Utilities: formats intervals (evidence: `app/routers/rooms.py`)
- Room Statistics → Domain Models: queries bookings (evidence: `app/services/stats.py`)
- Admin Reports & Export → Token & Password Auth: requires admin (evidence: `app/routers/admin.py`)
- Admin Reports & Export → SQLAlchemy Database: gets sessions (evidence: `app/routers/admin.py`)
- Admin Reports & Export → Domain Models: queries report data (evidence: `app/routers/admin.py`)
- Admin Reports & Export → CSV Export: generates CSV (evidence: `app/routers/admin.py`)
- Admin Reports & Export → Response Cache: reads and writes reports (evidence: `app/routers/admin.py`)
- Admin Reports & Export → UTC Time Utilities: parses date range (evidence: `app/routers/admin.py`)
- CSV Export → Domain Models: queries bookings (evidence: `app/services/export.py`)
- CSV Export → UTC Time Utilities: formats timestamps (evidence: `app/services/export.py`)
