# commercetools/telefonistka architecture

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

- Interactive diagram: https://gitdiagram.com/commercetools/telefonistka
- Repository: https://github.com/commercetools/telefonistka

## Overview

##### Main Components

a) Core Components:
- GitHub Webhook Server
- Promotion Engine
- Version Bumping Service
- Webhook Multiplexer
- ArgoCD Integration Service
- Configuration Manager

b) External Systems:
- GitHub API (REST & GraphQL)
- ArgoCD API
- Target GitOps Repositories
- Prometheus (for metrics)

##### Component Relationships and Architecture

**Top Layer: External Systems**
**Middle Layer: Core Telefonistka Services**
**Bottom Layer: Internal Libraries and Utilities**

##### Specific Implementation Details

a) Incoming Webhooks Flow:
- GitHub webhook → Webhook Server → Event Processing
- Multiplexing capability to multiple endpoints

b) Promotion Flow:
- Configuration Manager reads policies
- Promotion Engine analyzes changes
- GitHub API client creates PRs
- ArgoCD Integration provides deployment status

c) Version Bumping Flow:
- CLI commands → Version Bumper → GitHub API
- Supported methods (overwrite, regex, YAML)

##### Important Architectural Patterns to Highlight

- Plugin-style architecture for different version bumping strategies
- Event-driven webhook handling
- Configuration-driven promotion rules
- Service-oriented design with clear separation of concerns

##### Technical Details

- Go-based implementation
- REST/GraphQL API interactions
- File system interactions for GitOps
- Prometheus metrics endpoints
- Template-based PR generation

##### Specific Implementation Notes

- cmd/telefonistka: Entry points and core commands
- internal/pkg/: Core implementation packages
- argocd/: ArgoCD integration
- configuration/: Config management
- githubapi/: GitHub API clients
- prometheus/: Metrics handling

##### Key Flows to Emphasize

- Webhook reception → Event processing → Promotion analysis → PR creation
- Version bump command → File modification → PR creation
- Drift detection → Analysis → PR comments
- ArgoCD status → Manifest comparison → PR updates

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Systems"]
        direction TB
        GH[GitHub API]:::external
        ARGO[ArgoCD API]:::external
        GITOPS[GitOps Repositories]:::external
        PROM[Prometheus]:::external
    end

    subgraph Core["Core Services"]
        direction TB
        WHS[GitHub Webhook Server]:::core
        WHMP[Webhook Multiplexer]:::core
        PE[Promotion Engine]:::core
        VBS[Version Bumping Service]:::core
        ARGO_INT[ArgoCD Integration]:::core
        CM[Configuration Manager]:::core
        DD[Drift Detection]:::core
        PRM[PR Metrics Service]:::core
    end

    subgraph Internal["Internal Components"]
        direction TB
        GHAPI[GitHub API Client]:::internal
        TEMPLATES[Template System]:::internal
        METRICS[Prometheus Metrics]:::internal
    end

    %% External to Core Connections
    GH <--> GHAPI
    ARGO <--> ARGO_INT
    GITOPS <--> PE
    PROM <--> METRICS

    %% Core Service Connections
    WHS --> WHMP
    WHMP --> PE
    PE --> VBS
    PE --> ARGO_INT
    CM --> PE
    DD --> PE
    PE --> PRM

    %% Internal Component Connections
    GHAPI --> PE
    GHAPI --> VBS
    TEMPLATES --> PE
    METRICS --> PRM
    METRICS --> PE

    %% Click Events
    click WHS "https://github.com/commercetools/telefonistka/blob/main/cmd/telefonistka/server.go"
    click WHMP "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/githubapi/webhook_proxy.go"
    click VBS "https://github.com/commercetools/telefonistka/blob/main/cmd/telefonistka/bump-version-overwrite.go"
    click ARGO_INT "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/argocd/argocd.go"
    click CM "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/configuration/config.go"
    click PE "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/githubapi/promotion.go"
    click GHAPI "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/githubapi/github.go"
    click METRICS "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/prometheus/prometheus.go"
    click TEMPLATES "https://github.com/commercetools/telefonistka/tree/main/templates/"
    click DD "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/githubapi/drift_detection.go"
    click PRM "https://github.com/commercetools/telefonistka/blob/main/internal/pkg/githubapi/pr_metrics.go"

    %% Styling
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef internal fill:#D3D3D3,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        direction TB
        L1[External Systems]:::external
        L2[Core Services]:::core
        L3[Internal Components]:::internal
    end
```
