# gtech-mulearn/mulearnbackend architecture

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

- Interactive diagram: https://gitdiagram.com/gtech-mulearn/mulearnbackend
- Repository: https://github.com/gtech-mulearn/mulearnbackend

## Overview

This repository is a Django backend for µLearn, organized as a monolith with many domain apps rather than a set of separate services. The main runtime entrypoint is `manage.py`, with project configuration in `mulearnbackend/` and app code primarily under `api/` plus shared persistence models under `db/`.

The request-handling layer is Django URL routing plus DRF-style view/serializer pairs. `api/urls.py` aggregates feature routers, and each domain area exposes its own `urls.py`, `views.py`, and serializer modules. The architecture is heavily modularized by feature: auth, register, common utilities, dashboard subdomains, integrations, notification, leaderboard, launchpad, donate, hackathon, top100 coders, and URL shortener.

A major boundary is the dashboard subsystem under `api/dashboard/`. It is split into many management domains such as campus, events, users, roles, skills, tasks, projects, organizations, affiliations, coupons, referrals, districts, zonal, colleges, companies/jobs, learning circles, IG, Discord moderation, error logging, achievement, and dynamic management. Many of these have separate “admin/manage/public/scoped/meta” view variants, indicating different permissioned surfaces over the same underlying data.

The data model layer is centralized in `db/`, not embedded inside each feature app. This folder contains the core entities such as users, organizations, campuses, events, projects, tasks, skills, donations, hackathons, notifications, launchpad, integrations, and URL shortener records. `db/managers/user_manager.py` suggests custom user lifecycle behavior, and `db/settings.py` likely holds DB-specific configuration.

There is a clear real-time / websocket boundary. `api/routing.py`, `mulearnbackend/routing.py`, `api/common/common_consumer.py`, and `api/dashboard/lc/dash_lc_consumers.py` indicate Django Channels support. The learning-circle and common subsystems appear to be the primary websocket consumers, likely used for live updates or collaborative dashboard interactions.

Asynchronous/background processing is handled with Celery. The project includes `mulearnbackend/celery.py` plus task modules under `mu_celery/`, including achievement cron/task code. There is also a management command for generating achievements, so award/achievement computation can run both on-demand and scheduled.

External integrations are isolated under `api/integrations/`, with submodules for KKEM, Qseverse, and Wadhwani. These modules each have dedicated views, serializers, helpers, and URLs, so integration concerns are kept separate from the core dashboard logic. The presence of integration-specific templates in `api/templates/mails/KKEM/` shows that some integrations also trigger email workflows.

Messaging and notifications are another cross-cutting subsystem. `api/notification/` handles notification views, serializers, and utilities, while `api/templates/mails/` contains many transactional email templates for registration, password reset, referrals, donation confirmation, launchpad verification/reset, learning-circle invitations, mentor verification, and integration notifications.

Several subsystems generate downloadable or branded artifacts. `excel-templates/` contains spreadsheet templates for organizations, roles, tasks, and vouchers, and `api/dashboard/karma_voucher/assets` plus `fonts` indicate PDF/image generation or branded voucher output. This suggests some endpoints are not just CRUD APIs but document-producing workflows.

Shared concerns are factored into `utils/`. This includes permission helpers, response formatting, exception handling, OpenAPI/spectacular helpers, domain-specific karma and launchpad permission logic, and common type/util functions. These utilities act as the cross-cutting glue between the many feature apps and the shared model layer.

The repository also includes schema and migration-adjacent tooling. `schema.sql`, `alter-scripts/`, and the README’s note about applying a migration script indicate nontrivial database evolution and version-specific schema adjustments. That implies the backend has been maintained across multiple schema generations and possibly multiple deployment environments.

Operationally, the project is containerized and CI/CD-driven. `Dockerfile`, `docker-compose.yml`, `docker-compose.pod.yml`, and `entrypoint.sh` define the runtime packaging, while GitHub Actions workflows handle dev/prod deployment and pod rollouts. Environment configuration is externalized via `.env.sample`.

Overall, the architecture is a Django/DRF monolith with three strong boundaries: synchronous HTTP APIs by domain, asynchronous background/job processing, and real-time websocket channels. The shared `db/` models and `utils/` package provide the common substrate that all feature apps build on.

