# dev-yvonne/events-system architecture

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

- Interactive diagram: https://gitdiagram.com/dev-yvonne/events-system
- Repository: https://github.com/dev-yvonne/events-system

## Overview

1. **Overall shape**
   - EventHub is a **Django monolith** with a multi-portal architecture: **attendee**, **organizer**, **custom admin portal**, and the standard **Django admin**.
   - Core behavior is server-rendered through Django templates, with portal-specific JavaScript used for dynamic interactions and API calls.

2. **Routing and portal boundaries**
   - `config/urls.py` delegates into separate URL sets for attendee, organizer, admin, and API surfaces.
   - This is an important architectural boundary: each portal has its own templates, static assets, and page flows, while sharing the same backend models and auth system.

3. **Core domain modules**
   - `events/` is the central marketplace module: event creation, discovery, SEO pages, organizer APIs, checkout-related event logic, and seed data.
   - `bookings/` handles booking records, ticket lifecycle, and booking-related email workflows.
   - `payments/` manages payment orders, M-Pesa integration, verification, screenshots, and notification side effects.
   - `reviews/` covers event reviews and customer stories.
   - `subscriptions/` contains organizer plan logic and subscription services.
   - `notifications/` stores notification state and exposes notification views.

4. **Identity and account subsystem**
   - `accounts/` is the authentication and user-management boundary.
   - It includes user profiles, Google auth, organizer verification, API tokens/keys, team-member relationships, presence tracking, and revenue metrics.
   - The account model appears to support multiple roles and organization-oriented organizer accounts, which feeds the portal separation.

5. **Data model and persistence**
   - The project uses **Django ORM** with extensive migrations in each app, indicating a relational schema as the main system of record.
   - `config/settings.py` plus `DATABASE_URL` in the README imply SQLite for development and PostgreSQL in production.
   - `database_schema.dot` suggests the schema has been documented explicitly, which is useful for domain/data diagramming.

6. **Payment and ticketing flow**
   - The primary business flow is: attendee selects an event/tickets, creates a booking/order, initiates payment, and receives a confirmed booking/ticket after verification.
   - `payments/mpesa.py`, `payments/screenshot_verifier.py`, and `payments/screenshot_storage.py` show that M-Pesa is a first-class payment rail, with manual/assisted verification support.
   - `bookings/email_service.py` indicates booking confirmation and transactional email are part of the fulfillment path.

7. **Organizer operations**
   - Organizers manage events, tickets, bookings, attendees, promotions, reviews, support, and scanner/check-in flows from `frontend/templates/organizer/` and `frontend/static/js/organizer/`.
   - `events/api_organizer_views.py`, `admin_views.py`, and organizer-specific JS suggest an operational console rather than a consumer-facing marketplace.
   - Subscription state and billing views are part of this portal, tying organizer access to plan status.

8. **Custom platform administration**
   - The repo has a dedicated admin portal under `admin_views.py` and `frontend/templates/admin/`, separate from Django’s built-in admin.
   - This portal focuses on moderation and operations: users, organizers, events approvals, payments, bookings, tickets, reports, notifications, support, and settings.
   - That separation matters architecturally because it reflects a business-ops layer above the domain apps.

9. **Frontend structure**
   - The frontend is **template-first**, not an SPA: shared base templates plus portal-specific templates in `frontend/templates/{attendee,organizer,admin,shared}`.
   - Static assets are similarly partitioned by portal in `frontend/static/css` and `frontend/static/js`, with shared helpers in `frontend/static/js/shared/`.
   - This suggests a multi-page app enhanced with modular JavaScript services, fetch wrappers, and client-side UI state for carts, wishlist, auth, and dashboards.

10. **Discovery, SEO, and public content**
   - `events/seo_views.py`, `events/discovery.py`, and `frontend/templates/attendee/pages/*` show a strong public-discovery layer.
   - The README mentions `/robots.txt`, `/sitemap.xml`, and meta descriptions, so SEO is part of the public architecture rather than an afterthought.
   - The homepage is content-heavy and likely uses prefetching/curated sections such as featured events, stats, testimonials, and newsletter blocks.

