# safwank97/aro-rp architecture

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

- Interactive diagram: https://gitdiagram.com/safwank97/aro-rp
- Repository: https://github.com/safwank97/aro-rp

## Overview

##### Project Type and Purpose
- This is a cloud Resource Provider (RP) for Azure Red Hat OpenShift—a full-stack, microservices-style application that exposes an ARM-compliant HTTP API, persists state in CosmosDB, processes cluster create/update/delete operations via backend workers, and runs an in-cluster operator for ongoing cluster management.

##### Main Components
a. Azure ARM Frontend Layer
- Azure Resource Manager (external) issues REST PUT/GET/DELETE calls
- cmd/aro (CLI entrypoint for “az aro”)
- pkg/frontend: spec-compliant HTTP server (Go, Gorilla mux)
- pkg/gateway: optional HTTP(S) middleware/gateway
- CosmosDB (Azure CosmosDB)

b. Asynchronous Backend Workers
- pkg/backend: workers poll CosmosDB changefeed (non-terminal documents)
- pkg/cluster: wraps OpenShift installer for create/update/delete
- pkg/deploy and pkg/env: generate and deploy ARM templates & VMSS
- pkg/database: CosmosDB wrapper, optimistic concurrency

c. In-Cluster Operator
- pkg/operator/controllers: a suite of Kubernetes controllers running inside each OpenShift cluster
- CRDs (aro.openshift.io v1alpha1, preview.aro.openshift.io)
- Uses Kubernetes API server, dynamic-helper caches

d. User Portal & Proxy
- pkg/portal: React/Go portal for metrics, kubeconfig requests
- portal/v2: standalone React frontend served from pkg/portal
- pkg/proxy: reverse proxy for cluster-API calls (SSH, Prometheus)

e. Clients & Specs
- pkg/swagger: generates ARM Swagger specs
- python/az/aro: Python CLI extension & autogenerated Python client
- pkg/client/services/redhatopenshift: Go client for RedHat OpenShift ARM APIs

f. Shared Utilities & Monitoring
- pkg/util & pkg/metrics: common abstractions (Azure SDK wrappers, logging, statsd)
- Azure Monitor, StatsD for telemetry

