# b-s-f/yaku architecture

> Architecture diagram of the GitHub repository b-s-f/yaku, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b-s-f/yaku
- Repository: https://github.com/b-s-f/yaku

## Overview

##### Project type and purpose
- Yaku is a full-stack, Kubernetes-native microservice platform and monorepo that automates software release evidence collection (“QG assessments”).
- It provides:
- A single-page UI (Vue + Vuetify) for human interaction (“qg-service-ui”).
- A REST API backend (NestJS “qg-api-service”)
- A CLI client (“yaku-cli” in TypeScript, “onyx” in Go) for pipelines or scripting
- A workflow engine (Argo Workflows) that spins up Docker-based “autopilot” fetcher/evaluator apps (Python, TS)
- Standard infrastructure: PostgreSQL, Keycloak, Minio/S3, Kubernetes/Helm

##### File structure
- Top-level directories show separation of concerns:
- chart/helm definitions for Kubernetes deployment of core-api, UI, labs
- qg-api-service/: NestJS monolith with modules/controllers/services, integration tests, database migrations, OSS dependencies
- yaku-ui/: two UI packages – frog-vue component library and qg-service-ui application
- onyx/: Go-based CLI tool for transformation, migration, execution pipelines
- yaku-cli/ and yaku-client-lib/: TS CLI and HTTP client library
- yaku-apps-python/ and yaku-apps-typescript/: dozens of containerized “autopilot” fetcher/evaluator utilities
- CI/CD workflows automate building Docker images for each component

