# actinia-org/actinia-api architecture

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

- Interactive diagram: https://gitdiagram.com/actinia-org/actinia-api
- Repository: https://github.com/actinia-org/actinia-api

## Overview

##### Project type and purpose
- This repository is an open-source tool—a centralized collector and publisher of OpenAPI (Swagger2) documentation for the actinia‐core service and its plugins.
- It does not contain runtime application logic; it bundles YAML/Python swagger definitions, builds distributable packages (Python wheel, source), and publishes them independently of the code repositories.

##### File structure
- Top‐level “src/actinia_api/swagger2/actinia_core/apidocs” and “…/schemas” houses all REST API endpoint definitions and JSON schemas.
- Project root contains configuration for Python packaging (pyproject.toml, setup.py, setup.cfg), black/flake8 CI, and Docker‐based release tooling under “docker/release”.
- GitHub workflows for linting (black.yml), static analysis (flake8.yml), and automated Python package publishing (python-publish.yml).

##### README for additional insights
- Confirms the migration goal: decouple API docs versioning from code.
- Highlights ongoing migration work: some docs still live in source code repos, but this repo is the future canonical home.

a. Main components
– Developer Workstation (local dev tools)
– GitHub Repository (acts as source of truth)
– GitHub Actions CI pipelines (lint, format, test, package)
– Docker Build Environment (for release images)
– PyPI Registry (Python package distribution)
– Downstream Consumers (services or clients that import actinia_api docs)
b. Relationships and data flow
– Developer pushes commits → GitHub Repo
– Push triggers GitHub Actions:
- black & flake8 run over src/
- on tag → python-publish builds wheel/sdist → pushes to PyPI
- docker/release pipeline builds Docker image → pushes to Docker registry (optional)
– Consumers fetch actinia_api from PyPI (or Docker image) → integrate swagger definitions into documentation tools or API gateways
c. Architectural patterns and design principles
– Separation of concerns: docs are versioned separately from implementation
– CI/CD-driven packaging and deployment
– Modularity in swagger definitions (one file per endpoint group)
d. Key technologies and frameworks
– Python packaging: setuptools (setup.py), pyproject.toml
– Swagger2/OpenAPI for REST definitions
– Docker for release image management
– GitHub Actions for CI/CD
– Black and Flake8 for code style and linting

## Diagram (Mermaid)

```mermaid
graph TB
    Developer["Developer Workstation"]:::consumer
    GitHubRepo["GitHub Repository"]:::code

    subgraph "Repository Structure"
        direction TB

        subgraph "API Docs"
            direction TB
            APIDocs["OpenAPI (Swagger2) Endpoint Definitions"]:::code
            click APIDocs "https://github.com/actinia-org/actinia-api/tree/main/src/actinia_api/swagger2/actinia_core/apidocs"
            Schemas["JSON Schema Definitions"]:::code
            click Schemas "https://github.com/actinia-org/actinia-api/tree/main/src/actinia_api/swagger2/actinia_core/schemas"
        end

        subgraph "Packaging Config"
            direction TB
            Pyproject["pyproject.toml"]:::code
            click Pyproject "https://github.com/actinia-org/actinia-api/blob/main/pyproject.toml"
            SetupPy["setup.py"]:::code
            click SetupPy "https://github.com/actinia-org/actinia-api/blob/main/setup.py"
            SetupCfg["setup.cfg"]:::code
            click SetupCfg "https://github.com/actinia-org/actinia-api/blob/main/setup.cfg"
        end

        subgraph "CI/Workflows"
            direction TB
            Black["black.yml"]:::ci
            click Black "https://github.com/actinia-org/actinia-api/blob/main/.github/workflows/black.yml"
            Flake8["flake8.yml"]:::ci
            click Flake8 "https://github.com/actinia-org/actinia-api/blob/main/.github/workflows/flake8.yml"
            PublishYaml["python-publish.yml"]:::ci
            click PublishYaml "https://github.com/actinia-org/actinia-api/blob/main/.github/workflows/python-publish.yml"
        end

        subgraph "Docker Release Tooling"
            direction TB
            Dockerfile["Dockerfile"]:::ci
            click Dockerfile "https://github.com/actinia-org/actinia-api/tree/main/docker/release/Dockerfile"
            ReleaseScript["create_release_with_asset.sh"]:::ci
            click ReleaseScript "https://github.com/actinia-org/actinia-api/blob/main/docker/release/create_release_with_asset.sh"
            DockerReadme["README.md"]:::ci
            click DockerReadme "https://github.com/actinia-org/actinia-api/blob/main/docker/release/README.md"
        end

        subgraph "Other Configs"
            direction TB
            Readme["README.md"]:::code
            click Readme "https://github.com/actinia-org/actinia-api/blob/main/README.md"
            ReleaseMD["RELEASE.md"]:::code
            click ReleaseMD "https://github.com/actinia-org/actinia-api/blob/main/RELEASE.md"
            License["LICENSE.txt"]:::code
            click License "https://github.com/actinia-org/actinia-api/blob/main/LICENSE.txt"
            Cover[".coveragerc"]:::code
            click Cover "https://github.com/actinia-org/actinia-api/blob/main/.coveragerc"
            Gitignore[".gitignore"]:::code
            click Gitignore "https://github.com/actinia-org/actinia-api/blob/main/.gitignore"
            Renovate["renovate.json"]:::code
            click Renovate "https://github.com/actinia-org/actinia-api/blob/main/renovate.json"
        end
    end

    Developer -->|git push| GitHubRepo
    GitHubRepo -->|triggers| Black
    GitHubRepo -->|triggers| Flake8
    GitHubRepo -->|on tagged release| PublishYaml

    PublishYaml -->|build wheel/sdist| PyPI[(PyPI Registry)]:::external
    PublishYaml -->|build Docker image| Dockerfile
    Dockerfile -->|push image| DockerRegistry[(Docker Registry)]:::external

    PyPI -->|host package| Consumers["Downstream Consumers"]:::consumer
    DockerRegistry -->|host image| Consumers

    Consumers -->|fetch docs| APIDocs

    classDef code fill:#cce5ff,stroke:#2d6cdf;
    classDef ci fill:#d4edda,stroke:#28a745;
    classDef external fill:#ffe5b4,stroke:#e08e0b;
    classDef consumer fill:#e2e3e5,stroke:#6c757d;
```
