# pankajshindecodes-stack/cstep-django architecture

> Architecture diagram of the GitHub repository pankajshindecodes-stack/cstep-django, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pankajshindecodes-stack/cstep-django
- Repository: https://github.com/pankajshindecodes-stack/cstep-django

## Overview

#### Purpose and Runtime
CSTEP is a Django 5 / Django REST Framework backend for event management: identity and roles, event scheduling and livestream access, attendee registrations, and operational analytics. PostgreSQL is the system of record; Redis backs OTP cache storage. HTTP runs through Django WSGI/ASGI, while ASGI also exposes WebSocket routing. Core entry points are `cstep_backend/manage.py`, `cstep_backend/cstep_backend/urls.py`, `cstep_backend/cstep_backend/asgi.py`, and `cstep_backend/cstep_backend/settings.py`.

#### HTTP and Authorization Boundary
Project URL dispatch delegates API domains to app URL modules; views serialize requests/responses around Django models and enforce role-aware permissions. JWT access/refresh tokens authenticate protected endpoints, and account/event/registration permissions encode the BASE_USER → MODERATOR → EVENT_ADMIN → SUPER_ADMIN hierarchy.
Paths: `cstep_backend/cstep_backend/urls.py`, `cstep_backend/accounts/urls.py`, `cstep_backend/accounts/permissions.py`.

#### Accounts and Identity Lifecycle
The `accounts` app owns the custom user profile, role management, OTP-driven verification, login, and current-user APIs. Registration creates an identity and triggers verification; OTP values are stored through the cache boundary (Redis); verified users log in to receive SimpleJWT tokens. Admin-level users can inspect, change roles, and deactivate accounts.
Paths: `cstep_backend/accounts/models.py`, `cstep_backend/accounts/views.py`, `cstep_backend/accounts/serializers.py`.

#### Event and Broadcast Domain
The `events` app defines events, event days/schedule concepts, joins, feedback, and broadcast/viewer-session records. Event administrators create or modify event resources; authenticated users join events, recording attendance/session data and obtaining a stream link. Event signals, webhooks, media handling, and WebSocket consumers separate lifecycle integrations and real-time behavior from REST views.
Paths: `cstep_backend/events/models.py`, `cstep_backend/events/views.py`, `cstep_backend/events/consumers.py`.

#### Registration and Lobby Workflow
Registrations are a separate workflow layer linking users to events and capturing participation days, attendance choices, travel/translation assistance, and status. Users submit and retrieve their own registrations; moderators operate cross-event lists, lobby views, and acceptance/rejection decisions. This is the main approval boundary between self-service attendee input and staff operations.
Paths: `cstep_backend/registrations/models.py`, `cstep_backend/registrations/views.py`, `cstep_backend/registrations/permissions.py`.

#### Analytics and Background/Realtime Processing
Analytics aggregates user, participant, and event participation data for moderator-facing endpoints. Its service layer and Celery tasks indicate asynchronous computation/work, while consumers/routing provide live channels. Celery is configured at project scope; deployment must run compatible worker infrastructure when tasks are enabled.
Paths: `cstep_backend/analytics/views.py`, `cstep_backend/analytics/services.py`, `cstep_backend/analytics/tasks.py`, `cstep_backend/cstep_backend/celery.py`.

#### Streaming and Deployment Infrastructure
The repository packages Docker deployment and a MediaMTX service configuration for live streaming. MediaMTX is an external media-plane boundary: Django manages event/broadcast metadata and access while the streaming server handles media protocols. Docker Compose coordinates local services; `Dockerfile` packages the Django service. GitHub Actions provides Django CI.
Paths: `cstep_backend/docker-compose.yml`, `cstep_backend/docker/mediamtx/mediamtx.yml`, `cstep_backend/Dockerfile`, `.github/workflows/django.yml`.

