# pgarciaq/ros-ocp-backend architecture

> Architecture diagram of the GitHub repository pgarciaq/ros-ocp-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pgarciaq/ros-ocp-backend
- Repository: https://github.com/pgarciaq/ros-ocp-backend

## Overview

1. **What this service is**
   Resource Optimization for OpenShift is a Go backend that sits between OpenShift workload data, an internal PostgreSQL database, Kafka-based ingestion, and the external Kruize recommendation engine. It exposes an HTTP API for consumers and also runs background processors for report ingestion and recommendation polling.

2. **Top-level application shape**
   The `cmd/` package suggests a CLI-style bootstrap with separate entry points for the main API/service startup, DB setup, and aggregation-related commands. The runtime is a single Go service composed of API handlers plus background jobs rather than multiple independently deployed services.

3. **Primary inbound paths**
   There are two main data entry points:
   - **HTTP API** under `internal/api`, which likely serves request/response traffic for reports, recommendations, and metadata.
   - **Kafka consumer** under `internal/kafka`, which suggests asynchronous ingestion of report messages or events.
   The presence of `report_processor` and `recommendation_poller` indicates that some request flows are synchronous, while others are queued or polled in the background.

4. **Core processing pipeline**
   Raw input is converted into internal models, validated, aggregated, and then persisted. The `internal/services/report_processor.go`, `internal/utils/aggregator.go`, and `internal/utils/conversion.go` files indicate a pipeline that turns report data into normalized workload/namespace metrics and recommendation records. This is the main transformation boundary in the system.

5. **Domain model and persistence**
   The `internal/model/` package defines the service’s core entities: accounts, clusters, workloads, metrics, recommendation sets, and historical recommendation sets, including namespace-scoped variants. The database schema is managed through SQL migrations, which create and evolve tables, indexes, partitions, and timestamp/constraint changes. PostgreSQL is the durable system of record.

6. **Recommendation lifecycle**
   Recommendation data appears to be tracked both as current state and historical snapshots. The presence of `recommendation_set`, `historical_recommendation_set`, `namespace_recommendation_set`, and poller code implies a lifecycle where recommendations are fetched from Kruize, transformed into internal schema, stored, and periodically refreshed.

7. **External Kruize integration**
   The `internal/utils/kruize` and `internal/types/kruizePayload` packages define the service boundary to Kruize’s API schema. This is an important integration point: the backend likely creates experiments, updates results, and lists recommendations in Kruize, then maps those payloads into its own model and database structures.

8. **Security and authorization**
   The HTTP layer has middleware for identity and RBAC (`internal/api/middleware/identity.go`, `rbac.go`) and a query builder in `internal/rbac/`. This indicates request authorization is not just perimeter-based; access control is enforced per account/resource scope inside the application.

9. **Operational cleanup and retention**
   The `internal/services/housekeeper` package contains cleaners for sources and table partitions. That implies the service manages its own data retention and cleanup, especially for partitioned workload-metrics tables and stale source records.

10. **Feature flags and configuration**
   Configuration is centralized in `internal/config`, with feature flag support in `internal/featureflags` and an Unleash bootstrap file. This means behavior can be toggled at runtime, which is likely important for staged rollout of ingestion, namespace features, or recommendation behavior.

11. **Deployment and platform context**
   The repo is Kubernetes/OpenShift-oriented: `clowdapp.yaml`, `kruize-clowdapp.yaml`, `Dockerfile`, Tekton pipelines, and GitHub Actions indicate cloud-native deployment and CI/CD. The service is designed to run in managed OpenShift environments with platform-provided config, secrets, and Kafka/DB bindings.

12. **Observability and support artifacts**
   Grafana dashboards, OpenAPI spec, Postman collections, sample CSV/TAR inputs, and docs/examples show this repo is built around operational support and integration testing. These artifacts are useful when drawing the system diagram because they reflect the expected data formats and the monitoring boundary around the backend.

13. **Likely architecture diagram boundaries**
   A clear diagram should show:
   - Clients or internal producers calling the **HTTP API**
   - **Kafka** delivering asynchronous report/event messages
   - The **Go application** as the orchestration layer
   - **PostgreSQL** as persistence
   - **Kruize** as the external optimization engine
   - **OpenShift/Clowd** as the runtime/platform dependency
   The service’s main value is in translating raw workload/report data into persisted optimization state and serving it back through authenticated APIs.

