# bihealth/digestiflow-server architecture

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

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

## Overview

##### Main Components
- Web Application Server:
- Django project (including manage.py, the settings in config/settings, and the main URL routing in config/urls.py and config/wsgi.py).
- That each app has its own models, views, forms, templates, APIs (with subdirectories named “api”) and administrative interfaces.

- REST API Layer:
- That the same Django application exposes REST API endpoints (located in the api directories of each app) that handle external communications and integrate with the Digestiflow CLI and Demux projects.

- Database:
- Central database component (typically a SQL database such as PostgreSQL) that holds flow cell, library, and user data.

- Background Processing:
- Celery worker setup, indicated by the config/celery.py file and task modules (e.g., tasks in fileboxes and flowcells).
- That the Celery system processes asynchronous tasks (such as notifications, demultiplexing triggers, or email delivery using templates from the mails folders).

- Static Assets & Frontend Resources:
- That an Nginx (or similar) reverse proxy (configured in docker/config/nginx) is used in the Docker deployment for serving static files and forwarding requests to the Django application.

- External Integration Points:
- Connectivity to external tools:
- Digestiflow CLI: which extracts metadata and automatically registers new flowcells.
- Digestiflow Demux: which uses sample sheets from the server to run the demultiplexing process.

##### Component Interactions
- Web Clients (Browsers):
- Users interact with the web UI served by the Django application.
- Bi-directional data flow between the web client and the REST API when performing operations like creating or updating flow cell records.
- API Communication:
- Background Services:
- Data Persistence:

##### Architectural Patterns and Design Principles
- Modularity via Django Apps:
- That functionality is divided into distinct apps (barcodes, fileboxes, flowcells, sequencers) for separation of concerns.
- Use of Standard MVC/MVT:
- How models, views, and templates form the basis of the web UI and REST API responses.
- Asynchronous Processing:
- Presence of Celery for background task handling.
- RESTful API Design:
- Specify that the API layer is used both for external client interactions (Digestiflow CLI and Demux) and internal integrations.

##### Relevant Technologies and Frameworks
- Python and Django Framework:
- Django project structure including settings, URLs, and the management commands.
- Celery:
- Docker:
- That Docker (including the provided Dockerfile, docker-entrypoint, and Nginx configurations) is used for deployment.
- Frontend Resources:
- Mention static files management (CSS, JavaScript, and templates) as part of the UI layer.
- Testing and Continuous Integration:
- Existence of tests in various apps and CI configuration files (.travis.yml, .gitlab-ci.yml).