11. **Cross-cutting services**
   - `accounts/presence.py` and `frontend/static/js/shared/presence.js` indicate live user/organizer presence features.
   - `payments/notification_utils.py` and `payments/organizer_notifications.py` show internal notification fan-out from payment events.
   - `frontend/static/js/shared/*` includes reusable browser services for auth, cart storage, wishlist storage, event API calls, and portal notifications.

12. **Authentication and role handling**
   - Auth is spread across `accounts/auth.py`, `accounts/auth_views.py`, and `accounts/google_auth.py`, with shared login/register templates in `frontend/templates/shared/auth/`.
   - The app supports role-specific experiences and likely role-based authorization checks across attendee, organizer, and admin surfaces.
   - API key and team-member models imply some endpoints or operational tools are secured beyond simple session auth.

13. **Operational and deployment shape**
   - `Procfile`, `render.yaml`, and `vercel.json` indicate deployment is configured for hosted environments, with the backend likely running as a Django app and static assets served separately or as part of deployment packaging.
   - `backend/staticfiles/` suggests collected/static build output is tracked for deployment.
   - `config/requirements.txt` and top-level `requirements.txt` reinforce a Python runtime centered deployment.

14. **How the pieces connect**
   - Browser requests enter Django through portal-specific URLs.
   - Views read/write relational data through app models and migrations.
   - Payment/order actions trigger M-Pesa integration and verification workflows.
   - Successful bookings drive emails, notifications, and ticket state changes.
   - The frontend layers consume backend-rendered pages plus JSON endpoints for dashboard and management interactions.