Main entry points: [`internal/services/report_processor.go`](https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/services/report_processor.go) (Report processor), [`internal/api`](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/api) (HTTP API), [`migrations`](https://github.com/pgarciaq/ros-ocp-backend/tree/main/migrations) (PostgreSQL), [`internal/services/recommendation_poller.go`](https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/services/recommendation_poller.go) (Recommendation poller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Go service"]
  node_node_cmd["CLI bootstrap<br/>entrypoint"]
  node_node_api["HTTP API<br/>server"]
  node_node_middleware["Auth middleware<br/>security"]
  node_node_report["Report processor<br/>worker"]
  node_node_poller["Recommendation poller<br/>worker"]
  node_node_housekeeper["Housekeeper<br/>maintenance"]
  node_node_service_utils["Service utils<br/>service helpers"]
end

subgraph group_group_domain["Domain model"]
  node_node_model[("Domain model<br/>entities")]
  node_node_conversion["Conversion<br/>transform<br/>[conversion.go]"]
  node_node_aggregator["Aggregator<br/>transform<br/>[aggregator.go]"]
  node_node_kruize_types["Kruize payloads<br/>schema mapping"]
  node_node_rbac["RBAC query<br/>authorization"]
end

subgraph group_group_integration["External systems"]
  node_node_db[("PostgreSQL<br/>database")]
  node_node_kafka["Kafka<br/>stream"]
  node_node_kruize{{"Kruize<br/>external API"}}
  node_node_config["Config"]
  node_node_platform{{"OpenShift<br/>platform<br/>[clowdapp.yaml]"}}
end

subgraph group_group_ops["Operations"]
  node_node_ci["CI/CD<br/>delivery<br/>[workflows]"]
  node_node_observability["Docs & ops<br/>support<br/>[openapi.json]"]
end

node_node_cmd -->|"starts"| node_node_api
node_node_cmd -->|"starts"| node_node_report
node_node_cmd -->|"starts"| node_node_poller
node_node_api -->|"guards"| node_node_middleware
node_node_api -->|"reads/writes"| node_node_model
node_node_api -->|"authorizes"| node_node_rbac
node_node_report -->|"consumes"| node_node_kafka
node_node_report -->|"normalizes"| node_node_conversion
node_node_report -->|"aggregates"| node_node_aggregator
node_node_report -->|"persists"| node_node_db
node_node_poller -->|"fetches"| node_node_kruize
node_node_poller -->|"maps"| node_node_kruize_types
node_node_poller -->|"updates"| node_node_db
node_node_aggregator -->|"produces"| node_node_model
node_node_conversion -->|"maps to"| node_node_model
node_node_kruize_types -->|"binds"| node_node_kruize
node_node_model -->|"schema"| node_node_db
node_node_housekeeper -->|"cleans"| node_node_db
node_node_config -->|"configures"| node_node_api
node_node_config -->|"configures"| node_node_poller
node_node_config -->|"configures"| node_node_report
node_node_platform -->|"runs"| node_node_cmd
node_node_platform -->|"binds"| node_node_kafka
node_node_platform -->|"binds"| node_node_db
node_node_ci -->|"deploys"| node_node_platform
node_node_observability -->|"documents"| node_node_api
node_node_observability -->|"describes"| node_node_db

click node_node_cmd "https://github.com/pgarciaq/ros-ocp-backend/tree/main/cmd"
click node_node_api "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/api"
click node_node_middleware "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/api/middleware"
click node_node_report "https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/services/report_processor.go"
click node_node_poller "https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/services/recommendation_poller.go"
click node_node_housekeeper "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/services/housekeeper"
click node_node_service_utils "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/services"
click node_node_model "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/model"
click node_node_conversion "https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/utils/conversion.go"
click node_node_aggregator "https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/utils/aggregator.go"
click node_node_kruize_types "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/types/kruizePayload"
click node_node_rbac "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/rbac"
click node_node_db "https://github.com/pgarciaq/ros-ocp-backend/tree/main/migrations"
click node_node_kafka "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/kafka"
click node_node_kruize "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/utils/kruize"
click node_node_config "https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/config"
click node_node_platform "https://github.com/pgarciaq/ros-ocp-backend/blob/main/clowdapp.yaml"
click node_node_ci "https://github.com/pgarciaq/ros-ocp-backend/blob/main/.github/workflows"
click node_node_observability "https://github.com/pgarciaq/ros-ocp-backend/blob/main/openapi.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cmd,node_node_api,node_node_middleware,node_node_report,node_node_poller,node_node_housekeeper,node_node_service_utils toneBlue
class node_node_model,node_node_conversion,node_node_aggregator,node_node_kruize_types,node_node_rbac toneAmber
class node_node_db,node_node_kafka,node_node_kruize,node_node_config,node_node_platform toneMint
class node_node_ci,node_node_observability toneRose
```

## Components

### Go service

CLI bootstrap, HTTP API, background workers, and shared service logic.

- [CLI bootstrap](https://github.com/pgarciaq/ros-ocp-backend/tree/main/cmd): entrypoint · Main command set for starting the service, DB setup, and aggregation-related flows. · `cmd`
- [HTTP API](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/api): server · Authenticated request/response surface for reports, recommendations, and metadata. · `internal/api`
- [Auth middleware](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/api/middleware): security · Identity and RBAC enforcement for API requests. · `internal/api/middleware`
- [Report processor](https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/services/report_processor.go): worker · Background pipeline that ingests workload reports and normalizes them. · `internal/services/report_processor.go`
- [Recommendation poller](https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/services/recommendation_poller.go): worker · Background refresh loop for Kruize recommendation state. · `internal/services/recommendation_poller.go`
- [Housekeeper](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/services/housekeeper): maintenance · Retention and cleanup for sources and partitioned tables. · `internal/services/housekeeper`
- [Service utils](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/services): service helpers · Shared service-level helpers and metrics coordination. · `internal/services`

### Domain model

Internal entities, transforms, and persistence-facing structures.

- [Domain model](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/model): entities · Accounts, clusters, workloads, metrics, and recommendation state objects. · `internal/model`
- [Conversion](https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/utils/conversion.go): transform · Maps raw report and external payloads into internal structures. · `internal/utils/conversion.go`
- [Aggregator](https://github.com/pgarciaq/ros-ocp-backend/blob/main/internal/utils/aggregator.go): transform · Combines report data into normalized metrics and recommendation inputs. · `internal/utils/aggregator.go`
- [Kruize payloads](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/types/kruizePayload): schema mapping · Request/response schema definitions for Kruize integration, including namespace variants. · `internal/types/kruizePayload`
- [RBAC query](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/rbac): authorization · Resource-scope query construction for authorization checks. · `internal/rbac`

### External systems

Database, Kafka, Kruize, and OpenShift platform dependencies.

- [PostgreSQL](https://github.com/pgarciaq/ros-ocp-backend/tree/main/migrations): database · Durable system of record managed through migrations. · `migrations`
- [Kafka](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/kafka): stream · Asynchronous ingestion path for report and event messages. · `internal/kafka`
- [Kruize](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/utils/kruize): external API · Optimization engine used to create experiments, update results, and fetch recommendations. · `internal/utils/kruize`
- [Config](https://github.com/pgarciaq/ros-ocp-backend/tree/main/internal/config): runtime config · Service configuration and feature flag wiring. · `internal/config`
- [OpenShift](https://github.com/pgarciaq/ros-ocp-backend/blob/main/clowdapp.yaml): platform · ClowdApp, deployment, and container runtime integration for managed OpenShift environments. · `clowdapp.yaml`

### Operations

Deployment, CI/CD, observability, and support artifacts.

- [CI/CD](https://github.com/pgarciaq/ros-ocp-backend/blob/main/.github/workflows): delivery · GitHub Actions, Tekton, and build/deploy automation. · `.github/workflows`
- [Docs & ops](https://github.com/pgarciaq/ros-ocp-backend/blob/main/openapi.json): support · OpenAPI, dashboards, examples, and sample inputs for validation and monitoring. · `openapi.json`

## Connections

- CLI bootstrap → HTTP API: starts · Bootstraps the HTTP service.
- CLI bootstrap → Report processor: starts · Launches background report processing.
- CLI bootstrap → Recommendation poller: starts · Launches recommendation refresh polling.
- HTTP API → Auth middleware: guards · Applies identity and RBAC checks.
- HTTP API → Domain model: reads/writes · Serves and persists domain objects.
- HTTP API → RBAC query: authorizes · Builds scoped access queries.
- Report processor → Kafka: consumes · Reads asynchronous report messages.
- Report processor → Conversion: normalizes · Converts inbound payloads into internal records.
- Report processor → Aggregator: aggregates · Derives workload and metrics rollups.
- Report processor → PostgreSQL: persists · Stores processed report state and metrics.
- Recommendation poller → Kruize: fetches · Polls external recommendation state.
- Recommendation poller → Kruize payloads: maps · Uses Kruize request/response schemas.
- Recommendation poller → PostgreSQL: updates · Refreshes current and historical recommendations.
- Aggregator → Domain model: produces · Builds persisted domain entities.
- Conversion → Domain model: maps to · Transforms raw input into model objects.
- Kruize payloads → Kruize: binds · Defines the external API contract.
- Domain model → PostgreSQL: schema · Backed by migration-managed tables.
- Housekeeper → PostgreSQL: cleans · Manages partitions and stale source data.
- Config → HTTP API: configures · Supplies runtime settings.
- Config → Recommendation poller: configures · Controls polling behavior and flags.
- Config → Report processor: configures · Controls ingestion and processing behavior.
- OpenShift → CLI bootstrap: runs · Provides the OpenShift deployment environment.
- OpenShift → Kafka: binds · Provides platform Kafka connectivity.
- OpenShift → PostgreSQL: binds · Provides platform database connectivity.
- CI/CD → OpenShift: deploys · Builds and delivers the service to OpenShift.
- Docs & ops → HTTP API: documents · Captures the HTTP surface and sample usage.
- Docs & ops → PostgreSQL: describes · Reflects database schema and examples.