# globaleaks/globaleaks-whistleblowing-software architecture

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

- Interactive diagram: https://gitdiagram.com/globaleaks/globaleaks-whistleblowing-software
- Repository: https://github.com/globaleaks/globaleaks-whistleblowing-software

## Overview

##### Project type and purpose
- GlobaLeaks is a full-stack, open-source whistleblowing platform.
- It consists of a Python/Twisted-based backend providing REST and web-socket endpoints, an Angular-based Single Page Application (SPA) frontend (“client”), a relational database with migration support, plus external integrations (mail, Let’s Encrypt, Tor).

##### File structure
- Top-level “backend” directory: Python code, REST handlers, jobs, database migrations, configuration, ORM, services, utilities, tests, CLI scripts.
- Top-level “client” directory: Angular application with assets, components, pages per user‐role (admin, analyst, custodian, recipient, whistleblower), shared modules, services, styles, E2E tests (Cypress).
- Infrastructure files: docker/, debian/, scripts/, CI workflows (.github/workflows), readthedocs docs/, packaging (pyproject.toml), license, governance.

##### README for additional insights
- Clarifies tech stack: Python/Twisted, Angular, REST, secure communications, database migrations, continuous integration, documentation portal.

##### Elements
- Clear labels: name each component (e.g., “Angular SPA,” “Twisted Web Server,” “PostgreSQL DB,” “SMTP Service,” “Let’s Encrypt ACME”)
- From client to API, API to DB, jobs to external services
- Asynchronous flows for background jobs
- Frontend in blue rectangles
- Backend in green rectangles
- External services in gray clouds or parallelograms

##### Detailed capture of essential architectural elements
- HTTP server & REST decorators → Handler modules → Service layer → ORM → DB
- Reactor scheduler → Job modules
- Utility modules (crypto, PGP, TLS, file system)
- App shell → Router → Feature modules per user role → Shared components & services
- Packaging / deployment:
- Docker image build → Debian packages → Cloud or on-premise host
- Monitoring / logging flows if needed

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        SPA["Angular SPA"]:::frontend
        Entry["main.ts"]:::frontend
        Routing["app.routes.ts"]:::frontend
        Pages["Feature Modules (pages)"]:::frontend
        Shared["Shared Modules & Components"]:::frontend
        Services["Services"]:::frontend
        E2E["E2E Tests (Cypress)"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        WebServer["Twisted Web Server"]:::backend
        CLI["CLI Scripts"]:::backend
        APILayer["REST API Layer"]:::backend
        subgraph "HTTP Handlers"
            direction TB
            AdminH["Admin Handlers"]:::backend
            AuthH["Auth Handlers"]:::backend
            WhistleH["Whistleblower Handlers"]:::backend
            OtherH["Other Role Handlers"]:::backend
        end
        ServicesB["Business Services"]:::backend
        ORMInit["ORM Initialization"]:::backend
        Models["Data Models"]:::backend
        Migrations["DB Migrations"]:::backend
        subgraph "Background Jobs"
            direction TB
            JobsDef["Job Definitions"]:::backend
            Schedulers["Periodic Schedulers"]:::backend
        end
        Utils["Utility Modules"]:::backend
        Config["Configuration & Settings"]:::backend
        Transactions["Transaction Management"]:::backend
        TestsB["Backend Tests"]:::backend
        PackagingPy["Python Packaging"]:::backend
        Requirements["Requirements"]:::backend
    end

    %% Database
    DB["PostgreSQL / SQLite"]:::database

    %% External Services
    subgraph "External Integrations"
        direction TB
        SMTP["SMTP Service"]:::external
        ACME["Let's Encrypt ACME"]:::external
        TorNet["Tor Network"]:::external
        PGPKS["PGP Keyservers"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure & CI/CD"
        direction TB
        Docker["Docker"]:::infra
        Debian["Debian Packaging"]:::infra
        CICD["GitHub Actions CI/CD"]:::infra
        Docs["Documentation Portal"]:::infra
    end

    %% Connections
    SPA -->|"HTTPS API"| APILayer
    APILayer -->|"delegates to"| AdminH
    APILayer -->|"delegates to"| AuthH
    APILayer -->|"delegates to"| WhistleH
    APILayer -->|"delegates to"| OtherH
    AdminH --> ServicesB
    AuthH --> ServicesB
    WhistleH --> ServicesB
    OtherH --> ServicesB
    ServicesB --> ORMInit
    ORMInit --> Models
    Models --> DB
    Migrations --> DB
    ServicesB --> Transactions
    WebServer --> APILayer
    WebServer --> JobsDef
    JobsDef --> Schedulers
    Schedulers --> Utils
    Schedulers --> SMTP
    Schedulers --> ACME
    Schedulers --> TorNet
    Schedulers --> PGPKS
    Utils --> SMTP
    Utils --> PGPKS
    CLI --> WebServer
    Config --> WebServer
    Config --> JobsDef
    TestsB --> WebServer
    PackagingPy --> Docker
    Requirements --> Docker
    Docker --> CICD
    Debian --> CICD
    CICD --> Docs

    %% Click Events
    click SPA "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/client/app"
    click Entry "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/client/app/main.ts"
    click Routing "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/client/app/src/app.routes.ts"
    click Pages "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/client/app/src/pages"
    click Shared "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/client/app/src/shared"
    click Services "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/client/app/src/services"
    click Services "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/client/app/src/shared/services"
    click E2E "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/client/cypress"
    click E2E "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/client/cypress.config.ts"
    click WebServer "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/globaleaks/backend.py"
    click CLI "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/bin/globaleaks"
    click CLI "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/bin/gl-admin"
    click CLI "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/bin/gl-dev-utils"
    click APILayer "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/globaleaks/rest/api.py"
    click AdminH "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/handlers/admin"
    click AuthH "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/handlers/auth"
    click WhistleH "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/handlers/whistleblower"
    click ServicesB "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/globaleaks/services/service.py"
    click ServicesB "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/globaleaks/services/tor.py"
    click ORMInit "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/globaleaks/orm.py"
    click Models "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/models"
    click Migrations "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/db"
    click Utils "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/utils"
    click Config "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/globaleaks/settings.py"
    click Transactions "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/transactions"
    click TestsB "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/backend/globaleaks/tests"
    click PackagingPy "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/pyproject.toml"
    click Requirements "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/backend/requirements.txt"
    click Docker "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/docker/Dockerfile"
    click Docker "https://github.com/globaleaks/globaleaks-whistleblowing-software/blob/stable/docker/docker-compose.yml"
    click Debian "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/debian/"
    click CICD "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/.github/workflows"
    click Docs "https://github.com/globaleaks/globaleaks-whistleblowing-software/tree/stable/documentation/"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1976D2,color:#0D47A1
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef database fill:#FFE082,stroke:#F9A825,color:#FF6F00
    classDef external fill:#CFD8DC,stroke:#90A4AE,color:#37474F
    classDef infra fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
```
