Home

ChatRooms — Engineering Wiki

A reference-grade implementation of Clean Architecture, DDD, and CQRS in .NET 10, built to demonstrate secure, production-appropriate patterns from the ground up — not a toy CRUD app with fancy folder names.

This wiki documents the merged ChatRooms repository as it actually exists in code — not as it's aspirationally described. Every claim in this wiki is traceable to a specific file. Where the code contradicts itself (there are a couple of real inconsistencies — see Known Issues & Gaps), that's called out explicitly rather than papered over.

How to use this wiki

Read in this order if you're new to the codebase:

1. Getting Started
2. Architecture Overview
3. Project Structure
4. Domain Model
5. CQRS & MediatR Pipeline

Then dive into whichever subsystem you're touching.

Page Index

#	Page	Covers
01	Getting Started	Prereqs, running via Aspire, first login
02	Architecture Overview	Layering, dependency rules, request lifecycle
03	Project Structure	Every project in the .slnx, what lives where
04	Domain Model	Room, User aggregates, value objects, events, invariants
05	CQRS & MediatR Pipeline	Command/query flow, ValidationBehavior, ConcurrencyBehavior
06	Authentication & Security	Keycloak, BFF cookie/OIDC, JWT bearer, BffServiceOnly policy
07	Keycloak Setup & Realm	Realm JSON, systemuserid, KeycloakSetup runtime patcher
08	API & Client Behavior	Controllers, Blazor stores, HTTP clients, token refresh
09	Write Model (PostgreSQL)	EF Core configs, migrations, concurrency tokens
10	Outbox Design & State Machine	OutboxMessage lifecycle, DLQ
11	Lease & Worker Concurrency	OutboxBatchProcessor, heartbeat renewal, abandonment
12	Read Model, Mongo & Projectors	IEventProjector, idempotency, upsert strategies
13	Error Handling, Retries & DLQ	Exception middleware, retry counting, dead-lettering
14	Testing Strategy	Test projects, patterns, what's covered vs. not
15	CI/CD	GitHub Actions workflows, format/build/test gates
16	Configuration & Environment	appsettings.json, Aspire parameters, secrets
17	Deployment	Aspire orchestration topology, what's dev-only
18	Observability & Troubleshooting	OpenTelemetry, health checks, common failure modes
19	Performance & Scalability	Outbox batching, read/write split, scaling limits
20	ADRs & Known Issues	Locked-in decisions, and real bugs found in review
21	Coding Conventions	Naming, structure, .editorconfig, skill-encoded rules
22	Contribution & Dev Workflow	Git flow, PR format, CI bypass, migrations workflow
23	Glossary	Ubiquitous language reference

What ChatRooms is (one paragraph)

ChatRooms is a chat-room management system (room lifecycle + user accounts — not yet real-time messaging) split into a write side (ASP.NET Core API → MediatR command handlers → DDD aggregates → EF Core → PostgreSQL) and a read side (MongoDB, queried directly via IRoomQuery/IUserQuery), kept in sync by an Outbox background worker that reads an event log and projects it into MongoDB documents. A YARP-based BFF (ChatRooms.BFF) terminates the browser-facing OIDC/cookie session with Keycloak and forwards bearer tokens to the API; a Blazor Server app (ChatRooms.Blazor) is the UI. Everything is orchestrated locally by .NET Aspire (ChatRooms.AppHost), including a one-shot ChatRooms.KeycloakSetup project that patches Keycloak's realm at runtime to work around Aspire's dynamic port assignment.