OPC # 0001: Extract OPC into standalone repo

Co-authored-by: Copilot <copilot@github.com>
2026-04-25 19:17:48 -04:00
parent 7561ac7530
commit 76962a6af4
6 changed files with 326 additions and 65 deletions
@@ -1,4 +1,45 @@
-# Copilot Instructions
+# OPC (ControlPlane) — Copilot Instructions

-## Project Guidelines
- Commit message format for OPC repo is: "OPC # XXXX: Description" (with a space between OPC and #, and space after #). Example: "OPC # 0001: Extract OPC into standalone repo". This convention comes from enterprise work jargon.
+## 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`