Main entry points: [`api/urls.py`](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/urls.py) (API router), [`api/dashboard/urls.py`](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/urls.py) (Dashboard router), [`db/user.py`](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/db/user.py) (DB models), [`mulearnbackend/settings.py`](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mulearnbackend/settings.py) (Project core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_manage_py["manage.py<br/>django entrypoint<br/>[manage.py]"]
  node_project_core["Project core<br/>django project<br/>[settings.py]"]
end

subgraph group_api_layer["HTTP API"]
  node_api_urls["API router<br/>url aggregator<br/>[urls.py]"]
  node_auth_register["Auth & signup<br/>feature area<br/>[auth_views.py]"]
  node_common_api["Common API<br/>shared feature<br/>[common_views.py]"]
  node_core_features["Core features<br/>feature bundle<br/>[views.py]"]
  node_integrations_api["Integrations<br/>integration surface<br/>[urls.py]"]
  node_notification_api["Notifications<br/>cross-cutting API"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_root["Dashboard router<br/>[urls.py]"]
  node_dash_events["Events<br/>dashboard domain<br/>[admin_views.py]"]
  node_dash_people["Users & roles<br/>dashboard domain<br/>[dash_user_views.py]"]
  node_dash_org["Org & campus<br/>dashboard domain"]
  node_dash_work["Workflows<br/>dashboard domain<br/>[projects_view.py]"]
  node_dash_social["Community<br/>dashboard domain<br/>[dash_lc_view.py]"]
  node_dash_ops["Ops tools<br/>dashboard domain"]
end

subgraph group_data["Data Model"]
  node_db_models[("DB models<br/>persistence models<br/>[user.py]")]
  node_user_manager["User manager<br/>custom manager<br/>[user_manager.py]"]
end

subgraph group_async_rt["Async & Realtime"]
  node_celery_stack["Celery<br/>async runtime<br/>[task.py]"]
  node_channels_stack["Channels<br/>ws runtime<br/>[routing.py]"]
end

subgraph group_shared["Shared Utils"]
  node_shared_utils["Shared utils<br/>helpers<br/>[response.py]"]
end

node_manage_py -->|"boots"| node_project_core
node_project_core -->|"routes HTTP"| node_api_urls
node_project_core -->|"routes ws"| node_channels_stack
node_project_core -->|"configures jobs"| node_celery_stack
node_api_urls -->|"includes"| node_auth_register
node_api_urls -->|"includes"| node_common_api
node_api_urls -->|"includes"| node_core_features
node_api_urls -->|"includes"| node_integrations_api
node_api_urls -->|"includes"| node_notification_api
node_api_urls -->|"includes"| node_dashboard_root
node_dashboard_root -->|"dispatches"| node_dash_events
node_dashboard_root -->|"dispatches"| node_dash_people
node_dashboard_root -->|"dispatches"| node_dash_org
node_dashboard_root -->|"dispatches"| node_dash_work
node_dashboard_root -->|"dispatches"| node_dash_social
node_dashboard_root -->|"dispatches"| node_dash_ops
node_dash_people -->|"reads/writes"| node_db_models
node_dash_org -->|"reads/writes"| node_db_models
node_dash_work -->|"reads/writes"| node_db_models
node_dash_social -->|"reads/writes"| node_db_models
node_common_api -->|"uses"| node_shared_utils
node_core_features -->|"uses"| node_shared_utils
node_integrations_api -->|"uses"| node_shared_utils
node_notification_api -->|"uses"| node_shared_utils
node_celery_stack -->|"processes"| node_db_models
node_channels_stack -->|"streams"| node_db_models
node_db_models -->|"customizes"| node_user_manager

click node_manage_py "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/manage.py"
click node_project_core "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mulearnbackend/settings.py"
click node_api_urls "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/urls.py"
click node_auth_register "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/auth/auth_views.py"
click node_common_api "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/common/common_views.py"
click node_core_features "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/donate/views.py"
click node_dashboard_root "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/urls.py"
click node_dash_events "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/events/admin_views.py"
click node_dash_people "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/user/dash_user_views.py"
click node_dash_org "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/organisation/organisation_views.py"
click node_dash_work "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/projects/projects_view.py"
click node_dash_social "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/lc/dash_lc_view.py"
click node_dash_ops "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/achievement/achievement_views.py"
click node_db_models "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/db/user.py"
click node_user_manager "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/db/managers/user_manager.py"
click node_celery_stack "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mu_celery/task.py"
click node_channels_stack "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mulearnbackend/routing.py"
click node_integrations_api "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/integrations/urls.py"
click node_notification_api "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/notification/notification_view.py"
click node_shared_utils "https://github.com/gtech-mulearn/mulearnbackend/blob/dev/utils/response.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_manage_py,node_project_core toneBlue
class node_api_urls,node_auth_register,node_common_api,node_core_features,node_integrations_api,node_notification_api toneAmber
class node_dashboard_root,node_dash_events,node_dash_people,node_dash_org,node_dash_work,node_dash_social,node_dash_ops toneMint
class node_db_models,node_user_manager toneRose
class node_celery_stack,node_channels_stack toneIndigo
class node_shared_utils toneTeal
```

## Components

### Runtime

Process entrypoints and deployment wiring

- [manage.py](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/manage.py): django entrypoint · Management entrypoint for local and deployment commands · `manage.py`
- [Project core](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mulearnbackend/settings.py): django project · ASGI/WSGI, settings, middleware, and root URL/routing wiring · `mulearnbackend/settings.py`

### HTTP API

Django URL and view surface

- [API router](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/urls.py): url aggregator · Top-level HTTP router that assembles feature URLconfs · `api/urls.py`
- [Auth & signup](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/auth/auth_views.py): feature area · Authentication and registration request handling · `api/auth/auth_views.py`
- [Common API](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/common/common_views.py): shared feature · Shared public/external views, serializers, and consumer boundary · `api/common/common_views.py`
- [Core features](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/donate/views.py): feature bundle · Donate, hackathon, leaderboard, launchpad, top100, url shortener, protected · `api/donate/views.py`
- [Integrations](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/integrations/urls.py): integration surface · KKEM, Qseverse, and Wadhwani connectors with dedicated views and serializers · `api/integrations/urls.py`
- [Notifications](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/notification/notification_view.py): cross-cutting API · Notification views, serializers, and delivery helpers · `api/notification/notification_view.py`

### Dashboard

Permissioned management domains

- [Dashboard router](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/urls.py): dashboard router · Aggregates the modular dashboard management domains · `api/dashboard/urls.py`
- [Events](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/events/admin_views.py): dashboard domain · Event management surfaces split by admin, manage, public, scoped, and meta views · `api/dashboard/events/admin_views.py`
- [Users & roles](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/user/dash_user_views.py): dashboard domain · User, profile, and role administration surfaces · `api/dashboard/user/dash_user_views.py`
- [Org & campus](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/organisation/organisation_views.py): dashboard domain · Organizations, campuses, colleges, locations, districts, zonal, and affiliations · `api/dashboard/organisation/organisation_views.py`
- [Workflows](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/projects/projects_view.py): dashboard domain · Projects, tasks, task reports, skills, categories, coupons, referrals, and dynamic management · `api/dashboard/projects/projects_view.py`
- [Community](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/lc/dash_lc_view.py): dashboard domain · Learning circles, channels, IG, Discord moderation, and karma vouchers · `api/dashboard/lc/dash_lc_view.py`
- [Ops tools](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/api/dashboard/achievement/achievement_views.py): dashboard domain · Achievement automation, error logging, and dashboard utility surfaces · `api/dashboard/achievement/achievement_views.py`

### Data Model

Shared persistence layer

- [DB models](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/db/user.py): persistence models · Central shared entities for users, organizations, events, projects, tasks, skills, donations, notifications, launchpad, integrations, and URLs · `db/user.py`
- [User manager](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/db/managers/user_manager.py): custom manager · Custom user lifecycle and account behavior · `db/managers/user_manager.py`

### Async & Realtime

Celery and Channels boundaries

- [Celery](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mu_celery/task.py): async runtime · Background task entrypoint and scheduled achievement jobs · `mu_celery/task.py`
- [Channels](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/mulearnbackend/routing.py): ws runtime · ASGI websocket routing and learning-circle/common consumers · `mulearnbackend/routing.py`

### Shared Utils

Cross-cutting helpers and policies

- [Shared utils](https://github.com/gtech-mulearn/mulearnbackend/blob/dev/utils/response.py): helpers · Permissions, responses, exceptions, OpenAPI helpers, karma, and launchpad policies · `utils/response.py`

## Connections

- manage.py → Project core: boots · Starts the Django application using project settings
- Project core → API router: routes HTTP · Root URL configuration exposes API endpoints
- Project core → Channels: routes ws · ASGI routing includes websocket consumers
- Project core → Celery: configures jobs · Project wiring loads Celery application and task modules
- API router → Auth & signup: includes · Top-level router includes auth and registration endpoints
- API router → Common API: includes · Common/public API routes are mounted here
- API router → Core features: includes · Feature APIs for donation, hackathon, leaderboard, launchpad, and others
- API router → Integrations: includes · Integration endpoints are mounted at the API root
- API router → Notifications: includes · Notification endpoints are exposed through the API router
- API router → Dashboard router: includes · Dashboard subsystem is exposed as a major route group
- Dashboard router → Events: dispatches · Routes event management variants
- Dashboard router → Users & roles: dispatches · Routes user, profile, and role management
- Dashboard router → Org & campus: dispatches · Routes organization and geography management
- Dashboard router → Workflows: dispatches · Routes operational and workflow management
- Dashboard router → Community: dispatches · Routes community and live collaboration surfaces
- Dashboard router → Ops tools: dispatches · Routes operational support tools
- Users & roles → DB models: reads/writes · User and profile management persists through shared models
- Org & campus → DB models: reads/writes · Organization and location domains share the central persistence layer
- Workflows → DB models: reads/writes · Projects, tasks, skills, referrals, and related records live in shared models
- Community → DB models: reads/writes · Community and learning-circle data is persisted centrally
- Common API → Shared utils: uses · Common API code relies on shared helpers and response/permission logic
- Core features → Shared utils: uses · Feature APIs share common utilities and domain policies
- Integrations → Shared utils: uses · Integration flows share helper and response utilities
- Notifications → Shared utils: uses · Notification delivery uses shared helpers and formatting utilities
- Celery → DB models: processes · Background tasks compute and update persisted achievement-related data
- Channels → DB models: streams · Realtime consumers likely read and broadcast shared state
- DB models → User manager: customizes · User persistence is extended by a custom manager
