# grupoboticario/plat-eng-alquimia-crossplane-provider-sonar architecture

> Architecture diagram of the GitHub repository grupoboticario/plat-eng-alquimia-crossplane-provider-sonar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar
- Repository: https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar

## Overview

##### Project type and purpose
- This is a Crossplane “provider” scaffold called `provider-sonar`.
- Its purpose is to serve as a minimal example (“sonar”) for creating new Crossplane providers. It defines a custom resource (`MyType`), a `ProviderConfig`, a controller that reconciles managed resources, and code-generation & packaging pipelines.

##### File structure
- Top-level directories:
- apis/ – API definitions & generated deepcopy plus CRD manifests in package/crds
- internal/ – core logic: clients (Sonar API), controller implementations
- cmd/provider – entrypoint for running the provider’s controller
- cluster/ – local / integration test harness (images, scripts)
- hack/ – code-generation and scaffolding helpers
- examples/ – sample YAML to exercise CRDs and ProviderConfig
- package/crds & crossplane.yaml – distribution artifacts
- Configuration/build: Makefile, go.mod, .github workflows for CI, codegen, and release.

##### Extract insights from README
- Defines key features: ProviderConfig → Secret, MyType managed resource, a controller that logs observed configuration.
- Intended workflow: scaffold a new provider, generate code, run `make build`, install CRDs, and run the controller in-cluster or locally.

##### Main components
a. Kubernetes API Server (with CRDs installed)
b. provider-sonar Controller Manager (the `cmd/provider/main.go` binary)
c. Custom Resources:
- ProviderConfig (references kube-secret)
- MyType (the sample managed resource)
d. Secret store (Kubernetes Secret) holding provider credentials
e. External service endpoint (“Sonar API”) accessed by internal/clients/sonar
f. Codegen pipeline (hack scripts → controller-gen → CRD YAML)
g. Packaging & CI/CD artifacts (Makefile, .github workflows, cluster images)

##### Relationships & interactions
- The Controller Manager watches CRDs (MyType, ProviderConfig) via controller-runtime.
- On reconcile:
1. Reads ProviderConfig → fetches Secret with credentials
2. Uses internal/clients/sonar to call external Sonar API
3. Updates MyType.Status via Kubernetes API
- Codegen (hack/helpers + Makefile) produces deepcopy & CRDs → applied to API server → available for controllers.
- CI/CD workflows build & publish container images (cluster/images) and provider package (package/).