Main entry points: [`events/models.py`](https://github.com/dev-yvonne/events-system/blob/main/events/models.py) (Events), [`config/urls.py`](https://github.com/dev-yvonne/events-system/blob/main/config/urls.py) (Root URLs), [`payments/models.py`](https://github.com/dev-yvonne/events-system/blob/main/payments/models.py) (Payments), [`accounts/models.py`](https://github.com/dev-yvonne/events-system/blob/main/accounts/models.py) (Accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing"]
  node_config_urls["Root URLs<br/>django routing<br/>[urls.py]"]
  node_config_attendee_urls["Attendee URLs<br/>portal routing<br/>[attendee_urls.py]"]
  node_config_organizer_urls["Organizer URLs<br/>portal routing<br/>[organizer_urls.py]"]
  node_config_admin_urls["Admin URLs<br/>portal routing<br/>[admin_urls.py]"]
  node_config_api_urls["API URLs<br/>api routing<br/>[api_urls.py]"]
end

subgraph group_domain["Domain"]
  node_accounts[("Accounts<br/>identity<br/>[models.py]")]
  node_events[("Events<br/>marketplace<br/>[models.py]")]
  node_bookings[("Bookings<br/>fulfillment<br/>[models.py]")]
  node_payments[("Payments<br/>checkout<br/>[models.py]")]
  node_reviews[("Reviews<br/>trust content<br/>[models.py]")]
  node_subscriptions[("Subscriptions<br/>billing<br/>[models.py]")]
  node_notifications[("Notifications<br/>alerts<br/>[models.py]")]
  node_payments_mpesa["M-Pesa<br/>payment integration<br/>[mpesa.py]"]
  node_payments_verifier["Verifier<br/>payment verification"]
  node_bookings_email["Booking Email<br/>fulfillment service<br/>[email_service.py]"]
  node_events_seo["SEO Views<br/>public discovery<br/>[seo_views.py]"]
  node_events_checkout["Checkout<br/>purchase flow<br/>[checkout.py]"]
  node_events_organizer_api["Organizer API<br/>ops api"]
end

subgraph group_frontend["Frontend"]
  node_attendee_base["Attendee Shell<br/>server-rendered portal<br/>[base.html]"]
  node_organizer_base["Organizer Shell<br/>server-rendered portal<br/>[base.html]"]
  node_admin_base["Admin Shell<br/>operations portal<br/>[base_admin.html]"]
  node_shared_auth["Auth Pages<br/>shared templates<br/>[login.html]"]
  node_shared_event_api["Event API<br/>browser service"]
  node_shared_presence["Presence<br/>browser service<br/>[presence.js]"]
end

subgraph group_infra["Infra"]
  node_config_settings["Settings<br/>django config<br/>[settings.py]"]
end

node_config_urls -->|"routes to"| node_config_attendee_urls
node_config_urls -->|"routes to"| node_config_organizer_urls
node_config_urls -->|"routes to"| node_config_admin_urls
node_config_urls -->|"routes to"| node_config_api_urls
node_config_urls -->|"uses"| node_config_settings
node_config_attendee_urls -->|"renders"| node_attendee_base
node_config_organizer_urls -->|"renders"| node_organizer_base
node_config_admin_urls -->|"renders"| node_admin_base
node_shared_auth -->|"authenticates"| node_accounts
node_events -->|"depends on"| node_accounts
node_bookings -->|"references"| node_events
node_bookings -->|"belongs to"| node_accounts
node_payments -->|"settles"| node_bookings
node_payments -->|"prices"| node_events
node_payments -->|"integrates"| node_payments_mpesa
node_payments -->|"verifies"| node_payments_verifier
node_payments -->|"fan-out"| node_notifications
node_bookings -->|"sends"| node_bookings_email
node_events -->|"publishes"| node_events_seo
node_events -->|"orchestrates"| node_events_checkout
node_events -->|"exposes"| node_events_organizer_api
node_events -->|"shows"| node_reviews
node_subscriptions -->|"governs"| node_accounts
node_shared_event_api -->|"calls"| node_events
node_shared_presence -->|"tracks"| node_accounts

click node_config_urls "https://github.com/dev-yvonne/events-system/blob/main/config/urls.py"
click node_config_attendee_urls "https://github.com/dev-yvonne/events-system/blob/main/config/attendee_urls.py"
click node_config_organizer_urls "https://github.com/dev-yvonne/events-system/blob/main/config/organizer_urls.py"
click node_config_admin_urls "https://github.com/dev-yvonne/events-system/blob/main/config/admin_urls.py"
click node_config_api_urls "https://github.com/dev-yvonne/events-system/blob/main/config/api_urls.py"
click node_config_settings "https://github.com/dev-yvonne/events-system/blob/main/config/settings.py"
click node_accounts "https://github.com/dev-yvonne/events-system/blob/main/accounts/models.py"
click node_events "https://github.com/dev-yvonne/events-system/blob/main/events/models.py"
click node_bookings "https://github.com/dev-yvonne/events-system/blob/main/bookings/models.py"
click node_payments "https://github.com/dev-yvonne/events-system/blob/main/payments/models.py"
click node_reviews "https://github.com/dev-yvonne/events-system/blob/main/reviews/models.py"
click node_subscriptions "https://github.com/dev-yvonne/events-system/blob/main/subscriptions/models.py"
click node_notifications "https://github.com/dev-yvonne/events-system/blob/main/notifications/models.py"
click node_attendee_base "https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/attendee/base.html"
click node_organizer_base "https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/organizer/base.html"
click node_admin_base "https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/admin/base_admin.html"
click node_shared_auth "https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/shared/auth/login.html"
click node_shared_event_api "https://github.com/dev-yvonne/events-system/blob/main/frontend/static/js/shared/event-api.service.js"
click node_shared_presence "https://github.com/dev-yvonne/events-system/blob/main/frontend/static/js/shared/presence.js"
click node_payments_mpesa "https://github.com/dev-yvonne/events-system/blob/main/payments/mpesa.py"
click node_payments_verifier "https://github.com/dev-yvonne/events-system/blob/main/payments/screenshot_verifier.py"
click node_bookings_email "https://github.com/dev-yvonne/events-system/blob/main/bookings/email_service.py"
click node_events_seo "https://github.com/dev-yvonne/events-system/blob/main/events/seo_views.py"
click node_events_checkout "https://github.com/dev-yvonne/events-system/blob/main/events/checkout.py"
click node_events_organizer_api "https://github.com/dev-yvonne/events-system/blob/main/events/api_organizer_views.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_config_urls,node_config_attendee_urls,node_config_organizer_urls,node_config_admin_urls,node_config_api_urls toneBlue
class node_accounts,node_events,node_bookings,node_payments,node_reviews,node_subscriptions,node_notifications,node_payments_mpesa,node_payments_verifier,node_bookings_email,node_events_seo,node_events_checkout,node_events_organizer_api toneAmber
class node_attendee_base,node_organizer_base,node_admin_base,node_shared_auth,node_shared_event_api,node_shared_presence toneMint
class node_config_settings toneRose
```

## Components

### Routing

URL dispatch and portal boundaries

- [Root URLs](https://github.com/dev-yvonne/events-system/blob/main/config/urls.py): django routing · Main URL dispatcher that delegates into portal and API surfaces · `config/urls.py`
- [Attendee URLs](https://github.com/dev-yvonne/events-system/blob/main/config/attendee_urls.py): portal routing · Public attendee-facing routes · `config/attendee_urls.py`
- [Organizer URLs](https://github.com/dev-yvonne/events-system/blob/main/config/organizer_urls.py): portal routing · Organizer console routes · `config/organizer_urls.py`
- [Admin URLs](https://github.com/dev-yvonne/events-system/blob/main/config/admin_urls.py): portal routing · Custom operations portal routes · `config/admin_urls.py`
- [API URLs](https://github.com/dev-yvonne/events-system/blob/main/config/api_urls.py): api routing · Shared API surface used by portal JavaScript and backend clients · `config/api_urls.py`

### Domain

Core business apps and relational state

- [Accounts](https://github.com/dev-yvonne/events-system/blob/main/accounts/models.py): identity · Authentication, profiles, roles, organizer verification, and team relationships · `accounts/models.py`
- [Events](https://github.com/dev-yvonne/events-system/blob/main/events/models.py): marketplace · Event discovery, SEO pages, organizer event management, and core event data · `events/models.py`
- [Bookings](https://github.com/dev-yvonne/events-system/blob/main/bookings/models.py): fulfillment · Booking records, ticket lifecycle, and confirmation workflows · `bookings/models.py`
- [Payments](https://github.com/dev-yvonne/events-system/blob/main/payments/models.py): checkout · Payment orders, M-Pesa rails, screenshot verification, and side effects · `payments/models.py`
- [Reviews](https://github.com/dev-yvonne/events-system/blob/main/reviews/models.py): trust content · Event reviews and customer stories · `reviews/models.py`
- [Subscriptions](https://github.com/dev-yvonne/events-system/blob/main/subscriptions/models.py): billing · Organizer plans and subscription services · `subscriptions/models.py`
- [Notifications](https://github.com/dev-yvonne/events-system/blob/main/notifications/models.py): alerts · Notification state and user-facing notification views · `notifications/models.py`
- [M-Pesa](https://github.com/dev-yvonne/events-system/blob/main/payments/mpesa.py): payment integration · M-Pesa checkout and payment rail integration · `payments/mpesa.py`
- [Verifier](https://github.com/dev-yvonne/events-system/blob/main/payments/screenshot_verifier.py): payment verification · Screenshot and assisted payment verification workflow · `payments/screenshot_verifier.py`
- [Booking Email](https://github.com/dev-yvonne/events-system/blob/main/bookings/email_service.py): fulfillment service · Transactional booking confirmation email workflow · `bookings/email_service.py`
- [SEO Views](https://github.com/dev-yvonne/events-system/blob/main/events/seo_views.py): public discovery · Discovery and SEO-oriented public event pages · `events/seo_views.py`
- [Checkout](https://github.com/dev-yvonne/events-system/blob/main/events/checkout.py): purchase flow · Event checkout orchestration and ticket selection flow · `events/checkout.py`
- [Organizer API](https://github.com/dev-yvonne/events-system/blob/main/events/api_organizer_views.py): ops api · Organizer-facing event management endpoints · `events/api_organizer_views.py`

### Frontend

Template-first portals and shared browser services

- [Attendee Shell](https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/attendee/base.html): server-rendered portal · Shared attendee layout and page composition · `frontend/templates/attendee/base.html`
- [Organizer Shell](https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/organizer/base.html): server-rendered portal · Shared organizer layout and dashboard composition · `frontend/templates/organizer/base.html`
- [Admin Shell](https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/admin/base_admin.html): operations portal · Custom admin portal layout · `frontend/templates/admin/base_admin.html`
- [Auth Pages](https://github.com/dev-yvonne/events-system/blob/main/frontend/templates/shared/auth/login.html): shared templates · Login, register, reset, and verification screens shared across portals · `frontend/templates/shared/auth/login.html`
- [Event API](https://github.com/dev-yvonne/events-system/blob/main/frontend/static/js/shared/event-api.service.js): browser service · Shared client-side event API wrapper used across portals · `frontend/static/js/shared/event-api.service.js`
- [Presence](https://github.com/dev-yvonne/events-system/blob/main/frontend/static/js/shared/presence.js): browser service · Shared live presence tracking in browser and backend · `frontend/static/js/shared/presence.js`

### Infra

Settings, deployment, and runtime configuration

- [Settings](https://github.com/dev-yvonne/events-system/blob/main/config/settings.py): django config · Environment, database, apps, and deployment settings · `config/settings.py`

## Connections

- Root URLs → Attendee URLs: routes to · Dispatches public attendee requests
- Root URLs → Organizer URLs: routes to · Dispatches organizer console requests
- Root URLs → Admin URLs: routes to · Dispatches custom admin requests
- Root URLs → API URLs: routes to · Dispatches API requests
- Root URLs → Settings: uses · Loads project configuration and environment settings
- Attendee URLs → Attendee Shell: renders · Attendee pages share a common shell
- Organizer URLs → Organizer Shell: renders · Organizer pages share a common shell
- Admin URLs → Admin Shell: renders · Admin pages share a common shell
- Auth Pages → Accounts: authenticates · Shared login and registration flows feed the identity subsystem
- Events → Accounts: depends on · Events are owned and managed by organizer accounts
- Bookings → Events: references · Bookings are created from selected events and tickets
- Bookings → Accounts: belongs to · Bookings are associated with attendee identities
- Payments → Bookings: settles · Payment completion drives booking confirmation
- Payments → Events: prices · Payment orders are based on event ticket pricing
- Payments → M-Pesa: integrates · Primary payment rail
- Payments → Verifier: verifies · Assisted/manual verification path for screenshots and proof
- Payments → Notifications: fan-out · Payment events trigger notifications
- Bookings → Booking Email: sends · Booking confirmation and fulfillment emails
- Events → SEO Views: publishes · Public discovery and SEO pages
- Events → Checkout: orchestrates · Checkout flow starts from event pages and ticket selection
- Events → Organizer API: exposes · Organizer dashboard operations for event management
- Events → Reviews: shows · Reviews and customer stories enrich event pages
- Subscriptions → Accounts: governs · Organizer plan state ties into account capabilities
- Event API → Events: calls · Shared browser service talks to event endpoints
- Presence → Accounts: tracks · Presence features are anchored in user and organizer identities