# bookwyrm-social/bookwyrm architecture

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

- Interactive diagram: https://gitdiagram.com/bookwyrm-social/bookwyrm
- Repository: https://github.com/bookwyrm-social/bookwyrm

## Overview

##### Project type and purpose
- BookWyrm is a full-stack, open-source social-reading web application.
- It’s built on Django (Python), backed by PostgreSQL, with federated ActivityPub support, Celery for background tasks, and Redis as both a message broker and activity-stream cache.
- It provides a web UI (Django templates + Bulma CSS + vanilla JS), REST/ActivityPub endpoints, import connectors to external book data services, and a task queue for asynchronous work.

##### File structure
- Top level:
- bookwyrm/ – Django app (models, views, templates, static assets, ActivityPub logic, connector modules, management commands, etc.)
- celerywyrm/ – Celery “microservice” (app definition, worker settings, ASGI entry point)
- Dockerfile, docker-compose.yml – container build and orchestration
- nginx/ – reverse-proxy configs and SSL bootstrap scripts
- manage.py, gunicorn.conf.py – WSGI entry and Django management
- requirements.txt, pyproject.toml – Python dependencies
- Patterns:
- MVC (Django models/views/templates)
- Modular “connectors” for external services (OpenLibrary, Goodreads, etc.)
- ActivityPub endpoints under bookwyrm/activitypub and bookwyrm/views/wellknown
- Celery tasks defined in bookwyrm/tasks.py, celerywyrm/celery.py
- Deployment artifacts:
- docker-compose.yml orchestrates web, worker, Redis, PostgreSQL, Nginx, Flower
- contrib/systemd for running as services on a host

##### README for additional insights
- Tech stack confirms Django + PostgreSQL + Redis + Celery + Gunicorn + Nginx + Docker.
- Federation via ActivityPub—communication with Mastodon/Pleroma and other BookWyrm instances.
- Front end is server-rendered; no SPA, but uses client JS for autocompletion, guided tours, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Client Browser"]:::client

    %% Edge
    subgraph "Edge Layer"
        Nginx["Nginx"]:::edge
    end

    %% Web Service
    subgraph "Django Web App"
        Gunicorn["Gunicorn / Django Web App"]:::backend
        Templates["Templates"]:::frontend
        Static["Static Assets"]:::frontend
        AP_Layer["ActivityPub Layer"]:::backend
        Endpoints["ActivityPub Endpoints"]:::backend
        Connectors["External Connectors"]:::backend
        Importers["Import Pipelines"]:::backend
        TasksDef["Django Task Definitions"]:::backend
        MgmtCmds["Management Commands"]:::backend
    end

    %% Worker
    subgraph "Celery Worker"
        Celery["Celery Worker"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::db
        Redis["Redis"]:::datastore
        CeleryBroker["Redis (Broker)"]:::datastore
    end

    %% External
    subgraph "External Systems"
        BookData["External Book Data"]:::external
        APPeers["ActivityPub Peers"]:::external
    end

    %% Orchestration
    DockerCompose["Docker Compose & Dockerfile"]:::infra

    %% Flows
    Browser -->|"HTTPS"| Nginx
    Nginx -->|"WSGI"| Gunicorn
    Nginx -->|"Static Files"| Static

    Gunicorn -->|"Render UI"| Templates
    Gunicorn -->|"Read/Write"| Postgres
    Gunicorn -->|"Cache/PubSub"| Redis
    Gunicorn -->|"Enqueue Tasks"| CeleryBroker

    Gunicorn -->|"Inbound Federation"| AP_Layer
    AP_Layer -->|"Deliver to Views"| Gunicorn
    Gunicorn -->|"HTTP Metadata"| BookData
    Connectors -->|"HTTP"| BookData
    AP_Layer -->|"Outbound Federation"| APPeers
    APPeers -.->|"Incoming Posts"| Gunicorn

    Gunicorn -->|"Task Definitions"| TasksDef
    Gunicorn -->|"Invoke Importers"| Importers
    Gunicorn -->|"Invoke Connectors"| Connectors
    Gunicorn -->|"Mgmt Operations"| MgmtCmds

    CeleryBroker -->|Broker| Celery
    Celery -->|"Process Tasks"| Postgres
    Celery -->|"Cache/PubSub"| Redis

    %% Orchestration links
    DockerCompose -->|Orchestrates| Nginx
    DockerCompose -->|Orchestrates| Gunicorn
    DockerCompose -->|Orchestrates| Celery
    DockerCompose -->|Orchestrates| Postgres
    DockerCompose -->|Orchestrates| Redis

    %% Click Events
    click Nginx "https://github.com/bookwyrm-social/bookwyrm/tree/main/nginx/"
    click Nginx "https://github.com/bookwyrm-social/bookwyrm/blob/main/nginx/https.conf"
    click Nginx "https://github.com/bookwyrm-social/bookwyrm/blob/main/nginx/reverse_proxy.conf"
    click DockerCompose "https://github.com/bookwyrm-social/bookwyrm/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/bookwyrm-social/bookwyrm/tree/main/Dockerfile"
    click DockerCompose "https://github.com/bookwyrm-social/bookwyrm/tree/main/contrib/systemd/"
    click Redis "https://github.com/bookwyrm-social/bookwyrm/blob/main/docker-compose.yml"
    click Redis "https://github.com/bookwyrm-social/bookwyrm/blob/main/redis.conf"
    click Gunicorn "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/"
    click Gunicorn "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/settings.py"
    click Gunicorn "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/urls.py"
    click Gunicorn "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/wsgi.py"
    click Templates "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/templates/"
    click Static "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/static/"
    click AP_Layer "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/activitypub/"
    click AP_Layer "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/activitypub/base_activity.py"
    click Endpoints "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/views/wellknown.py"
    click Endpoints "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/views/inbox.py"
    click Endpoints "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/views/outbox.py"
    click Connectors "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/connectors/"
    click Connectors "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/connectors/abstract_connector.py"
    click Importers "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/importers/"
    click TasksDef "https://github.com/bookwyrm-social/bookwyrm/blob/main/bookwyrm/tasks.py"
    click MgmtCmds "https://github.com/bookwyrm-social/bookwyrm/tree/main/bookwyrm/management/commands/"
    click Celery "https://github.com/bookwyrm-social/bookwyrm/tree/main/celerywyrm/"
    click Celery "https://github.com/bookwyrm-social/bookwyrm/blob/main/celerywyrm/celery.py"
    click Celery "https://github.com/bookwyrm-social/bookwyrm/blob/main/celerywyrm/apps.py"
    click Celery "https://github.com/bookwyrm-social/bookwyrm/blob/main/celerywyrm/asgi.py"
    click Celery "https://github.com/bookwyrm-social/bookwyrm/blob/main/celerywyrm/wsgi.py"

    %% Styles
    classDef client fill:#e0f7fa,stroke:#006064
    classDef edge fill:#e1f5fe,stroke:#0d47a1
    classDef backend fill:#bbdefb,stroke:#1e88e5
    classDef db fill:#c8e6c9,stroke:#2e7d32
    classDef datastore fill:#dcedc8,stroke:#558b2f
    classDef external fill:#ffe0b2,stroke:#ef6c00
    classDef frontend fill:#f3e5f5,stroke:#6a1b9a
    classDef infra fill:#cfd8dc,stroke:#37474f
```
