# oqtopus-team/qdash architecture

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

- Interactive diagram: https://gitdiagram.com/oqtopus-team/qdash
- Repository: https://github.com/oqtopus-team/qdash

## Overview

##### Main components
- Frontend (UI): Represented by the “ui” directory (built with Next.js/React). This layer handles user interaction, visualization (charts, tables) and communicates with the backend via API calls.
- Backend API: Under “src/qdash/api” which contains routers, API business logic, authentication, and integration with other internal modules such as calibration and file handling.
- Database & Data Models: Shown by directories “src/qdash/dbmodel”, “src/qdash/datamodel” and “src/qdash/db/init”. These handle persistence for users, calibration data, execution history, and more.
- Workflow Engine: Contained in “src/qdash/workflow” and its subcomponents. This module orchestrates calibration workflows, task scheduling, plugin integrations (e.g. bluefors), and chain-of-task executions.
- CLI Tools: Under “src/qdash/cli”. They likely facilitate command-line access to execute workflows or administrative tasks.
- External Integrations: Within the backend “src/qdash/api/lib” (for authentication and Slack notifications) and in workflow integrations. Also note configuration files for Docker and deployment shows container orchestration.
- Configuration/Deployment: Dockerfiles, compose YAML files, and the devcontainer support that provide containerized environments.
- Documentation & Tests: Although not part of runtime, these show the overall project structure (e.g., “docs” provides architectural and development flow documentation).

##### Relationships & interactions
- The Workflow Engine interacts with the API and database, managing calibration and execution tasks. You might represent it as a separate module that communicates bidirectionally with both the API and the DB.
- External integration (e.g., Slack notifications) should be shown as an external service that the backend (or workflow engine) calls.

##### Architectural patterns and design principles
- Layered/MVC Pattern: The separation between API (controller/business logic) and models (database and datamodel) is clear.
- Micro-modular design: The division into submodules (routers, schemas, dbmodel, workflow tasks) shows a separation of concerns.
- Containerization: The presence of Dockerfiles in both the backend and UI, along with compose files, indicates a deployable microservices/containerized environment.
- Extensibility: The workflow plugins and clear CLI division indicate plug-and-play extensibility for new calibration tasks or integrations.

##### Specific elements
- UI → API: for user requests.
- API ↔ Database: for data persistence.
- API ↔ Workflow Engine: for calibration task management.
- Workflow Engine → External Services: for notifications and integrations.
- Optionally, add notes for configuration details like Docker Compose orchestration and CI/CD pipelines (as indicated by GitHub workflows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["UI (Next.js/React)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["API (Python Service)"]:::backend
        
        subgraph "Database Layer"
            PD["Persistence Models"]:::database
            DS["Data Schemata"]:::database
            DI["DB Initialization"]:::database
        end
        
        subgraph "External Integrations"
            ExAPI["API Integrations (Auth/Slack)"]:::integration
            ExWorkflow["Workflow Plugin Integrations"]:::integration
        end
    end

    %% Workflow Layer
    subgraph "Workflow Layer"
        Workflow["Workflow Engine"]:::workflow
    end

    %% CLI Tools
    CLI["CLI Tools"]:::cli

    %% Configuration/Deployment Layer
    subgraph "Config/Deployment"
        Container["Containerization (Docker)"]:::config
        CI["CI/CD (GitHub_workflows)"]:::config
    end

    %% Documentation & Tests
    subgraph "Documentation & Tests"
        Docs["Documentation"]:::docs
        Tests["Tests"]:::docs
    end

    %% Connections
    UI -->|"APIRequests/Responses"| API
    API -->|"DataPersistence"| PD
    API -->|"DataPersistence"| DS
    API -->|"DataPersistence"| DI
    API <-->|"WorkflowTasks"| Workflow
    CLI -->|"Triggers"| API
    CLI -->|"Triggers"| Workflow
    Workflow -->|"Integrates"| ExWorkflow
    API -->|"Notifies"| ExAPI

    %% Containerization indication as a deployment overlay (dashed arrows)
    Container ---|"Dockerizes"| UI
    Container ---|"Dockerizes"| API
    Container ---|"Dockerizes"| Workflow

    %% Class definitions for color styling
    classDef frontend fill:#b3ffcc,stroke:#006600,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef database fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef workflow fill:#ffe699,stroke:#b38f00,stroke-width:2px;
    classDef cli fill:#e6ccff,stroke:#663399,stroke-width:2px;
    classDef integration fill:#ffedcc,stroke:#cc6600,stroke-width:2px;
    classDef config fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef docs fill:#fce5cd,stroke:#b45f06,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/oqtopus-team/qdash/tree/develop/ui/"
    click API "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/api/"
    click PD "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/dbmodel/"
    click DS "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/datamodel/"
    click DI "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/db/init/"
    click Workflow "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/workflow/"
    click CLI "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/cli/"
    click ExAPI "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/api/lib/"
    click ExWorkflow "https://github.com/oqtopus-team/qdash/tree/develop/src/qdash/workflow/plugin/"
    click Container "https://github.com/oqtopus-team/qdash/tree/develop/.devcontainer/"
    click CI "https://github.com/oqtopus-team/qdash/tree/develop/.github/workflows/"
    click Docs "https://github.com/oqtopus-team/qdash/tree/develop/docs/"
    click Tests "https://github.com/oqtopus-team/qdash/tree/develop/tests/"
```
