# activist-org/activist architecture

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

- Interactive diagram: https://gitdiagram.com/activist-org/activist
- Repository: https://github.com/activist-org/activist

## Overview

##### Project type and purpose
- This is a full-stack, open-source activism platform (“activist.org”) comprised of:
- A Nuxt 3/Vue 3 SPA/SSR frontend (TypeScript, Tailwind CSS, i18n)
- A Django REST API backend (multiple Django “apps” for auth, communities, content, events, utils)
- A PostgreSQL database and Redis for caching/session support
- Containerized deployment (Docker Compose), CI/CD pipelines (GitHub Actions, Netlify), and integrations (Plausible analytics, Weblate, Matrix chat).

##### File structure
- Top-level directories:
- backend/ → Django project subdivided into core, authentication, communities, content, events, utils, management commands, settings, migrations, tests
- frontend/ → Nuxt 3 project with pages/, components/, composables/, stores/, test suites (Vitest, Playwright), configuration files (nuxt.config.ts, tailwind.config.ts)
- .github/ & workflows → CI definitions for backend, frontend, i18n, security scans
- docker-compose.yml + Dockerfiles → local dev orchestration
- Architectural patterns:
- Django’s MVC (apps as modules) feeding a REST API
- Nuxt’s filesystem-based routing and component hierarchy
- Clear separation of concerns: UI vs. business logic vs. data layer
- Deployment/infra artifacts: Docker Compose, Netlify site for frontend, Django admin & Swagger UI, external translation service (Weblate), analytics (Plausible).

##### Extract extra insights from the README
- Tech stack recap: Django 5, Nuxt 3, Vue 3, Tailwind 3, PostgreSQL, Docker, Netlify, Vitest, Weblate, Plausible
- Features/modules: Organizations, Events, Resources, Discussions, Tasks, Affiliations, Votes
- CI: GitHub Actions for linting, tests, security scans, E2E
- Developer tools: pre-commit hooks, Matrix chat, Figma designs

a. Main components:
- Client (browser/mobile)
- Frontend (Nuxt 3 Server + SPA)
- API Gateway / REST API (Django)
- Data stores: PostgreSQL, Redis
- Media storage (local mount or S3-style)
- External services: Plausible, Weblate, Matrix, Figma (design), GitHub Actions, Netlify
- Docker Compose orchestrator / containers
b. Relationships and data flow:
- Client → Frontend (HTTP/HTTPS)
- Frontend → Django API (JSON over HTTP)
- Django → PostgreSQL (SQL)
- Django → Redis (caching, sessions)
- Frontend & Django → External services (analytics, i18n, chat)
- CI pipelines → Build & deploy Frontend to Netlify, Backend Docker images
c. Architectural patterns & design principles:
- Monolithic Django API with modular apps (separate “subsystems” for auth, communities, content, events)
- Component-driven UI (Vue components + composables)
- Containerization for isolation & reproducible dev/test/prod environments
- Clear separation: presentation vs. business vs. persistence layers
- Automated CI/CD and security scanning
d. Key technologies & libraries:
- Frontend: Nuxt 3, Vue 3, TypeScript, Tailwind, Headless UI, Playwright, Vitest
- Backend: Django REST Framework, PostgreSQL, Redis, Docker, pre-commit, Celery? (if used)
- DevOps: Docker Compose, GitHub Actions, Netlify, OWASP ZAP, Zap local scans
- i18n: Nuxt I18n + Weblate
- Analytics: Plausible

##### Elements
- Blue for UI/browser components
- Green for application servers/services
- Orange for data stores
- Gray for external third-party services

