# octo-sts/app architecture

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

- Interactive diagram: https://gitdiagram.com/octo-sts/app
- Repository: https://github.com/octo-sts/app

## Overview

##### Main Components

a) Core Service Components:
- GitHub App Interface
- STS Exchange Service
- Token Federation System
- Trust Policy Manager
- Webhook Handler
- Prober Service

b) External Systems:
- GitHub API
- Client Workloads (Token Requestors)
- Google Cloud Platform (indicated by GCP KMS usage)

**Client Layer**

**API Layer**

**Service Layer**

**Infrastructure Layer**

##### Component Relationships

a) Primary Flow:
**Client Workload → STS Exchange Service → Trust Policy Manager → GitHub API**

b) Secondary Flows:
- Webhook Handler ↔ GitHub API
- Prober Service → System Health Monitoring
- GCP KMS Integration → Security Layer

##### Specific Implementation Details

Key technical elements:
- GRPC Service Implementation
- Trust Policy Configuration (.github/chainguard/*.sts.yaml)
- Token Exchange Flow
- Permission Management System

##### Detailed Component Breakdown

- envconfig: Configuration Management
- gcpkms: Security Layer
- ghtransport: GitHub Transport Layer
- octosts: Core STS Logic
- webhook: GitHub Event Handling
- prober: Health Monitoring

##### Infrastructure Components

- Load Balancer (gclb.tf)
- Message Broker (broker.tf)
- Probing System (prober.tf)

##### Implementation Notes

- Clear separation between command (cmd/) and package (pkg/) components
- Infrastructure as Code integration
- Testing components and validation flows
- Security boundary demarcation

##### Key Flows to Illustrate

a) Token Exchange Flow:
**Client → STS Exchange → Trust Policy Validation → GitHub Token Generation**

b) Webhook Processing:
**GitHub → Webhook Handler → Event Processing → State Update**

##### Additional Elements

Annotations for:
- Configuration Management
- Security Controls
- Monitoring Points
- Integration Points

This system design should emphasize the security-first nature of the project while clearly showing how it eliminates the need for GitHub Personal Access Tokens through its federation mechanism.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        CW[Client Workloads]
    end

    subgraph API["API Layer"]
        GH[("GitHub API")]:::external
        WH["Webhook Handler"]:::service
        STS["STS Exchange Service"]:::service
        click WH "https://github.com/octo-sts/app/blob/main/cmd/webhook/main.go"
        click STS "https://github.com/octo-sts/app/blob/main/pkg/octosts/octosts.go"
    end

    subgraph Services["Service Layer"]
        APP["GitHub App Interface"]:::service
        TPM["Trust Policy Manager"]:::security
        EP["Event Processing"]:::service
        PS["Prober Service"]:::monitoring
        click APP "https://github.com/octo-sts/app/blob/main/cmd/app/main.go"
        click TPM "https://github.com/octo-sts/app/blob/main/pkg/octosts/trust_policy.go"
        click EP "https://github.com/octo-sts/app/blob/main/pkg/octosts/event.go"
        click PS "https://github.com/octo-sts/app/blob/main/cmd/prober/main.go"
    end

    subgraph Infra["Infrastructure Layer"]
        LB["Load Balancer"]:::infra
        MB["Message Broker"]:::infra
        KMS["GCP KMS"]:::security
        CM["Configuration Management"]:::infra
        click LB "https://github.com/octo-sts/app/blob/main/iac/gclb.tf"
        click MB "https://github.com/octo-sts/app/blob/main/iac/broker.tf"
        click KMS "https://github.com/octo-sts/app/blob/main/pkg/gcpkms/gcpkms.go"
        click CM "https://github.com/octo-sts/app/blob/main/pkg/envconfig/envconfig.go"
    end

    %% Primary Flow
    CW -->|Token Request| STS
    STS -->|Validate| TPM
    TPM -->|Auth| GH
    GH -->|Token| STS
    STS -->|Response| CW

    %% Secondary Flows
    GH -.->|Events| WH
    WH -.->|Process| EP
    EP -.->|Update| MB
    PS -->|Health Check| LB
    PS -.->|Monitor| STS

    %% Infrastructure Connections
    APP --- KMS
    TPM --- CM
    STS --- CM
    WH --- CM
    PS --- CM
    
    %% Security Flows
    TPM -.->|Verify| KMS
    APP -.->|Secure| KMS

    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    classDef service fill:#3498db,stroke:#2980b9,color:white
    classDef security fill:#f1c40f,stroke:#f39c12
    classDef external fill:#2ecc71,stroke:#27ae60,color:white
    classDef monitoring fill:#e74c3c,stroke:#c0392b,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d

    %% Legend
    subgraph Legend
        L1[Service Component]:::service
        L2[Security Component]:::security
        L3[External System]:::external
        L4[Monitoring Component]:::monitoring
        L5[Infrastructure Component]:::infra
    end
```
