ums

Architecture Portal

Welcome to the Architecture Portal for the User Management System (UMS).

Governance Model — Evolith Satellite Architecture

UMS is a satellite product of the Evolith Architecture Reference. This relationship defines how architectural decisions are made in this repository.

How the inheritance works

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)

Why this matters for onboarding

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.

Worked example — API Tier decision

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

• Architecture Overview: Global architecture vision, bounded context map, aggregate catalog, and cross-context integration principles.

---

Core Architecture Assets

This section focuses on structural design, data models, domain alignment, and implementation traceability.

Blueprints

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.
  • BeyondNetCode.Shell.Ddd · BeyondNetCode.Shell.Factory · BeyondNetCode.Shell.Aop · BeyondNetCode.Shell.Bootstrapper · Combined Usage

API .NET

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.

Web Frontend

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.

Traceability Matrix

Cross-reference of Functional Stories to ADRs and Technical Enablers.

Technical Enablers

Engineering blueprints specifying how ADRs are implemented in the UMS context:

• TE-04: Transactional Outbox
• TE-05: Distributed Saga with Dapr
• TE-06: CQRS Projection Rebuild

Canonical Patterns

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

Related — Domain Layer Design

• 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.

---

Engineering Metrics

• Solution Metrics Dashboard: Consolidated engineering metrics across all solutions (API, Web, Libs, Tests) organized by category: coding, security, quality, tests, and AI usage.

---

Back to Master Index

Back to Root README

This site is open source. Improve this page.