# italo0072/misago architecture

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

- Interactive diagram: https://gitdiagram.com/italo0072/misago
- Repository: https://github.com/italo0072/misago

## Overview

##### Project type and purpose
- Misago is a full-stack, containerized forum application.
- Backend: Django (multiple reusable apps, REST & GraphQL APIs, OAuth2 client, admin panel).
- Frontend: React.js SPA (webpack-built assets under frontend/).
- Asynchronous tasks: Celery.
- Persistence: PostgreSQL (ORM), Redis (cache, broker).
- Features: user accounts, content threads, categories, notifications, search, attachments, theming.

##### File structure
- Top level:
- docker-compose.yaml, Dockerfile → container definitions (web, worker, db, cache).
- dev/ → dev helper script for local setup.
- frontend/ → React source, components, webpack config.
- devproject/ & misago/ → Django project config and apps.
- manage.py → Django entrypoint.
- Django code organized into apps: acl, users, threads, notifications, etc.
- Celery config in devproject/celery.py and misago/notifications/tasks.py.
- API endpoints under misago/apiv2/, misago/graphql/, plus Django templated admin under misago/admin.

##### README for insights
- Backend serves both HTML (admin, public pages) and JSON endpoints for SPA.
- Docker‐based development: web container + db + redis + optional mail / search services.
- Frontend built and deployed into Django’s static/ directory.

##### Main components
a. Browser (User & Admin)
b. React SPA (frontend assets served as static)
c. Django WSGI server (gunicorn/uWSGI)
d. REST/GraphQL API layer
e. Celery Worker(s)
f. Redis (cache + broker)
g. PostgreSQL
h. External services: OAuth providers, SMTP/email, third-party search or analytics.

##### Relationships & interactions
- Browser → HTTP(S) → Django (serves HTML pages & initial index.html + static JS/CSS).
- React app in browser → AJAX/GraphQL → Django API.
- Django API → ORM → PostgreSQL (reads & writes).
- Django → Redis (caching, session storage, real-time pub/sub if used).
- Django → Celery (enqueue jobs for email, notifications, read-tracking).
- Celery → Redis (broker) and Celery → PostgreSQL (job results if configured).
- Celery → external SMTP or notification services.
- OAuth flows: Browser ↔ OAuth provider ↔ Django OAuth2 client.

##### Architectural patterns & design principles
- Layered architecture (Presentation / API / Business logic / Data).
- Modular Django apps (plugin-like separation of concerns).
- SPA decoupled from backend.
- Asynchronous “fire-and-forget” via Celery tasks.
- Configuration via 12-factor (docker + environment variables).
- Docker Compose orchestrates multi-container setup.

##### Technologies & frameworks
- Backend: Python 3.11, Django, DRF, Graphene (GraphQL), Celery.
- Broker & Cache: Redis.
- Database: PostgreSQL.
- Frontend: React.js, Babel, webpack, ESLint, Prettier.
- Containerization: Docker, Docker Compose.
- CI: GitHub Actions (tests.yml, publish.yml).

