# bibbox/sys-bibbox architecture

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

- Interactive diagram: https://gitdiagram.com/bibbox/sys-bibbox
- Repository: https://github.com/bibbox/sys-bibbox

## Overview

##### Project Type and Purpose
- This is a containerized, full-stack, modular web application (“BIBBOX Framework”) for deploying and managing bioinformatics apps.
- It comprises an Angular single-page frontend, a Flask-based Python backend, background task workers, several infrastructure services (DB, cache/message broker, auth, monitoring), and an HTTP/TCP proxy layer.

##### File Structure Analysis
- Top-level folders:
- frontend/ – Angular client code, build scripts, Dockerfile
- backend/ – Flask app (WSGI entrypoints, API modules, Celery tasks, services, models), Dockerfile, uWSGI, Celery config
- apacheproxy/, nginx/, postgresql/, keycloak/, redis (implied in compose) – per-service Dockerfiles and configs
- config-templates/, proxy-configs/, fdp-configs/ – templated configuration for deployment
- docker-compose*.yml – development and production service orchestration
- CI/CD workflows under .github/workflows for Node.js, Docker image build & publish, deployment.
- README describes a multi-container Docker environment with key components: apacheproxy, backend (Flask), celery, postgres, redis, keycloak, adminer, cadvisor.

##### Key Architecture Insights from README
- Each major service runs in its own Docker container, orchestrated via Docker Compose on a shared network.
- The Angular frontend is served by apacheproxy (HTTPD) which also proxies API calls to Flask.
- Flask backend exposes REST endpoints, connects to Postgres (activity, logs, users), and to Redis (celery broker).
- Celery workers pick up background jobs from Redis.
- Keycloak provides OAuth2/OpenID authentication; Angular and Flask both integrate with it.
- Adminer and cadvisor run as auxiliary containers for DB management and container monitoring.

