# priyayids/mybogamidfastapi architecture

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

- Interactive diagram: https://gitdiagram.com/priyayids/mybogamidfastapi
- Repository: https://github.com/priyayids/mybogamidfastapi

## Overview

Nuveq Access Control Middle Service is an asynchronous BFF between meeting-room booking clients and Nuveq Cloud. A client authenticates and manages rooms or bookings; booking creation validates room availability, provisions visitor access with Nuveq, persists the booking, and can return a QR credential. Nuveq tap webhooks drive booking state and room-status updates, which the service can push to client webhooks. A background scheduler handles no-show revocation, auto-checkout, and optional event reconciliation. The graph follows documented capabilities and indexed references; unsampled route and service internals are not treated as inspected evidence.

Main entry points: [`app/api/deps.py`](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/deps.py) (API Dependencies), [`app/services/booking_service.py`](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/booking_service.py) (Booking Lifecycle), [`app/services/webhook_service.py`](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/webhook_service.py) (Tap Processing), [`app/api/v1/router.py`](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/router.py) (V1 Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_router["V1 Router<br/>[router.py]"]
  node_booking_api["Booking Routes<br/>[bookings.py]"]
  node_room_api["Room Routes<br/>[rooms.py]"]
  node_nuveq_api["Nuveq Discovery<br/>[nuveq.py]"]
  node_webhook_api["Tap Receiver<br/>[webhooks.py]"]
  node_health_api["Health Route<br/>[health.py]"]
end

subgraph group_domain["Booking &amp; Rooms"]
  node_booking_service["Booking Lifecycle<br/>[booking_service.py]"]
  node_room_service["Room Status &amp; Mapping<br/>[room_service.py]"]
  node_qr_service["QR Generation<br/>[qr_service.py]"]
end

subgraph group_integration["Access Integrations"]
  node_webhook_service["Tap Processing<br/>[webhook_service.py]"]
  node_scheduler["Background Jobs"]
  node_nuveq_client["Nuveq API Client<br/>[nuveq_client.py]"]
end

subgraph group_platform["Runtime &amp; State"]
  node_deps["API Dependencies<br/>[deps.py]"]
  node_security["API Security<br/>[security.py]"]
  node_schemas["API Schemas"]
  node_database[("Async Database<br/>[database.py]")]
  node_models["Domain Records<br/>[__init__.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_exceptions["Domain Errors<br/>[exceptions.py]"]
  node_logging["Structured Logging<br/>[logging.py]"]
end

node_client(("Booking Client"))
node_nuveq["Nuveq Cloud"]
node_client_webhook["Client Webhook"]

node_client -->|"calls API"| node_app
node_app -->|"mounts routes"| node_router
node_router -->|"registers"| node_booking_api
node_router -->|"registers"| node_room_api
node_router -->|"registers"| node_nuveq_api
node_router -->|"registers"| node_webhook_api
node_router -->|"registers"| node_health_api
node_booking_api -->|"delegates to"| node_booking_service
node_room_api -->|"delegates to"| node_room_service
node_nuveq_api -->|"proxies discovery"| node_nuveq_client
node_webhook_api -->|"processes tap"| node_webhook_service
node_booking_api -->|"authenticates"| node_security
node_room_api -->|"authenticates"| node_security
node_webhook_api -->|"checks secret"| node_security
node_booking_api -->|"resolves services"| node_deps
node_room_api -->|"resolves services"| node_deps
node_webhook_api -->|"resolves service"| node_deps
node_booking_service -->|"provisions access"| node_nuveq_client
node_booking_service -->|"generates QR"| node_qr_service
node_booking_service -->|"reads and writes"| node_database
node_room_service -->|"reads and writes"| node_database
node_webhook_service -->|"records events"| node_database
node_webhook_service -->|"derives status"| node_room_service
node_webhook_service -->|"posts updates"| node_client_webhook
node_nuveq -->|"delivers taps"| node_webhook_api
node_nuveq_client -->|"calls REST API"| node_nuveq
node_scheduler -->|"revokes access"| node_nuveq_client
node_scheduler -->|"checks status"| node_room_service
node_scheduler -->|"dispatches updates"| node_webhook_service
node_app -->|"starts jobs"| node_scheduler
node_deps -->|"opens sessions"| node_database
node_deps -->|"constructs"| node_booking_service
node_deps -->|"constructs"| node_nuveq_client
node_deps -->|"constructs"| node_room_service
node_deps -->|"constructs"| node_webhook_service
node_database -->|"loads URL"| node_config
node_models -->|"uses declarative base"| node_database
node_security -->|"checks keys"| node_config
node_booking_service -->|"queries bookings"| node_models
node_room_service -->|"derives room state"| node_models
node_webhook_service -->|"records tap state"| node_models
node_booking_api -->|"uses DTOs"| node_schemas
node_room_api -->|"uses DTOs"| node_schemas
node_nuveq_api -->|"uses DTOs"| node_schemas
node_webhook_api -->|"uses payloads"| node_schemas
node_booking_service -->|"raises domain errors"| node_exceptions
node_nuveq_client -->|"raises API errors"| node_exceptions
node_app -->|"configures logging"| node_logging

click node_app "https://github.com/priyayids/mybogamidfastapi/blob/main/app/main.py"
click node_router "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/router.py"
click node_booking_api "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/bookings.py"
click node_room_api "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/rooms.py"
click node_nuveq_api "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/nuveq.py"
click node_webhook_api "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/webhooks.py"
click node_health_api "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/health.py"
click node_deps "https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/deps.py"
click node_security "https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/security.py"
click node_schemas "https://github.com/priyayids/mybogamidfastapi/tree/main/app/schemas"
click node_booking_service "https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/booking_service.py"
click node_room_service "https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/room_service.py"
click node_qr_service "https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/qr_service.py"
click node_webhook_service "https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/webhook_service.py"
click node_scheduler "https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/scheduler_service.py"
click node_nuveq_client "https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/nuveq_client.py"
click node_database "https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/database.py"
click node_models "https://github.com/priyayids/mybogamidfastapi/blob/main/app/models/__init__.py"
click node_config "https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/config.py"
click node_exceptions "https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/exceptions.py"
click node_logging "https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/logging.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_router,node_booking_api,node_room_api,node_nuveq_api,node_webhook_api,node_health_api,node_client,node_client_webhook toneBlue
class node_booking_service,node_room_service,node_qr_service toneAmber
class node_webhook_service,node_scheduler,node_nuveq_client toneMint
class node_deps,node_security,node_schemas,node_database,node_models,node_config,node_exceptions,node_logging toneRose
class node_nuveq toneIndigo
```

## Components

### HTTP API

- [FastAPI App](https://github.com/priyayids/mybogamidfastapi/blob/main/app/main.py): `app/main.py`
- [V1 Router](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/router.py): `app/api/v1/router.py`
- [Booking Routes](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/bookings.py): `app/api/v1/bookings.py`
- [Room Routes](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/rooms.py): `app/api/v1/rooms.py`
- [Nuveq Discovery](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/nuveq.py): `app/api/v1/nuveq.py`
- [Tap Receiver](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/webhooks.py): `app/api/v1/webhooks.py`
- [Health Route](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/v1/health.py): `app/api/v1/health.py`

### Booking & Rooms

- [Booking Lifecycle](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/booking_service.py): `app/services/booking_service.py`
- [Room Status & Mapping](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/room_service.py): `app/services/room_service.py`
- [QR Generation](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/qr_service.py): `app/services/qr_service.py`

### Access Integrations

- [Tap Processing](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/webhook_service.py): `app/services/webhook_service.py`
- [Background Jobs](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/scheduler_service.py): `app/services/scheduler_service.py`
- [Nuveq API Client](https://github.com/priyayids/mybogamidfastapi/blob/main/app/services/nuveq_client.py): `app/services/nuveq_client.py`

### Runtime & State

- [API Dependencies](https://github.com/priyayids/mybogamidfastapi/blob/main/app/api/deps.py): `app/api/deps.py`
- [API Security](https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/security.py): `app/core/security.py`
- [API Schemas](https://github.com/priyayids/mybogamidfastapi/tree/main/app/schemas): `app/schemas`
- [Async Database](https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/database.py): `app/core/database.py`
- [Domain Records](https://github.com/priyayids/mybogamidfastapi/blob/main/app/models/__init__.py): `app/models/__init__.py`
- [Configuration](https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/config.py): `app/core/config.py`
- [Domain Errors](https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/exceptions.py): `app/core/exceptions.py`
- [Structured Logging](https://github.com/priyayids/mybogamidfastapi/blob/main/app/core/logging.py): `app/core/logging.py`

### Other components

- **Booking Client**
- **Nuveq Cloud**
- **Client Webhook**

## Connections

- Booking Client → FastAPI App: calls API (evidence: `README.md`)
- FastAPI App → V1 Router: mounts routes (evidence: `app/main.py`)
- V1 Router → Booking Routes: registers (evidence: `app/api/v1/router.py`)
- V1 Router → Room Routes: registers (evidence: `app/api/v1/router.py`)
- V1 Router → Nuveq Discovery: registers (evidence: `app/api/v1/router.py`)
- V1 Router → Tap Receiver: registers (evidence: `app/api/v1/router.py`)
- V1 Router → Health Route: registers (evidence: `app/api/v1/router.py`)
- Booking Routes → Booking Lifecycle: delegates to (evidence: `app/api/v1/bookings.py`)
- Room Routes → Room Status & Mapping: delegates to (evidence: `app/api/v1/rooms.py`)
- Nuveq Discovery → Nuveq API Client: proxies discovery (evidence: `app/api/v1/nuveq.py`)
- Tap Receiver → Tap Processing: processes tap (evidence: `app/api/v1/webhooks.py`)
- Booking Routes → API Security: authenticates (evidence: `app/api/v1/bookings.py`)
- Room Routes → API Security: authenticates (evidence: `app/api/v1/rooms.py`)
- Tap Receiver → API Security: checks secret (evidence: `app/api/v1/webhooks.py`)
- Booking Routes → API Dependencies: resolves services (evidence: `app/api/v1/bookings.py`)
- Room Routes → API Dependencies: resolves services (evidence: `app/api/v1/rooms.py`)
- Tap Receiver → API Dependencies: resolves service (evidence: `app/api/v1/webhooks.py`)
- Booking Lifecycle → Nuveq API Client: provisions access (evidence: `app/services/booking_service.py`)
- Booking Lifecycle → QR Generation: generates QR (evidence: `app/services/booking_service.py`)
- Booking Lifecycle → Async Database: reads and writes (evidence: `app/services/booking_service.py`)
- Room Status & Mapping → Async Database: reads and writes (evidence: `app/services/room_service.py`)
- Tap Processing → Async Database: records events (evidence: `app/services/webhook_service.py`)
- Tap Processing → Room Status & Mapping: derives status (evidence: `app/services/webhook_service.py`)
- Tap Processing → Client Webhook: posts updates (evidence: `app/services/webhook_service.py`)
- Nuveq Cloud → Tap Receiver: delivers taps (evidence: `README.md`)
- Nuveq API Client → Nuveq Cloud: calls REST API (evidence: `app/services/nuveq_client.py`)
- Background Jobs → Nuveq API Client: revokes access (evidence: `app/services/scheduler_service.py`)
- Background Jobs → Room Status & Mapping: checks status (evidence: `app/services/scheduler_service.py`)
- Background Jobs → Tap Processing: dispatches updates (evidence: `app/services/scheduler_service.py`)
- FastAPI App → Background Jobs: starts jobs (evidence: `app/main.py`)
- API Dependencies → Async Database: opens sessions (evidence: `app/api/deps.py`)
- API Dependencies → Booking Lifecycle: constructs (evidence: `app/api/deps.py`)
- API Dependencies → Nuveq API Client: constructs (evidence: `app/api/deps.py`)
- API Dependencies → Room Status & Mapping: constructs (evidence: `app/api/deps.py`)
- API Dependencies → Tap Processing: constructs (evidence: `app/api/deps.py`)
- Async Database → Configuration: loads URL (evidence: `app/core/database.py`)
- Domain Records → Async Database: uses declarative base (evidence: `app/models/__init__.py`)
- API Security → Configuration: checks keys (evidence: `app/core/security.py`)
- Booking Lifecycle → Domain Records: queries bookings (evidence: `app/services/booking_service.py`)
- Room Status & Mapping → Domain Records: derives room state (evidence: `app/services/room_service.py`)
- Tap Processing → Domain Records: records tap state (evidence: `app/services/webhook_service.py`)
- Booking Routes → API Schemas: uses DTOs (evidence: `app/api/v1/bookings.py`)
- Room Routes → API Schemas: uses DTOs (evidence: `app/api/v1/rooms.py`)
- Nuveq Discovery → API Schemas: uses DTOs (evidence: `app/api/v1/nuveq.py`)
- Tap Receiver → API Schemas: uses payloads (evidence: `app/api/v1/webhooks.py`)
- Booking Lifecycle → Domain Errors: raises domain errors (evidence: `app/services/booking_service.py`)
- Nuveq API Client → Domain Errors: raises API errors (evidence: `app/services/nuveq_client.py`)
- FastAPI App → Structured Logging: configures logging (evidence: `app/main.py`)
