# cmdmnt/commandment architecture

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

- Interactive diagram: https://gitdiagram.com/cmdmnt/commandment
- Repository: https://github.com/cmdmnt/commandment

## Overview

##### Project type and purpose
- Commandment is a full-stack, open-source Apple MDM (Mobile Device Management) server.
- It provides a REST/JSON-API backend (Python/Flask + SQLAlchemy + Alembic migrations) and a React/Redux/TypeScript SPA as its frontend.
- It interacts with Apple’s APNS (push), DEP (enrollment), and VPP (volume-purchase) services, manages device profiles, certificates, and commands.

##### File structure
- Top-level “commandment/” directory: the Python package with sub‐apps (api, auth, apns, dep, enroll, mdm, vpp, pki, profiles, etc.). Each has its own Flask “app.py” and resource/schema modules.
- “alembic/” and “commandment/alembic/”: database migration scripts for SQLAlchemy.
- “ui/”: the web UI; React components, Redux store modules, webpack configs.
- Docker and CI configs (.circleci/, .docker/, docker-compose.yml, GitLab CI, Travis settings): container orchestration & deployment.

##### Key insights from README
- Python 3.6+ backend requiring a TLS cert, APNS certificate, and a relational database.
- Frontend is a static bundle, served by nginx (in Docker) or any static host, and communicates over HTTPS to the Flask API.
- No external message broker—background “threads” (startup, VPP, APNS) run inside the same container via supervisord.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        SPA["React/Redux SPA"]:::frontend
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        NGINX["nginx Load Balancer"]:::infra
        SUPERVISOR["supervisord"]:::infra
        DOCKER["Docker & Compose"]:::infra
        CI["CI/CD Pipeline"]:::infra
    end

    %% Monolith Application
    subgraph "Flask Monolith"
        UWSGI["uWSGI"]:::internal
        FlaskApp["Flask App (commandment/app.py)"]:::internal
        API["JSON:API (commandment/api/)"]:::internal

        %% Blueprints Modules
        subgraph "Blueprints"
            APNS["APNS Blueprint"]:::internal
            DEP["DEP Blueprint"]:::internal
            ENROLL["Enrollment Blueprint"]:::internal
            MDM["MDM Blueprint"]:::internal
            VPP["VPP Blueprint"]:::internal
            PKI["PKI Module"]:::internal
            PROFILES["Profiles Blueprint"]:::internal
            AUTH["Auth/OAuth2 Service"]:::internal
            INV["Inventory Blueprint"]:::internal
        end

        %% Migrations & Core
        ALEMBIC["Alembic Migrations"]:::internal
        UTIL["Core Models & Utils"]:::internal
        STATIC["Static Assets & Templates"]:::internal
        CONFIG["Configuration & Settings"]:::internal

        %% Background Workers
        subgraph "Background Workers"
            APNS_W["APNS Push Worker"]:::workers
            DEP_W["DEP Poller"]:::workers
            VPP_W["VPP Poller"]:::workers
            STARTUP["Startup Thread"]:::workers
        end
    end

    %% Database
    DB[(Relational Database)]:::db

    %% External Services
    subgraph "External Apple Services"
        APNS_EXT["Apple APNS"]:::external
        DEP_EXT["Apple DEP API"]:::external
        VPP_EXT["Apple VPP API"]:::external
    end

    %% Connections
    Browser["User Browser"]:::frontend -->|"HTTPS"| SPA
    SPA -->|"HTTPS"| NGINX
    NGINX -->|"uWSGI"| UWSGI
    UWSGI -->|"Flask HTTP/JSON"| FlaskApp
    FlaskApp -->|"uses"| API
    API -->|"ORM → SQL"| DB
    FlaskApp -->|"loads"| STATIC
    FlaskApp -->|"reads"| CONFIG
    FlaskApp -->|"imports"| UTIL
    FlaskApp -->|"runs migrations"| ALEMBIC

    UWSGI -->|"spawns"| APNS_W
    UWSGI -->|"spawns"| DEP_W
    UWSGI -->|"spawns"| VPP_W
    UWSGI -->|"spawns"| STARTUP

    APNS_W -->|"APNS TLS Push"| APNS_EXT
    DEP_W -->|"Poll DEP"| DEP_EXT
    VPP_W -->|"Poll VPP"| VPP_EXT

    APNS_W -->|"ORM → SQL"| DB
    DEP_W -->|"ORM → SQL"| DB
    VPP_W -->|"ORM → SQL"| DB
    STARTUP -->|"ORM → SQL"| DB

    DOCKER --> NGINX
    DOCKER --> UWSGI
    DOCKER --> SUPERVISOR
    CI --> DOCKER

    %% Click Events
    click SPA "https://github.com/cmdmnt/commandment/tree/master/ui/src/"
    click SPA "https://github.com/cmdmnt/commandment/blob/master/ui/webpack.config.js"
    click SPA "https://github.com/cmdmnt/commandment/blob/master/ui/webpack.config.prod.js"
    click SPA "https://github.com/cmdmnt/commandment/blob/master/ui/package.json"

    click NGINX "https://github.com/cmdmnt/commandment/blob/master/.docker/nginx.conf"
    click NGINX "https://github.com/cmdmnt/commandment/blob/master/doc/_static/config/nginx-commandment.conf"

    click FlaskApp "https://github.com/cmdmnt/commandment/blob/master/commandment/app.py"
    click API "https://github.com/cmdmnt/commandment/tree/master/commandment/api/"

    click ALEMBIC "https://github.com/cmdmnt/commandment/tree/master/commandment/alembic/versions/"
    click ALEMBIC "https://github.com/cmdmnt/commandment/blob/master/commandment/alembic/env.py"
    click ALEMBIC "https://github.com/cmdmnt/commandment/blob/master/alembic.ini"

    click APNS "https://github.com/cmdmnt/commandment/blob/master/commandment/apns/app.py"
    click APNS "https://github.com/cmdmnt/commandment/blob/master/commandment/apns/push.py"
    click APNS "https://github.com/cmdmnt/commandment/blob/master/commandment/apns/threads.py"
    click APNS "https://github.com/cmdmnt/commandment/blob/master/commandment/apns/schema.py"

    click DEP "https://github.com/cmdmnt/commandment/blob/master/commandment/dep/app.py"
    click DEP "https://github.com/cmdmnt/commandment/blob/master/commandment/dep/dep.py"
    click DEP "https://github.com/cmdmnt/commandment/blob/master/commandment/dep/threads.py"
    click DEP "https://github.com/cmdmnt/commandment/blob/master/commandment/dep/apple_schema.py"
    click DEP "https://github.com/cmdmnt/commandment/blob/master/commandment/dep/schema.py"

    click ENROLL "https://github.com/cmdmnt/commandment/blob/master/commandment/enroll/app.py"
    click ENROLL "https://github.com/cmdmnt/commandment/blob/master/commandment/enroll/profiles.py"

    click MDM "https://github.com/cmdmnt/commandment/blob/master/commandment/mdm/app.py"
    click MDM "https://github.com/cmdmnt/commandment/blob/master/commandment/mdm/handlers.py"
    click MDM "https://github.com/cmdmnt/commandment/blob/master/commandment/mdm/commands.py"
    click MDM "https://github.com/cmdmnt/commandment/blob/master/commandment/mdm/resources.py"

    click VPP "https://github.com/cmdmnt/commandment/blob/master/commandment/vpp/app.py"
    click VPP "https://github.com/cmdmnt/commandment/blob/master/commandment/vpp/vpp.py"
    click VPP "https://github.com/cmdmnt/commandment/blob/master/commandment/threads/vpp_thread.py"
    click VPP "https://github.com/cmdmnt/commandment/blob/master/commandment/vpp/schema.py"

    click PKI "https://github.com/cmdmnt/commandment/blob/master/commandment/pki/ca.py"
    click PKI "https://github.com/cmdmnt/commandment/blob/master/commandment/pki/openssl.py"
    click PKI "https://github.com/cmdmnt/commandment/blob/master/commandment/pki/serialization.py"
    click PKI "https://github.com/cmdmnt/commandment/blob/master/commandment/pki/ssl.py"

    click PROFILES "https://github.com/cmdmnt/commandment/blob/master/commandment/profiles/api.py"
    click PROFILES "https://github.com/cmdmnt/commandment/blob/master/commandment/profiles/models.py"
    click PROFILES "https://github.com/cmdmnt/commandment/blob/master/commandment/profiles/schema.py"
    click PROFILES "https://github.com/cmdmnt/commandment/blob/master/commandment/profiles/resources.py"

    click AUTH "https://github.com/cmdmnt/commandment/blob/master/commandment/auth/app.py"
    click AUTH "https://github.com/cmdmnt/commandment/blob/master/commandment/auth/oauth2.py"
    click AUTH "https://github.com/cmdmnt/commandment/blob/master/commandment/auth/models.py"

    click INV "https://github.com/cmdmnt/commandment/blob/master/commandment/inventory/api.py"
    click INV "https://github.com/cmdmnt/commandment/blob/master/commandment/inventory/models.py"
    click INV "https://github.com/cmdmnt/commandment/blob/master/commandment/inventory/resources.py"

    click STARTUP "https://github.com/cmdmnt/commandment/blob/master/commandment/threads/startup_thread.py"
    click SUPERVISOR "https://github.com/cmdmnt/commandment/blob/master/.docker/supervisord.conf"
    click SUPERVISOR "https://github.com/cmdmnt/commandment/blob/master/.docker/entry.sh"

    click STATIC "https://github.com/cmdmnt/commandment/tree/master/commandment/static/"
    click STATIC "https://github.com/cmdmnt/commandment/blob/master/commandment/templates/index.html"

    click CONFIG "https://github.com/cmdmnt/commandment/blob/master/commandment/default_settings.py"
    click CONFIG "https://github.com/cmdmnt/commandment/blob/master/settings.cfg.example"
    click CONFIG "https://github.com/cmdmnt/commandment/blob/master/.docker/settings.cfg.docker"

    click DOCKER "https://github.com/cmdmnt/commandment/blob/master/docker-compose.yml"
    click DOCKER "https://github.com/cmdmnt/commandment/tree/master/.docker/Dockerfile"

    click CI "https://github.com/cmdmnt/commandment/blob/master/.circleci/config.yml"
    click CI "https://github.com/cmdmnt/commandment/blob/master/.gitlab-ci.yml"
    click CI "https://github.com/cmdmnt/commandment/blob/master/travis-ci-settings.cfg"

    %% Styles
    classDef frontend fill:#fdfd96,stroke:#333,stroke-width:1px
    classDef infra fill:#ffb347,stroke:#333,stroke-width:1px
    classDef internal fill:#add8e6,stroke:#333,stroke-width:1px
    classDef workers fill:#ffd700,stroke:#333,stroke-width:1px
    classDef db fill:#aec6cf,stroke:#333,stroke-width:1px
    classDef external fill:#77dd77,stroke:#333,stroke-width:1px
```
