Welcome to the Architecture Portal for the User Management System (UMS).
UMS is a satellite product of the Evolith Architecture Reference. This relationship defines how architectural decisions are made in this repository.
Evolith (parent) UMS (satellite)
───────────────────────────── ──────────────────────────────────
Defines baseline policies ──► Inherits by reference (ADR-0050)
Provides canonical patterns ──► Adopts or adapts per UMS context
Sets naming conventions ──► Conforms + documents exceptions
A UMS ADR can do one of three things relative to Evolith:
| Mode | When to use | Example |
|---|---|---|
| Adopt | Evolith policy applies as-is | ADR-0050: Naming taxonomy adopted verbatim |
| Specialize | Evolith policy applies but UMS adds constraints | ADR-0052: Immutable audit trail with SQL Server specifics |
| Override | UMS diverges from Evolith with explicit justification | ADR-0059: Single API tier decision (co-location over split tiers) |
When you encounter a decision that seems to conflict with Evolith, check the relevant UMS ADR first. The override may be intentional and justified. If no ADR exists, the Evolith baseline applies. Never assume silence means permission to deviate.
Evolith permits splitting query and command surfaces into separate API tiers when scale or team ownership justifies it. UMS explicitly decided not to do this at current maturity:
- CQRS separation already exists at protocol level (GraphQL queries / REST commands).
- Splitting tiers adds operational cost with no measurable benefit at MVP scale.
- Multi-tenant load risk is mitigated by complexity limits, timeouts, and gateway rate limiting (TE-07).
This decision is recorded in ADR-0059 with explicit triggers for when the decision should be revisited.
This is the intended pattern: inherit the baseline, override with evidence, document the trigger to revert.
- Architecture Overview: Global architecture vision, bounded context map, aggregate catalog, and cross-context integration principles.
This section focuses on structural design, data models, domain alignment, and implementation traceability.
Detailed engineering blueprints focusing on:
- Database Design ER: The authoritative physical entity-relationship model.
- Data Model Consistency Review: Cross-check between conceptual model, DDD aggregates, ER diagrams, and EF Core persistence records.
- ER Export Formats: SQL, Mermaid, and image exports of the schema.
- Interactive ER Viewer: Browser-based tool to explore the database structure.
- Service Entity Map: Logical mapping between system services and database entities.
- Shell Library Architecture: UMS-owned shell layer for inherited DDD and Factory patterns.
- Shell Library Developer Guides: Comprehensive developer guides for all four shell libraries with independent and combined usage examples.
Applied backend API reference for UMS. This section maps current .NET API source evidence to the Evolith API Standard - .NET while keeping product-specific implementation details local to UMS.
Applied React Web reference for UMS. This section maps current source evidence to the Evolith Web Frontend Standard - React while keeping product-specific implementation details local to UMS.
Cross-reference of Functional Stories to ADRs and Technical Enablers.
Engineering blueprints specifying how ADRs are implemented in the UMS context:
Reference implementations for core architectural patterns:
- CP-01: Hexagonal Architecture — Port & Adapter
- CP-02: Aggregate Root & Domain Event
- CP-03: Result Pattern
- CP-04: Multi-Tenant Repository with RLS
- Domain Aggregate Index: Authoritative aggregate-root catalog.
- DDD Design Portal: Bounded contexts, aggregates, value objects, commands, events, and state machines for the complete product.
- DDD Primitives: Domain primitives implemented through the UMS shell library layer.
- Interactive DDD Viewer: Browser-based tool to explore bounded context map, state machines, and cross-context flows.
- Solution Metrics Dashboard: Consolidated engineering metrics across all solutions (API, Web, Libs, Tests) organized by category: coding, security, quality, tests, and AI usage.