# priyayids/vms-myboga architecture

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

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

## Overview

Visitor Middleware Service accepts visitor registrations and room-management requests, coordinates bookings with Nuveq’s access-control API, and returns booking details and QR-code access. The principal flow validates and deduplicates a registration, resolves its room and doors, creates paired check-in/check-out visitor records upstream, and generates QR codes. Card events then advance booking state; room availability and no-show expiry support the booking lifecycle. The README documents both webhook and polling event modes. Several runtime connections are supported by the README or source index; unsampled implementation details are not inferred.

Main entry points: [`src/main/java/com/visitorbridge/service/BookingService.java`](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/BookingService.java) (Booking orchestration), [`src/main/java/com/visitorbridge/service/RoomService.java`](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/RoomService.java) (Room and door management), [`src/main/java/com/visitorbridge/client/NuveqVisitorClient.java`](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/client/NuveqVisitorClient.java) (Nuveq API client), [`src/main/java/com/visitorbridge/controller/RoomController.java`](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/RoomController.java) (Room endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["API intake"]
  node_visitor_api["Visitor endpoints"]
  node_booking_api["Booking endpoints"]
  node_room_api["Room endpoints"]
  node_webhook_api["Event webhook"]
end

subgraph group_booking["Booking lifecycle"]
  node_booking_service["Booking orchestration"]
  node_booking_model["Booking state<br/>[Booking.java]"]
  node_qr_service["QR generation<br/>[QrCodeService.java]"]
end

subgraph group_rooms["Room and access"]
  node_room_service["Room and door management<br/>[RoomService.java]"]
  node_room_model["Room model<br/>[Room.java]"]
  node_door_model["Door model<br/>[Door.java]"]
  node_startup_sync["Startup door sync"]
end

subgraph group_integration["Nuveq integration"]
  node_nuveq_client["Nuveq API client"]
  node_nuveq_config["Nuveq configuration"]
  node_webhook_listener["Webhook event listener"]
  node_polling_listener["Polling event listener"]
end

subgraph group_support["Persistence and operations"]
  node_booking_repo[("Booking repository")]
  node_room_repo[("Room repository")]
  node_door_repo[("Door repository")]
  node_event_log[("Webhook event log")]
  node_event_log_repo[("Event log repository")]
  node_transaction_log["Transaction logging"]
  node_vms_config["Booking and QR settings<br/>[VmsProperties.java]"]
end

node_visitor(("Visitor form/client"))
node_operator(("Room operator"))
node_nuveq{{"Nuveq Access API"}}

node_visitor -->|"submits registration"| node_visitor_api
node_visitor_api -->|"registers visitor"| node_booking_service
node_booking_service -->|"checks and saves"| node_booking_repo
node_booking_service -->|"resolves room"| node_room_repo
node_booking_service -.->|"resolves doors"| node_door_repo
node_booking_service -->|"creates visitors"| node_nuveq_client
node_nuveq_client -->|"sends API requests"| node_nuveq
node_booking_service -.->|"generates QR codes"| node_qr_service
node_booking_api -->|"handles booking"| node_booking_service
node_booking_api -->|"serves QR codes"| node_qr_service
node_booking_service -->|"updates state"| node_booking_model
node_webhook_api -->|"processes event"| node_booking_service
node_webhook_api -.->|"records event"| node_event_log_repo
node_webhook_listener -->|"processes card event"| node_booking_service
node_polling_listener -->|"polls events"| node_nuveq_client
node_polling_listener -.->|"processes events"| node_booking_service
node_operator -->|"manages rooms"| node_room_api
node_room_api -->|"manages rooms"| node_room_service
node_room_api -->|"checks availability"| node_booking_service
node_room_service -->|"reads and writes"| node_room_repo
node_room_service -->|"reads and writes"| node_door_repo
node_room_service -->|"fetches doors"| node_nuveq_client
node_room_model -->|"associates doors"| node_door_model
node_startup_sync -.->|"syncs doors"| node_room_service
node_booking_service -.->|"logs transactions"| node_transaction_log
node_qr_service -->|"reads QR settings"| node_vms_config
node_nuveq_client -->|"uses API settings"| node_nuveq_config
node_event_log_repo -->|"persists events"| node_event_log

click node_visitor_api "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/VisitorController.java"
click node_booking_api "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/BookingController.java"
click node_room_api "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/RoomController.java"
click node_webhook_api "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/EventWebhookController.java"
click node_booking_service "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/BookingService.java"
click node_booking_model "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/Booking.java"
click node_qr_service "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/QrCodeService.java"
click node_room_service "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/RoomService.java"
click node_room_model "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/Room.java"
click node_door_model "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/Door.java"
click node_nuveq_client "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/client/NuveqVisitorClient.java"
click node_nuveq_config "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/config/NuveqProperties.java"
click node_webhook_listener "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/listener/WebhookCardEventListener.java"
click node_polling_listener "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/listener/PollingCardEventListener.java"
click node_booking_repo "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/BookingRepository.java"
click node_room_repo "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/RoomRepository.java"
click node_door_repo "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/DoorRepository.java"
click node_event_log "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/WebhookEventLog.java"
click node_event_log_repo "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/WebhookEventLogRepository.java"
click node_transaction_log "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/TransactionLogger.java"
click node_vms_config "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/config/VmsProperties.java"
click node_startup_sync "https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/RoomStartupSyncRunner.java"

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_visitor_api,node_booking_api,node_room_api,node_webhook_api,node_visitor toneBlue
class node_booking_service,node_booking_model,node_qr_service toneAmber
class node_room_service,node_room_model,node_door_model,node_startup_sync,node_nuveq toneMint
class node_nuveq_client,node_nuveq_config,node_webhook_listener,node_polling_listener toneRose
class node_booking_repo,node_room_repo,node_door_repo,node_event_log,node_event_log_repo,node_transaction_log,node_vms_config,node_operator toneIndigo
```

## Components

### API intake

- [Visitor endpoints](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/VisitorController.java): `src/main/java/com/visitorbridge/controller/VisitorController.java`
- [Booking endpoints](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/BookingController.java): `src/main/java/com/visitorbridge/controller/BookingController.java`
- [Room endpoints](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/RoomController.java): `src/main/java/com/visitorbridge/controller/RoomController.java`
- [Event webhook](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/controller/EventWebhookController.java): `src/main/java/com/visitorbridge/controller/EventWebhookController.java`

### Booking lifecycle

- [Booking orchestration](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/BookingService.java): `src/main/java/com/visitorbridge/service/BookingService.java`
- [Booking state](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/Booking.java): `src/main/java/com/visitorbridge/model/Booking.java`
- [QR generation](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/QrCodeService.java): `src/main/java/com/visitorbridge/service/QrCodeService.java`

### Room and access

- [Room and door management](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/RoomService.java): `src/main/java/com/visitorbridge/service/RoomService.java`
- [Room model](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/Room.java): `src/main/java/com/visitorbridge/model/Room.java`
- [Door model](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/Door.java): `src/main/java/com/visitorbridge/model/Door.java`
- [Startup door sync](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/RoomStartupSyncRunner.java): `src/main/java/com/visitorbridge/service/RoomStartupSyncRunner.java`

### Nuveq integration

- [Nuveq API client](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/client/NuveqVisitorClient.java): `src/main/java/com/visitorbridge/client/NuveqVisitorClient.java`
- [Nuveq configuration](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/config/NuveqProperties.java): `src/main/java/com/visitorbridge/config/NuveqProperties.java`
- [Webhook event listener](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/listener/WebhookCardEventListener.java): `src/main/java/com/visitorbridge/listener/WebhookCardEventListener.java`
- [Polling event listener](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/listener/PollingCardEventListener.java): `src/main/java/com/visitorbridge/listener/PollingCardEventListener.java`

### Persistence and operations

- [Booking repository](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/BookingRepository.java): `src/main/java/com/visitorbridge/repository/BookingRepository.java`
- [Room repository](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/RoomRepository.java): `src/main/java/com/visitorbridge/repository/RoomRepository.java`
- [Door repository](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/DoorRepository.java): `src/main/java/com/visitorbridge/repository/DoorRepository.java`
- [Webhook event log](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/model/WebhookEventLog.java): `src/main/java/com/visitorbridge/model/WebhookEventLog.java`
- [Event log repository](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/repository/WebhookEventLogRepository.java): `src/main/java/com/visitorbridge/repository/WebhookEventLogRepository.java`
- [Transaction logging](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/service/TransactionLogger.java): `src/main/java/com/visitorbridge/service/TransactionLogger.java`
- [Booking and QR settings](https://github.com/priyayids/vms-myboga/blob/main/src/main/java/com/visitorbridge/config/VmsProperties.java): `src/main/java/com/visitorbridge/config/VmsProperties.java`

### Other components

- **Visitor form/client**
- **Room operator**
- **Nuveq Access API**

## Connections

- Visitor form/client → Visitor endpoints: submits registration
- Visitor endpoints → Booking orchestration: registers visitor (evidence: `src/main/java/com/visitorbridge/controller/VisitorController.java`)
- Booking orchestration → Booking repository: checks and saves (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- Booking orchestration → Room repository: resolves room (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- Booking orchestration → Door repository: resolves doors (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- Booking orchestration → Nuveq API client: creates visitors (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- Nuveq API client → Nuveq Access API: sends API requests (evidence: `src/main/java/com/visitorbridge/client/NuveqVisitorClient.java`)
- Booking orchestration → QR generation: generates QR codes (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- Booking endpoints → Booking orchestration: handles booking (evidence: `src/main/java/com/visitorbridge/controller/BookingController.java`)
- Booking endpoints → QR generation: serves QR codes (evidence: `src/main/java/com/visitorbridge/controller/BookingController.java`)
- Booking orchestration → Booking state: updates state (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- Event webhook → Booking orchestration: processes event (evidence: `src/main/java/com/visitorbridge/controller/EventWebhookController.java`)
- Event webhook → Event log repository: records event
- Webhook event listener → Booking orchestration: processes card event (evidence: `src/main/java/com/visitorbridge/listener/WebhookCardEventListener.java`)
- Polling event listener → Nuveq API client: polls events (evidence: `src/main/java/com/visitorbridge/listener/PollingCardEventListener.java`)
- Polling event listener → Booking orchestration: processes events
- Room operator → Room endpoints: manages rooms (evidence: `src/main/java/com/visitorbridge/controller/RoomController.java`)
- Room endpoints → Room and door management: manages rooms (evidence: `src/main/java/com/visitorbridge/controller/RoomController.java`)
- Room endpoints → Booking orchestration: checks availability (evidence: `src/main/java/com/visitorbridge/controller/RoomController.java`)
- Room and door management → Room repository: reads and writes (evidence: `src/main/java/com/visitorbridge/service/RoomService.java`)
- Room and door management → Door repository: reads and writes (evidence: `src/main/java/com/visitorbridge/service/RoomService.java`)
- Room and door management → Nuveq API client: fetches doors (evidence: `src/main/java/com/visitorbridge/service/RoomService.java`)
- Room model → Door model: associates doors (evidence: `src/main/java/com/visitorbridge/model/Room.java`)
- Startup door sync → Room and door management: syncs doors
- Booking orchestration → Transaction logging: logs transactions (evidence: `src/main/java/com/visitorbridge/service/BookingService.java`)
- QR generation → Booking and QR settings: reads QR settings (evidence: `src/main/java/com/visitorbridge/service/QrCodeService.java`)
- Nuveq API client → Nuveq configuration: uses API settings (evidence: `src/main/java/com/visitorbridge/client/NuveqVisitorClient.java`)
- Event log repository → Webhook event log: persists events (evidence: `src/main/java/com/visitorbridge/repository/WebhookEventLogRepository.java`)
