# osac-project/osac architecture

> Architecture diagram of the GitHub repository osac-project/osac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/osac-project/osac
- Repository: https://github.com/osac-project/osac

## Overview

OSAC is a multi-tenant cloud platform. Users provision cloud resources through its CLI, web UI, or gRPC/REST API; the fulfillment service manages resource state, and Kubernetes operators reconcile resources and invoke infrastructure automation. The repository also includes bare-metal provisioning, storage integration, CSI routing, and a metering pipeline. Cross-component links below rely on README statements; sampled source confirms selected storage, bare-metal, and CSI responsibilities, but does not expose every runtime connection.

Main entry points: [`fulfillment-service/internal/servers`](https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/servers) (gRPC and REST API), [`osac-operator/internal/controller`](https://github.com/osac-project/osac/tree/main/osac-operator/internal/controller) (OSAC operator), [`fulfillment-service/internal/servers/private_storage_backends_server.go`](https://github.com/osac-project/osac/blob/main/fulfillment-service/internal/servers/private_storage_backends_server.go) (Storage backend API), [`osac-csi-driver/pkg/driver/controller.go`](https://github.com/osac-project/osac/blob/main/osac-csi-driver/pkg/driver/controller.go) (OSAC CSI driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["OSAC CLI"]
  node_webui["Web UI"]
end

subgraph group_fulfillment["Fulfillment control plane"]
  node_api["gRPC and REST API"]
  node_auth["Tenant auth and RBAC"]
  node_database[("PostgreSQL state")]
  node_controllers["Resource controllers"]
end

subgraph group_provisioning["Provisioning and infrastructure"]
  node_baremetalcr["Bare-metal resources"]
  node_baremetalreconcile["Bare-metal reconciler"]
  node_hostmanager["Host management<br/>[manager.go]"]
  node_operator["OSAC operator"]
  node_automation["AAP automation"]
  node_infrastructure{{"Cloud infrastructure"}}
end

subgraph group_storage["Storage services"]
  node_storagecontroller["Storage reconciler"]
  node_storageapi["Storage backend API"]
  node_storageui["Storage admin UI"]
  node_csidriver["OSAC CSI driver<br/>[controller.go]"]
  node_vendorcsi{{"Vendor CSI drivers"}}
end

subgraph group_events["Metering"]
  node_metering["Metering service<br/>[main.go]"]
  node_kafka["Kafka"]
  node_adapters["Billing adapters"]
end

node_user(("Cloud user"))
node_modelaas{{"Model inference service"}}

node_user -->|"uses"| node_cli
node_user -->|"uses"| node_webui
node_user -->|"automates through"| node_api
node_cli -->|"calls"| node_api
node_webui -.->|"uses"| node_api
node_api -->|"authorizes"| node_auth
node_api -->|"stores state"| node_database
node_api -->|"manages resources"| node_controllers
node_controllers -->|"creates resources"| node_operator
node_operator -->|"triggers jobs"| node_automation
node_automation -->|"provisions"| node_infrastructure
node_user -->|"requests hosts"| node_baremetalcr
node_baremetalcr -.->|"reconciled by"| node_baremetalreconcile
node_baremetalreconcile -.->|"manages hosts"| node_hostmanager
node_operator -->|"reconciles storage"| node_storagecontroller
node_storageui -.->|"manages backends"| node_storageapi
node_storageapi -.->|"persists records"| node_database
node_csidriver -->|"resolves storage tiers"| node_storageapi
node_csidriver -->|"routes requests"| node_vendorcsi
node_metering -->|"watches events"| node_api
node_metering -->|"publishes events"| node_kafka
node_kafka -->|"feeds billing"| node_adapters
node_user -->|"requests inference"| node_modelaas

click node_cli "https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/cmd/cli"
click node_webui "https://github.com/osac-project/osac/tree/main/osac-ui/apps/app-frontend/src"
click node_api "https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/servers"
click node_auth "https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/auth"
click node_database "https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/database"
click node_controllers "https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/controllers"
click node_baremetalcr "https://github.com/osac-project/osac/blob/main/bare-metal-fulfillment-operator/api/v1alpha1/baremetalinstance_types.go"
click node_baremetalreconcile "https://github.com/osac-project/osac/blob/main/bare-metal-fulfillment-operator/internal/controller/baremetalinstance_controller.go"
click node_hostmanager "https://github.com/osac-project/osac/blob/main/bare-metal-fulfillment-operator/internal/baremetalhost/manager.go"
click node_operator "https://github.com/osac-project/osac/tree/main/osac-operator/internal/controller"
click node_automation "https://github.com/osac-project/osac/tree/main/osac-aap"
click node_storagecontroller "https://github.com/osac-project/osac/blob/main/osac-operator/internal/controller/storage_controller.go"
click node_storageapi "https://github.com/osac-project/osac/blob/main/fulfillment-service/internal/servers/private_storage_backends_server.go"
click node_storageui "https://github.com/osac-project/osac/blob/main/osac-ui/libs/ui-components/src/components/Storage/StorageTierCreatePage.tsx"
click node_csidriver "https://github.com/osac-project/osac/blob/main/osac-csi-driver/pkg/driver/controller.go"
click node_metering "https://github.com/osac-project/osac/blob/main/osac-metering/metering-service/cmd/metering-service/main.go"
click node_adapters "https://github.com/osac-project/osac/tree/main/osac-metering/adapters"

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_cli,node_webui,node_user toneBlue
class node_api,node_auth,node_database,node_controllers toneAmber
class node_baremetalcr,node_baremetalreconcile,node_hostmanager,node_operator,node_automation,node_infrastructure toneMint
class node_storagecontroller,node_storageapi,node_storageui,node_csidriver,node_vendorcsi toneRose
class node_metering,node_kafka,node_adapters,node_modelaas toneIndigo
```

## Components

### User interfaces

- [OSAC CLI](https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/cmd/cli): `fulfillment-service/internal/cmd/cli`
- [Web UI](https://github.com/osac-project/osac/tree/main/osac-ui/apps/app-frontend/src): `osac-ui/apps/app-frontend/src`

### Fulfillment control plane

- [gRPC and REST API](https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/servers): `fulfillment-service/internal/servers`
- [Tenant auth and RBAC](https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/auth): `fulfillment-service/internal/auth`
- [PostgreSQL state](https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/database): `fulfillment-service/internal/database`
- [Resource controllers](https://github.com/osac-project/osac/tree/main/fulfillment-service/internal/controllers): `fulfillment-service/internal/controllers`

### Provisioning and infrastructure

- [Bare-metal resources](https://github.com/osac-project/osac/blob/main/bare-metal-fulfillment-operator/api/v1alpha1/baremetalinstance_types.go): `bare-metal-fulfillment-operator/api/v1alpha1/baremetalinstance_types.go`
- [Bare-metal reconciler](https://github.com/osac-project/osac/blob/main/bare-metal-fulfillment-operator/internal/controller/baremetalinstance_controller.go): `bare-metal-fulfillment-operator/internal/controller/baremetalinstance_controller.go`
- [Host management](https://github.com/osac-project/osac/blob/main/bare-metal-fulfillment-operator/internal/baremetalhost/manager.go): `bare-metal-fulfillment-operator/internal/baremetalhost/manager.go`
- [OSAC operator](https://github.com/osac-project/osac/tree/main/osac-operator/internal/controller): `osac-operator/internal/controller`
- [AAP automation](https://github.com/osac-project/osac/tree/main/osac-aap): `osac-aap`
- **Cloud infrastructure**

### Storage services

- [Storage reconciler](https://github.com/osac-project/osac/blob/main/osac-operator/internal/controller/storage_controller.go): `osac-operator/internal/controller/storage_controller.go`
- [Storage backend API](https://github.com/osac-project/osac/blob/main/fulfillment-service/internal/servers/private_storage_backends_server.go): `fulfillment-service/internal/servers/private_storage_backends_server.go`
- [Storage admin UI](https://github.com/osac-project/osac/blob/main/osac-ui/libs/ui-components/src/components/Storage/StorageTierCreatePage.tsx): `osac-ui/libs/ui-components/src/components/Storage/StorageTierCreatePage.tsx`
- [OSAC CSI driver](https://github.com/osac-project/osac/blob/main/osac-csi-driver/pkg/driver/controller.go): `osac-csi-driver/pkg/driver/controller.go`
- **Vendor CSI drivers**

### Metering

- [Metering service](https://github.com/osac-project/osac/blob/main/osac-metering/metering-service/cmd/metering-service/main.go): `osac-metering/metering-service/cmd/metering-service/main.go`
- **Kafka**
- [Billing adapters](https://github.com/osac-project/osac/tree/main/osac-metering/adapters): `osac-metering/adapters`

### Other components

- **Cloud user**
- **Model inference service**

## Connections

- Cloud user → OSAC CLI: uses (evidence: `README.md`)
- Cloud user → Web UI: uses (evidence: `README.md`)
- Cloud user → gRPC and REST API: automates through (evidence: `README.md`)
- OSAC CLI → gRPC and REST API: calls (evidence: `README.md`)
- Web UI → gRPC and REST API: uses
- gRPC and REST API → Tenant auth and RBAC: authorizes (evidence: `README.md`)
- gRPC and REST API → PostgreSQL state: stores state (evidence: `README.md`)
- gRPC and REST API → Resource controllers: manages resources (evidence: `README.md`)
- Resource controllers → OSAC operator: creates resources (evidence: `README.md`)
- OSAC operator → AAP automation: triggers jobs (evidence: `README.md`)
- AAP automation → Cloud infrastructure: provisions (evidence: `README.md`)
- Cloud user → Bare-metal resources: requests hosts (evidence: `README.md`)
- Bare-metal resources → Bare-metal reconciler: reconciled by
- Bare-metal reconciler → Host management: manages hosts
- OSAC operator → Storage reconciler: reconciles storage (evidence: `README.md`)
- Storage admin UI → Storage backend API: manages backends
- Storage backend API → PostgreSQL state: persists records (evidence: `fulfillment-service/internal/servers/private_storage_backends_server.go`)
- OSAC CSI driver → Storage backend API: resolves storage tiers (evidence: `README.md`)
- OSAC CSI driver → Vendor CSI drivers: routes requests (evidence: `README.md`)
- Metering service → gRPC and REST API: watches events (evidence: `README.md`)
- Metering service → Kafka: publishes events (evidence: `README.md`)
- Kafka → Billing adapters: feeds billing (evidence: `README.md`)
- Cloud user → Model inference service: requests inference (evidence: `README.md`)
