OPC/.github/copilot-instructions.md

OPC (ControlPlane) — Copilot Instructions

What is OPC?

OPC is the ClarityStack control plane. It provisions and manages tenant infrastructure. "OPC" and "ControlPlane" are interchangeable — use context to determine meaning (system vs ticket). "OPC # XXXX" refers to a ticket/work-item. Commit format: OPC # XXXX: Description (space between OPC and #, space after #).

Responsibility

When a new tenant is onboarded, OPC orchestrates:

1. Keycloak realm + client creation
2. Vault secret engine + policies for the tenant
3. Gitea organisation + repo creation
4. Postgres database provisioning
5. Nginx config generation (written to infra/nginx/conf.d/)
6. Spinning up the tenant's Clarity Docker stack

Projects

Project	Role
ControlPlane.AppHost	.NET Aspire host — owns opc-postgres, RabbitMQ, Gitea, ControlPlane UI
ControlPlane.Api	REST API — receives provisioning requests, publishes MassTransit messages
ControlPlane.Worker	Background worker — consumes MassTransit messages, executes provisioning steps
ControlPlane.Core	Shared models, interfaces, messages, config
ControlPlane.ServiceDefaults	Shared Aspire service defaults (OTel, resilience, service discovery)

Messaging

• MassTransit over RabbitMQ for async provisioning steps
• Api publishes, Worker consumes

Key External Dependencies (via infra/docker-compose.yml)

• Keycloak → http://localhost:8080
• Vault → http://localhost:8200
• MinIO → http://localhost:9000
• Platform Postgres → localhost:5432

OPC-owned Infrastructure (via Aspire)

• opc-postgres on port 5433 — databases: opcdb, giteadb
• RabbitMQ with management plugin
• Gitea at http://opc.clarity.test

Conventions

• Target framework: .NET 10
• Nullable and ImplicitUsings enabled globally via root Directory.Build.props
• Central package management via root Directory.Packages.props
• Background services extend BackgroundService