# sissbruecker/linkding architecture

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

- Interactive diagram: https://gitdiagram.com/sissbruecker/linkding
- Repository: https://github.com/sissbruecker/linkding

## Overview

##### Main Components
- Backend (Django): Represent the “bookmarks” directory as the core application. This component includes models, views, API endpoints (in bookmarks/api), management commands, signals, middlewares, migrations, and the admin panel. It also contains the REST API, authentication routines (including SSO via OIDC/proxies), and the business logic for handling bookmarks, tags, and archiving.
- Database: Although not explicitly detailed in the files, the migration files indicate a persistent database backend (commonly used with Django, likely PostgreSQL). Represent the database as a separate component that the Django backend interacts with.
- DevOps & Deployment: Include components for deployment such as Docker (docker-compose.yml, Dockerfiles), configuration files (uwsgi.ini, supervisord.conf), and GitHub Actions (in .github/workflows) to illustrate continuous integration/deployment.
- Documentation & Assets: Show a side component representing the “docs” directory (documentation built with Astro and Markdown) and assets (logos, design files). This supports developers and end users but is separate from the runtime architecture.
- Testing & Scripts: Represent integration tests (pytest, tests and tests_e2e directories) and custom scripts (in scripts/) for building, releasing, and managing backups, which ensure quality and deployment automation.

##### Relationships and Data Flows
- Backend’s interaction with the Database, especially for CRUD operations on bookmarks, tags, and user profiles.
- Flow for asynchronous or background processes – for example, the management commands (backup, auto-tagging, asset caching) and service integrations (e.g., Internet Archive integration for archiving websites).

##### Architectural Patterns and Design Principles
- Model-View-Controller (or model–template–view in Django) pattern used in the backend. Show separation between data (models), presentation (templates, static assets) and control (views, APIs).
- Call out the integration of a REST API layer that supports external integrations and browser-based API consumption.
- Clear separation between development tasks (Node.js for frontend asset building) and the runtime server (Django), which is a crucial design element.

##### Relevant Technologies
- Backend: Python 3.12, Django (with its built-in ORM, middleware, and templating system). Also note Django-specific aspects such as migrations, signals, and management commands.
- Frontend: Node.js, npm, Svelte components, and JavaScript utilities for handling dynamic UI behaviors.
- Database: Likely PostgreSQL (inferred from standard Django usage and Docker configurations).
- Docker & DevOps: Docker Compose, Dockerfiles, GitHub workflows, and scripting for deployment and testing.

##### Specific Elements
- Clear Labels: Each component should be clearly labeled (e.g., “Django Backend – Bookmarks Application”, “Frontend – JavaScript & Svelte Components”, “Database”, “CI/CD & Docker Infrastructure”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        A["Browser"]:::client
    end

    subgraph "Frontend Layer"
        B["Frontend – JavaScript & Svelte Components"]:::frontend
    end

    subgraph "Backend Layer"
        C["Django Backend – Bookmarks Application"]:::backend
        D["API Endpoints & Authentication"]:::backend
        E["Database (PostgreSQL)"]:::database
    end

    subgraph "Infrastructure & Testing"
        F["CI/CD & Docker Infrastructure"]:::devops
        H["Testing & Scripts"]:::tests
        G["Documentation & Design Assets"]:::documentation
    end

    A -->|"HTTPRequests"| B
    B -->|"APICalls"| C
    C -->|"RESTAPI"| D
    C -->|"CRUD"| E
    C -->|"Deployment"| F
    F -->|"RunTests"| H
    A -->|"UserGuide"| G

    click B "https://github.com/sissbruecker/linkding/tree/master/bookmarks/frontend/"
    click C "https://github.com/sissbruecker/linkding/tree/master/bookmarks/"
    click D "https://github.com/sissbruecker/linkding/tree/master/bookmarks/api/"
    click E "https://github.com/sissbruecker/linkding/tree/master/bookmarks/migrations/"
    click F "https://github.com/sissbruecker/linkding/tree/master/docker/"
    click F "https://github.com/sissbruecker/linkding/blob/master/docker-compose.yml"
    click F "https://github.com/sissbruecker/linkding/tree/master/.github/workflows/"
    click G "https://github.com/sissbruecker/linkding/tree/master/docs/"
    click G "https://github.com/sissbruecker/linkding/tree/master/assets/"
    click H "https://github.com/sissbruecker/linkding/tree/master/bookmarks/tests/"
    click H "https://github.com/sissbruecker/linkding/tree/master/bookmarks/tests_e2e/"
    click H "https://github.com/sissbruecker/linkding/tree/master/scripts/"

    classDef client fill:#fff799,stroke:#8f8f2d,stroke-width:2px;
    classDef frontend fill:#9fdf9f,stroke:#2d7a2d,stroke-width:2px;
    classDef backend fill:#9fcfdf,stroke:#2d5a7a,stroke-width:2px;
    classDef database fill:#ffd27f,stroke:#a67a2d,stroke-width:2px;
    classDef devops fill:#cfaaff,stroke:#7a2d8a,stroke-width:2px;
    classDef documentation fill:#fdfd9f,stroke:#7a7a2d,stroke-width:2px;
    classDef tests fill:#d3d3d3,stroke:#696969,stroke-width:2px;
```