##### Detail without over-splitting
- I18n pipeline: source code → Weblate → localized assets delivered by frontend.
- Management/CI flow: GitHub Actions → Docker images → deploy to Netlify (frontend) & hosting (backend).
- Testing layers: Vitest (frontend), Pytest (backend), Playwright E2E.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    Browser["Browser / Mobile Client"]:::ui

    %% Local Dev Environment
    subgraph "Local Dev Environment (Docker Compose)"
        direction TB

        DockerCompose["Docker Compose"]:::service
        click DockerCompose "https://github.com/activist-org/activist/blob/main/docker-compose.yml"

        subgraph "Frontend Container"
            direction TB
            NuxtApp["Nuxt 3 Frontend"]:::service
            click NuxtApp "https://github.com/activist-org/activist/tree/main/frontend/"

            NuxtConfig["nuxt.config.ts"]:::service
            click NuxtConfig "https://github.com/activist-org/activist/blob/main/frontend/nuxt.config.ts"
            TailwindConfig["tailwind.config.ts"]:::service
            click TailwindConfig "https://github.com/activist-org/activist/blob/main/frontend/tailwind.config.ts"
            Pages["pages/"]:::service
            click Pages "https://github.com/activist-org/activist/tree/main/frontend/pages/"
            Components["components/"]:::service
            click Components "https://github.com/activist-org/activist/tree/main/frontend/components/"
            Stores["stores/"]:::service
            click Stores "https://github.com/activist-org/activist/tree/main/frontend/stores/"
            Composables["composables/"]:::service
            click Composables "https://github.com/activist-org/activist/tree/main/frontend/composables/"
            I18nConfig["i18n.config.ts"]:::service
            click I18nConfig "https://github.com/activist-org/activist/blob/main/frontend/i18n.config.ts"
            I18nDir["i18n/"]:::service
            click I18nDir "https://github.com/activist-org/activist/tree/main/frontend/i18n/"
            E2ETests["test-e2e/"]:::service
            click E2ETests "https://github.com/activist-org/activist/tree/main/frontend/test-e2e/"
            UnitTests["test/ & vitest.config.mts"]:::service
            click UnitTests "https://github.com/activist-org/activist/blob/main/frontend/vitest.config.mts"
            FrontendDockerfile["Dockerfile"]:::service
            click FrontendDockerfile "https://github.com/activist-org/activist/tree/main/frontend/Dockerfile"
        end

        subgraph "Backend Container"
            direction TB
            DjangoAPI["Django REST API"]:::service
            click DjangoAPI "https://github.com/activist-org/activist/tree/main/backend/"

            CoreProject["core/"]:::service
            click CoreProject "https://github.com/activist-org/activist/tree/main/backend/core/"
            Settings["settings.py & custom_settings.py"]:::service
            click Settings "https://github.com/activist-org/activist/blob/main/backend/core/settings.py"
            click Settings "https://github.com/activist-org/activist/blob/main/backend/core/custom_settings.py"
            EntryPoints["asgi.py & wsgi.py"]:::service
            click EntryPoints "https://github.com/activist-org/activist/blob/main/backend/core/asgi.py"
            click EntryPoints "https://github.com/activist-org/activist/blob/main/backend/core/wsgi.py"

            AuthApp["authentication/"]:::service
            click AuthApp "https://github.com/activist-org/activist/tree/main/backend/authentication/"
            CommunitiesApp["communities/"]:::service
            click CommunitiesApp "https://github.com/activist-org/activist/tree/main/backend/communities/"
            ContentApp["content/"]:::service
            click ContentApp "https://github.com/activist-org/activist/tree/main/backend/content/"
            EventsApp["events/"]:::service
            click EventsApp "https://github.com/activist-org/activist/tree/main/backend/events/"
            UtilsApp["utils/"]:::service
            click UtilsApp "https://github.com/activist-org/activist/tree/main/backend/utils/"

            Migrations["migrations/"]:::service
            Fixtures["fixtures/"]:::service
            MediaStorage["media/images/"]:::data
            click MediaStorage "https://github.com/activist-org/activist/tree/main/backend/media/images/"
            ManagementCmds["management/commands/"]:::service
            click ManagementCmds "https://github.com/activist-org/activist/tree/main/backend/core/management/commands/"
            BackendDockerfile["Dockerfile"]:::service
            click BackendDockerfile "https://github.com/activist-org/activist/tree/main/backend/Dockerfile"
            RedisDoc["REDIS_IMPLEMENTATION.md"]:::service
            click RedisDoc "https://github.com/activist-org/activist/blob/main/backend/REDIS_IMPLEMENTATION.md"
        end

        subgraph "Data Layer"
            direction TB
            Postgres["PostgreSQL Database"]:::data
            Redis["Redis Cache / Session Store"]:::data
        end

        %% Container connections
        DockerCompose --> FrontendDockerfile
        DockerCompose --> BackendDockerfile

        FrontendDockerfile --> NuxtApp
        BackendDockerfile --> DjangoAPI

    end

    %% Cloud Services
    subgraph "Cloud & External Services"
        direction TB
        Netlify["Netlify (Frontend Hosting)"]:::external
        GitHubActions["GitHub Actions CI/CD"]:::external
        Plausible["Plausible Analytics"]:::external
        Weblate["Weblate i18n Service"]:::external
        MatrixChat["Matrix Chat"]:::external
        Figma["Figma Designs"]:::external
    end

    %% Main Flow
    Browser -->|"HTTP/HTTPS"| NuxtApp
    NuxtApp -->|"API Calls (JSON)"| DjangoAPI
    DjangoAPI -->|"SQL Queries"| Postgres
    DjangoAPI -->|"Cache / Sessions"| Redis
    NuxtApp -->|"Analytics Events"| Plausible
    NuxtApp -->|"Translation API"| Weblate
    NuxtApp -->|"Chat Integration"| MatrixChat
    DjangoAPI -->|"Logging/Events"| MatrixChat

    GitHubActions -->|"CI: Build & Test"| FrontendDockerfile
    GitHubActions -->|"CI: Build & Test"| BackendDockerfile
    GitHubActions -->|"Deploy Frontend"| Netlify
    GitHubActions -->|"Deploy Backend"| DockerCompose

    %% Docker Compose runtime connections
    NuxtApp --- Postgres
    NuxtApp --- Redis
    DjangoAPI --- MediaStorage

    %% Classes
    classDef ui fill:#D0E8FF,stroke:#0284C7,color:#000
    classDef service fill:#D1FAE5,stroke:#059669,color:#000
    classDef data fill:#FFEDD5,stroke:#F97316,color:#000
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#000
```
