# wanabro227/eventsphere architecture

> Architecture diagram of the GitHub repository wanabro227/eventsphere, 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/wanabro227/eventsphere
- Repository: https://github.com/wanabro227/eventsphere

## Overview

EventSphere is a web platform for venue and event management, ticket booking, QR-based entry validation, waitlists, and venue hire. The main attendee flow is authenticated booking through the API, agent-mediated availability handling, payment, and ticket generation; staff validate tickets separately. The graph also includes administration, notifications, and agent monitoring. Some capabilities are documented but their implementation was not sampled, so those links are documentation-based; unsampled internal call paths are not asserted.

Main entry points: [`backend/app/main.py`](https://github.com/wanabro227/eventsphere/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/messaging/message_bus.py`](https://github.com/wanabro227/eventsphere/blob/main/backend/app/messaging/message_bus.py) (Agent message bus), [`backend/app/models/__init__.py`](https://github.com/wanabro227/eventsphere/blob/main/backend/app/models/__init__.py) (Domain records), [`backend/app/routers/bookings.py`](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/bookings.py) (Booking routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["EventSphere UI<br/>[events.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_admin_ui["Admin UI<br/>[admin.js]"]
  node_scanner["Ticket scanner<br/>[scanner.js]"]
end

subgraph group_api["API and access"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_access["Identity and roles<br/>[dependencies.py]"]
  node_auth_logic["Authentication service<br/>[auth_service.py]"]
  node_security["Password and JWT"]
end

subgraph group_domain["Booking and operations"]
  node_booking_routes["Booking routes<br/>[bookings.py]"]
  node_ticket_routes["Ticket routes<br/>[tickets.py]"]
  node_event_routes["Event routes<br/>[events.py]"]
  node_venue_routes["Venue routes<br/>[venues.py]"]
  node_hire_routes["Venue hire routes<br/>[venue_hire.py]"]
  node_waitlist_routes["Waitlist routes<br/>[waitlist.py]"]
  node_admin_routes["Administration<br/>[admin.py]"]
  node_notify_routes["Notifications<br/>[notifications.py]"]
  node_payment["Payment simulation<br/>[payment_service.py]"]
  node_qr["QR generation<br/>[qr_service.py]"]
end

subgraph group_agents["Agent system"]
  node_booking_agent["Booking agent<br/>[booking_agent.py]"]
  node_ticket_agent["Ticket agent<br/>[ticket_agent.py]"]
  node_waitlist_agent["Waitlist agent<br/>[waitlist_agent.py]"]
  node_notification_agent["Notification agent"]
  node_message_bus["Agent message bus<br/>[message_bus.py]"]
  node_message["Structured messages<br/>[message.py]"]
  node_agent_logs["Agent activity logs<br/>[agent_logs.py]"]
end

subgraph group_data["Persistence"]
  node_db_layer["Database sessions<br/>[database.py]"]
  node_booking_model[("Booking records<br/>[booking.py]")]
  node_data_models[("Domain records<br/>[__init__.py]")]
end

node_attendee(("Attendee"))
node_staff(("Staff member"))
node_relational_db[("Relational database")]

node_attendee -->|"uses"| node_web
node_staff -->|"validates tickets"| node_scanner
node_web -->|"requests API"| node_api_client
node_admin_ui -->|"requests API"| node_api_client
node_scanner -->|"requests API"| node_api_client
node_api_client -->|"sends HTTP"| node_app
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_booking_routes
node_app -->|"registers"| node_ticket_routes
node_app -->|"registers"| node_event_routes
node_app -->|"registers"| node_venue_routes
node_app -->|"registers"| node_hire_routes
node_app -->|"registers"| node_waitlist_routes
node_app -->|"registers"| node_admin_routes
node_app -->|"registers"| node_notify_routes
node_app -->|"registers"| node_agent_logs
node_auth_routes -->|"calls"| node_auth_logic
node_auth_routes -->|"creates token"| node_security
node_auth_logic -->|"hashes and checks"| node_security
node_booking_routes -->|"requires user"| node_access
node_booking_routes -->|"dispatches booking"| node_message_bus
node_booking_routes -->|"simulates payment"| node_payment
node_booking_routes -->|"requests ticket"| node_message_bus
node_message_bus -->|"dispatches message"| node_booking_agent
node_message_bus -->|"dispatches message"| node_ticket_agent
node_message_bus -->|"dispatches message"| node_waitlist_agent
node_app -->|"registers agents"| node_message_bus
node_message_bus -->|"records exchanges"| node_agent_logs
node_waitlist_routes -->|"dispatches request"| node_message_bus
node_app -->|"registers agent"| node_notification_agent
node_booking_agent -->|"handles messages"| node_message
node_waitlist_agent -->|"handles messages"| node_message
node_booking_agent -->|"uses records"| node_data_models
node_waitlist_agent -->|"uses records"| node_data_models
node_booking_routes -->|"loads booking"| node_booking_model
node_db_layer -->|"connects to"| node_relational_db
node_booking_model -->|"uses ORM base"| node_db_layer
node_event_routes -->|"queries records"| node_data_models
node_venue_routes -->|"queries records"| node_data_models
node_hire_routes -->|"queries records"| node_data_models
node_ticket_routes -->|"queries records"| node_data_models
node_admin_routes -->|"manages records"| node_data_models
node_notify_routes -->|"queries records"| node_data_models
node_qr -.->|"generates codes"| node_ticket_agent
node_notification_agent -.->|"supports notification flow"| node_notify_routes

click node_web "https://github.com/wanabro227/eventsphere/blob/main/frontend/js/events.js"
click node_api_client "https://github.com/wanabro227/eventsphere/blob/main/frontend/js/api.js"
click node_admin_ui "https://github.com/wanabro227/eventsphere/blob/main/frontend/js/admin.js"
click node_scanner "https://github.com/wanabro227/eventsphere/blob/main/frontend/js/scanner.js"
click node_app "https://github.com/wanabro227/eventsphere/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/auth.py"
click node_access "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/dependencies.py"
click node_auth_logic "https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/auth_service.py"
click node_security "https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/security_service.py"
click node_booking_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/bookings.py"
click node_ticket_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/tickets.py"
click node_event_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/events.py"
click node_venue_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/venues.py"
click node_hire_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/venue_hire.py"
click node_waitlist_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/waitlist.py"
click node_admin_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/admin.py"
click node_notify_routes "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/notifications.py"
click node_payment "https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/payment_service.py"
click node_qr "https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/qr_service.py"
click node_booking_agent "https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/booking_agent.py"
click node_ticket_agent "https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/ticket_agent.py"
click node_waitlist_agent "https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/waitlist_agent.py"
click node_notification_agent "https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/notification_agent.py"
click node_message_bus "https://github.com/wanabro227/eventsphere/blob/main/backend/app/messaging/message_bus.py"
click node_message "https://github.com/wanabro227/eventsphere/blob/main/backend/app/messaging/message.py"
click node_agent_logs "https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/agent_logs.py"
click node_db_layer "https://github.com/wanabro227/eventsphere/blob/main/backend/app/database.py"
click node_booking_model "https://github.com/wanabro227/eventsphere/blob/main/backend/app/models/booking.py"
click node_data_models "https://github.com/wanabro227/eventsphere/blob/main/backend/app/models/__init__.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_web,node_api_client,node_admin_ui,node_scanner toneBlue
class node_app,node_auth_routes,node_access,node_auth_logic,node_security,node_relational_db toneAmber
class node_booking_routes,node_ticket_routes,node_event_routes,node_venue_routes,node_hire_routes,node_waitlist_routes,node_admin_routes,node_notify_routes,node_payment,node_qr toneMint
class node_booking_agent,node_ticket_agent,node_waitlist_agent,node_notification_agent,node_message_bus,node_message,node_agent_logs toneRose
class node_db_layer,node_booking_model,node_data_models,node_attendee,node_staff toneIndigo
```

## Components

### Web client

- [EventSphere UI](https://github.com/wanabro227/eventsphere/blob/main/frontend/js/events.js): `frontend/js/events.js`
- [API client](https://github.com/wanabro227/eventsphere/blob/main/frontend/js/api.js): `frontend/js/api.js`
- [Admin UI](https://github.com/wanabro227/eventsphere/blob/main/frontend/js/admin.js): `frontend/js/admin.js`
- [Ticket scanner](https://github.com/wanabro227/eventsphere/blob/main/frontend/js/scanner.js): `frontend/js/scanner.js`

### API and access

- [FastAPI application](https://github.com/wanabro227/eventsphere/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Identity and roles](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/dependencies.py): `backend/app/routers/dependencies.py`
- [Authentication service](https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Password and JWT](https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/security_service.py): `backend/app/services/security_service.py`

### Booking and operations

- [Booking routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/bookings.py): `backend/app/routers/bookings.py`
- [Ticket routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/tickets.py): `backend/app/routers/tickets.py`
- [Event routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/events.py): `backend/app/routers/events.py`
- [Venue routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/venues.py): `backend/app/routers/venues.py`
- [Venue hire routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/venue_hire.py): `backend/app/routers/venue_hire.py`
- [Waitlist routes](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/waitlist.py): `backend/app/routers/waitlist.py`
- [Administration](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [Notifications](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/notifications.py): `backend/app/routers/notifications.py`
- [Payment simulation](https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/payment_service.py): `backend/app/services/payment_service.py`
- [QR generation](https://github.com/wanabro227/eventsphere/blob/main/backend/app/services/qr_service.py): `backend/app/services/qr_service.py`

### Agent system

- [Booking agent](https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/booking_agent.py): `backend/app/agents/booking_agent.py`
- [Ticket agent](https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/ticket_agent.py): `backend/app/agents/ticket_agent.py`
- [Waitlist agent](https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/waitlist_agent.py): `backend/app/agents/waitlist_agent.py`
- [Notification agent](https://github.com/wanabro227/eventsphere/blob/main/backend/app/agents/notification_agent.py): `backend/app/agents/notification_agent.py`
- [Agent message bus](https://github.com/wanabro227/eventsphere/blob/main/backend/app/messaging/message_bus.py): `backend/app/messaging/message_bus.py`
- [Structured messages](https://github.com/wanabro227/eventsphere/blob/main/backend/app/messaging/message.py): `backend/app/messaging/message.py`
- [Agent activity logs](https://github.com/wanabro227/eventsphere/blob/main/backend/app/routers/agent_logs.py): `backend/app/routers/agent_logs.py`

### Persistence

- [Database sessions](https://github.com/wanabro227/eventsphere/blob/main/backend/app/database.py): `backend/app/database.py`
- [Booking records](https://github.com/wanabro227/eventsphere/blob/main/backend/app/models/booking.py): `backend/app/models/booking.py`
- [Domain records](https://github.com/wanabro227/eventsphere/blob/main/backend/app/models/__init__.py): `backend/app/models/__init__.py`

### Other components

- **Attendee**
- **Staff member**
- **Relational database**

## Connections

- Attendee → EventSphere UI: uses
- Staff member → Ticket scanner: validates tickets
- EventSphere UI → API client: requests API
- Admin UI → API client: requests API
- Ticket scanner → API client: requests API
- API client → FastAPI application: sends HTTP
- FastAPI application → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Booking routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Ticket routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Event routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Venue routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Venue hire routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Waitlist routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Administration: registers (evidence: `backend/app/main.py`)
- FastAPI application → Notifications: registers (evidence: `backend/app/main.py`)
- FastAPI application → Agent activity logs: registers (evidence: `backend/app/main.py`)
- Authentication routes → Authentication service: calls (evidence: `backend/app/routers/auth.py`)
- Authentication routes → Password and JWT: creates token (evidence: `backend/app/routers/auth.py`)
- Authentication service → Password and JWT: hashes and checks (evidence: `backend/app/services/auth_service.py`)
- Booking routes → Identity and roles: requires user (evidence: `backend/app/routers/bookings.py`)
- Booking routes → Agent message bus: dispatches booking (evidence: `backend/app/routers/bookings.py`)
- Booking routes → Payment simulation: simulates payment (evidence: `backend/app/routers/bookings.py`)
- Booking routes → Agent message bus: requests ticket (evidence: `backend/app/routers/bookings.py`)
- Agent message bus → Booking agent: dispatches message (evidence: `backend/app/messaging/message_bus.py`)
- Agent message bus → Ticket agent: dispatches message (evidence: `backend/app/messaging/message_bus.py`)
- Agent message bus → Waitlist agent: dispatches message (evidence: `backend/app/messaging/message_bus.py`)
- FastAPI application → Agent message bus: registers agents (evidence: `backend/app/main.py`)
- Agent message bus → Agent activity logs: records exchanges (evidence: `backend/app/messaging/message_bus.py`)
- Waitlist routes → Agent message bus: dispatches request (evidence: `backend/app/routers/waitlist.py`)
- FastAPI application → Notification agent: registers agent
- Booking agent → Structured messages: handles messages (evidence: `backend/app/agents/booking_agent.py`)
- Waitlist agent → Structured messages: handles messages (evidence: `backend/app/agents/waitlist_agent.py`)
- Booking agent → Domain records: uses records (evidence: `backend/app/agents/booking_agent.py`)
- Waitlist agent → Domain records: uses records (evidence: `backend/app/agents/waitlist_agent.py`)
- Booking routes → Booking records: loads booking (evidence: `backend/app/routers/bookings.py`)
- Database sessions → Relational database: connects to (evidence: `backend/app/database.py`)
- Booking records → Database sessions: uses ORM base (evidence: `backend/app/models/booking.py`)
- Event routes → Domain records: queries records (evidence: `backend/app/routers/events.py`)
- Venue routes → Domain records: queries records (evidence: `backend/app/routers/venues.py`)
- Venue hire routes → Domain records: queries records (evidence: `backend/app/routers/venue_hire.py`)
- Ticket routes → Domain records: queries records (evidence: `backend/app/routers/tickets.py`)
- Administration → Domain records: manages records (evidence: `backend/app/routers/admin.py`)
- Notifications → Domain records: queries records (evidence: `backend/app/routers/notifications.py`)
- QR generation → Ticket agent: generates codes
- Notification agent → Notifications: supports notification flow
