# washu-it-ris/coldfront-wustl-fork architecture

> Architecture diagram of the GitHub repository washu-it-ris/coldfront-wustl-fork, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/washu-it-ris/coldfront-wustl-fork
- Repository: https://github.com/washu-it-ris/coldfront-wustl-fork

## Overview

##### Project type and purpose
- ColdFront is a full-stack, open-source resource and allocation management system built on Django (Python).
- It provides a self-service web portal for HPC centers to manage users, projects, grants, allocations, publications, and integrate with third-party systems via plugins (e.g., Qumulo, FreeIPA, LDAP, SLURM, XDMoD).

##### High-level file-structure analysis
- Top-level directories:
- coldfront/ – Django project (config, core apps, plugin loader)
- coldfront/plugins/ – plugin modules for external integrations
- coldfront/static/ & coldfront/templates/ – shared static assets and global templates
- docs/ – MkDocs documentation
- Core apps follow Django’s MVC (Model→Template→View) pattern: `core/allocation`, `core/project`, `core/user` etc.
- Plugins implement their own Django apps, management commands, REST/HTML views, tasks, and, in the Qumulo case, a small React front-end.

##### Key components
a. Client-side (Browser/SPA)
- Static assets served (CSS/JS)
- React-based UI (Qumulo plugin)
- Traditional Django templates for core pages
b. Web-server / Application layer
- Nginx (or similar) as reverse-proxy/​static-file server
- Gunicorn (WSGI) hosting the Django project (`manage.py`, `config/wsgi.py`)
- Django apps (“core” + loaded “plugins”)
c. Persistence layer
- Relational database (PostgreSQL/MySQL) for all Django models
- Django migrations to evolve schema
d. Asynchronous/task layer
- Celery (or Django-Q/Beat) for scheduled tasks defined in `core/*/tasks.py` and `plugins/*/tasks.py`
- Broker (RabbitMQ/Redis) for queuing
e. Email / Notification service
- SMTP server for sending system-generated emails (`core/utils/mail.py`, templates/email/*.txt)
f. External services (via plugins)
- Qumulo REST API client
- Active Directory / FreeIPA (LDAP)
- SLURM scheduler
- XDMoD monitoring
- Custom plugin endpoints

##### Relationships & interactions
- Browser → Nginx → Gunicorn → Django URL dispatcher (`config/urls.py`)
- Views → Models → Database (ORM)
- Views trigger signals/tasks for asynchronous workflows (e.g., email reminders, allocation ACL resets)
- Celery Beat triggers periodic tasks → Plugin services → External systems
- Management commands (CLI) for one-off scripts and scheduled CRON jobs (via Django-crontab or Celery Beat)
- Plugins are discovered via Django’s `INSTALLED_APPS` and hooked into the core through URLs, templates, static files, and signals

##### Architectural patterns & principles
- MVC/MVT: clear separation of Models, Templates, and Views
- Plugin architecture: core system defines extension points; each plugin is an independent Django app that registers URLs, templates, static resources, and tasks
- Command pattern: management commands for administrative workflows
- Signal-based decoupling: apps and plugins communicate via Django signals
- Asynchronous/off-loaded workload: long-running or periodic jobs handled by Celery

b. Inside App Server, subdivide into “Core Django Apps” and “Plugin Apps”
- HTTP(s) requests (Browser → Nginx → Gunicorn → Django URLs)
- ORM calls (Django → Database)
- Task enqueues (Django Views/Signals → Broker → Celery workers)
- Email dispatch (Django/Celery → SMTP)
- External API calls (Plugin Services → Qumulo/LDAP/SLURM/etc.)
d. Component with key technologies (e.g., React, Django, PostgreSQL, Celery, RabbitMQ)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser (User)"]:::external
        StaticAssets["Static Assets (CSS/JS)"]:::infra
        ReactUI["React UI (Qumulo Plugin SPA)"]:::plugin
    end

    %% Web Server Layer
    subgraph "Web Server Layer"
        direction TB
        Nginx["Nginx (Reverse Proxy/Static)"]:::infra
    end

    %% Application Server
    subgraph "Application Server"
        direction TB
        Gunicorn["Gunicorn (WSGI)"]:::infra
        URLDispatcher["Django URL Dispatcher"]:::core

        subgraph "Core Django Apps"
            direction TB
            AllocationApp["Allocation App"]:::core
            ProjectApp["Project App"]:::core
            UserApp["User App"]:::core
            GrantApp["Grant App"]:::core
            PublicationApp["Publication App"]:::core
            ResourceApp["Resource App"]:::core
            PortalApp["Portal App"]:::core
            ResearchOutputApp["Research Output App"]:::core
            UtilsApp["Core Utils"]:::core
        end

        subgraph "Plugin Apps"
            direction TB
            FreeIPA["FreeIPA Plugin"]:::plugin
            LDAP["LDAP Plugin"]:::plugin
            Qumulo["Qumulo Plugin"]:::plugin
            SLURM["SLURM Plugin"]:::plugin
            XDMoD["XDMoD Plugin"]:::plugin
            SystemMonitor["System Monitor Plugin"]:::plugin
        end
    end

    %% Persistence and Task Layers
    DB[(PostgreSQL/MySQL DB)]:::infra
    Broker[(RabbitMQ/Redis Broker)]:::infra
    CeleryWorker["Celery Workers & Beat"]:::infra
    SMTP["SMTP Server"]:::infra

    %% External Services
    subgraph "External Services"
        direction TB
        QumuloAPI["Qumulo REST API"]:::external
        LDAPService["LDAP/FreeIPA"]:::external
        SLURMService["SLURM Scheduler"]:::external
        XDMoDService["XDMoD Monitoring"]:::external
    end

    %% Connections
    Browser -->|"HTTP(S) Request"| Nginx
    Nginx -->|"Proxy"| Gunicorn
    Gunicorn -->|"Django Request"| URLDispatcher

    URLDispatcher -->|routes| AllocationApp
    URLDispatcher -->|routes| ProjectApp
    URLDispatcher -->|routes| UserApp
    URLDispatcher -->|routes| GrantApp
    URLDispatcher -->|routes| PublicationApp
    URLDispatcher -->|routes| ResourceApp
    URLDispatcher -->|routes| PortalApp
    URLDispatcher -->|routes| ResearchOutputApp
    URLDispatcher -->|routes| UtilsApp

    URLDispatcher -->|routes| FreeIPA
    URLDispatcher -->|routes| LDAP
    URLDispatcher -->|routes| Qumulo
    URLDispatcher -->|routes| SLURM
    URLDispatcher -->|routes| XDMoD
    URLDispatcher -->|routes| SystemMonitor

    AllocationApp -->|"ORM (SQL)"| DB
    ProjectApp -->|"ORM (SQL)"| DB
    UserApp -->|"ORM (SQL)"| DB
    GrantApp -->|"ORM (SQL)"| DB
    PublicationApp -->|"ORM (SQL)"| DB
    ResourceApp -->|"ORM (SQL)"| DB
    PortalApp -->|"ORM (SQL)"| DB
    ResearchOutputApp -->|"ORM (SQL)"| DB
    UtilsApp -->|"ORM (SQL)"| DB

    FreeIPA -->|"ORM (SQL)"| DB
    LDAP -->|"ORM (SQL)"| DB
    Qumulo -->|"ORM (SQL)"| DB
    SLURM -->|"ORM (SQL)"| DB
    XDMoD -->|"ORM (SQL)"| DB
    SystemMonitor -->|"ORM (SQL)"| DB

    AllocationApp -->|"Tasks (AMQP)"| Broker
    ProjectApp -->|"Tasks (AMQP)"| Broker
    UtilsApp -->|"Tasks (AMQP)"| Broker
    FreeIPA -->|"Tasks (AMQP)"| Broker
    Qumulo -->|"Tasks (AMQP)"| Broker

    Broker -->|"Consume"| CeleryWorker
    CeleryWorker -->|"Email (SMTP)"| SMTP

    FreeIPA -->|"LDAP Sync"| LDAPService
    LDAP -->|"LDAP Search"| LDAPService
    Qumulo -->|"REST API Calls"| QumuloAPI
    SLURM -->|"Scheduler API"| SLURMService
    XDMoD -->|"Monitoring API"| XDMoDService

    Browser --> StaticAssets
    Browser --> ReactUI

    %% Click Events
    click StaticAssets "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/static/"
    click ReactUI "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/qumulo/frontend/react/src/"
    click Gunicorn "https://github.com/washu-it-ris/coldfront-wustl-fork/blob/main/manage.py & coldfront/config/wsgi.py"
    click URLDispatcher "https://github.com/washu-it-ris/coldfront-wustl-fork/blob/main/coldfront/config/urls.py"
    click AllocationApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/allocation/"
    click ProjectApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/project/"
    click UserApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/user/"
    click GrantApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/grant/"
    click PublicationApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/publication/"
    click ResourceApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/resource/"
    click PortalApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/portal/"
    click ResearchOutputApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/research_output/"
    click UtilsApp "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/core/utils/"
    click FreeIPA "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/freeipa/"
    click LDAP "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/ldap_user_search/"
    click Qumulo "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/qumulo/"
    click SLURM "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/slurm/"
    click XDMoD "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/xdmod/"
    click SystemMonitor "https://github.com/washu-it-ris/coldfront-wustl-fork/tree/main/coldfront/plugins/system_monitor/"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,stroke-width:1px
    classDef plugin fill:#DFFFE0,stroke:#28a745,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#666,stroke-width:1px
    classDef external fill:#FFF4D0,stroke:#DAA520,stroke-width:1px
```
