# digitalfabrik/integreat-cms architecture

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

- Interactive diagram: https://gitdiagram.com/digitalfabrik/integreat-cms
- Repository: https://github.com/digitalfabrik/integreat-cms

## Overview

##### Project Type & Purpose
- This is a full‐stack, monolithic Django CMS (“Integreat CMS”) that exposes both a backend CMS (Django admin-style UI + templates + JS/TS frontend) and a JSON REST API for mobile/web clients.
- It integrates with multiple external services for translations, push notifications, maps, sitemaps, etc., and uses Celery for background tasks.

##### High-Level Architecture & Components
A. Clients
– Web Browser / CMS UI
– Mobile/Web App (consuming the JSON API)
– CLI Tool (“integreat-cms-cli”)
B. Edge & Ingress
– Nginx/Apache or direct Gunicorn/uWSGI WSGI server
– SSL/TLS termination, static‐asset caching
C. Django Monolith
– Core Django project (“core” app) with settings, middleware, URL router
– “cms” app: models, forms, views, templates (HTML + React/TS components served via webpack)
– “api” app: DRF or similar JSON views
– Connector apps: firebase_api, deepl_api, google_translate_api, summ_ai_api, textlab_api, gvz_api, nominatim_api, sitemap, xliff
– “integreat_celery” app: Celery configuration & tasks module
D. Asynchronous Layer
– Message broker (Redis or RabbitMQ)
– Celery workers running background jobs (translations, push notifications, PDF exports, sitemap generation)
E. Persistence & Cache
– Primary relational database (PostgreSQL)
– Optional cache store (Redis/Memcached) for sessions, rate limiting
F. Static Build & Assets
– Node.js, webpack, TypeScript, SCSS pipeline produces JS/CSS bundles
– Served via Django staticfiles or a CDN
G. CI / CD / DevOps
– CircleCI pipelines, pre-commit, Flake8/Ruff, Docker/devcontainer & Nix flake for dev environment
– Migration scripts & management commands under “tools/”

##### Component Interactions & Data Flows
1) Synchronous HTTP flow:
Browser/Client → HTTPS → Nginx → Gunicorn/uWSGI → Django URL router → appropriate app (cms, api, sitemap) → ORM → PostgreSQL → HTTP response → browser
2) Asynchronous tasks:
Django code (e.g. view or signal) → Celery task submitted → broker (Redis/RabbitMQ) → Celery worker → external API or DB → task result persisted or triggers follow-up
3) External API integrations:
Connector modules call DeepL, Google Translate, SUMM.AI, TextLab for translations; Firebase for push; Nominatim/GVZ for geodata; Matomo for analytics.
4) Static asset pipeline:
Developers → webpack → generated bundles → served to browser via Django staticfiles