##### Architectural Patterns & Principles
- Microservices / layered services: separate HTTP-API layer, asynchronous worker layer, in-cluster operator layer
- Event-driven: CosmosDB changefeed triggers backend workers
- Idempotent & crash-safe: optimistic concurrency, missing-field passthrough
- Versioned APIs: pkg/api defines internal/external API versions with strong validation
- Horizontal scale: frontends and workers are stateless (scale out via Kubernetes or VMSS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients & ARM
    subgraph "External Layer" 
        ARM["Azure Resource Manager"]:::external
        User["User Browser/CLI"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer (Go Services)" 
        CLI["CLI Entrypoint\n(cmd/aro)"]:::frontend
        FE["Frontend Service\n(pkg/frontend)"]:::frontend
        GW["API Gateway\n(pkg/gateway)"]:::frontend
    end

    %% Database & Event Feed
    subgraph "Database & Event Feed"
        CosmosDBInt["CosmosDB Interface\n(pkg/database/cosmosdb)"]:::db
        CosmosDB["CosmosDB"]:::db
    end

    %% Backend Workers
    subgraph "Backend Workers" 
        BW["Changefeed Worker\n(pkg/backend)"]:::backend
        ClusterOp["Cluster Ops\n(pkg/cluster)"]:::backend
        Deploy["ARM Template Deploy\n(pkg/deploy)"]:::backend
        Env["Env Config\n(pkg/env)"]:::backend
        DBWrap["DB Wrapper\n(pkg/database)"]:::backend
    end

    %% In-Cluster Operator
    subgraph "In-Cluster Operator" 
        API1["CRDs v1alpha1\n(pkg/operator/apis/aro.openshift.io/v1alpha1)"]:::operator
        API2["CRDs v1alpha1\n(pkg/operator/apis/preview.aro.openshift.io)"]:::operator
        Ctrl["Controllers\n(pkg/operator/controllers)"]:::operator
        OpDeploy["Operator Manifests\n(pkg/operator/deploy)"]:::operator
        K8sAPI["Kubernetes API Server"]:::external
    end

    %% User Portal & Proxy
    subgraph "User Portal & Proxy"
        PortalAPI["Portal API\n(pkg/portal)"]:::portal
        ReactUI["Portal v2 UI\n(portal/v2)"]:::portal
        Proxy["Reverse Proxy\n(pkg/proxy)"]:::portal
    end

    %% Clients & Specs
    subgraph "Clients & Specs"
        Swagger["Swagger Generator\n(pkg/swagger)"]:::specs
        PyCLI["Python CLI Extension\n(python/az/aro)"]:::specs
        GoClient["Go ARM Client\n(pkg/client/services/redhatopenshift)"]:::specs
    end

    %% Shared Utilities & Monitoring
    subgraph "Shared Utils & Monitoring"
        Util["Utilities\n(pkg/util)"]:::shared
        Metrics["Metrics & Telemetry\n(pkg/metrics)"]:::shared
        AzureMon["Azure Monitor / StatsD"]:::external
    end

    %% Interactions
    ARM -->|1 HTTPS PUT/GET/DELETE| FE
    CLI -->|5 CLI calls| FE
    FE -->|write state| CosmosDBInt --> CosmosDB
    CosmosDB -->|2 changefeed| BW
    BW -->|"invoke cluster ops"| ClusterOp
    BW -->|"arm template deploy"| Deploy
    BW -->|"env config"| Env
    BW -->|"db update"| DBWrap --> CosmosDBInt --> CosmosDB
    ClusterOp -->|create/delete VMSS| AzureMon
    BW --> AzureMon
    User -->|4 portal UI| ReactUI --> PortalAPI
    User -->|4 CLI| PyCLI
    PortalAPI --> Proxy -->|proxy to| K8sAPI
    PyCLI -->|calls API| FE
    Swagger --> FE
    GoClient --> FE
    Util --> FE
    Util --> BW
    Util --> Ctrl
    Metrics --> AzureMon

    API1 --> Ctrl
    API2 --> Ctrl
    OpDeploy --> Ctrl
    K8sAPI --> Ctrl

    %% Click Events
    click CLI "https://github.com/safwank97/aro-rp/tree/master/cmd/aro"
    click FE "https://github.com/safwank97/aro-rp/tree/master/pkg/frontend"
    click GW "https://github.com/safwank97/aro-rp/tree/master/pkg/gateway"
    click CosmosDBInt "https://github.com/safwank97/aro-rp/tree/master/pkg/database/cosmosdb"
    click BW "https://github.com/safwank97/aro-rp/tree/master/pkg/backend"
    click ClusterOp "https://github.com/safwank97/aro-rp/tree/master/pkg/cluster"
    click Deploy "https://github.com/safwank97/aro-rp/tree/master/pkg/deploy"
    click Env "https://github.com/safwank97/aro-rp/tree/master/pkg/env"
    click DBWrap "https://github.com/safwank97/aro-rp/tree/master/pkg/database"
    click API1 "https://github.com/safwank97/aro-rp/tree/master/pkg/operator/apis/aro.openshift.io/v1alpha1"
    click API2 "https://github.com/safwank97/aro-rp/tree/master/pkg/operator/apis/preview.aro.openshift.io/v1alpha1"
    click Ctrl "https://github.com/safwank97/aro-rp/tree/master/pkg/operator/controllers"
    click OpDeploy "https://github.com/safwank97/aro-rp/tree/master/pkg/operator/deploy"
    click PortalAPI "https://github.com/safwank97/aro-rp/tree/master/pkg/portal"
    click ReactUI "https://github.com/safwank97/aro-rp/tree/master/portal/v2"
    click Proxy "https://github.com/safwank97/aro-rp/tree/master/pkg/proxy"
    click Swagger "https://github.com/safwank97/aro-rp/tree/master/pkg/swagger"
    click PyCLI "https://github.com/safwank97/aro-rp/tree/master/python/az/aro"
    click GoClient "https://github.com/safwank97/aro-rp/tree/master/pkg/client/services/redhatopenshift"
    click Util "https://github.com/safwank97/aro-rp/tree/master/pkg/util"
    click Metrics "https://github.com/safwank97/aro-rp/tree/master/pkg/metrics"

    %% Styles
    classDef external fill:#D0E6FF,stroke:#000,stroke-width:1px
    classDef frontend fill:#D5F5E3,stroke:#000,stroke-width:1px
    classDef db fill:#FDEBD0,stroke:#000,stroke-width:1px
    classDef backend fill:#FCF3CF,stroke:#000,stroke-width:1px
    classDef operator fill:#E8DAEF,stroke:#000,stroke-width:1px
    classDef portal fill:#D1F2EB,stroke:#000,stroke-width:1px
    classDef specs fill:#E5E7E9,stroke:#000,stroke-width:1px
    classDef shared fill:#F0F3F4,stroke:#000,stroke-width:1px
```
