UMS — Enterprise User Management System

Bilingual Navigation: Versión en Español

_{↑ Evolith E2E Architecture Framework · UMS — Official Satellite Product · click to enlarge}

UMS is a modular monolith for identity, authorization, configuration, approvals, compliance, IGA, and audit.
Built on .NET 10 · PostgreSQL · React 18 · TypeScript · Nx. Database-provider agnostic by design.
Applied satellite of the Evolith corporate architecture framework.

---

Quick Navigation Menu

Category	Entry Point	Description
Architecture	Architecture Portal	Blueprints, ADRs, TEs, canonical patterns
ADRs	ADR Registry	32 architecture decisions
Domain Model	Aggregate Index	Bounded contexts · aggregates · entities
SDK	SDK Portal	.NET · TypeScript · NestJS
Requirements	Functional Stories	Full product backlog
Planning	Project Backlog	Epics · MVP · gap tracker
Operations	Operations Portal	Runbooks · metrics
QA	QA Report	Test results · coverage · evidences
Infrastructure	K8s Plan	Kubernetes deployment guide
Full Index	Master Index	Complete lifecycle navigation
Evolith Upstream	Evolith Framework	Architecture reference base

---

Start Here — Choose Your Path

Path 1 — 5-Minute Overview

Product Vision · Architecture Overview · Traceability Matrix

What is UMS? What problem does it solve? How does it fit Evolith?

Path 2 — By Role

Role	Start Here	Then Read
Architect	Architecture Portal	ADR Registry · Traceability Matrix
Backend Dev	Canonical Patterns	Domain Aggregates · .NET SDK
Frontend Dev	ADR-0056: Clean Architecture	TypeScript SDK · ADR-0057: State Mgmt
DevOps / SRE	Infrastructure Plan	Runbooks · Metrics
Product / PM	Product Vision	Gap Tracker · OKRs
AI Contributor	AGENTS.md	ADR Template

Path 3 — Make an Architectural Decision

1. Check ADR Registry — does the decision already exist?
2. If not, use the ADR Template
3. Verify against Evolith ADR Matrix — should this be promoted upstream?

---

Repository Structure (Deep Dive)

Architecture & Patterns

Artifact	Purpose
Architecture Portal	Central entry for all architecture artifacts
Architecture Overview	System-wide diagram and layered model
Traceability Matrix	FS → ADR → Technical Enabler coverage
Blueprints	Database ER, service-entity map, shell library design
Technical Enablers	TE-01 through TE-07
Canonical Patterns	CP-01 through CP-08
API Reference (.NET)	HTTP contract reference

Architecture Decision Records

ADR	Title	Evolith
0050	Naming & Taxonomy Standard	Adopts ADR-0056
0051	Event Bus Injectable Port	Adopts ADR-0015
0052	Immutable Audit Trail	Adopts ADR-0016
0053	OpenTelemetry Observability	Adopts ADR-0007
0054	Shell Library Isolation	UMS-specific
0055	GraphQL/REST Hybrid API	Implements ADR-0012
0056	Clean Architecture Frontend	→ Evolith nodejs/0044
0057	Zustand + TanStack Query	→ Evolith nodejs/0045
0058	API Gateway YARP	Implements ADR-0008
0059	Single API Tier	Override of Evolith baseline
0060	AOP Cross-Cutting Concern	→ Evolith dotnet/0072
0061	Execution Context Accessor	→ Evolith dotnet/0064
0062	PII-Safe Serilog	→ Evolith dotnet/0065
0063	Idempotency Middleware	→ Evolith dotnet/0066
0064	Lean Root Repository Taxonomy	→ Evolith core/0070
0065	No Raw GUIDs in UI	→ Evolith nodejs/0046
0066	Actionable User Error Contract	→ Evolith nodejs/0047
0067	Modular Monolith Schema	→ Evolith core/0067
0068	Feature Flag System Scope	→ Evolith nodejs/0048
0069	Domain Inheritance Strategy	→ Evolith core/0071
0070	Database Schema Strategy	Adopts ADR-0067
0071	Authorization Graph Engine	UMS-specific
0072	Dynamic Auth Method Resolution	UMS-specific
0073	UMS SDK Multi-Runtime	UMS-specific
0074	Auth Graph Schema Versioning	UMS-specific
0075	Onboarding Approval Inbox	UMS-specific
0076	UTC Dates & Language Resolution	→ Evolith core/0072
0077	Tenant Portal Auth Boundary	UMS-specific
0078	DDD Domain Resource Hierarchy	UMS-specific
0079	Dependency Guard Policy	UMS-specific
0080	Auth Graph Preview Pipeline	UMS-specific
0081	Semantic Auth Graph Contract	UMS-specific

