# pytition/pytition architecture

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

- Interactive diagram: https://gitdiagram.com/pytition/pytition
- Repository: https://github.com/pytition/pytition

## Overview

##### Project type and purpose
- Pytition is a monolithic, full-stack web application built with Django (Python) to let organizations host privacy-focused petition sites.
- It serves dynamic petition pages, dashboards, registration flows, signature exports, email confirmations and integrates with external SMTP and mailing-list endpoints.

##### File structure
- Top-level
– Dockerfile, docker-compose.yml, nginx-uwsgi/ (Nginx + uWSGI setup), Jenkinsfile → containerized CI/CD + deployment
– dev/ (shell scripts for local setup, prepopulation, Docker config)
– doc/ & .readthedocs.yaml → Sphinx documentation and ReadTheDocs integration
– pyproject.toml, requirements*.txt, pdm.lock → Python packaging and dependencies
- Core code under pytition/
– pytition/settings, urls.py, wsgi.py → Django project configuration
– petition/ → Django app with models, views, forms, management commands, templates, static assets, tests
– cli_pytition.py → custom CLI entry point
- Static assets and i18n
– petition/static/ (CSS, JS, vendor libs, manifest)
– petition/locale/ for multi-language support
- Tests, migrations and management commands illustrate custom background tasks (data generation, email queue, moderation, update jobs).

##### README for additional insights
- Technology stack: Django 4.2, Python 3.8–3.11, Bootstrap4, jQuery, TinyMCE, MySQL/PostgreSQL via mysqlclient, requests, bcrypt
- Features like email retry via queue middleware, Open Graph support, CSV export, mailing-list subscription integration
- Deployment targets: self-hosted, no third-party CDN, Dockerized setups

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        Browser["Browser"]:::frontend
        Mobile["Mobile Device"]:::frontend
        Browser -->|HTTPS Request| Nginx
        Mobile -->|HTTPS Request| Nginx
    end

    subgraph "Ingress & App Server"
        Nginx["Nginx Reverse Proxy"]:::infra
        Uwsgi["uWSGI Application Server"]:::infra
        Nginx -->|forwards| Uwsgi
    end

    subgraph "Django Application"
        Djangoproj["Django Project (pytition)"]:::app
        PetitionApp["petition App"]:::app
        Cli["CLI Entry Point"]:::app
        Uwsgi -->|WSGI| Djangoproj
        Djangoproj --> PetitionApp
        Djangoproj --> Cli
    end

    subgraph "Datastores"
        DB["Relational DB (MySQL/PostgreSQL)"]:::db
        Media["Media Storage (Filesystem)"]:::db
        Djangoproj -->|CRUD| DB
        Djangoproj -->|Read/Write| Media
    end

    subgraph "External Services"
        SMTP["SMTP Server"]:::external
        MailList["Mailing List API"]:::external
        Djangoproj -->|Emails| SMTP
        Djangoproj -->|Subscriptions| MailList
    end

    subgraph "CI/CD Pipeline"
        Jenkins["Jenkins CI"]:::external
        DockerReg["Docker Registry"]:::external
        DocsSite["ReadTheDocs"]:::external
        Jenkins -->|build & push| DockerReg
        Jenkins -->|docs build| DocsSite
    end

    subgraph "Development & Documentation"
        DevScripts["dev/ Scripts"]:::infra
        Docs["Sphinx Documentation"]:::infra
        DevScripts -->|configure & init| Nginx
        DevScripts -->|setup images| DockerReg
        Docs -->|publish| DocsSite
    end

    click Nginx "https://github.com/pytition/pytition/blob/master/nginx-uwsgi/nginx.conf"
    click Uwsgi "https://github.com/pytition/pytition/blob/master/nginx-uwsgi/uwsgi.ini"
    click Jenkins "https://github.com/pytition/pytition/tree/master/Jenkinsfile"
    click DockerReg "https://github.com/pytition/pytition/tree/master/Dockerfile"
    click DocsSite "https://github.com/pytition/pytition/blob/master/.readthedocs.yaml"
    click DevScripts "https://github.com/pytition/pytition/blob/master/dev/dev_setup.sh"
    click Docs "https://github.com/pytition/pytition/blob/master/doc/index.rst"
    click Djangoproj "https://github.com/pytition/pytition/blob/master/pytition/pytition/settings/base.py"
    click PetitionApp "https://github.com/pytition/pytition/blob/master/pytition/petition/apps.py"
    click Cli "https://github.com/pytition/pytition/blob/master/pytition/cli_pytition.py"
    click Media "https://github.com/pytition/pytition/blob/master/pytition/mediaroot/.gitignore"

    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef infra fill:#e6e6e6,stroke:#999999,color:#333333;
    classDef app fill:#d4edda,stroke:#28a745,color:#155724;
    classDef db fill:#fff3cd,stroke:#ffcd39,color:#856404;
    classDef external fill:#e2d6f1,stroke:#8c4bb8,color:#4b0082;
```
