# okfde/froide architecture

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

- Interactive diagram: https://gitdiagram.com/okfde/froide
- Repository: https://github.com/okfde/froide

## Overview

##### Project type and purpose
- Froide is a full-stack, internationalized Freedom-of-Information web portal built on Django (Python) with a Vue/TypeScript frontend.
- It provides public request filing, document storage/viewing, search (Elasticsearch), background processing (Celery), email notifications (SMTP), and geospatial features (PostGIS/GDAL).

##### High-level file structure and clues to architecture
- Top-level “froide/” directory: the Django monolithic codebase, split into many apps (account, document, foirequest, publicbody, etc.).
- “frontend/” directory: Vue single-page-app components, API clients (generated from OpenAPI), static assets, styles, and build config (Vite, pnpm).
- Docker compose (“compose-dev.yaml”) spins up Postgres+PostGIS and Elasticsearch.
- Celery config (“froide/celery.py”) indicates a task queue for asynchronous jobs.
- Configuration files: manage.py, settings.py, local_settings.py.example, openapi-schema.yaml, tsconfig.json, vite.config.ts.

##### Key points from README
- Dependencies: Python 3.12+, Node.js 22+, Docker, Postgres/PostGIS, Elasticsearch, Poppler, GDAL.
- Run services via Docker Compose on ports 5432 (DB) and 9200 (search).
- Django migrations, search index creation, and a development server.
- Frontend built with pnpm and Vite or served with dev server.

