# leqo-framework/qc-atlas-api architecture

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

- Interactive diagram: https://gitdiagram.com/leqo-framework/qc-atlas-api
- Repository: https://github.com/leqo-framework/qc-atlas-api

## Overview

##### Project type and purpose
- This is a monorepo hosting a Java-based backend service for the QC-Atlas project. It consists of two Maven modules:
- org.planqk.atlas.core – the domain-centric library (entities, repositories, services, Liquibase changelogs, integration utilities)
- org.planqk.atlas.web  – a Spring Boot REST API layer exposing the core services via HTTP (controllers, DTOs, configuration, Swagger/OpenAPI)
- Purpose: to provide a RESTful catalog of quantum-computing artifacts (algorithms, implementations, compute resources, TOSCA templates, etc.) backed by PostgreSQL and optional cloud storage.

##### File structure
- Top-level directories:
- .docker, Dockerfile, docker-compose.yml – containerization artifacts
- config, org.planqk.atlas.core, org.planqk.atlas.web – actual code/config
- docs/adr – architectural decision records, docs/dev – developer guides
- Core module: follows the classic layered architecture (model → repository → service → exception/util). Uses Liquibase for DB migrations, JPA/Hibernate, Testcontainers for integration tests, RestTemplate to call external Winery service.
- Web module: Spring Boot app with a package per layer: configuration, controllers (one per domain aggregate), DTOs & link assemblers for hypermedia, exception handlers, utilities (validation, model mapping).

##### Key insights from README
- Built via Maven, packaged as a Spring Boot JAR/WAR, runnable in Docker.
- Exposes OpenAPI/Swagger UI (build_swagger_ui.yml).
- Integrates with Postgres (JDBC/Hibernate) and optionally external cloud storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Browser("Browser / HTTP Client / Swagger UI"):::client
    end

    %% Web Module
    subgraph "Web Module (org.planqk.atlas.web)" 
        direction TB
        Application["Application"]:::web
        CorsConfig["CorsConfiguration"]:::web
        DBConfig["DatabaseConfiguration"]:::web
        SwaggerConfig["SwaggerConfiguration"]:::web
        WebConfig["WebConfiguration"]:::web
        LoggingConfig["LoggingConfiguration"]:::web

        subgraph Controllers
            direction TB
            ControllerPackage["controller package"]:::web
        end

        subgraph "DTOs & LinkAssemblers"
            direction TB
            Dtos["dtos package"]:::web
            LinkAssembler["LinkBuilderService"]:::web
        end

        subgraph Utils
            direction TB
            UtilsPackage["utils package"]:::web
        end
    end

    %% Core Module
    subgraph "Core Module (org.planqk.atlas.core)"
        direction TB
        subgraph "Domain Model"
            ModelPackage["model package"]:::core
        end
        subgraph Repositories
            RepoPackage["repository package"]:::core
        end
        subgraph Services
            ServicePackage["services package"]:::core
        end
        subgraph "Exceptions & Utilities"
            ExceptionPackage["exceptions package"]:::core
            CoreUtils["util package"]:::core
        end
    end

    %% Persistence & Migrations
    subgraph "Persistence & Migrations"
        direction TB
        Liquibase["Liquibase Changelogs"]:::infra
        HibernateProps["hibernate.properties"]:::infra
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        CloudConfig["CloudStorageConfiguration"]:::external
        WineryService["WineryService"]:::external
        RestTemplateConfig["RestTemplateConfiguration"]:::external
        EnversConfig["EnversConfiguration"]:::external
    end

    %% Database
    PostgreSQL[(PostgreSQL DB)]:::database

    %% Infra & CI/CD
    subgraph "Infrastructure & CI/CD"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        DockerDir[".docker directory"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        GitHubActions[".github/workflows"]:::infra
        MavenPoms["pom.xml files"]:::infra
        ADRs["docs/adr"]:::infra
    end

    %% Relationships
    Browser -->|"HTTP/JSON"| Application
    Application -->|startup| Liquibase
    Application -->|"invokes"| ControllerPackage
    ControllerPackage -->|"calls"| ServicePackage
    ServicePackage -->|"uses"| RepoPackage
    RepoPackage -->|"JDBC"| PostgreSQL
    ServicePackage -->|"HTTP S3 API"| CloudConfig
    ServicePackage -->|"HTTP TOSCA API"| WineryService

    %% Click Events
    click Application "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/Application.java"
    click CorsConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/CorsConfiguration.java"
    click DBConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/DatabaseConfiguration.java"
    click SwaggerConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/SwaggerConfiguration.java"
    click WebConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/WebConfiguration.java"
    click LoggingConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/LoggingConfiguration.java"
    click ControllerPackage "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/controller"
    click Dtos "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/dtos"
    click LinkAssembler "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/linkassembler/LinkBuilderService.java"
    click UtilsPackage "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.web/src/main/java/org/planqk/atlas/web/utils"
    click ModelPackage "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/model"
    click RepoPackage "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/repository"
    click ServicePackage "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/services"
    click ExceptionPackage "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/exceptions"
    click CoreUtils "https://github.com/leqo-framework/qc-atlas-api/tree/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/util"
    click Liquibase "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.core/src/main/resources/db/changelog-master.xml"
    click HibernateProps "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.core/src/main/resources/hibernate.properties"
    click CloudConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/CloudStorageConfiguration.java"
    click WineryService "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/WineryService.java"
    click RestTemplateConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/RestTemplateConfiguration.java"
    click EnversConfig "https://github.com/leqo-framework/qc-atlas-api/blob/master/org.planqk.atlas.core/src/main/java/org/planqk/atlas/core/EnversConfiguration.java"
    click Dockerfile "https://github.com/leqo-framework/qc-atlas-api/tree/master/Dockerfile"
    click DockerDir "https://github.com/leqo-framework/qc-atlas-api/blob/master/.docker"
    click DockerCompose "https://github.com/leqo-framework/qc-atlas-api/blob/master/docker-compose.yml"
    click GitHubActions "https://github.com/leqo-framework/qc-atlas-api/blob/master/.github/workflows/build_swagger_ui.yml"
    click MavenPoms "https://github.com/leqo-framework/qc-atlas-api/blob/master/pom.xml"
    click ADRs "https://github.com/leqo-framework/qc-atlas-api/tree/master/docs/adr"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#64B5F6;
    classDef web fill:#BBDEFB,stroke:#2196F3;
    classDef core fill:#C8E6C9,stroke:#388E3C;
    classDef database fill:#FFF9C4,stroke:#FBC02D,shape: cylinder;
    classDef infra fill:#E0E0E0,stroke:#9E9E9E;
    classDef external fill:#F3E5F5,stroke:#8E24AA;
```
