# ishitasequeira/models-as-a-service architecture

> Architecture diagram of the GitHub repository ishitasequeira/models-as-a-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ishitasequeira/models-as-a-service
- Repository: https://github.com/ishitasequeira/models-as-a-service

## Overview

MaaS is an OpenShift/Kubernetes platform for publishing model access with tenant, subscription, authentication, and guardrail policy management. Its main control-plane workflow reconciles MaaS resources into tenant/platform configuration; the MaaS API then serves model discovery, subscriptions, and API-key operations to callers. A separate discovery service exposes visible tenants, while an optional usage-log proxy authenticates callers and queries Loki. The graph follows documented capabilities and indexed references; unsampled controller and API internals limit some call-level detail.

Main entry points: [`maas-controller/cmd/manager/main.go`](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/cmd/manager/main.go) (Controller manager), [`maas-api/cmd/main.go`](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/cmd/main.go) (HTTP API), [`maas-controller/pkg/platform/tenantreconcile/pipeline.go`](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/platform/tenantreconcile/pipeline.go) (Platform reconciliation), [`deployment/components/observability/usage-logs/dsci-managed/proxy/main.py`](https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/main.py) (Usage-log proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_manager["Controller manager<br/>[main.go]"]
  node_resources["MaaS resources"]
  node_tenant_ctrl["Tenant reconciliation"]
  node_ai_tenant["AI tenant lifecycle"]
  node_subscription_ctrl["Subscription policy"]
  node_authpolicy_ctrl["Auth policy"]
  node_modelref_ctrl["Model references"]
  node_self_deploy["Self deployment"]
  node_tenant_pipeline["Platform reconciliation<br/>[pipeline.go]"]
end

subgraph group_api["MaaS API"]
  node_api["HTTP API<br/>[main.go]"]
  node_api_key_handler["API key operations<br/>[handler.go]"]
  node_api_key_service["API key service<br/>[service.go]"]
  node_subscription_handler["Subscription endpoints<br/>[handler.go]"]
  node_tenant_endpoint["Tenant endpoint<br/>[handler.go]"]
  node_loki_handler["Loki proxy handler<br/>[handler.go]"]
end

subgraph group_discovery["Tenant discovery"]
  node_discovery_service["Discovery service<br/>[main.go]"]
  node_discovery_handler["Tenant listing<br/>[handler.go]"]
  node_tenant_cache[("Tenant informer cache<br/>[informer.go]")]
  node_gateway_metadata["Gateway metadata<br/>[metadata.go]"]
end

subgraph group_observability["Usage logs"]
  node_logs_proxy["Usage-log proxy<br/>[main.py]"]
  node_proxy_auth["Token authentication<br/>[auth.py]"]
  node_query_rewriter["Query rewriting<br/>[rewriter.py]"]
end

node_operator(("Cluster operator"))
node_loki[("Loki service")]
node_caller(("API caller"))

node_operator -->|"deploys"| node_manager
node_manager -->|"registers"| node_tenant_ctrl
node_manager -->|"registers"| node_ai_tenant
node_manager -->|"registers"| node_subscription_ctrl
node_manager -->|"registers"| node_authpolicy_ctrl
node_manager -->|"registers"| node_modelref_ctrl
node_manager -->|"registers"| node_self_deploy
node_tenant_ctrl -->|"uses"| node_tenant_pipeline
node_ai_tenant -->|"uses"| node_tenant_pipeline
node_subscription_ctrl -->|"uses"| node_tenant_pipeline
node_authpolicy_ctrl -->|"uses"| node_tenant_pipeline
node_self_deploy -->|"uses"| node_tenant_pipeline
node_authpolicy_ctrl -->|"reads"| node_resources
node_modelref_ctrl -->|"reads"| node_resources
node_subscription_ctrl -->|"reads"| node_resources
node_tenant_pipeline -->|"deploys"| node_api
node_caller -->|"requests"| node_api
node_api -->|"routes"| node_api_key_handler
node_api -->|"routes"| node_subscription_handler
node_api -->|"routes"| node_tenant_endpoint
node_api_key_handler -->|"calls"| node_api_key_service
node_api -->|"configures"| node_loki_handler
node_caller -->|"requests"| node_discovery_service
node_discovery_service -->|"registers routes"| node_discovery_handler
node_discovery_handler -->|"lists tenants"| node_tenant_cache
node_tenant_cache -->|"uses"| node_gateway_metadata
node_caller -->|"queries logs"| node_logs_proxy
node_logs_proxy -->|"authenticates"| node_proxy_auth
node_logs_proxy -->|"rewrites queries"| node_query_rewriter
node_logs_proxy -->|"forwards queries"| node_loki
node_caller -.->|"requests logs"| node_loki_handler

click node_manager "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/cmd/manager/main.go"
click node_resources "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/api/maas/v1alpha1/maassubscription_types.go"
click node_tenant_ctrl "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/tenant_controller.go"
click node_ai_tenant "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/aitenant_controller.go"
click node_subscription_ctrl "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/maassubscription_controller.go"
click node_authpolicy_ctrl "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/maasauthpolicy_controller.go"
click node_modelref_ctrl "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/maasmodelref_controller.go"
click node_self_deploy "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/self_deployment_controller.go"
click node_tenant_pipeline "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/platform/tenantreconcile/pipeline.go"
click node_api "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/cmd/main.go"
click node_api_key_handler "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/api_keys/handler.go"
click node_api_key_service "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/api_keys/service.go"
click node_subscription_handler "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/subscription/handler.go"
click node_tenant_endpoint "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/tenant/handler.go"
click node_loki_handler "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/lokiproxy/handler.go"
click node_discovery_service "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/cmd/discovery/main.go"
click node_discovery_handler "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/internal/handler/handler.go"
click node_tenant_cache "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/internal/cache/informer.go"
click node_gateway_metadata "https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/internal/gateway/metadata.go"
click node_logs_proxy "https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/main.py"
click node_proxy_auth "https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/auth.py"
click node_query_rewriter "https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/rewriter.py"

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_manager,node_resources,node_tenant_ctrl,node_ai_tenant,node_subscription_ctrl,node_authpolicy_ctrl,node_modelref_ctrl,node_self_deploy,node_tenant_pipeline toneBlue
class node_api,node_api_key_handler,node_api_key_service,node_subscription_handler,node_tenant_endpoint,node_loki_handler,node_loki toneAmber
class node_discovery_service,node_discovery_handler,node_tenant_cache,node_gateway_metadata,node_caller toneMint
class node_logs_proxy,node_proxy_auth,node_query_rewriter toneRose
class node_operator toneIndigo
```

## Components

### Control plane

- [Controller manager](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/cmd/manager/main.go): `maas-controller/cmd/manager/main.go`
- [MaaS resources](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/api/maas/v1alpha1/maassubscription_types.go): `maas-controller/api/maas/v1alpha1/maassubscription_types.go`
- [Tenant reconciliation](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/tenant_controller.go): `maas-controller/pkg/controller/maas/tenant_controller.go`
- [AI tenant lifecycle](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/aitenant_controller.go): `maas-controller/pkg/controller/maas/aitenant_controller.go`
- [Subscription policy](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/maassubscription_controller.go): `maas-controller/pkg/controller/maas/maassubscription_controller.go`
- [Auth policy](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/maasauthpolicy_controller.go): `maas-controller/pkg/controller/maas/maasauthpolicy_controller.go`
- [Model references](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/maasmodelref_controller.go): `maas-controller/pkg/controller/maas/maasmodelref_controller.go`
- [Self deployment](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/controller/maas/self_deployment_controller.go): `maas-controller/pkg/controller/maas/self_deployment_controller.go`
- [Platform reconciliation](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-controller/pkg/platform/tenantreconcile/pipeline.go): `maas-controller/pkg/platform/tenantreconcile/pipeline.go`

### MaaS API

- [HTTP API](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/cmd/main.go): `maas-api/cmd/main.go`
- [API key operations](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/api_keys/handler.go): `maas-api/internal/api_keys/handler.go`
- [API key service](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/api_keys/service.go): `maas-api/internal/api_keys/service.go`
- [Subscription endpoints](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/subscription/handler.go): `maas-api/internal/subscription/handler.go`
- [Tenant endpoint](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/tenant/handler.go): `maas-api/internal/tenant/handler.go`
- [Loki proxy handler](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-api/internal/lokiproxy/handler.go): `maas-api/internal/lokiproxy/handler.go`

### Tenant discovery

- [Discovery service](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/cmd/discovery/main.go): `maas-discovery/cmd/discovery/main.go`
- [Tenant listing](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/internal/handler/handler.go): `maas-discovery/internal/handler/handler.go`
- [Tenant informer cache](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/internal/cache/informer.go): `maas-discovery/internal/cache/informer.go`
- [Gateway metadata](https://github.com/ishitasequeira/models-as-a-service/blob/main/maas-discovery/internal/gateway/metadata.go): `maas-discovery/internal/gateway/metadata.go`

### Usage logs

- [Usage-log proxy](https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/main.py): `deployment/components/observability/usage-logs/dsci-managed/proxy/main.py`
- [Token authentication](https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/auth.py): `deployment/components/observability/usage-logs/dsci-managed/proxy/auth.py`
- [Query rewriting](https://github.com/ishitasequeira/models-as-a-service/blob/main/deployment/components/observability/usage-logs/dsci-managed/proxy/rewriter.py): `deployment/components/observability/usage-logs/dsci-managed/proxy/rewriter.py`

### Other components

- **Cluster operator**
- **Loki service**
- **API caller**

## Connections

- Cluster operator → Controller manager: deploys (evidence: `README.md`)
- Controller manager → Tenant reconciliation: registers (evidence: `maas-controller/cmd/manager/main.go`)
- Controller manager → AI tenant lifecycle: registers (evidence: `maas-controller/cmd/manager/main.go`)
- Controller manager → Subscription policy: registers (evidence: `maas-controller/cmd/manager/main.go`)
- Controller manager → Auth policy: registers (evidence: `maas-controller/cmd/manager/main.go`)
- Controller manager → Model references: registers (evidence: `maas-controller/cmd/manager/main.go`)
- Controller manager → Self deployment: registers (evidence: `maas-controller/cmd/manager/main.go`)
- Tenant reconciliation → Platform reconciliation: uses (evidence: `maas-controller/pkg/controller/maas/tenant_controller.go`)
- AI tenant lifecycle → Platform reconciliation: uses (evidence: `maas-controller/pkg/controller/maas/aitenant_controller.go`)
- Subscription policy → Platform reconciliation: uses (evidence: `maas-controller/pkg/controller/maas/maassubscription_controller.go`)
- Auth policy → Platform reconciliation: uses (evidence: `maas-controller/pkg/controller/maas/maasauthpolicy_controller.go`)
- Self deployment → Platform reconciliation: uses (evidence: `maas-controller/pkg/controller/maas/self_deployment_controller.go`)
- Auth policy → MaaS resources: reads (evidence: `maas-controller/pkg/controller/maas/maasauthpolicy_controller.go`)
- Model references → MaaS resources: reads (evidence: `maas-controller/pkg/controller/maas/maasmodelref_controller.go`)
- Subscription policy → MaaS resources: reads (evidence: `maas-controller/pkg/controller/maas/maassubscription_controller.go`)
- Platform reconciliation → HTTP API: deploys (evidence: `README.md`)
- API caller → HTTP API: requests (evidence: `maas-api/cmd/main.go`)
- HTTP API → API key operations: routes (evidence: `maas-api/cmd/main.go`)
- HTTP API → Subscription endpoints: routes (evidence: `maas-api/cmd/main.go`)
- HTTP API → Tenant endpoint: routes (evidence: `maas-api/cmd/main.go`)
- API key operations → API key service: calls (evidence: `maas-api/internal/api_keys/handler.go`)
- HTTP API → Loki proxy handler: configures (evidence: `maas-api/cmd/main.go`)
- API caller → Discovery service: requests (evidence: `maas-discovery/cmd/discovery/main.go`)
- Discovery service → Tenant listing: registers routes (evidence: `maas-discovery/cmd/discovery/main.go`)
- Tenant listing → Tenant informer cache: lists tenants (evidence: `maas-discovery/internal/handler/handler.go`)
- Tenant informer cache → Gateway metadata: uses (evidence: `maas-discovery/internal/cache/informer.go`)
- API caller → Usage-log proxy: queries logs (evidence: `deployment/components/observability/usage-logs/dsci-managed/proxy/main.py`)
- Usage-log proxy → Token authentication: authenticates (evidence: `deployment/components/observability/usage-logs/dsci-managed/proxy/main.py`)
- Usage-log proxy → Query rewriting: rewrites queries (evidence: `deployment/components/observability/usage-logs/dsci-managed/proxy/main.py`)
- Usage-log proxy → Loki service: forwards queries (evidence: `deployment/components/observability/usage-logs/dsci-managed/proxy/main.py`)
- API caller → Loki proxy handler: requests logs
