# fandujar/choregate architecture

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

- Interactive diagram: https://gitdiagram.com/fandujar/choregate
- Repository: https://github.com/fandujar/choregate

## Overview

##### Project type and purpose
- Choregate is a full-stack web application for managing and automating TektonCD tasks.
- The README says it consists of a React/TypeScript front-end (“choregate-ui”), a Go back-end (in cmd/choregate and pkg/…), a Postgres database, and integrates with TektonCD.
- It targets both local development (via Docker Compose + Kind) and production (via Helm charts on Kubernetes).

##### File structure
- Top-level “choregate-ui” directory holds all front-end code: Vite config, pages, components, services that call the HTTP API.
- “cmd/choregate” is the Go entrypoint for the API server.
- “pkg” is organized as a layered/hexagonal architecture:
- transport: HTTP handlers (tasks, users, triggers, etc.)
- controller: orchestrates request handling
- services: business logic (tasks.go, triggers.go, …)
- repositories: persistence interfaces and implementations (in-memory & Postgres)
- providers: external integrations (auth, TektonCD)
- entities: domain models and related errors
- rbac: role-based access control logic
- “migrations” holds SQL schema files for the Postgres DB.
- “docker/” and “hack/development/” contain Dockerfiles and Docker Compose / Kind configs for local dev.
- “helm/chart” contains Kubernetes manifests/templates for production deployment.

##### README for additional insights
- Local setup boots a Kind cluster and runs front-end, back-end, Postgres, and TektonCD integration via Docker Compose.
- Access through HTTP port 8080.
- Emphasizes tasks creation, execution, logs—i.e., UI→API→Tekton pipeline→DB for state and logs.

- Use clear, descriptive labels for each component
- Blue rectangles for application code (UI, API)
- Rectangle with “API” for Go server
- Cloud or hexagon for TektonCD

##### Detail
- Migrations as a step between API server startup and DB schema.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Browser UI (React/Vite)"]:::frontend
    end

    %% Backend Layer
    subgraph "API Server (Go)"
        Main["cmd/choregate/main.go"]:::backend
        subgraph "Transport Layer"
            Transport["pkg/transport"]:::backend
        end
        subgraph "Controller Layer"
            Controller["pkg/controller/controller.go"]:::backend
        end
        subgraph "Service Layer"
            Services["pkg/services"]:::backend
        end
        subgraph "Repository Layer"
            ReposInt["pkg/repositories"]:::backend
            ReposMem["pkg/repositories/memory"]:::backend
            ReposPG["pkg/repositories/postgres"]:::backend
        end
        subgraph "Domain & RBAC"
            Entities["pkg/entities"]:::backend
            RBAC["pkg/rbac/rbac.go"]:::backend
        end
        subgraph "Providers"
            AuthProv["pkg/providers/auth/auth.go"]:::external
            TektonProv["pkg/providers/tektoncd/tektoncd.go"]:::external
        end
        Utils["pkg/utils/utils.go"]:::backend
    end

    %% Database
    DB["Postgres Database"]:::db

    %% External CI/CD
    Tekton["TektonCD"]:::external

    %% Migrations
    Migrations["migrations/00001_init_schema.sql"]:::dev

    %% Local Development Infrastructure
    subgraph "Local Dev Infra" 
        DC["hack/development/docker-compose.yml"]:::dev
        Kind["hack/development/kind-config.yaml"]:::dev
        DockerBE["hack/development/Dockerfile.backend"]:::dev
        DockerFE["hack/development/Dockerfile.frontend"]:::dev
        DockerMigrate["hack/development/Dockerfile.migrate"]:::dev
    end

    %% Production Deployment
    subgraph "Production (K8s via Helm)" 
        HelmChart["helm/chart"]:::prod
    end

    %% Connections
    UI -->|"REST API"| Main
    Main --> Transport
    Transport --> Controller
    Controller --> Services
    Services --> ReposInt
    ReposInt --> ReposPG
    ReposInt --> ReposMem
    Services --> AuthProv
    Services --> TektonProv
    ReposPG --> DB
    Migrations --> DB
    TektonProv --> Tekton
    Main --> Utils
    Main --> Entities
    Main --> RBAC

    %% Development Infra Relationships
    DC --> Main
    DC --> UI
    DC --> DB
    DC --> Tekton
    Kind --> DC

    %% Helm Chart Relationships
    HelmChart --> Main
    HelmChart --> UI
    HelmChart --> DB
    HelmChart --> Tekton

    %% Click Events
    click UI "https://github.com/fandujar/choregate/tree/main/choregate-ui/"
    click Main "https://github.com/fandujar/choregate/blob/main/cmd/choregate/main.go"
    click Transport "https://github.com/fandujar/choregate/tree/main/pkg/transport/"
    click Controller "https://github.com/fandujar/choregate/blob/main/pkg/controller/controller.go"
    click Services "https://github.com/fandujar/choregate/tree/main/pkg/services/"
    click ReposInt "https://github.com/fandujar/choregate/tree/main/pkg/repositories/"
    click ReposMem "https://github.com/fandujar/choregate/tree/main/pkg/repositories/memory/"
    click ReposPG "https://github.com/fandujar/choregate/tree/main/pkg/repositories/postgres/"
    click Entities "https://github.com/fandujar/choregate/tree/main/pkg/entities/"
    click RBAC "https://github.com/fandujar/choregate/blob/main/pkg/rbac/rbac.go"
    click AuthProv "https://github.com/fandujar/choregate/blob/main/pkg/providers/auth/auth.go"
    click TektonProv "https://github.com/fandujar/choregate/blob/main/pkg/providers/tektoncd/tektoncd.go"
    click Utils "https://github.com/fandujar/choregate/blob/main/pkg/utils/utils.go"
    click Migrations "https://github.com/fandujar/choregate/blob/main/migrations/00001_init_schema.sql"
    click DC "https://github.com/fandujar/choregate/blob/main/hack/development/docker-compose.yml"
    click Kind "https://github.com/fandujar/choregate/blob/main/hack/development/kind-config.yaml"
    click DockerBE "https://github.com/fandujar/choregate/blob/main/hack/development/Dockerfile.backend"
    click DockerFE "https://github.com/fandujar/choregate/blob/main/hack/development/Dockerfile.frontend"
    click DockerMigrate "https://github.com/fandujar/choregate/blob/main/hack/development/Dockerfile.migrate"
    click HelmChart "https://github.com/fandujar/choregate/tree/main/helm/chart/"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef backend fill:#87cefa,stroke:#000,stroke-width:1px
    classDef db fill:#ffa500,stroke:#000,stroke-width:1px
    classDef external fill:#90ee90,stroke:#000,stroke-width:1px
    classDef dev fill:#f4cccc,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef prod fill:#ffdead,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