##### README for additional insights
- The system uses Argo Workflows on Kubernetes to orchestrate jobs
- A PostgreSQL database named “yaku” stores core data
- Keycloak provides OIDC/SAML2 authentication

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        direction TB
        UI["Web UI (Vue + Vuetify)"]:::frontend
        YCLI["yaku-cli (TS CLI)"]:::backend
        ONYX["onyx (Go CLI)"]:::backend
    end

    %% Control Plane inside Kubernetes
    subgraph "Kubernetes Cluster"
        direction TB
        subgraph "API & Auth"
            direction TB
            API["qg-api-service\n(NestJS monolith)"]:::backend
            KEYC["Keycloak\n(OIDC Identity Provider)"]:::infra
        end

        subgraph "Data Stores"
            direction TB
            PG["PostgreSQL\n(persistent)"]:::infra
            MINIO["Minio/S3\n(Object Storage)"]:::infra
        end

        subgraph "Workflow Engine"
            direction TB
            ARGO["Argo Workflows\n(Controller & CRDs)"]:::infra
            Runner["Autopilot Pods\n(Python/TS containers)"]:::backend
        end
    end

    %% External Services
    subgraph "External Systems"
        direction TB
        EXT["External Services\n(SharePoint, Git, Jira, SonarQube, etc.)"]:::external
    end

    %% Interactions
    UI -->|"HTTPS REST API"| API
    YCLI -->|"REST API"| API
    ONYX -->|"REST API"| API
    API -->|"OIDC Token Validation"| KEYC
    API -->|"Read/Write"| PG
    API -->|"Store/Retrieve Artifacts"| MINIO
    API -->|"Submit Workflow (K8s API)"| ARGO
    ARGO -->|"Launch Pods"| Runner
    Runner -->|"Fetch/Evaluate"| EXT
    Runner -->|"Push Results"| API

    %% Click Events - Helm Charts
    click chart "https://github.com/b-s-f/yaku/tree/main/chart/"
    click CoreAPIChart "https://github.com/b-s-f/yaku/tree/main/chart/charts/yaku-core-api/"
    click UIChart "https://github.com/b-s-f/yaku/tree/main/chart/charts/yaku-ui/"
    click LabsChart "https://github.com/b-s-f/yaku/tree/main/chart/charts/yaku-labs/"

    %% Click Events - REST API Backend
    click API_src "https://github.com/b-s-f/yaku/tree/main/qg-api-service/qg-api-service/src/"
    click API_main "https://github.com/b-s-f/yaku/blob/main/qg-api-service/qg-api-service/src/main.ts"
    click API_namespace "https://github.com/b-s-f/yaku/tree/main/qg-api-service/qg-api-service/src/namespace/"
    click API_argo "https://github.com/b-s-f/yaku/blob/main/qg-api-service/qg-api-service/src/namespace/workflow/workflow-argo.service.ts"
    click API_migrations "https://github.com/b-s-f/yaku/tree/main/qg-api-service/qg-api-service/src/database/migrations/"
    click API_Commons "https://github.com/b-s-f/yaku/tree/main/qg-api-service/api-commons-lib/"
    click API_KeycloakLib "https://github.com/b-s-f/yaku/tree/main/qg-api-service/api-keycloak-auth-lib/"

    %% Click Events - Go CLI onyx
    click Onyx_main "https://github.com/b-s-f/yaku/blob/main/onyx/cmd/cli/main.go"
    click Onyx_exec "https://github.com/b-s-f/yaku/blob/main/onyx/internal/onyx/exec/exec.go"
    click Onyx_autopilot "https://github.com/b-s-f/yaku/blob/main/onyx/pkg/executor/autopilot.go"
    click Onyx_finalize "https://github.com/b-s-f/yaku/blob/main/onyx/pkg/finalize/engine.go"
    click Onyx_mod "https://github.com/b-s-f/yaku/blob/main/onyx/go.mod"

    %% Click Events - TS CLI yaku-cli
    click YCLI_index "https://github.com/b-s-f/yaku/blob/main/yaku-cli/src/index.ts"
    click YCLI_cmds "https://github.com/b-s-f/yaku/tree/main/yaku-cli/src/commands/"
    click YCLI_handlers "https://github.com/b-s-f/yaku/tree/main/yaku-cli/src/handlers/"
    click YCLI_pkg "https://github.com/b-s-f/yaku/blob/main/yaku-cli/package.json"

    %% Click Events - TS HTTP Client lib
    click Client_client "https://github.com/b-s-f/yaku/blob/main/yaku-client-lib/src/client.ts"
    click Client_api "https://github.com/b-s-f/yaku/blob/main/yaku-client-lib/src/api-calls.ts"
    click Client_pkg "https://github.com/b-s-f/yaku/blob/main/yaku-client-lib/package.json"

    %% Click Events - Vue component lib
    click Frog_index "https://github.com/b-s-f/yaku/blob/main/yaku-ui/frog-vue/src/index.ts"
    click Frog_atoms "https://github.com/b-s-f/yaku/tree/main/yaku-ui/frog-vue/src/atoms/"
    click Frog_molecules "https://github.com/b-s-f/yaku/tree/main/yaku-ui/frog-vue/src/molecules/"
    click Frog_organisms "https://github.com/b-s-f/yaku/tree/main/yaku-ui/frog-vue/src/organisms/"

    %% Click Events - Single-page UI
    click UI_main "https://github.com/b-s-f/yaku/blob/main/yaku-ui/qg-service-ui/src/main.ts"
    click UI_App "https://github.com/b-s-f/yaku/blob/main/yaku-ui/qg-service-ui/src/App.vue"
    click UI_components "https://github.com/b-s-f/yaku/tree/main/yaku-ui/qg-service-ui/src/components/"
    click UI_api "https://github.com/b-s-f/yaku/tree/main/yaku-ui/qg-service-ui/src/api/"
    click UI_auth "https://github.com/b-s-f/yaku/blob/main/yaku-ui/qg-service-ui/src/auth/KeycloakService.ts"

    %% Click Events - Python Autopilot Apps
    click Py_apps "https://github.com/b-s-f/yaku/tree/main/yaku-apps-python/apps/"
    click Py_utils "https://github.com/b-s-f/yaku/tree/main/yaku-apps-python/packages/autopilot-utils/"

    %% Click Events - TS Autopilot Apps
    click TS_apps "https://github.com/b-s-f/yaku/tree/main/yaku-apps-typescript/apps/"
    click TS_utils "https://github.com/b-s-f/yaku/tree/main/yaku-apps-typescript/packages/autopilot-utils/"

    %% Click Events - Documentation
    click Docs_dev "https://github.com/b-s-f/yaku/tree/main/documentation/"
    click Docs_user "https://github.com/b-s-f/yaku/tree/main/user-documentation/"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef backend fill:#bbf,stroke:#333,stroke-width:1px
    classDef infra fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#fdc,stroke:#333,stroke-width:1px
```
