# cdanh11/event-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/cdanh11/event-management-system
- Repository: https://github.com/cdanh11/event-management-system

## Overview

Evently is an event-management web app for attendees, organizers, and assigned staff. Attendees discover events, register, and use QR tickets; organizers create and operate events, assign staff, and monitor occupancy; staff check tickets in. The React client uses REST with JWT/refresh-cookie authentication and WebSockets for occupancy. FastAPI routers implement the domain operations over SQLAlchemy models and PostgreSQL. The README documents lifecycle automation and post-commit notifications; sampled excerpts do not show every router’s internal calls, so those links are documented at the product boundary rather than inferred between handlers.

Main entry points: [`Backend/app/routers/events.py`](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/events.py) (Event management), [`Frontend/src/api/apiClient.ts`](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/api/apiClient.ts) (API client), [`Frontend/src/app/App.tsx`](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/app/App.tsx) (Role-based app), [`Backend/app/main.py`](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Role-based app<br/>[App.tsx]"]
  node_attendee["Attendee pages"]
  node_organizer["Organizer pages"]
  node_staff["Staff check-in<br/>[CheckinDesk.tsx]"]
  node_api["API client<br/>[apiClient.ts]"]
  node_occupancy["Live occupancy<br/>[useOccupancy.ts]"]
end

subgraph group_identity["Identity and access"]
  node_authui["Auth context<br/>[AuthContext.tsx]"]
  node_authroutes["Authentication<br/>[auth.py]"]
  node_security["Token security<br/>[security.py]"]
  node_access["Role access<br/>[access.py]"]
end

subgraph group_events["Event operations"]
  node_eventroutes["Event management<br/>[events.py]"]
  node_lifecycle["Event lifecycle<br/>[lifecycle.py]"]
end

subgraph group_attendance["Attendance and entry"]
  node_registrations["Registrations<br/>[registrations.py]"]
  node_tickets["Tickets<br/>[tickets.py]"]
  node_checkins["Check-ins<br/>[checkins.py]"]
  node_staffops["Staff assignments<br/>[staff.py]"]
  node_notifier["Notifications<br/>[notifier.py]"]
end

subgraph group_platform["API and persistence"]
  node_main["FastAPI application<br/>[main.py]"]
  node_realtimeapi["Occupancy socket API<br/>[realtime.py]"]
  node_realtime["Occupancy hub<br/>[realtime.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("PostgreSQL")]
  node_dbsession["DB sessions<br/>[db.py]"]
  node_schemas["Validation schemas<br/>[schemas.py]"]
  node_serializers["Response serializers<br/>[serializers.py]"]
  node_time["Event time handling<br/>[timeutils.py]"]
  node_cursors["Cursor pagination<br/>[cursors.py]"]
end

node_browser(("User"))

node_browser -->|"uses"| node_app
node_app -->|"routes to"| node_attendee
node_app -->|"routes to"| node_organizer
node_app -->|"routes to"| node_staff
node_app -->|"reads auth"| node_authui
node_attendee -->|"requests"| node_api
node_organizer -->|"requests"| node_api
node_staff -->|"requests"| node_api
node_authui -->|"calls"| node_api
node_api -->|"REST calls"| node_main
node_main -->|"mounts routes"| node_authroutes
node_main -->|"mounts routes"| node_eventroutes
node_main -.->|"mounts routes"| node_realtimeapi
node_authroutes -->|"issues tokens"| node_security
node_authroutes -->|"uses session"| node_dbsession
node_authroutes -->|"validates"| node_schemas
node_eventroutes -.->|"supports sign-up"| node_registrations
node_attendee -->|"registers"| node_registrations
node_attendee -->|"views tickets"| node_tickets
node_staff -->|"checks in"| node_checkins
node_organizer -->|"assigns staff"| node_staffops
node_organizer -->|"manages events"| node_eventroutes
node_eventroutes -->|"requests notices"| node_notifier
node_main -->|"starts sweep"| node_lifecycle
node_lifecycle -->|"publishes occupancy"| node_realtime
node_occupancy -->|"REST fallback"| node_api
node_occupancy -->|"WebSocket"| node_realtimeapi
node_realtimeapi -.->|"uses hub"| node_realtime
node_eventroutes -->|"queries"| node_dbsession
node_dbsession -->|"connects"| node_database
node_models -->|"maps records"| node_dbsession
node_eventroutes -->|"queries records"| node_models
node_eventroutes -->|"validates"| node_schemas
node_eventroutes -->|"serializes"| node_serializers
node_eventroutes -->|"paginates"| node_cursors
node_models -->|"uses time type"| node_time

click node_app "https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/app/App.tsx"
click node_attendee "https://github.com/cdanh11/event-management-system/tree/main/Frontend/src/pages/attendee"
click node_organizer "https://github.com/cdanh11/event-management-system/tree/main/Frontend/src/pages/organizer"
click node_staff "https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/pages/staff/CheckinDesk.tsx"
click node_api "https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/api/apiClient.ts"
click node_occupancy "https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/realtime/useOccupancy.ts"
click node_authui "https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/features/auth/AuthContext.tsx"
click node_authroutes "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/auth.py"
click node_security "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/security.py"
click node_access "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/access.py"
click node_eventroutes "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/events.py"
click node_lifecycle "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/services/lifecycle.py"
click node_registrations "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/registrations.py"
click node_tickets "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/tickets.py"
click node_checkins "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/checkins.py"
click node_staffops "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/staff.py"
click node_notifier "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/services/notifier.py"
click node_main "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/main.py"
click node_realtimeapi "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/realtime.py"
click node_realtime "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/realtime.py"
click node_models "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/models.py"
click node_dbsession "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/db.py"
click node_schemas "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/schemas.py"
click node_serializers "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/serializers.py"
click node_time "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/timeutils.py"
click node_cursors "https://github.com/cdanh11/event-management-system/blob/main/Backend/app/cursors.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_attendee,node_organizer,node_staff,node_api,node_occupancy,node_browser toneBlue
class node_authui,node_authroutes,node_security,node_access toneAmber
class node_eventroutes,node_lifecycle toneMint
class node_registrations,node_tickets,node_checkins,node_staffops,node_notifier toneRose
class node_main,node_realtimeapi,node_realtime,node_models,node_database,node_dbsession,node_schemas,node_serializers,node_time,node_cursors toneIndigo
```

## Components

### Web client

- [Role-based app](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/app/App.tsx): `Frontend/src/app/App.tsx`
- [Attendee pages](https://github.com/cdanh11/event-management-system/tree/main/Frontend/src/pages/attendee): `Frontend/src/pages/attendee`
- [Organizer pages](https://github.com/cdanh11/event-management-system/tree/main/Frontend/src/pages/organizer): `Frontend/src/pages/organizer`
- [Staff check-in](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/pages/staff/CheckinDesk.tsx): `Frontend/src/pages/staff/CheckinDesk.tsx`
- [API client](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/api/apiClient.ts): `Frontend/src/api/apiClient.ts`
- [Live occupancy](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/realtime/useOccupancy.ts): `Frontend/src/realtime/useOccupancy.ts`

### Identity and access

- [Auth context](https://github.com/cdanh11/event-management-system/blob/main/Frontend/src/features/auth/AuthContext.tsx): `Frontend/src/features/auth/AuthContext.tsx`
- [Authentication](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/auth.py): `Backend/app/routers/auth.py`
- [Token security](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/security.py): `Backend/app/security.py`
- [Role access](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/access.py): `Backend/app/access.py`

### Event operations

- [Event management](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/events.py): `Backend/app/routers/events.py`
- [Event lifecycle](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/services/lifecycle.py): `Backend/app/services/lifecycle.py`

### Attendance and entry

- [Registrations](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/registrations.py): `Backend/app/routers/registrations.py`
- [Tickets](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/tickets.py): `Backend/app/routers/tickets.py`
- [Check-ins](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/checkins.py): `Backend/app/routers/checkins.py`
- [Staff assignments](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/staff.py): `Backend/app/routers/staff.py`
- [Notifications](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/services/notifier.py): `Backend/app/services/notifier.py`

### API and persistence

- [FastAPI application](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/main.py): `Backend/app/main.py`
- [Occupancy socket API](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/routers/realtime.py): `Backend/app/routers/realtime.py`
- [Occupancy hub](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/realtime.py): `Backend/app/realtime.py`
- [Domain records](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/models.py): `Backend/app/models.py`
- **PostgreSQL**
- [DB sessions](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/db.py): `Backend/app/db.py`
- [Validation schemas](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/schemas.py): `Backend/app/schemas.py`
- [Response serializers](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/serializers.py): `Backend/app/serializers.py`
- [Event time handling](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/timeutils.py): `Backend/app/timeutils.py`
- [Cursor pagination](https://github.com/cdanh11/event-management-system/blob/main/Backend/app/cursors.py): `Backend/app/cursors.py`

### Other components

- **User**

## Connections

- User → Role-based app: uses
- Role-based app → Attendee pages: routes to (evidence: `Frontend/src/app/App.tsx`)
- Role-based app → Organizer pages: routes to (evidence: `Frontend/src/app/App.tsx`)
- Role-based app → Staff check-in: routes to (evidence: `Frontend/src/app/App.tsx`)
- Role-based app → Auth context: reads auth (evidence: `Frontend/src/app/App.tsx`)
- Attendee pages → API client: requests
- Organizer pages → API client: requests
- Staff check-in → API client: requests
- Auth context → API client: calls (evidence: `Frontend/src/features/auth/AuthContext.tsx`)
- API client → FastAPI application: REST calls
- FastAPI application → Authentication: mounts routes (evidence: `Backend/app/main.py`)
- FastAPI application → Event management: mounts routes (evidence: `Backend/app/main.py`)
- FastAPI application → Occupancy socket API: mounts routes
- Authentication → Token security: issues tokens (evidence: `Backend/app/routers/auth.py`)
- Authentication → DB sessions: uses session (evidence: `Backend/app/routers/auth.py`)
- Authentication → Validation schemas: validates (evidence: `Backend/app/routers/auth.py`)
- Event management → Registrations: supports sign-up
- Attendee pages → Registrations: registers
- Attendee pages → Tickets: views tickets
- Staff check-in → Check-ins: checks in
- Organizer pages → Staff assignments: assigns staff
- Organizer pages → Event management: manages events
- Event management → Notifications: requests notices (evidence: `Backend/app/routers/events.py`)
- FastAPI application → Event lifecycle: starts sweep (evidence: `Backend/app/main.py`)
- Event lifecycle → Occupancy hub: publishes occupancy (evidence: `Backend/app/services/lifecycle.py`)
- Live occupancy → API client: REST fallback (evidence: `Frontend/src/realtime/useOccupancy.ts`)
- Live occupancy → Occupancy socket API: WebSocket
- Occupancy socket API → Occupancy hub: uses hub
- Event management → DB sessions: queries (evidence: `Backend/app/routers/events.py`)
- DB sessions → PostgreSQL: connects (evidence: `Backend/app/db.py`)
- Domain records → DB sessions: maps records (evidence: `Backend/app/models.py`)
- Event management → Domain records: queries records (evidence: `Backend/app/routers/events.py`)
- Event management → Validation schemas: validates (evidence: `Backend/app/routers/events.py`)
- Event management → Response serializers: serializes (evidence: `Backend/app/routers/events.py`)
- Event management → Cursor pagination: paginates (evidence: `Backend/app/routers/events.py`)
- Domain records → Event time handling: uses time type (evidence: `Backend/app/models.py`)