##### Key Architectural Patterns & Principles
- Layered monolith: clear separation of “apps” under one Django project
- MVC (Model → View → Template) for CMS UI
- API layer (REST) for headless clients
- Asynchronous task queue for heavy or external-dependent work (Celery)
- Configuration-as-code: environment variables, ini files, devcontainer.json, nix flake
- Extensibility: each integration (translation, push, map) as pluggable Django app

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        Browser["Web Browser"]:::frontend
        Mobile["Mobile/Web App"]:::frontend
        CLI["CLI Tool (integreat-cms-cli)"]:::frontend
    end

    %% Static Build Pipeline
    subgraph "Static Asset Pipeline" 
        direction TB
        StaticBuild["webpack + TS/SCSS"]:::frontend
        StaticBundles["JS/CSS Bundles"]:::frontend
    end

    %% Edge & Ingress
    Nginx["Nginx/Apache (SSL/TLS, Caching)"]:::backend
    Gunicorn["Gunicorn/uWSGI"]:::backend

    %% Django Monolith
    subgraph "Django Monolith" 
        direction TB
        DjangoWSGI["Django WSGI Entry"]:::backend
        core["core app"]:::backend
        cms["cms app"]:::backend
        api["api app"]:::backend
        sitemap["sitemap app"]:::backend
        subgraph "Connectors"
            direction TB
            deepl["DeepL Integration"]:::backend
            google["Google Translate Integration"]:::backend
            summ["SUMM.AI Integration"]:::backend
            textlab["TextLab Integration"]:::backend
            firebase["Firebase Push Integration"]:::backend
            gvz["GVZ Geodata Integration"]:::backend
            nominatim["Nominatim Geocoding"]:::backend
            matomo["Matomo Analytics"]:::backend
            xliff["XLIFF Import/Export"]:::backend
        end
        integreat_celery["integreat_celery app"]:::backend
    end

    %% Persistence & Cache
    DB["PostgreSQL"]:::db
    Cache["Redis/Memcached (Cache)"]:::db

    %% Asynchronous Layer
    Broker["Redis/RabbitMQ (Broker)"]:::async
    Workers["Celery Workers"]:::async

    %% External Services
    subgraph "External Services"
        direction TB
        ExtAPIs["DeepL, Google, SUMM.AI, TextLab, Firebase, GVZ, Nominatim, Matomo"]:::external
    end

    %% Connections: Frontend to Edge
    Browser -->|HTTPS| Nginx
    Mobile -->|HTTPS| Nginx
    CLI -->|HTTP| Nginx
    StaticBundles -->|served| Browser

    %% Build pipeline
    Browser --> StaticBuild
    StaticBuild --> StaticBundles

    %% Edge to Backend
    Nginx -->|WSGI| Gunicorn
    Gunicorn -->|calls wsgi.py| DjangoWSGI

    %% Within Django
    DjangoWSGI --> core
    DjangoWSGI --> cms
    DjangoWSGI --> api
    DjangoWSGI --> sitemap
    DjangoWSGI --> integreat_celery

    %% Data stores
    core -->|ORM| DB
    api -->|ORM| DB
    cms -->|ORM| DB
    sitemap -->|ORM| DB
    core --> Cache
    api --> Cache

    %% Async flows
    cms -->|submit task| Broker
    api -->|submit task| Broker
    integreat_celery --> Broker
    Broker -->|runs tasks| Workers
    Workers -->|writes| DB
    Workers -->|calls| ExtAPIs

    %% Direct integrations
    DjangoWSGI -->|sync calls| ExtAPIs

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#024,stroke-width:1px
    classDef backend fill:#DBFFD0,stroke:#072,stroke-width:1px
    classDef async fill:#FFD8A8,stroke:#A64,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#666,stroke-width:1px
    classDef db fill:#FFF0B3,stroke:#AA0,stroke-width:1px

    %% Click Events
    click core "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/core/"
    click cms "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/cms/"
    click api "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/api/"
    click integreat_celery "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/integreat_celery/"
    click deepl "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/deepl_api/"
    click google "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/google_translate_api/"
    click summ "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/summ_ai_api/"
    click textlab "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/textlab_api/"
    click firebase "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/firebase_api/"
    click gvz "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/gvz_api/"
    click nominatim "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/nominatim_api/"
    click matomo "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/matomo_api/"
    click xliff "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/xliff/"
    click sitemap "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/sitemap/"
    click wsgi "https://github.com/digitalfabrik/integreat-cms/blob/develop/integreat_cms/core/wsgi.py"
    click settings "https://github.com/digitalfabrik/integreat-cms/blob/develop/integreat_cms/core/settings.py"
    click urls "https://github.com/digitalfabrik/integreat-cms/blob/develop/integreat_cms/core/urls.py"
    click middleware "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/core/middleware/"
    click static_src "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/static/src/"
    click cli "https://github.com/digitalfabrik/integreat-cms/tree/develop/integreat_cms/integreat-cms-cli/"
    click tools_cli "https://github.com/digitalfabrik/integreat-cms/tree/develop/tools/integreat-cms-cli"
    click nginxconf "https://github.com/digitalfabrik/integreat-cms/blob/develop/example-configs/apache2-integreat-vhost.conf"
    click ini "https://github.com/digitalfabrik/integreat-cms/blob/develop/example-configs/integreat-cms.ini"
    click circleciCfg "https://github.com/digitalfabrik/integreat-cms/blob/develop/.circleci/config.yml"
    click circleciScripts "https://github.com/digitalfabrik/integreat-cms/tree/develop/.circleci/scripts/"
    click github "https://github.com/digitalfabrik/integreat-cms/tree/develop/.github/workflows/"
    click devcontainer "https://github.com/digitalfabrik/integreat-cms/tree/develop/.devcontainer/"
    click nix "https://github.com/digitalfabrik/integreat-cms/blob/develop/flake.nix"
```
