# taigaio/taiga-back architecture

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

- Interactive diagram: https://gitdiagram.com/taigaio/taiga-back
- Repository: https://github.com/taigaio/taiga-back

## Overview

##### Project type and purpose
- This is the Taiga backend: a monolithic, modular Django REST API that powers Taiga.io.
- Its purpose is to serve as the data and business-logic layer for task tracking: it exposes HTTP/JSON endpoints, processes authentication, enforces permissions, handles webhooks and importers, schedules background jobs, sends e-mail and stores attachments.
- It integrates with external services (GitHub, GitLab, Asana, Jira, Trello, Bitbucket), uses Celery for async work, and persists data in PostgreSQL with Django ORM.

##### File structure
- Top-level orchestrator: manage.py, wsgi.py, settings/ directory holding environment-specific configs.
- Docker folder: Dockerfile, entrypoint scripts, config template for containerizing both Django and Celery.
- Apps under taiga/: auth, base, events, export_import, external_apps, feedback, front, hooks, importers, locale, mdrender, permissions, projects (with submodules attachments, epics, issues, tasks, userstories, wiki, notifications, etc.), searches, stats, telemetry, timeline, users, userstorage, webhooks.
- Asynchronous job definitions: taiga/celery.py, Celery tasks in various apps, RabbitMQ/PostgreSQL backends for events.
- tests/ covering unit and integration for each module.
- Configuration files for CI (pytest.ini, tox.ini), code style (setup.cfg), dependency management (requirements*.txt).

##### README for additional insights
- Emphasis on API docs, installation guides, contribution guidelines.
- Target audience: backend developers extending or deploying the service.

##### Elements
- Clear, descriptive labels: “Django API Server,” “Celery Worker,” “PostgreSQL,” “RabbitMQ,” “SMTP,” “S3/Blob Storage.”
- Rectangles for compute containers (API, Workers)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        Web["Web Frontend"]:::external
        Mobile["Mobile App"]:::external
        CLI["CLI Tools"]:::external
    end

    %% API Container
    subgraph "API Container" 
        direction TB
        API["Django API Server"]:::api
        subgraph "HTTP API Layer"
            direction TB
            URLs["URL Routing"]:::api
            Routers["Routers"]:::api
            Manage["manage.py"]:::api
            WSGI["wsgi.py"]:::api
            Settings["settings/common.py"]:::api
        end
        subgraph "Authentication & Permissions"
            direction TB
            AuthApp["taiga/auth/"]:::api
            PermApp["taiga/permissions/"]:::api
            BaseAuth["base/api/authentication.py"]:::api
            BasePerm["base/api/permissions.py"]:::api
            BaseThrottle["base/api/throttling.py"]:::api
        end
        subgraph "Service Layer"
            direction TB
            AuthSvc["taiga/auth/services.py"]:::api
            ProjSvc["taiga/projects/services/projects.py"]:::api
            WebhookSvc["taiga/webhooks/tasks.py"]:::api
            ImportSvc["taiga/importers/services.py"]:::api
        end
        subgraph "Data Access (ORM)"
            direction TB
            Models["taiga/base/db/models/"]:::api
        end
    end

    %% Worker Container
    subgraph "Worker Container" 
        direction TB
        Worker["Celery Worker"]:::worker
        CeleryCfg["taiga/celery.py"]:::worker
        AsyncEntry["docker/async_entrypoint.sh"]:::worker
        subgraph "Celery Tasks"
            direction TB
            TaskAuth["auth token tasks"]:::worker
            TaskExport["export_import tasks"]:::worker
            TaskImport["importers tasks"]:::worker
            TaskNotif["projects notifications tasks"]:::worker
            TaskWebhooks["webhooks tasks"]:::worker
        end
        Markdown["Markdown Rendering"]:::worker
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres[(PostgreSQL)]:::datastore
        Broker[(RabbitMQ/Redis)]:::datastore
        Cache[(Redis Cache)]:::datastore
        Storage[(S3/Blob Storage)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GitHub["GitHub"]:::external
        GitLab["GitLab"]:::external
        Jira["Jira/Asana/Trello"]:::external
        SMTP["SMTP Email"]:::external
    end

    %% Wire up flows
    Web -->|HTTP/JSON| API
    Mobile -->|HTTP/JSON| API
    CLI -->|HTTP/JSON| API

    API -->|ORM Queries| Models
    API -->|enqueue AMQP| Broker
    API -->|HTTP calls| GitHub
    API -->|HTTP calls| GitLab
    API -->|HTTP calls| Jira

    Worker -->|consume AMQP| Broker
    Worker -->|ORM Queries| Models
    Worker -->|send SMTP| SMTP
    Worker -->|store attachments| Storage

    API -->|rate limit| Cache
    Worker -->|rate limit| Cache

    %% Click events
    click Manage "https://github.com/taigaio/taiga-back/blob/main/manage.py"
    click URLs "https://github.com/taigaio/taiga-back/blob/main/taiga/urls.py"
    click Routers "https://github.com/taigaio/taiga-back/blob/main/taiga/routers.py"
    click Settings "https://github.com/taigaio/taiga-back/blob/main/settings/common.py"
    click WSGI "https://github.com/taigaio/taiga-back/blob/main/taiga/wsgi.py"

    click AuthApp "https://github.com/taigaio/taiga-back/tree/main/taiga/auth/"
    click PermApp "https://github.com/taigaio/taiga-back/tree/main/taiga/permissions/"
    click BaseAuth "https://github.com/taigaio/taiga-back/blob/main/taiga/base/api/authentication.py"
    click BasePerm "https://github.com/taigaio/taiga-back/blob/main/taiga/base/api/permissions.py"
    click BaseThrottle "https://github.com/taigaio/taiga-back/blob/main/taiga/base/api/throttling.py"

    click AuthSvc "https://github.com/taigaio/taiga-back/blob/main/taiga/auth/services.py"
    click ProjSvc "https://github.com/taigaio/taiga-back/blob/main/taiga/projects/services/projects.py"
    click WebhookSvc "https://github.com/taigaio/taiga-back/blob/main/taiga/webhooks/tasks.py"
    click ImportSvc "https://github.com/taigaio/taiga-back/blob/main/taiga/importers/services.py"

    click Models "https://github.com/taigaio/taiga-back/tree/main/taiga/base/db/models/"

    click CeleryCfg "https://github.com/taigaio/taiga-back/blob/main/taiga/celery.py"
    click AsyncEntry "https://github.com/taigaio/taiga-back/blob/main/docker/async_entrypoint.sh"

    click Markdown "https://github.com/taigaio/taiga-back/blob/main/taiga/mdrender/service.py"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#3498DB,stroke-width:2px
    classDef worker fill:#E8F8F5,stroke:#1ABC9C,stroke-width:2px
    classDef datastore fill:#F4F6F7,stroke:#7F8C8D,stroke-width:2px
    classDef external fill:#FEF9E7,stroke:#F1C40F,stroke-width:2px
```