Domain Model

Bounded Context	Aggregates
Identity	Tenant · UserAccount · Delegation · Auth Graph · Auth Method
Authorization	SystemSuite · PermissionTemplate · Profile
Configuration	IdpConfiguration · AppConfiguration · FeatureFlag
Approvals	ApprovalWorkflow · ApprovalRequest · DocumentType
IGA	PromotionRequest · RoleMaturityStatus
Audit	AuditRecord

Also: Bounded Context Map · Cross-Context Flows · DDD Primitives

SDK

Runtime	README	Quickstart
.NET	README	Quickstart
TypeScript	README	Quickstart
NestJS	README	Quickstart

Contracts: Schema Overview · Error Codes · Compatibility Matrix · Semantic Client Contract

Product & Requirements

Artifact	Purpose
Product Vision	Strategy, goals, and market positioning
Business Context	Problem space and market context
Scope & Boundaries	What UMS is and is not
Objectives (OKRs)	Measurable success criteria
Stakeholders	Roles and responsibilities
Glossary	Ubiquitous language
Functional Stories	Full requirements backlog
Conceptual Data Model	High-level domain model
Permission Matrix	Role/permission reference

Planning & Backlog

Artifact	Purpose
Project Backlog	Epics and sprint planning
MVP Product Backlog	Prioritized MVP scope
Gap Tracker	Implementation status per story
Epic 06: Approvals	Approval workflow detailed design
Epic 07: Compliance	Compliance module design
Epic 08: IGA	Identity Governance design

Operations

Artifact	Purpose
Metrics Dashboard	API, frontend, tests, aggregate metrics
RB-01: Incident Response	On-call incident playbook
RB-02: Rollback Procedure	Safe rollback steps
RB-03: Cache Failure Recovery	Redis failure recovery
RB-04: Database Failover	SQL Server failover procedure
Dev DB Anonymization	PII anonymization for dev environments
GDPR Backup Retention	Backup retention compliance

QA & Testing

Artifact	Purpose
QA Report	Overall QA status
Unit Testing Results	Unit test coverage and results
Integration Testing Results	Integration test status
Performance Testing Plan	Load testing strategy
Performance Testing Results	Load test outcomes
QA Evidences	US-001 through US-008 screenshots

Infrastructure

Artifact	Purpose
K8s Deployment Plan	Full Kubernetes deployment guide
Infrastructure Plan	Infrastructure design
Implementation Plan	Deployment implementation steps
Local Access Guide	Local environment endpoints

---

Local Development

# Install all dependencies
cd src && npm install

# Frontend (React · Vite · port 5173)
npx nx run app-web:dev

# Backend (.NET 10 · port 7114)
cd src/apps/ums.api && dotnet build && dotnet run

# Run all tests
cd src && npx nx run-many --target=test --all

# Validate documentation consistency
python .bmad-core/scripts/validate_docs_consistency.py README.md docs/

Note: After any change requiring a server reload, kill backend (:7114) and frontend (:5173) and restart both.

---

UMS vs Evolith — What Goes Where

Question	Evolith (Upstream)	UMS (Satellite Product)
What belongs here?	Reusable standards, cross-product ADRs, canonical patterns, governance	Product-specific implementation, domain aggregates, schemas, seeds
How does a product contribute?	Promote an ADR backed by real UMS evidence	Provide executable proof, then propose upstream
What stays local?	Enterprise policies require governance review	Product routes, tenant configs, branding, UMS-specific ADRs

13 UMS ADRs have been promoted to Evolith. See the ADR table above (→ Evolith column).

---

Contributing

Before contributing, read:

• AGENTS.md — Agent rules and conventions
• Standards — Engineering standards
• ADR Template — How to propose a decision
• Evolith Child Repository Inheritance Guide — How UMS inherits from Evolith

---

All Navigation Indexes

Index	Purpose
Master Index	Complete lifecycle navigation (Phase 00–06)
Architecture Index	All architecture artifacts
Domain Index	All aggregates by bounded context
SDK Portal	All SDK runtimes and contracts
Operations Portal	Runbooks and metrics

---

_{UMS — Enterprise User Management System · Satellite of Evolith · .NET 10 · React 18 · Modular Monolith}