pgarciaq/ros-ocp-backend

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.