##### Final remarks
- Be detailed: include key Django apps if needed (e.g., notifications, threads).
- Don’t overthink: more components = better clarity.
- Essential elements: build pipeline (npm → webpack → static), API, data stores, task queue.
- Review against README and file structure to verify no major component is omitted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Services
    subgraph "Docker Compose"
        direction TB
        WebService["Web (gunicorn/uWSGI)"]:::compute
        WorkerService["Worker (Celery)"]:::compute
        DB["PostgreSQL"]:::db
        Cache["Redis"]:::db
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser(("Browser")):::browser
        ReactSPA["React SPA"]:::frontend
        Webpack["Webpack Config"]:::tools
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        WSGI["Django WSGI Server"]:::compute
        CLI["manage.py"]:::tools
        subgraph "API Layer"
            direction TB
            RESTAPI["REST API"]:::api
            GraphQLAPI["GraphQL API"]:::api
        end
        OAuthClient["OAuth2 Client"]:::backend
        subgraph "Admin Panel"
            direction TB
            AdminBE["Admin Backend"]:::backend
            AdminFE["Admin Frontend"]:::frontend
        end
        subgraph "Django Apps"
            direction TB
            Users["Users"]:::app
            Threads["Threads"]:::app
            Categories["Categories"]:::app
            NotificationsCore["Notifications Core"]:::app
            SearchApp["Search"]:::app
            Markup["Markup"]:::app
            Plugins["Plugins"]:::app
            Themes["Themes"]:::app
            CacheApp["Cache Layer"]:::app
            ReadTracker["ReadTracker"]:::app
            SocialAuth["SocialAuth"]:::app
            Conf["Conf/Settings"]:::app
            Analytics["Analytics"]:::app
            Healthcheck["Healthcheck"]:::app
            CoreUtilities["Core Utilities"]:::app
            Locale["Locale"]:::app
            StaticAssets["Static Assets"]:::app
            Templates["Templates"]:::app
            Settings["Settings & URLs"]:::app
        end
        CeleryConfig["Celery Config"]:::tools
        NotificationTasks["Notification Tasks"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAuthProviders["OAuth2 Providers"]:::external
        SMTP["SMTP / Email"]:::external
        ThirdSearch["3rd-Party Search"]:::external
        AnalyticsExt["Analytics"]:::external
    end

    %% Build & Deployment
    Dockerfile["Dockerfile"]:::tools
    Compose["docker-compose.yaml"]:::tools

    %% Connections
    Browser -->|loads| ReactSPA
    Webpack -->|builds| StaticAssets
    ReactSPA -->|AJAX/REST| RESTAPI
    ReactSPA -->|AJAX/GraphQL| GraphQLAPI
    Browser -->|HTTP GET| WSGI
    WSGI -->|serves static| ReactSPA
    WSGI -->|calls| RESTAPI
    WSGI -->|calls| GraphQLAPI
    RESTAPI -->|reads/writes| DB
    GraphQLAPI -->|reads/writes| DB
    WSGI -->|caches| Cache
    RESTAPI -->|caches| Cache
    GraphQLAPI -->|caches| Cache
    WSGI -->|enqueues| WorkerService
    WorkerService -->|broker| Cache
    WorkerService -->|reads/writes| DB
    WorkerService -->|executes| NotificationTasks
    NotificationTasks -->|send| SMTP
    Browser -->|auth flow| OAuthProviders
    OAuthProviders -->|callback| OAuthClient
    WSGI -->|uses| OAuthClient
    Compose -->|orchestrates| WebService
    Compose -->|orchestrates| WorkerService
    Compose -->|orchestrates| DB
    Compose -->|orchestrates| Cache
    Dockerfile -->|builds| WebService
    Dockerfile -->|builds| WorkerService
    WSGI -->|configured by| CeleryConfig
    WSGI -->|runs| CLI

    %% Click Events
    click ReactSPA "https://github.com/italo0072/misago/tree/main/frontend/"
    click Webpack "https://github.com/italo0072/misago/blob/main/frontend/webpack.config.js"
    click WSGI "https://github.com/italo0072/misago/blob/main/devproject/wsgi.py"
    click CLI "https://github.com/italo0072/misago/blob/main/manage.py"
    click Compose "https://github.com/italo0072/misago/blob/main/docker-compose.yaml"
    click Dockerfile "https://github.com/italo0072/misago/tree/main/Dockerfile"
    click CeleryConfig "https://github.com/italo0072/misago/blob/main/devproject/celery.py"
    click NotificationTasks "https://github.com/italo0072/misago/blob/main/misago/notifications/tasks.py"
    click RESTAPI "https://github.com/italo0072/misago/tree/main/misago/apiv2/"
    click GraphQLAPI "https://github.com/italo0072/misago/tree/main/misago/graphql/"
    click OAuthClient "https://github.com/italo0072/misago/tree/main/misago/oauth2/"
    click AdminBE "https://github.com/italo0072/misago/tree/main/misago/admin/"
    click AdminFE "https://github.com/italo0072/misago/tree/main/misago/admin/src/"
    click Users "https://github.com/italo0072/misago/tree/main/misago/users/"
    click Threads "https://github.com/italo0072/misago/tree/main/misago/threads/"
    click Categories "https://github.com/italo0072/misago/tree/main/misago/categories/"
    click NotificationsCore "https://github.com/italo0072/misago/tree/main/misago/notifications/"
    click SearchApp "https://github.com/italo0072/misago/tree/main/misago/search/"
    click Markup "https://github.com/italo0072/misago/tree/main/misago/markup/"
    click Plugins "https://github.com/italo0072/misago/tree/main/misago/plugins/"
    click Themes "https://github.com/italo0072/misago/tree/main/misago/themes/"
    click CacheApp "https://github.com/italo0072/misago/tree/main/misago/cache/"
    click ReadTracker "https://github.com/italo0072/misago/tree/main/misago/readtracker/"
    click SocialAuth "https://github.com/italo0072/misago/tree/main/misago/socialauth/"
    click Conf "https://github.com/italo0072/misago/tree/main/misago/conf/"
    click Analytics "https://github.com/italo0072/misago/tree/main/misago/analytics/"
    click Healthcheck "https://github.com/italo0072/misago/tree/main/misago/healthcheck/"
    click CoreUtilities "https://github.com/italo0072/misago/tree/main/misago/core/"
    click Locale "https://github.com/italo0072/misago/tree/main/misago/locale/"
    click StaticAssets "https://github.com/italo0072/misago/tree/main/misago/static/"
    click Templates "https://github.com/italo0072/misago/tree/main/misago/templates/"
    click Settings "https://github.com/italo0072/misago/blob/main/misago/settings.py"
    click Settings "https://github.com/italo0072/misago/blob/main/misago/urls.py"

    %% Styles
    classDef compute fill:#D0E6FF,stroke:#0366d6,stroke-width:1px
    classDef db fill:#DFFFE0,stroke:#28a745,stroke-width:1px
    classDef external fill:#FFE7D9,stroke:#d73a49,stroke-width:1px
    classDef frontend fill:#FFF5C4,stroke:#dbab09,stroke-width:1px
    classDef api fill:#E6D5FF,stroke:#6f42c1,stroke-width:1px
    classDef tools fill:#F0F0F0,stroke:#6a737d,stroke-width:1px
    classDef app fill:#E8F0FF,stroke:#0366d6,stroke-width:1px
    classDef browser fill:#FFF7E6,stroke:#dbab09,stroke-width:1px
```
