# inducer/relate architecture

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

- Interactive diagram: https://gitdiagram.com/inducer/relate
- Repository: https://github.com/inducer/relate

## Overview

##### Project Type and Purpose
- RELATE is a full-stack, web-based courseware platform built on Django.
- It provides content creation (YAML/Markdown), versioning via Git, code-question sandboxes, grading workflows, calendar/gradebook features, and instant messaging (XMPP).

##### High-Level Architectural Overview
- Browser / Client (HTML, CSS, JS assets served under frontend/)
- Reverse Proxy / Load Balancer (e.g., Nginx)
- Django Application Server
- WSGI entry point (relate/wsgi.py)
- Core Django project (relate/settings.py, URLs, middleware)
- Django apps:
– accounts (authentication, admin)
– course (content, flows, grading, calendar)
– prairietest (test harness)
– relate (global URLs, templates, static assets)
- Celery workers (relate/celery.py) for background tasks
- Data Stores
- Relational DB (PostgreSQL)
- Message broker (Redis or RabbitMQ) for Celery
- File storage (bulk-storage/ for large uploads)
- Git repositories (local or remote) for content versioning
- Sandboxed Code Execution
- Separate container or process (course/sandbox.py + docker-image-run-py/)
- Secured by Linux namespaces, resource limits
- External Services
- XMPP server for instant messaging
- Email service (SMTP) for notifications
- SAML Identity Provider for SSO
- Caching (e.g., Redis or memcached) for session data and analytics
- CI/CD pipelines (.github/, .ci/) and Docker scripts for deployment

##### Detailed Component Relationships
- Client → HTTP(S) → Load Balancer → Nginx
- Static assets (CSS/JS under frontend/) routed via Nginx or CDN
- Dynamic requests → Gunicorn/uWSGI → Django WSGI
- Django
- Views/controllers handle REST API and page rendering
- Views invoke models (accounts.models, course.models)
- Templates (relate/templates, course/templates) produce HTML
- Static files collected by collectstatic.sh
- Background Processing
- Django tasks (course.tasks, relate tasks) enqueued to broker
- Celery workers consume tasks for grading, analytics, email
- Code Sandbox
- User code submitted via a page (course/page/code_run_backend.py)
- Code execution delegated to sandbox container
- Results returned to Django, then to user and grading engine
- Data Persistence
- PostgreSQL stores user, course, flow session, grading, messaging data
- Git stores course content under version control
- Messaging
- In-class chat via XMPP (relate/auth integration)
- Instantflow requests (course/instantflowrequest) managed by Django