##### Detail the Essential Architectural Elements
- Precisely show how the different Django apps (barcodes, fileboxes, flowcells, sequencers) are integrated under a single project.
- Layered design: presentation layer (templates/static files), application layer (Django views and API), service layer (Celery, CLI interactions), and the persistence layer (database).
- Where external scripts (e.g., management commands and shell scripts in the utility directory) fit into the deployment or operational lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        browser["User Browser"]:::web
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        dockerfile["Dockerfile"]:::infra
        dockerEntrypoint["Docker Entry Point"]:::infra
        nginxConf["Nginx Config"]:::infra
        nginx["Docker/Nginx Reverse Proxy"]:::proxy
        dockerfile --> nginx
        dockerEntrypoint --> nginx
        nginxConf --> nginx
    end

    %% Application Core: Digestiflow Server (Django)
    subgraph "Application Core: Digestiflow Server (Django)"
        %% Django Core
        subgraph "Django Core"
            managepy["manage.py"]:::django
            configSettings["config/settings"]:::django
            configUrls["config/urls.py"]:::django
            configWsgi["config/wsgi.py"]:::django
        end

        %% Django Apps
        subgraph "Django Apps"
            barcodes["Barcodes App"]:::app
            fileboxes["Fileboxes App"]:::app
            flowcells["Flowcells App"]:::app
            sequencers["Sequencers App"]:::app
        end

        %% API Endpoints
        subgraph "API Endpoints"
            barcodesAPI["Barcodes API"]:::api
            fileboxesAPI["Fileboxes API"]:::api
            flowcellsAPI["Flowcells API"]:::api
            sequencersAPI["Sequencers API"]:::api
        end

        %% Background Processing
        subgraph "Background Processing"
            celeryConfig["Celery Config: config/celery.py"]:::celery
            fileboxesTasks["Fileboxes Tasks: fileboxes/tasks.py"]:::celery
            flowcellsTasks["Flowcells Tasks: flowcells/tasks.py"]:::celery
            celeryWorker["Celery Worker"]:::celery
            celeryConfig --> celeryWorker
            fileboxesTasks --> celeryWorker
            flowcellsTasks --> celeryWorker
        end

        %% Frontend Assets
        subgraph "Frontend Assets"
            staticFiles["Static Files"]:::app
            templates["Templates"]:::app
        end

        %% Database
        database["PostgreSQL Database"]:::db
    end

    %% External Integration
    subgraph "External Integration"
        externalClients["External Clients (Digestiflow CLI / Demux)"]:::external
    end

    %% Connections
    browser --> nginx
    nginx --> configUrls
    nginx --> staticFiles
    staticFiles --> browser

    %% Routing from Django Core to Apps
    configUrls --> barcodes
    configUrls --> fileboxes
    configUrls --> flowcells
    configUrls --> sequencers

    %% Apps expose their API endpoints
    barcodes --> barcodesAPI
    fileboxes --> fileboxesAPI
    flowcells --> flowcellsAPI
    sequencers --> sequencersAPI

    %% External clients interact via the APIs
    externalClients --> barcodesAPI
    externalClients --> fileboxesAPI
    externalClients --> flowcellsAPI
    externalClients --> sequencersAPI

    %% Background task invocation from apps
    fileboxes --> fileboxesTasks
    flowcells --> flowcellsTasks

    %% Data persistence flows
    configUrls --> database
    barcodes --> database
    fileboxes --> database
    flowcells --> database
    sequencers --> database
    celeryWorker --> database

    %% Styles
    classDef web fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef proxy fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef django fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef app fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef api fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef celery fill:#FFECB3,stroke:#F57C00,stroke-width:2px;
    classDef db fill:#CFD8DC,stroke:#607D8B,stroke-width:2px;
    classDef infra fill:#FFE0B2,stroke:#FF9800,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;

    %% Click Events for Django Core
    click managepy "https://github.com/bihealth/digestiflow-server/blob/main/manage.py"
    click configSettings "https://github.com/bihealth/digestiflow-server/tree/main/config/settings"
    click configUrls "https://github.com/bihealth/digestiflow-server/blob/main/config/urls.py"
    click configWsgi "https://github.com/bihealth/digestiflow-server/blob/main/config/wsgi.py"

    %% Click Events for Django Apps
    click barcodes "https://github.com/bihealth/digestiflow-server/tree/main/barcodes"
    click fileboxes "https://github.com/bihealth/digestiflow-server/tree/main/fileboxes"
    click flowcells "https://github.com/bihealth/digestiflow-server/tree/main/flowcells"
    click sequencers "https://github.com/bihealth/digestiflow-server/tree/main/sequencers"

    %% Click Events for API Endpoints
    click barcodesAPI "https://github.com/bihealth/digestiflow-server/tree/main/barcodes/api"
    click fileboxesAPI "https://github.com/bihealth/digestiflow-server/tree/main/fileboxes/api"
    click flowcellsAPI "https://github.com/bihealth/digestiflow-server/tree/main/flowcells/api"
    click sequencersAPI "https://github.com/bihealth/digestiflow-server/tree/main/sequencers/api"

    %% Click Events for Background Processing
    click celeryConfig "https://github.com/bihealth/digestiflow-server/blob/main/config/celery.py"
    click fileboxesTasks "https://github.com/bihealth/digestiflow-server/blob/main/fileboxes/tasks.py"
    click flowcellsTasks "https://github.com/bihealth/digestiflow-server/blob/main/flowcells/tasks.py"

    %% Click Events for Frontend Assets
    click staticFiles "https://github.com/bihealth/digestiflow-server/tree/main/digestiflow/static"
    click templates "https://github.com/bihealth/digestiflow-server/tree/main/digestiflow/templates"

    %% Click Event for External Integration
    click externalClients "https://github.com/bihealth/digestiflow-server/tree/main/fileboxes-cli"

    %% Click Events for Deployment & Infrastructure
    click dockerfile "https://github.com/bihealth/digestiflow-server/tree/main/docker/Dockerfile"
    click dockerEntrypoint "https://github.com/bihealth/digestiflow-server/blob/main/docker/docker-entrypoint.sh"
    click nginxConf "https://github.com/bihealth/digestiflow-server/blob/main/docker/config/nginx/nginx.conf"
```