Main entry points: [`cstep_backend/cstep_backend/urls.py`](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/urls.py) (Project URL dispatch), [`cstep_backend/accounts/views.py`](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/views.py) (Accounts API), [`cstep_backend/events/views.py`](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/views.py) (Events API), [`cstep_backend/registrations/models.py`](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/models.py) (Participation records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_django["Django runtime"]
  node_urls["Project URL dispatch<br/>Django routing<br/>[urls.py]"]
  node_runtime["WSGI / ASGI runtime<br/>Django entrypoint<br/>[asgi.py]"]
  node_settings["Project settings<br/>Django configuration<br/>[settings.py]"]
end

subgraph group_domains["Business domains"]
  node_accounts_api["Accounts API<br/>DRF views and serializers<br/>[views.py]"]
  node_account_auth{{"JWT and role permissions<br/>authorization boundary<br/>[permissions.py]"}}
  node_accounts_data[("Identity and roles<br/>account models<br/>[models.py]")]
  node_events_api["Events API<br/>DRF views<br/>[views.py]"]
  node_events_data[("Event and broadcast data<br/>event models<br/>[models.py]")]
  node_registration_api["Registration workflow<br/>DRF views<br/>[views.py]"]
  node_registration_auth{{"Registration permissions<br/>workflow authorization<br/>[permissions.py]"}}
  node_registration_data[("Participation records<br/>registration models<br/>[models.py]")]
end

subgraph group_processing["Async and realtime"]
  node_analytics_api["Analytics endpoints<br/>DRF views<br/>[views.py]"]
  node_analytics_service["Analytics aggregation<br/>service layer<br/>[services.py]"]
  node_analytics_tasks["Analytics tasks<br/>Celery tasks<br/>[tasks.py]"]
  node_celery["Celery worker setup<br/>task runtime<br/>[celery.py]"]
  node_websocket["Event WebSocket consumers<br/>ASGI consumers<br/>[consumers.py]"]
end

subgraph group_infra["Deployment services"]
  node_redis[("OTP cache<br/>Redis")]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_mediamtx["MediaMTX<br/>media-plane service<br/>[mediamtx.yml]"]
  node_compose["Docker Compose deployment<br/>service orchestration<br/>[docker-compose.yml]"]
end

node_runtime -->|"serves HTTP"| node_urls
node_runtime -->|"serves WebSockets"| node_websocket
node_settings -.->|"configures"| node_runtime
node_urls -->|"routes"| node_accounts_api
node_urls -->|"routes"| node_events_api
node_urls -->|"routes"| node_registration_api
node_urls -->|"routes"| node_analytics_api
node_accounts_api -->|"authorizes with JWT"| node_account_auth
node_accounts_api -->|"manages"| node_accounts_data
node_accounts_api -->|"stores OTPs"| node_redis
node_events_api -->|"requires roles"| node_account_auth
node_events_api -->|"manages"| node_events_data
node_registration_api -->|"enforces workflow"| node_registration_auth
node_registration_api -->|"creates and reviews"| node_registration_data
node_registration_data -->|"links user"| node_accounts_data
node_registration_data -->|"links event"| node_events_data
node_accounts_data -->|"persists"| node_postgres
node_events_data -->|"persists"| node_postgres
node_registration_data -->|"persists"| node_postgres
node_analytics_api -->|"queries"| node_analytics_service
node_analytics_service -->|"aggregates records"| node_postgres
node_analytics_tasks -->|"runs aggregation"| node_analytics_service
node_celery -->|"executes"| node_analytics_tasks
node_events_api -->|"manages stream access"| node_mediamtx
node_websocket -->|"uses event state"| node_events_data
node_compose -.->|"deploys Django"| node_runtime
node_compose -.->|"coordinates"| node_mediamtx

click node_urls "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/urls.py"
click node_runtime "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/asgi.py"
click node_settings "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/settings.py"
click node_accounts_api "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/views.py"
click node_account_auth "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/permissions.py"
click node_accounts_data "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/models.py"
click node_events_api "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/views.py"
click node_events_data "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/models.py"
click node_registration_api "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/views.py"
click node_registration_auth "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/permissions.py"
click node_registration_data "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/models.py"
click node_analytics_api "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/analytics/views.py"
click node_analytics_service "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/analytics/services.py"
click node_analytics_tasks "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/analytics/tasks.py"
click node_celery "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/celery.py"
click node_websocket "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/consumers.py"
click node_mediamtx "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/docker/mediamtx/mediamtx.yml"
click node_compose "https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/docker-compose.yml"

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_urls,node_runtime,node_settings toneBlue
class node_accounts_api,node_account_auth,node_accounts_data,node_events_api,node_events_data,node_registration_api,node_registration_auth,node_registration_data toneAmber
class node_analytics_api,node_analytics_service,node_analytics_tasks,node_celery,node_websocket toneMint
class node_redis,node_postgres,node_mediamtx,node_compose toneRose
```

## Components

### Django runtime

- [Project URL dispatch](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/urls.py): Django routing · Delegates API domains to app routes. · `cstep_backend/cstep_backend/urls.py`
- [WSGI / ASGI runtime](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/asgi.py): Django entrypoint · ASGI also serves WebSocket connections. · `cstep_backend/cstep_backend/asgi.py`
- [Project settings](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/settings.py): Django configuration · `cstep_backend/cstep_backend/settings.py`

### Business domains

- [Accounts API](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/views.py): DRF views and serializers · Registration, verification, login, profile, and account administration. · `cstep_backend/accounts/views.py`
- [JWT and role permissions](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/permissions.py): authorization boundary · Enforces the user-to-super-admin role hierarchy. · `cstep_backend/accounts/permissions.py`
- [Identity and roles](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/accounts/models.py): account models · Custom user profile and role state. · `cstep_backend/accounts/models.py`
- [Events API](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/views.py): DRF views · Manages events, joins, attendance, and stream access. · `cstep_backend/events/views.py`
- [Event and broadcast data](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/models.py): event models · Events, schedules, feedback, broadcasts, and viewer sessions. · `cstep_backend/events/models.py`
- [Registration workflow](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/views.py): DRF views · Self-service submissions and moderator lobby decisions. · `cstep_backend/registrations/views.py`
- [Registration permissions](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/permissions.py): workflow authorization · Separates own-registration access from staff operations. · `cstep_backend/registrations/permissions.py`
- [Participation records](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/registrations/models.py): registration models · Links users and events with attendance, assistance, and status. · `cstep_backend/registrations/models.py`

### Async and realtime

- [Analytics endpoints](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/analytics/views.py): DRF views · Moderator-facing participation reporting. · `cstep_backend/analytics/views.py`
- [Analytics aggregation](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/analytics/services.py): service layer · Aggregates user, participant, and event data. · `cstep_backend/analytics/services.py`
- [Analytics tasks](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/analytics/tasks.py): Celery tasks · Runs asynchronous analytics work. · `cstep_backend/analytics/tasks.py`
- [Celery worker setup](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/cstep_backend/celery.py): task runtime · `cstep_backend/cstep_backend/celery.py`
- [Event WebSocket consumers](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/events/consumers.py): ASGI consumers · Handles real-time event behavior. · `cstep_backend/events/consumers.py`

### Deployment services

- **OTP cache**: Redis · Stores verification OTP values.
- **PostgreSQL**: system of record
- [MediaMTX](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/docker/mediamtx/mediamtx.yml): media-plane service · Handles live-stream media protocols. · `cstep_backend/docker/mediamtx/mediamtx.yml`
- [Docker Compose deployment](https://github.com/pankajshindecodes-stack/cstep-django/blob/master/cstep_backend/docker-compose.yml): service orchestration · Coordinates local Django and media services. · `cstep_backend/docker-compose.yml`

## Connections

- WSGI / ASGI runtime → Project URL dispatch: serves HTTP
- WSGI / ASGI runtime → Event WebSocket consumers: serves WebSockets
- Project settings → WSGI / ASGI runtime: configures
- Project URL dispatch → Accounts API: routes
- Project URL dispatch → Events API: routes
- Project URL dispatch → Registration workflow: routes
- Project URL dispatch → Analytics endpoints: routes
- Accounts API → JWT and role permissions: authorizes with JWT
- Accounts API → Identity and roles: manages
- Accounts API → OTP cache: stores OTPs
- Events API → JWT and role permissions: requires roles
- Events API → Event and broadcast data: manages
- Registration workflow → Registration permissions: enforces workflow
- Registration workflow → Participation records: creates and reviews
- Participation records → Identity and roles: links user
- Participation records → Event and broadcast data: links event
- Identity and roles → PostgreSQL: persists
- Event and broadcast data → PostgreSQL: persists
- Participation records → PostgreSQL: persists
- Analytics endpoints → Analytics aggregation: queries
- Analytics aggregation → PostgreSQL: aggregates records
- Analytics tasks → Analytics aggregation: runs aggregation
- Celery worker setup → Analytics tasks: executes
- Events API → MediaMTX: manages stream access
- Event WebSocket consumers → Event and broadcast data: uses event state
- Docker Compose deployment → WSGI / ASGI runtime: deploys Django
- Docker Compose deployment → MediaMTX: coordinates