# kustoszapp/server architecture

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

- Interactive diagram: https://gitdiagram.com/kustoszapp/server
- Repository: https://github.com/kustoszapp/server

## Overview

##### Project type and purpose
- This is the “Kustosz” backend server: a Django-based, self-hosted, open-source web application backend. It exposes REST APIs, runs scheduled/fetch tasks via Celery, manages a relational database, and is packaged for containerized or systemd/supervisor deployments.

##### File structure
- Top-level:
- kustosz/           ← Django project module (settings, URLs, WSGI/ASGI entrypoints)
- manage.py          ← Django CLI entrypoint
- containers/        ← Dockerfiles, docker-compose.yaml, Kubernetes manifest, local settings
- etc/               ← host-level cron scripts, supervisor and systemd configs
- .celery/           ← persistent queue directory for broker backing store
- tests/             ← unit and API tests
- Key configuration: Dockerfile, docker-compose.yaml, pyproject.toml, settings/*.yaml
- Celery integration: kustosz/celery.py, tasks/ modules, .celery directory

##### README for additional insights
- Confirms backend only, guides to installation and dev docs, mentions self-hosting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client (HTTP)"]:::external

    %% Core Services
    WebService["Django + DRF (Gunicorn/ASGI)"]:::sync
    Database[(“PostgreSQL Database”)]:::sync
    Broker[(“Redis/RabbitMQ Broker”)]:::async
    Workers["Celery Workers"]:::async
    Scheduler["Scheduler (Celery Beat)"]:::async
    ExternalFeeds["External Feed Sources"]:::external
    CronJobs["Cron Jobs (etc/cron)"]:::external

    %% Deployment Runners
    Supervisor["Supervisor/systemd"]:::runner
    ContainerRunner["Docker & Kubernetes"]:::runner

    %% File Structure Subgraphs
    subgraph "Django Project Module"
        DjangoModule["kustosz/ Module"]:::sync
        Manage["manage.py"]:::sync
    end

    subgraph "Web Service Components"
        Views["Views"]:::sync
        Serializers["Serializers"]:::sync
        URLs["URL Routing"]:::sync
        Renderers["Renderers"]:::sync
    end

    subgraph "Database Components"
        Models["Models"]:::sync
        Migrations["Migrations"]:::sync
    end

    subgraph "Broker Components"
        CeleryFS[".celery/queue"]:::async
        RedisConf["etc/supervisor/redis.conf"]:::async
        ComposeBroker["containers/docker-compose.yaml"]:::async
    end

    subgraph "Celery Integration"
        CeleryApp["kustosz/celery.py"]:::async
        Tasks["kustosz/tasks/"]:::async
        FetchCmd["fetch_new_content cmd"]:::async
        BeatMigration["0003_create_celery_beat_…py"]:::async
    end

    subgraph "External Feed Fetchers"
        FeedFetcher["feed.py"]:::external
        URLFetcher["url.py"]:::external
    end

    subgraph "Utility Functions"
        FilterActions["filter_actions.py"]:::sync
        ExtractMeta["extract_metadata.py"]:::sync
        ExtractReadability["extract_readability.py"]:::sync
        Autodetect["autodetect_content.py"]:::sync
        DuplicateFinder["duplicate_finder.py"]:::sync
        OPMLExporter["opml_exporter.py"]:::sync
        RunScript["run_script.py"]:::sync
    end

    subgraph "Deployment & Process Mgmt"
        CronJobs
        Supervisor
        Systemd["etc/systemd/system/kustosz@.service"]:::runner
        Dispatcher["etc/systemd/bin/kustosz-service-dispatcher"]:::runner
        ContainerRunner
    end

    %% Connections
    Client -->|"HTTP"| WebService
    WebService -->|"read/write"| Database
    WebService -->|"enqueue tasks"| Broker
    Broker -->|"deliver tasks"| Workers
    Workers -->|"persist results"| Database
    Scheduler -->|"schedule tasks"| Broker
    ExternalFeeds -->|"polled by tasks"| Workers
    CronJobs -->|"trigger fetch cmd"| FetchCmd
    Supervisor -.-> WebService
    Supervisor -.-> Workers
    Supervisor -.-> Scheduler
    ContainerRunner -.-> WebService
    ContainerRunner -.-> Workers
    ContainerRunner -.-> Scheduler

    %% Internal Structure Links
    WebService --> DjangoModule
    WebService --> Manage
    WebService --> Views
    WebService --> Serializers
    WebService --> URLs
    WebService --> Renderers
    Database --> Models
    Database --> Migrations
    Broker --> CeleryFS
    Broker --> RedisConf
    Broker --> ComposeBroker
    Scheduler --> BeatMigration
    Workers --> CeleryApp
    Workers --> Tasks
    FetchCmd --> CeleryApp
    CeleryApp --> Tasks
    FeedFetcher --> Workers
    URLFetcher --> Workers
    WebService --> FeedFetcher
    WebService --> URLFetcher
    WebService --> FilterActions
    WebService --> ExtractMeta
    WebService --> ExtractReadability
    WebService --> Autodetect
    WebService --> DuplicateFinder
    WebService --> OPMLExporter
    WebService --> RunScript

    %% Click Events
    click DjangoModule "https://github.com/kustoszapp/server/tree/main/kustosz/"
    click Manage "https://github.com/kustoszapp/server/blob/main/manage.py"
    click Views "https://github.com/kustoszapp/server/blob/main/kustosz/views.py"
    click Serializers "https://github.com/kustoszapp/server/blob/main/kustosz/serializers.py"
    click URLs "https://github.com/kustoszapp/server/blob/main/kustosz/urls.py"
    click Renderers "https://github.com/kustoszapp/server/blob/main/kustosz/renderers.py"
    click Models "https://github.com/kustoszapp/server/blob/main/kustosz/models.py"
    click Migrations "https://github.com/kustoszapp/server/tree/main/kustosz/migrations/"
    click CeleryFS "https://github.com/kustoszapp/server/tree/main/.celery/queue/"
    click RedisConf "https://github.com/kustoszapp/server/blob/main/etc/supervisor/redis.conf"
    click ComposeBroker "https://github.com/kustoszapp/server/blob/main/containers/docker-compose.yaml"
    click CeleryApp "https://github.com/kustoszapp/server/blob/main/kustosz/celery.py"
    click Tasks "https://github.com/kustoszapp/server/tree/main/kustosz/tasks/"
    click FetchCmd "https://github.com/kustoszapp/server/blob/main/kustosz/management/commands/fetch_new_content.py"
    click BeatMigration "https://github.com/kustoszapp/server/blob/main/kustosz/migrations/0003_create_celery_beat_20220108_0935.py"
    click FeedFetcher "https://github.com/kustoszapp/server/blob/main/kustosz/fetchers/feed.py"
    click URLFetcher "https://github.com/kustoszapp/server/blob/main/kustosz/fetchers/url.py"
    click FilterActions "https://github.com/kustoszapp/server/blob/main/kustosz/utils/filter_actions.py"
    click ExtractMeta "https://github.com/kustoszapp/server/blob/main/kustosz/utils/extract_metadata.py"
    click ExtractReadability "https://github.com/kustoszapp/server/blob/main/kustosz/utils/extract_readability.py"
    click Autodetect "https://github.com/kustoszapp/server/blob/main/kustosz/utils/autodetect_content.py"
    click DuplicateFinder "https://github.com/kustoszapp/server/blob/main/kustosz/utils/duplicate_finder.py"
    click OPMLExporter "https://github.com/kustoszapp/server/blob/main/kustosz/utils/opml_exporter.py"
    click RunScript "https://github.com/kustoszapp/server/blob/main/kustosz/utils/run_script.py"
    click CronJobs "https://github.com/kustoszapp/server/blob/main/etc/cron/kustosz-fetch-content.sh"
    click Supervisor "https://github.com/kustoszapp/server/blob/main/etc/supervisor/supervisord.conf"
    click Systemd "https://github.com/kustoszapp/server/blob/main/etc/systemd/system/kustosz@.service"
    click Dispatcher "https://github.com/kustoszapp/server/tree/main/etc/systemd/bin/kustosz-service-dispatcher"
    click ContainerRunner "https://github.com/kustoszapp/server/blob/main/containers/docker-compose.yaml"
    
    %% Styles
    classDef sync fill:#B3CDE0,stroke:#0B3D91,color:#000;
    classDef async fill:#FBB4AE,stroke:#B10026,color:#000;
    classDef external fill:#CCEBC5,stroke:#006D2C,color:#000;
    classDef runner stroke-dasharray: 5 5,fill:none,stroke:#555,color:#000;
```