##### Architectural Patterns and Design Principles
- MVC (Model-View-Template) with clear separation of concerns
- Modular Django apps encapsulate features
- Asynchronous processing via Celery for scalability
- Containerized sandbox for isolation
- Git-backed versioning supports immutability and content previews
- Pluggable SSO (SAML) and external integrations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser"]:::client
        CSS["CSS Assets"]:::client
        JS["JS Assets"]:::client
    end

    %% Proxy Layer
    subgraph "Reverse Proxy / Load Balancer"
        direction TB
        Nginx["Nginx (Proxy/Load Balancer)"]:::external
    end

    %% Web Tier
    subgraph "Django Web Tier"
        direction TB
        WSGI["WSGI Entry Point\nrelate/wsgi.py"]:::web
        Settings["Core Settings\nrelate/settings.py"]:::web
        URLs["URL Config\nrelate/urls.py"]:::web
        subgraph "Django Apps"
            direction TB
            Templates["Global Templates\nrelate/templates/"]:::web
            Static["Global Static\nrelate/static/"]:::web
            Accounts["Accounts App"]:::web
            Course["Course App"]:::web
            Prairie["PrairieTest App"]:::web
            CelerySetup["Celery Setup\nrelate/celery.py"]:::worker
        end
    end

    %% Worker Tier
    subgraph "Celery Worker Tier"
        direction TB
        Worker["Celery Workers"]:::worker
    end

    %% Sandbox
    subgraph "Code Sandbox"
        direction TB
        SandboxPy["Sandbox Script\ncourse/sandbox.py"]:::worker
        DockerRun["Sandbox Container\ndocker-image-run-py/"]:::worker
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres[(PostgreSQL)]:::datastore
        Broker[(Redis/RabbitMQ)]:::datastore
        FileStore[(Bulk File Storage)]:::datastore
        GitRepos[(Git Repositories)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        XMPP["XMPP Server"]:::external
        SMTP["SMTP Service"]:::external
        SAML["SAML IdP"]:::external
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        direction TB
        CIci[".ci/"]:::ci
        CIgh[".github/workflows/"]:::ci
    end

    %% Management Commands
    subgraph "Management Commands"
        direction TB
        Mgmt["Bulk Import & Testing\ncourse/management/commands/"]:::web
    end

    %% Versioning Helpers
    subgraph "Versioning Helpers"
        direction TB
        Versioning["Versioning Helpers\ncourse/versioning.py"]:::web
        GitRoots["git-roots/"]:::web
    end

    %% Connections
    Browser -->|HTTP GET/POST| Nginx
    CSS -->|served by| Nginx
    JS -->|served by| Nginx

    Nginx -->|HTTP → Gunicorn| WSGI
    WSGI -->|loads| Settings
    WSGI -->|routes| URLs

    URLs --> Accounts
    URLs --> Course
    URLs --> Prairie

    Accounts -->|DB queries| Postgres
    Course -->|DB queries| Postgres
    Prairie -->|DB queries| Postgres

    Course -->|enqueue tasks| Broker
    Accounts -->|enqueue tasks| Broker

    Broker -->|task delivery| Worker
    Worker -->|exec tasks| Postgres
    Worker -->|send email| SMTP

    Course -->|submit code| SandboxPy
    SandboxPy -->|docker run| DockerRun
    DockerRun -->|return result| Course

    Course -->|git operations| GitRepos
    Versioning -->|git helpers| GitRepos

    Course -->|store files| FileStore

    Course -->|chat via| XMPP
    Accounts -->|SSO via| SAML

    CIci -->|build/test| DockerRun
    CIgh -->|pipeline| WSGI

    Mgmt -->|runs| Course

    %% Click Events
    click CSS "https://github.com/inducer/relate/tree/main/frontend/css"
    click JS "https://github.com/inducer/relate/tree/main/frontend/js"
    click WSGI "https://github.com/inducer/relate/blob/main/relate/wsgi.py"
    click Settings "https://github.com/inducer/relate/blob/main/relate/settings.py"
    click URLs "https://github.com/inducer/relate/blob/main/relate/urls.py"
    click CelerySetup "https://github.com/inducer/relate/blob/main/relate/celery.py"
    click Templates "https://github.com/inducer/relate/tree/main/relate/templates/"
    click Static "https://github.com/inducer/relate/tree/main/relate/static/"
    click Accounts "https://github.com/inducer/relate/tree/main/accounts/"
    click Course "https://github.com/inducer/relate/tree/main/course/"
    click Prairie "https://github.com/inducer/relate/tree/main/prairietest/"
    click Versioning "https://github.com/inducer/relate/blob/main/course/versioning.py"
    click GitRoots "https://github.com/inducer/relate/tree/main/git-roots/"
    click FileStore "https://github.com/inducer/relate/tree/main/bulk-storage/"
    click DockerRun "https://github.com/inducer/relate/tree/main/docker-image-run-py/"
    click SandboxPy "https://github.com/inducer/relate/blob/main/course/sandbox.py"
    click SAML "https://github.com/inducer/relate/tree/main/saml-config/"
    click CIci "https://github.com/inducer/relate/tree/main/.ci/"
    click CIgh "https://github.com/inducer/relate/tree/main/.github/workflows/"
    click Mgmt "https://github.com/inducer/relate/tree/main/course/management/commands/"

    %% Styles
    classDef client fill:#D3E5FF,stroke:#333,stroke-width:1px
    classDef web fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef worker fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFD580,stroke:#333,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef ci fill:#F0F0F0,stroke:#333,stroke-width:1px
```