##### Architectural patterns & design principles
- Kubernetes operator pattern (control-loop reconciliation)
- Separation of concerns:
- apis/ defines schema
- internal/clients isolates external API calls
- internal/controller contains business-logic reconcile code
- Code generation for CRD manifests and client deepcopy methods
- GitHub Actions for automated testing, code analysis, and releases

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Code Generation Pipeline
    subgraph "Code Generation & Scaffolding" 
        direction TB
        Scripts["hack/helpers/apis/\n& hack/helpers/controller/"]:::artifact
        Helpers["hack/boilerplate.go.txt\nhack/helpers/prepare.sh\napis/generate.go"]:::artifact
        Scripts -->|runs| Helpers
        Helpers -->|generates| DeepCopyGo["Deepcopy Go code\n(zz_generated.deepcopy.go)"]:::artifact
        Helpers -->|generates| CRDYaml["Generated CRD manifests\n(package/crds/*.yaml)"]:::artifact
    end

    %% API Server & Storage
    subgraph "Kubernetes Control Plane" 
        direction TB
        APIServer["Kubernetes API Server"]:::component
        etcd["etcd (CRDs & Secrets)"]:::datastore
        APIServer --> etcd
        CRDYaml -->|applied| APIServer
    end

    %% Custom Resources
    subgraph "Custom Resources" 
        direction TB
        ProviderConfigCRD["ProviderConfig CRD"]:::datastore
        MyTypeCRD["MyType (Project) CRD"]:::datastore
        ProviderConfigCRD -->|stored in| etcd
        MyTypeCRD -->|stored in| etcd
    end

    %% Runtime Controller
    subgraph "Controller Runtime" 
        direction TB
        ControllerManager["provider-sonar Controller Manager\n(cmd/provider/main.go)"]:::component
        ReconcilerGeneral["internal/controller/project/project.go\n& internal/controller/sonar.go"]:::component
        Features["internal/controller/features/features.go"]:::component
        ConfigWire["internal/controller/config/config.go"]:::component
        Doc["internal/controller/doc.go"]:::component
        ControllerManager -->|watches| APIServer
        APIServer -->|events| ControllerManager
        ControllerManager --> ReconcilerGeneral
        ControllerManager --> Features
        ControllerManager --> ConfigWire
        ControllerManager --> Doc

        %% Secret retrieval
        SecretStore["Kubernetes Secret"]:::datastore
        APIServer -->|get| SecretStore
        ControllerManager -->|reads| SecretStore

        %% External Sonar API
        subgraph "External Service"
            SonarAPI["Sonar API"]:::external
        end
        SonarClient["internal/clients/sonar/\nsonarapi.go & project.go"]:::component
        ReconcilerGeneral -->|uses| SonarClient
        SonarClient -->|calls| SonarAPI

        %% Status update
        ControllerManager -->|updates status| APIServer
    end

    %% Packaging & CI/CD
    subgraph "Packaging & CI-CD" 
        direction TB
        Makefile["Makefile"]:::artifact
        Workflows[".github/workflows/*.yml"]:::artifact
        PackageDesc["package/crossplane.yaml"]:::artifact
        Makefile -->|builds| ControllerManager
        Workflows -->|run CI/CD| Makefile
        Makefile -->|packages| PackageDesc
        CRDYaml -->|included in| PackageDesc
    end

    %% Examples and Tests
    subgraph "Examples & Tests" 
        direction TB
        Examples["examples/*.yaml"]:::artifact
        ClusterImages["cluster/images/..."]:::artifact
        LocalTests["cluster/local/integration_tests.sh"]:::artifact
        Examples --> APIServer
        LocalTests -->|deploys| ClusterImages
        ClusterImages -->|runs| ControllerManager
    end

    %% Legend
    subgraph "Legend"
        direction TB
        A[Component]:::component
        B[Data Store]:::datastore
        C[Code Artifact]:::artifact
        D[External Service]:::external
    end

    %% Click events
    click ControllerManager "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/cmd/provider/main.go"
    click ProviderConfigCRD "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/apis/v1alpha1/providerconfig_types.go"
    click MyTypeCRD "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/apis/project/v1alpha1/project_types.go"
    click DeepCopyGo "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/apis/v1alpha1/zz_generated.deepcopy.go"
    click DeepCopyGo "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/apis/project/v1alpha1/zz_generated.deepcopy.go"
    click CRDYaml "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/tree/main/package/crds/"
    click ConfigWire "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/internal/controller/config/config.go"
    click Features "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/internal/controller/features/features.go"
    click ReconcilerGeneral "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/internal/controller/project/project.go"
    click SonarClient "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/internal/clients/sonar/sonarapi.go"
    click SonarClient "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/internal/clients/sonar/project.go"
    click Scripts "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/tree/main/hack/helpers/apis/"
    click Scripts "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/tree/main/hack/helpers/controller/"
    click Helpers "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/hack/boilerplate.go.txt"
    click Helpers "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/hack/helpers/prepare.sh"
    click Helpers "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/apis/generate.go"
    click Examples "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/examples/provider/config.yaml"
    click Examples "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/examples/storeconfig/vault.yaml"
    click Examples "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/examples/project/project.yaml"
    click ClusterImages "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/tree/main/cluster/images/provider-sonar-controller/"
    click LocalTests "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/cluster/local/integration_tests.sh"
    click PackageDesc "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/package/crossplane.yaml"
    click Makefile "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/tree/main/Makefile"
    click Workflows "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/.github/workflows/ci.yml"
    click Workflows "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/.github/workflows/codeql.yml"
    click Workflows "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/.github/workflows/promote.yml"
    click Workflows "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/.github/workflows/tag.yml"
    click Workflows "https://github.com/grupoboticario/plat-eng-alquimia-crossplane-provider-sonar/blob/main/.github/workflows/backport.yml"

    classDef component fill:#DDEEFF,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFEECC,stroke:#663300,stroke-width:1px,shape:cylinder
    classDef artifact fill:#E8E8E8,stroke:#666666,stroke-width:1px,shape:parallelogram
    classDef external fill:#FFE0E0,stroke:#CC0000,stroke-width:1px
```