##### Detail without over-splitting
- Domain app only if it has its own service boundary; otherwise group under “Django monolith.”
- Infrastructure components (Docker, CI) at a high level.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Browser["Web Browser"]:::frontend
        SPA["Vue/TypeScript SPA"]:::frontend
        VITE["vite.config.ts"]:::frontend
        PKG["package.json"]:::frontend
        LOCK["pnpm-lock.yaml"]:::frontend
        TS["tsconfig.json"]:::frontend
        OPENAPI_TS["openapi-ts.config.ts"]:::frontend
        API_CLIENT["Generated API Client"]:::frontend
        COMPONENTS["Vue Components"]:::frontend
        STYLES["SCSS Styles"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Django Monolith)"
        direction TB
        MONO["Django Monolith"]:::backend
        SETTINGS["settings.py"]:::backend
        ROUTING["routing.py"]:::backend
        WSGI["wsgi.py"]:::backend
        MANAGE["manage.py"]:::backend
        URLS["urls.py"]:::backend
        OPENAPI_SCHEMA["openapi-schema.yaml"]:::backend

        %% Django Apps
        subgraph "Apps"
            direction TB
            ACCOUNT["Account App"]:::backend
            FOIREQUEST["Foirequest App"]:::backend
            CONSUMERS["foirequest/consumers.py"]:::backend
            FR_TASKS["foirequest/tasks.py"]:::backend
            DOCUMENT_APP["Document App"]:::backend
            DOC_TASKS["document/tasks.py"]:::backend
            PUBLICBODY["Publicbody App"]:::backend
            GEO["Georegion App"]:::backend
            SEARCH_HELPER["Search Helper"]:::backend
            SIGNAL_PROC["signal_processor.py"]:::backend
        end

        CELERY_CFG["froi­de/celery.py"]:::worker
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        POSTGRES["PostgreSQL + PostGIS"]:::datastore
        ELASTIC["Elasticsearch"]:::datastore
    end

    %% Workers & Queue
    subgraph "Asynchronous Processing"
        direction TB
        BROKER["Task Queue (AMQP/Redis)"]:::worker
        CELERY["Celery Workers"]:::worker
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP Mail Service"]:::external
        PDF_LIB["Poppler/GDAL"]:::external
        FILE_STORAGE["File Storage (FS/S3)"]:::external
    end

    %% DevOps / Infra
    subgraph "Infrastructure"
        direction TB
        DOCKER["Docker Compose"]:::infra
        CI["GitHub Actions CI/CD"]:::infra
        PRECOMMIT[".pre-commit-config.yaml"]:::infra
        MAKE["Makefile"]:::infra
    end

    %% Connections
    Browser -->|"HTTPS"| SPA
    Browser -->|"WS (optional)"| CONSUMERS
    SPA -->|"HTTPS API"| MONO
    MONO -->|"SQL"| POSTGRES
    MONO -->|"HTTP"| ELASTIC
    MONO -->|"AMQP/Redis"| BROKER
    BROKER -->|"tasks"| CELERY
    CELERY -->|"DB/ES"| POSTGRES
    CELERY -->|"DB/ES"| ELASTIC
    CELERY -->|"SMTP"| SMTP
    MONO -->|"PDF/Image"| PDF_LIB
    MONO -->|"File I/O"| FILE_STORAGE
    DOCKER --> POSTGRES
    DOCKER --> ELASTIC
    CI --> DOCKER
    SPA --> VITE
    VITE --> PKG
    SPA --> PKG

    %% Click Events - Frontend
    click Browser "https://github.com/okfde/froide/tree/main/frontend/"
    click SPA "https://github.com/okfde/froide/tree/main/frontend/"
    click VITE "https://github.com/okfde/froide/blob/main/frontend/vite.config.ts"
    click PKG "https://github.com/okfde/froide/blob/main/frontend/package.json"
    click LOCK "https://github.com/okfde/froide/blob/main/frontend/pnpm-lock.yaml"
    click TS "https://github.com/okfde/froide/blob/main/frontend/tsconfig.json"
    click OPENAPI_TS "https://github.com/okfde/froide/blob/main/frontend/openapi-ts.config.ts"
    click API_CLIENT "https://github.com/okfde/froide/tree/main/frontend/javascript/api/gen/"
    click COMPONENTS "https://github.com/okfde/froide/tree/main/frontend/javascript/components/"
    click STYLES "https://github.com/okfde/froide/tree/main/frontend/styles/"

    %% Click Events - Backend
    click MONO "https://github.com/okfde/froide/tree/main/froide/"
    click SETTINGS "https://github.com/okfde/froide/blob/main/froide/settings.py"
    click ROUTING "https://github.com/okfde/froide/blob/main/froide/routing.py"
    click WSGI "https://github.com/okfde/froide/blob/main/froide/wsgi.py"
    click MANAGE "https://github.com/okfde/froide/blob/main/manage.py"
    click URLS "https://github.com/okfde/froide/blob/main/froide/urls.py"
    click OPENAPI_SCHEMA "https://github.com/okfde/froide/blob/main/froide/openapi-schema.yaml"

    %% Click Events - Apps
    click ACCOUNT "https://github.com/okfde/froide/tree/main/froide/account/"
    click FOIREQUEST "https://github.com/okfde/froide/tree/main/froide/foirequest/"
    click CONSUMERS "https://github.com/okfde/froide/blob/main/froide/foirequest/consumers.py"
    click FR_TASKS "https://github.com/okfde/froide/blob/main/froide/foirequest/tasks.py"
    click DOCUMENT_APP "https://github.com/okfde/froide/tree/main/froide/document/"
    click DOC_TASKS "https://github.com/okfde/froide/blob/main/froide/document/tasks.py"
    click PUBLICBODY "https://github.com/okfde/froide/tree/main/froide/publicbody/"
    click GEO "https://github.com/okfde/froide/tree/main/froide/georegion/"
    click SEARCH_HELPER "https://github.com/okfde/froide/tree/main/froide/helper/search/"
    click SIGNAL_PROC "https://github.com/okfde/froide/blob/main/froide/helper/search/signal_processor.py"

    %% Click Events - Celery
    click CELERY_CFG "https://github.com/okfde/froide/blob/main/froide/celery.py"

    %% Click Events - Infra
    click DOCKER "https://github.com/okfde/froide/blob/main/compose-dev.yaml"
    click CI "https://github.com/okfde/froide/blob/main/.github/workflows/ci.yml"
    click PRECOMMIT "https://github.com/okfde/froide/blob/main/.pre-commit-config.yaml"
    click MAKE "https://github.com/okfde/froide/tree/main/Makefile"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef datastore fill:#fff3cd,stroke:#856404,color:#856404;
    classDef worker fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef infra fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