##### Depth & Detail
- Essential containers as separate nodes.
- Internal subcomponents only where critical (e.g., Celery beat vs. worker).
- Environment-specific overrides if useful (dev vs. prod compose).
- Don’t overcomplicate – group closely related files/services under the same block.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Tier
    subgraph "UI Tier"
        Angular["Angular SPA"]:::frontend
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        apache["apacheproxy (HTTPD)"]:::proxy
        nginxp["nginx (optional)"]:::proxy
    end

    %% Service Tier
    subgraph "Service Tier"
        Flask["Flask API (uWSGI)"]:::service
        CeleryWorker["Celery Workers"]:::service
    end

    %% Data Tier
    subgraph "Data Tier"
        Postgres["PostgreSQL DB"]:::data
        Redis["Redis Broker"]:::data
    end

    %% Auth Tier
    subgraph "Auth Tier"
        Keycloak["Keycloak Server"]:::infra
    end

    %% Monitoring Tools
    subgraph "Monitoring / Tools"
        Adminer["Adminer"]:::infra
        CeleryMon["Celery Monitor"]:::infra
        Cadvisor["cAdvisor"]:::infra
    end

    %% Connections
    Angular -->|"HTTP/S REST"| apache
    apache -->|"proxy API calls"| Flask
    ApacheStatic["Static Assets"]:::frontend -.-> apache
    Flask -->|"SQL (5432)"| Postgres
    Flask -->|"AMQP/Redis"| Redis
    Redis -->|"tasks"| CeleryWorker
    CeleryWorker -->|"reads/writes"| Postgres
    Angular -->|"OAuth2/OpenID"| Keycloak
    Flask -->|"OAuth2/OpenID"| Keycloak
    Adminer -->|"SQL"| Postgres
    CeleryMon -->|"metrics"| CeleryWorker
    Cadvisor -->|"container metrics"| Cadvisor

    %% Click Events - UI Tier
    click Angular "https://github.com/bibbox/sys-bibbox/tree/master/frontend/"
    click Angular "https://github.com/bibbox/sys-bibbox/tree/master/frontend/src/"
    click Angular "https://github.com/bibbox/sys-bibbox/tree/master/frontend/Dockerfile"
    click Angular "https://github.com/bibbox/sys-bibbox/blob/master/frontend/build.sh"

    %% Click Events - Proxy Layer
    click apache "https://github.com/bibbox/sys-bibbox/tree/master/apacheproxy/Dockerfile"
    click apache "https://github.com/bibbox/sys-bibbox/blob/master/apacheproxy/httpd.conf"
    click apache "https://github.com/bibbox/sys-bibbox/blob/master/apacheproxy/httpd.conf.template"
    click nginxp "https://github.com/bibbox/sys-bibbox/tree/master/nginx/Dockerfile"
    click nginxp "https://github.com/bibbox/sys-bibbox/blob/master/nginx/timeout.conf"

    %% Click Events - Service Tier
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/wsgi.py"
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/runflask.py"
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/manage.py"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/api/"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/bibbox/"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/models/"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/services/"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/static/"
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/settings.py"
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/uwsgi.ini"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/uwsgi_params"
    click Flask "https://github.com/bibbox/sys-bibbox/tree/master/backend/Dockerfile"
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/.env"
    click Flask "https://github.com/bibbox/sys-bibbox/blob/master/backend/entrypoint.sh"
    click CeleryWorker "https://github.com/bibbox/sys-bibbox/blob/master/backend/app/celeryconfig.py"
    click CeleryWorker "https://github.com/bibbox/sys-bibbox/tree/master/backend/app/celerytasks/"
    click CeleryWorker "https://github.com/bibbox/sys-bibbox/blob/master/backend/celery_worker.py"

    %% Click Events - Data Tier
    click Postgres "https://github.com/bibbox/sys-bibbox/tree/master/postgresql/Dockerfile"
    click Postgres "https://github.com/bibbox/sys-bibbox/blob/master/postgresql/init.sql"

    %% Click Events - Auth Tier
    click Keycloak "https://github.com/bibbox/sys-bibbox/blob/master/keycloak/realms/realm-export.json"
    click Keycloak "https://github.com/bibbox/sys-bibbox/blob/master/keycloak/realms/realm-export.json.template"
    click Keycloak "https://github.com/bibbox/sys-bibbox/blob/master/keycloak/realms/notes.txt"
    click Keycloak "https://github.com/bibbox/sys-bibbox/tree/master/keycloak/themes/custom/login/"
    click Keycloak "https://github.com/bibbox/sys-bibbox/blob/master/keycloak.md"

    %% Click Events - Configuration & CI/CD
    click configTemplates "https://github.com/bibbox/sys-bibbox/tree/master/config-templates/"
    click fdpConfigs "https://github.com/bibbox/sys-bibbox/tree/master/fdp-configs/"
    click proxyConfigs "https://github.com/bibbox/sys-bibbox/tree/master/proxy-configs/"
    click composeAll "https://github.com/bibbox/sys-bibbox/blob/master/docker-compose.yml"
    click composeDev "https://github.com/bibbox/sys-bibbox/blob/master/docker-compose.dev.yml"
    click composeFE "https://github.com/bibbox/sys-bibbox/blob/master/docker-compose_frontend_builder.yml"
    click wfDocker "https://github.com/bibbox/sys-bibbox/blob/master/ .github/workflows/docker-image.yml"
    click wfPublish "https://github.com/bibbox/sys-bibbox/blob/master/ .github/workflows/docker-publish.yml"
    click wfDeploy "https://github.com/bibbox/sys-bibbox/blob/master/ .github/workflows/deploy.yml"
    click wfNode "https://github.com/bibbox/sys-bibbox/blob/master/ .github/workflows/node.js.yml"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:2px
    classDef proxy fill:#90caf9,stroke:#1565c0,stroke-width:2px
    classDef service fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef data fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
    classDef infra fill:#e0e0e0,stroke:#616161,stroke-width:2px
```
