Clarity/.github/copilot-instructions.md

Clarity — Copilot Instructions

What is Clarity?

Clarity is the tenant-facing product in ClarityStack. Each tenant gets their own isolated Clarity instance, provisioned and managed by OPC (the ControlPlane).

Projects

Project	Role
Clarity.AppHost	.NET Aspire host — owns Postgres, Keycloak, Redis, MinIO, frontend
Clarity.Server	REST API — main backend, EF Core, Keycloak auth, MinIO, Redis output caching
Clarity.MigrationService	Worker that runs EF Core migrations on startup before the server starts
Clarity.ServiceDefaults	Shared Aspire service defaults (OTel, resilience, service discovery)

Aspire-owned Infrastructure

• postgres on port 5432 — databases: postgresdb, authdb (Keycloak)
• Keycloak on port 8080 with realm imported from KeycloakConfig/
• Redis cache
• MinIO object storage
• Vite React frontend at ../frontend

Auth

• Keycloak is the identity provider — realm per tenant in production, clarity realm in dev
• Clarity.Server uses Aspire.Keycloak.Authentication

Conventions

• Commit format: OPC # XXXX: Description
• Target framework: .NET 10
• Nullable and ImplicitUsings enabled globally via root Directory.Build.props
• Central package management via root Directory.Packages.props
• EF Core migrations are handled by Clarity.MigrationService, not inline in the server
• Frontend is a Vite React app at Clarity/frontend/