# xuanmai1812/event_checkin_system architecture

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

- Interactive diagram: https://gitdiagram.com/xuanmai1812/event_checkin_system
- Repository: https://github.com/xuanmai1812/event_checkin_system

## Overview

This is a three-service event ticketing system: organizers create events, attendees register and receive signed QR tickets by email, and staff scan tickets for check-in. Registration publishes ticket-created events so email delivery does not block registration; the worker consumes them, while check-in independently verifies tickets and records admissions. The README documents the Redis Stream, per-service databases, and gateway behavior. Some internal integrations are represented from README statements because their implementation was not excerpted.

Main entry points: [`registration-service/app/routers/registrations.py`](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/routers/registrations.py) (Registration API), [`checkin-service/app/routers/checkin.py`](https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/routers/checkin.py) (Check-in API), [`notification-worker/app/consumer.py`](https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/consumer.py) (Stream Consumer), [`registration-service/app/routers/events.py`](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/routers/events.py) (Event API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_registration["Registration Service"]
  node_registration_api["Registration API<br/>[registrations.py]"]
  node_event_api["Event API<br/>[events.py]"]
  node_registration_crud["Registration Data Access<br/>[crud.py]"]
  node_ticket_security["Ticket Signing and QR<br/>[security.py]"]
  node_event_publisher["Ticket Event Publisher<br/>[events.py]"]
  node_registration_models["Registration Models<br/>[models.py]"]
  node_registration_db[("Registration Database<br/>[database.py]")]
end

subgraph group_checkin["Check-in Service"]
  node_checkin_api["Check-in API<br/>[checkin.py]"]
  node_ticket_verifier["Ticket Verification<br/>[security.py]"]
  node_checkin_crud["Check-in Data Access<br/>[crud.py]"]
  node_checkin_models["Check-in Records<br/>[models.py]"]
  node_checkin_db[("Check-in Database<br/>[database.py]")]
end

subgraph group_worker["Notification Worker"]
  node_stream_consumer["Stream Consumer<br/>[consumer.py]"]
  node_email_sender["Ticket Email Sender<br/>[notifier.py]"]
  node_notification_crud["Sent-Email Data Access<br/>[crud.py]"]
  node_notification_models["Notification Records<br/>[models.py]"]
  node_notification_db[("Worker Database<br/>[database.py]")]
end

subgraph group_messaging["Messaging and Storage"]
  node_redis_stream["Redis Stream"]
  node_mail_service["Email Service"]
end

node_attendees(("Attendees"))
node_gate_staff(("Gate Staff"))
node_nginx["Nginx Gateway"]

node_attendees -->|"submit requests"| node_nginx
node_nginx -->|"routes events"| node_event_api
node_nginx -->|"routes registration"| node_registration_api
node_gate_staff -->|"submit scans"| node_nginx
node_nginx -->|"routes check-in"| node_checkin_api
node_event_api -->|"calls"| node_registration_crud
node_registration_api -->|"checks and stores"| node_registration_crud
node_registration_api -->|"signs and renders"| node_ticket_security
node_registration_api -->|"publishes ticket"| node_event_publisher
node_registration_crud -->|"uses models"| node_registration_models
node_registration_models -->|"uses base"| node_registration_db
node_registration_api -->|"gets session"| node_registration_db
node_event_api -->|"gets session"| node_registration_db
node_event_publisher -->|"publishes event"| node_redis_stream
node_redis_stream -->|"delivers messages"| node_stream_consumer
node_stream_consumer -->|"sends ticket email"| node_email_sender
node_stream_consumer -->|"checks and records"| node_notification_crud
node_notification_crud -->|"uses models"| node_notification_models
node_notification_models -->|"uses base"| node_notification_db
node_stream_consumer -->|"creates tables and sessions"| node_notification_db
node_email_sender -->|"sends email"| node_mail_service
node_checkin_api -->|"verifies token"| node_ticket_verifier
node_checkin_api -->|"records admission"| node_checkin_crud
node_checkin_crud -->|"uses models"| node_checkin_models
node_checkin_models -->|"uses base"| node_checkin_db
node_checkin_api -->|"gets session"| node_checkin_db

click node_registration_api "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/routers/registrations.py"
click node_event_api "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/routers/events.py"
click node_registration_crud "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/crud.py"
click node_ticket_security "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/security.py"
click node_event_publisher "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/events.py"
click node_registration_models "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/models.py"
click node_registration_db "https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/database.py"
click node_checkin_api "https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/routers/checkin.py"
click node_ticket_verifier "https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/security.py"
click node_checkin_crud "https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/crud.py"
click node_checkin_models "https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/models.py"
click node_checkin_db "https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/database.py"
click node_stream_consumer "https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/consumer.py"
click node_email_sender "https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/notifier.py"
click node_notification_crud "https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/crud.py"
click node_notification_models "https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/models.py"
click node_notification_db "https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/database.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_registration_api,node_event_api,node_registration_crud,node_ticket_security,node_event_publisher,node_registration_models,node_registration_db toneBlue
class node_checkin_api,node_ticket_verifier,node_checkin_crud,node_checkin_models,node_checkin_db toneAmber
class node_stream_consumer,node_email_sender,node_notification_crud,node_notification_models,node_notification_db toneMint
class node_redis_stream,node_mail_service toneRose
class node_attendees,node_gate_staff,node_nginx toneIndigo
```

## Components

### Registration Service

- [Registration API](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/routers/registrations.py): `registration-service/app/routers/registrations.py`
- [Event API](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/routers/events.py): `registration-service/app/routers/events.py`
- [Registration Data Access](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/crud.py): `registration-service/app/crud.py`
- [Ticket Signing and QR](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/security.py): `registration-service/app/security.py`
- [Ticket Event Publisher](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/events.py): `registration-service/app/events.py`
- [Registration Models](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/models.py): `registration-service/app/models.py`
- [Registration Database](https://github.com/xuanmai1812/event_checkin_system/blob/main/registration-service/app/database.py): `registration-service/app/database.py`

### Check-in Service

- [Check-in API](https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/routers/checkin.py): `checkin-service/app/routers/checkin.py`
- [Ticket Verification](https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/security.py): `checkin-service/app/security.py`
- [Check-in Data Access](https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/crud.py): `checkin-service/app/crud.py`
- [Check-in Records](https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/models.py): `checkin-service/app/models.py`
- [Check-in Database](https://github.com/xuanmai1812/event_checkin_system/blob/main/checkin-service/app/database.py): `checkin-service/app/database.py`

### Notification Worker

- [Stream Consumer](https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/consumer.py): `notification-worker/app/consumer.py`
- [Ticket Email Sender](https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/notifier.py): `notification-worker/app/notifier.py`
- [Sent-Email Data Access](https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/crud.py): `notification-worker/app/crud.py`
- [Notification Records](https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/models.py): `notification-worker/app/models.py`
- [Worker Database](https://github.com/xuanmai1812/event_checkin_system/blob/main/notification-worker/app/database.py): `notification-worker/app/database.py`

### Messaging and Storage

- **Redis Stream**
- **Email Service**

### Other components

- **Attendees**
- **Gate Staff**
- **Nginx Gateway**

## Connections

- Attendees → Nginx Gateway: submit requests
- Nginx Gateway → Event API: routes events
- Nginx Gateway → Registration API: routes registration
- Gate Staff → Nginx Gateway: submit scans
- Nginx Gateway → Check-in API: routes check-in
- Event API → Registration Data Access: calls (evidence: `registration-service/app/routers/events.py`)
- Registration API → Registration Data Access: checks and stores (evidence: `registration-service/app/routers/registrations.py`)
- Registration API → Ticket Signing and QR: signs and renders (evidence: `registration-service/app/routers/registrations.py`)
- Registration API → Ticket Event Publisher: publishes ticket (evidence: `registration-service/app/routers/registrations.py`)
- Registration Data Access → Registration Models: uses models (evidence: `registration-service/app/crud.py`)
- Registration Models → Registration Database: uses base (evidence: `registration-service/app/models.py`)
- Registration API → Registration Database: gets session (evidence: `registration-service/app/routers/registrations.py`)
- Event API → Registration Database: gets session (evidence: `registration-service/app/routers/events.py`)
- Ticket Event Publisher → Redis Stream: publishes event
- Redis Stream → Stream Consumer: delivers messages
- Stream Consumer → Ticket Email Sender: sends ticket email (evidence: `notification-worker/app/consumer.py`)
- Stream Consumer → Sent-Email Data Access: checks and records (evidence: `notification-worker/app/consumer.py`)
- Sent-Email Data Access → Notification Records: uses models (evidence: `notification-worker/app/crud.py`)
- Notification Records → Worker Database: uses base (evidence: `notification-worker/app/models.py`)
- Stream Consumer → Worker Database: creates tables and sessions (evidence: `notification-worker/app/consumer.py`)
- Ticket Email Sender → Email Service: sends email
- Check-in API → Ticket Verification: verifies token (evidence: `checkin-service/app/routers/checkin.py`)
- Check-in API → Check-in Data Access: records admission (evidence: `checkin-service/app/routers/checkin.py`)
- Check-in Data Access → Check-in Records: uses models (evidence: `checkin-service/app/crud.py`)
- Check-in Records → Check-in Database: uses base (evidence: `checkin-service/app/models.py`)
- Check-in API → Check-in Database: gets session (evidence: `checkin-service/app/routers/checkin.py`)
