Skip to content

Commit e2c3f2d

Browse files
beyondnetPeruclaude
beyondnetPeru
and
claude
committed
docs(readme): replace complex README with comprehensive navigation index
Rewrite main README as a single flat index covering all documentation areas: product & requirements, planning, architecture (ADRs, blueprints, TEs, CPs), domain aggregates by bounded context, SDK per runtime, operations runbooks, QA, infrastructure, and Evolith upstream. Removes intermediate hub redirects so any document is reachable in one click from the root. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent fd3b3e0 commit e2c3f2d

1 file changed

Lines changed: 179 additions & 58 deletions

File tree

‎README.md‎

Lines changed: 179 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,204 @@
1-
# UMS - Enterprise User Management System
1+
# UMS — Enterprise User Management System
22

33
> Language: [English](./README.md) | [Español](./docs/README.es.md)
44
5-
UMS is a modular monolith for identity, authorization, configuration, approvals, compliance, IGA, and audit. It is an applied implementation based on Evolith: reusable enterprise standards live upstream, while UMS documents product-specific evidence, local decisions, and ADR-backed deviations in `docs/`.
5+
Modular monolith for identity, authorization, configuration, approvals, compliance, IGA, and audit.
6+
Built on **.NET 10 · SQL Server 2022 · React 18 · TypeScript · Nx**.
7+
Applied implementation of the [Evolith](https://github.com/beyondnetcode/evolith_arch32) architecture framework.
68

7-
## Documentation Entry Points
9+
---
810

9-
| Need | Open this |
10-
|---|---|
11-
| English documentation portal | [docs/README.md](./docs/README.md) |
12-
| Portal documental en español | [docs/README.es.md](./docs/README.es.md) |
13-
| Master Index | [docs/MASTER_INDEX.md](./docs/MASTER_INDEX.md) |
14-
| Índice Maestro | [docs/MASTER_INDEX.es.md](./docs/MASTER_INDEX.es.md) |
15-
| Standards | [docs/STANDARDS.md](./docs/STANDARDS.md) |
16-
| Estándares | [docs/STANDARDS.es.md](./docs/STANDARDS.es.md) |
11+
## Navigation Index
1712

18-
## Fast Routes
13+
### Product & Requirements
1914

20-
| Need | Open this |
15+
| Document | Description |
16+
|---|---|
17+
| [Product Vision](./docs/governance/product/product-vision.md) | Strategy, goals, and positioning |
18+
| [Business Context](./docs/governance/product/business-context.md) | Market context and problem space |
19+
| [Scope & Boundaries](./docs/governance/product/scope.md) | What UMS is and is not |
20+
| [Objectives (OKRs)](./docs/governance/product/objectives.md) | Measurable success criteria |
21+
| [Stakeholders](./docs/governance/product/stakeholders.md) | Roles and responsibilities |
22+
| [Innovation Roadmap](./docs/governance/product/innovation-roadmap.md) | Future evolution plan |
23+
| [Glossary](./docs/governance/requirements/glossary.md) | Ubiquitous language |
24+
| [Conceptual Data Model](./docs/governance/requirements/conceptual-data-model.md) | High-level domain model |
25+
| [Functional Stories](./docs/governance/requirements/functional-stories/index.md) | Full requirements backlog |
26+
| [Permission Matrix](./docs/governance/requirements/permission-matrix-example.md) | Role/permission reference |
27+
28+
### Planning & Backlog
29+
30+
| Document | Description |
2131
|---|---|
22-
| Short navigation by team or goal | [Quick Navigation](./docs/governance/quick-navigation.md) |
23-
| Architecture portal | [Architecture Portal](./docs/architecture/index.md) |
24-
| Portal de Arquitectura | [Portal de Arquitectura](./docs/architecture/index.es.md) |
25-
| Governance portal | [Governance Portal](./docs/governance/index.md) |
26-
| Portal de Gobernanza | [Portal de Gobernanza](./docs/governance/index.es.md) |
27-
| Operations portal | [Operations Portal](./docs/operations/index.md) |
28-
| Portal de Operaciones | [Portal de Operaciones](./docs/operations/index.es.md) |
32+
| [Project Backlog](./docs/governance/project/index.md) | Epics and sprint planning |
33+
| [MVP Product Backlog](./docs/governance/project/mvp-product-backlog.md) | Prioritized MVP scope |
34+
| [Functional Story Gap Tracker](./docs/governance/project/functional-story-gap-tracker.md) | Implementation status per story |
35+
| [Epic 06: Approvals](./docs/governance/project/ep-06-approvals-detailed-design.md) | Approval workflow design |
36+
| [Epic 07: Compliance](./docs/governance/project/ep-07-compliance-detailed-design.md) | Compliance module design |
37+
| [Epic 08: IGA](./docs/governance/project/ep-08-iga-detailed-design.md) | Identity Governance design |
2938

30-
## At a Glance
39+
### Architecture
3140

32-
| Area | Authoritative choice |
41+
| Document | Description |
42+
|---|---|
43+
| [Architecture Portal](./docs/architecture/index.md) | Architecture hub |
44+
| [Architecture Overview](./docs/architecture/overview.md) | System-wide diagram and layers |
45+
| [Traceability Matrix](./docs/architecture/traceability-matrix.md) | FS → ADR → Technical Enabler |
46+
| [Database Design ER](./docs/architecture/blueprints/database-design-er.md) | Entity-relationship model |
47+
| [Service Entity Map](./docs/architecture/blueprints/service-entity-map.md) | Service-to-entity ownership |
48+
| [Shell Library Architecture](./docs/architecture/blueprints/shell-library-architecture.md) | BeyondNetCode.Shell.* design |
49+
| [Notification & Feedback Architecture](./docs/architecture/blueprints/notification-feedback-architecture.md) | Error/feedback wire contract |
50+
| [Observability Architecture Flow](./docs/architecture/blueprints/observability-architecture-flow.md) | OTel tracing & logging |
51+
52+
### Architecture Decision Records (ADRs)
53+
54+
| ADR | Title | Evolith Relationship |
55+
|---|---|---|
56+
| [ADR-0050](./docs/architecture/adrs/0050-naming-taxonomy-standard.md) | Naming & Taxonomy Standard | Adopts Evolith ADR-0056 |
57+
| [ADR-0051](./docs/architecture/adrs/0051-event-bus-injectable-port.md) | Event Bus Injectable Port | Adopts Evolith ADR-0015 |
58+
| [ADR-0052](./docs/architecture/adrs/0052-immutable-audit-trail-enforcement.md) | Immutable Audit Trail | Adopts Evolith ADR-0016 |
59+
| [ADR-0053](./docs/architecture/adrs/0053-opentelemetry-observability.md) | OpenTelemetry Observability | Adopts Evolith ADR-0007 |
60+
| [ADR-0054](./docs/architecture/adrs/0054-shell-library-isolation.md) | Shell Library Isolation | UMS-specific |
61+
| [ADR-0055](./docs/architecture/adrs/0055-graphql-rest-hybrid-api.md) | GraphQL/REST Hybrid API | Implements Evolith ADR-0012 |
62+
| [ADR-0056](./docs/architecture/adrs/0056-clean-architecture-frontend.md) | Clean Architecture Frontend | Promoted → Evolith nodejs/0044 |
63+
| [ADR-0057](./docs/architecture/adrs/0057-zustand-tanstack-query-state.md) | Zustand + TanStack Query | Promoted → Evolith nodejs/0045 |
64+
| [ADR-0058](./docs/architecture/adrs/0058-api-gateway-yarp-evolution.md) | API Gateway YARP Evolution | Implements Evolith ADR-0008 |
65+
| [ADR-0059](./docs/architecture/adrs/0059-single-api-tier-decision.md) | Single API Tier Decision | Override of Evolith baseline |
66+
| [ADR-0060](./docs/architecture/adrs/0060-aop-cross-cutting-concern-strategy.md) | AOP Cross-Cutting Concern | Promoted → Evolith dotnet/0072 |
67+
| [ADR-0061](./docs/architecture/adrs/0061-execution-context-accessor.md) | Execution Context Accessor | Promoted → Evolith dotnet/0064 |
68+
| [ADR-0062](./docs/architecture/adrs/0062-pii-safe-serilog-configuration.md) | PII-Safe Serilog | Promoted → Evolith dotnet/0065 |
69+
| [ADR-0063](./docs/architecture/adrs/0063-idempotency-middleware.md) | Idempotency Middleware | Promoted → Evolith dotnet/0066 |
70+
| [ADR-0064](./docs/architecture/adrs/0064-lean-root-repository-taxonomy.md) | Lean Root Repository Taxonomy | Promoted → Evolith core/0070 |
71+
| [ADR-0065](./docs/architecture/adrs/0065-no-raw-guids-in-ui.md) | No Raw GUIDs in UI | Promoted → Evolith nodejs/0046 |
72+
| [ADR-0066](./docs/architecture/adrs/0066-actionable-user-error-contract.md) | Actionable User Error Contract | Promoted → Evolith nodejs/0047 |
73+
| [ADR-0067](./docs/architecture/adrs/0067-modular-monolith-schema-per-domain.md) | Modular Monolith Schema Per Domain | Promoted → Evolith core/0067 |
74+
| [ADR-0068](./docs/architecture/adrs/0068-feature-flag-system-scope.md) | Feature Flag System Scope | Promoted → Evolith nodejs/0048 |
75+
| [ADR-0069](./docs/architecture/adrs/0069-domain-inheritance-strategy.md) | Domain Inheritance Strategy | Promoted → Evolith core/0071 |
76+
| [ADR-0070](./docs/architecture/adrs/0070-database-schema-strategy-decision.md) | Database Schema Strategy | Adopts Evolith ADR-0067 |
77+
| [ADR-0071](./docs/architecture/adrs/0071-auth-graph-engine.md) | Authorization Graph Engine | UMS-specific |
78+
| [ADR-0072](./docs/architecture/adrs/0072-dynamic-auth-method-resolution.md) | Dynamic Auth Method Resolution | UMS-specific |
79+
| [ADR-0073](./docs/architecture/adrs/0073-ums-sdk-multi-runtime.md) | UMS SDK Multi-Runtime | UMS-specific |
80+
| [ADR-0074](./docs/architecture/adrs/0074-auth-graph-schema-versioning.md) | Auth Graph Schema Versioning | UMS-specific |
81+
| [ADR-0075](./docs/architecture/adrs/0075-onboarding-approval-inbox-and-scope-based-authorization.md) | Onboarding Approval Inbox | UMS-specific |
82+
| [ADR-0076](./docs/architecture/adrs/0076-utc-dates-timezone-language-resolution.md) | UTC Dates & Language Resolution | Promoted → Evolith core/0072 |
83+
| [ADR-0077](./docs/architecture/adrs/0077-tenant-portal-management-authorization-boundary.md) | Tenant Portal Auth Boundary | UMS-specific |
84+
| [ADR-0078](./docs/architecture/adrs/0078-ddd-domain-resource-hierarchy.md) | DDD Domain Resource Hierarchy | UMS-specific |
85+
| [ADR-0079](./docs/architecture/adrs/0079-dependency-guard-policy.md) | Dependency Guard Policy | UMS-specific |
86+
| [ADR-0080](./docs/architecture/adrs/0080-auth-graph-preview-internal-pipeline.md) | Auth Graph Preview Pipeline | UMS-specific |
87+
| [ADR-0081](./docs/architecture/adrs/0081-semantic-auth-graph-client-contract.md) | Semantic Auth Graph Contract | UMS-specific |
88+
89+
### Technical Enablers & Canonical Patterns
90+
91+
| Document | Description |
92+
|---|---|
93+
| [Technical Enablers Index](./docs/architecture/blueprints/technical-enablers/index.md) | All TE documents |
94+
| [TE-01: JWT / OIDC Flow](./docs/architecture/blueprints/technical-enablers/te-01-jwt-oidc-flow.md) | Authentication token flow |
95+
| [TE-02: Permission Graph Compiler](./docs/architecture/blueprints/technical-enablers/te-02-permission-graph-compiler.md) | Auth graph build pipeline |
96+
| [TE-03: Tenant Provisioning](./docs/architecture/blueprints/technical-enablers/te-03-tenant-provisioning.md) | Tenant onboarding flow |
97+
| [TE-04: Transactional Outbox](./docs/architecture/blueprints/technical-enablers/te-04-transactional-outbox.md) | Reliable event publishing |
98+
| [TE-05: Distributed Saga (Dapr)](./docs/architecture/blueprints/technical-enablers/te-05-distributed-saga-dapr.md) | Cross-context sagas |
99+
| [TE-06: CQRS Projection Rebuild](./docs/architecture/blueprints/technical-enablers/te-06-cqrs-projection-rebuild.md) | Read model rebuild strategy |
100+
| [TE-07: YARP API Gateway](./docs/architecture/blueprints/technical-enablers/te-07-yarp-api-gateway.md) | Reverse proxy setup |
101+
| [Canonical Patterns Index](./docs/architecture/artifacts/canonical-patterns/index.md) | All CP documents |
102+
| [CP-01: Hexagonal Port/Adapter](./docs/architecture/artifacts/canonical-patterns/cp-01-hexagonal-port-adapter.md) | Port/adapter pattern |
103+
| [CP-02: Aggregate Root & Domain Event](./docs/architecture/artifacts/canonical-patterns/cp-02-aggregate-root-domain-event.md) | DDD aggregate pattern |
104+
| [CP-03: Result Pattern](./docs/architecture/artifacts/canonical-patterns/cp-03-result-pattern.md) | Error handling without exceptions |
105+
| [CP-04: Multi-tenant Repository + RLS](./docs/architecture/artifacts/canonical-patterns/cp-04-multitenant-repository-rls.md) | Tenant-scoped data access |
106+
| [CP-05: Execution Context Propagation](./docs/architecture/artifacts/canonical-patterns/cp-05-execution-context-propagation.md) | Request scope propagation |
107+
| [CP-06: PII-Safe Structured Logging](./docs/architecture/artifacts/canonical-patterns/cp-06-pii-safe-structured-logging.md) | Serilog + redaction |
108+
| [CP-07: Idempotency Middleware](./docs/architecture/artifacts/canonical-patterns/cp-07-idempotency-middleware.md) | Request deduplication |
109+
| [CP-08: AOP Logging Decorator](./docs/architecture/artifacts/canonical-patterns/cp-08-aop-logging-decorator.md) | DispatchProxy AOP |
110+
111+
### Domain Model
112+
113+
| Document | Description |
114+
|---|---|
115+
| [Domain Aggregate Index](./docs/domain/index.md) | All aggregates with full structure |
116+
| [Bounded Context Map](./docs/governance/construction/ddd-design/01-bounded-context-map.md) | Context map and relationships |
117+
| [Ubiquitous Language](./docs/governance/construction/ddd-design/02-ubiquitous-language.md) | Domain vocabulary |
118+
| **Identity BC** | [Tenant](./docs/domain/identity/tenant.md) · [UserAccount](./docs/domain/identity/user-account.md) · [Delegation](./docs/domain/identity/user-management-delegation.md) · [Auth Graph](./docs/domain/identity/auth-graph.md) · [Auth Method](./docs/domain/identity/auth-method-resolution.md) |
119+
| **Authorization BC** | [SystemSuite](./docs/domain/authorization/system-suite.md) · [PermissionTemplate](./docs/domain/authorization/permission-template.md) · [Profile](./docs/domain/authorization/profile.md) |
120+
| **Configuration BC** | [IdpConfiguration](./docs/domain/configuration/idp-configuration.md) · [AppConfiguration](./docs/domain/configuration/app-configuration.md) · [FeatureFlag](./docs/domain/configuration/feature-flag.md) |
121+
| **Approvals BC** | [ApprovalWorkflow](./docs/domain/approvals/approval-workflow.md) · [ApprovalRequest](./docs/domain/approvals/approval-request.md) · [DocumentType](./docs/domain/approvals/document-type.md) |
122+
| **IGA BC** | [PromotionRequest](./docs/domain/iga/promotion-request.md) · [RoleMaturityStatus](./docs/domain/iga/role-maturity-status.md) |
123+
| **Audit BC** | [AuditRecord](./docs/domain/audit/audit-record.md) |
124+
| [Cross-Context Flows](./docs/governance/construction/ddd-design/10-cross-context-flows.md) | Inter-context sagas and flows |
125+
| [DDD Primitives](./docs/governance/construction/ddd-design/11-ddd-primitives.md) | Base classes and value objects |
126+
127+
### SDK
128+
129+
| Document | Description |
33130
|---|---|
34-
| Backend | .NET 10, SQL Server 2022, EF Core |
35-
| Frontend | React 18, Vite, TypeScript |
36-
| Monorepo | Nx, npm workspaces |
37-
| Delivery method | BMAD-METHOD, Clean Architecture, DDD |
38-
| Multi-tenancy | Application-layer tenant filtering first, SQL Server RLS as a secondary failsafe |
131+
| [SDK Portal](./docs/sdk/index.md) | SDK hub |
132+
| [Schema Overview](./docs/sdk/contracts/schema-overview.md) | AuthorizationGraph JSON schema |
133+
| [Error Codes](./docs/sdk/contracts/error-codes.md) | AUTH_xxx code reference |
134+
| [Versioning Policy](./docs/sdk/contracts/versioning.md) | Schema version compatibility |
135+
| [Compatibility Matrix](./docs/sdk/contracts/compatibility-matrix.md) | Runtime version matrix |
136+
| [Fixtures](./docs/sdk/contracts/fixtures.md) | Test fixture reference |
137+
| [Semantic Client Contract](./docs/sdk/contracts/semantic-client-contract.md) | Code-first, ID-optional contract |
138+
| **.NET** | [README](./docs/sdk/dotnet/README.md) · [Quickstart](./docs/sdk/dotnet/quickstart.md) |
139+
| **TypeScript** | [README](./docs/sdk/typescript/README.md) · [Quickstart](./docs/sdk/typescript/quickstart.md) |
140+
| **NestJS** | [README](./docs/sdk/nestjs/README.md) · [Quickstart](./docs/sdk/nestjs/quickstart.md) |
141+
142+
### Operations
143+
144+
| Document | Description |
145+
|---|---|
146+
| [Operations Portal](./docs/operations/index.md) | Operations hub |
147+
| [Metrics Dashboard](./docs/operations/metrics/index.md) | API, frontend, tests, aggregate metrics |
148+
| [RB-01: Incident Response](./docs/operations/runbooks/rb-01-incident-response.md) | On-call incident playbook |
149+
| [RB-02: Rollback Procedure](./docs/operations/runbooks/rb-02-rollback-procedure.md) | Safe rollback steps |
150+
| [RB-03: Cache Failure Recovery](./docs/operations/runbooks/rb-03-cache-failure-recovery.md) | Redis failure recovery |
151+
| [RB-04: Database Failover](./docs/operations/runbooks/rb-04-database-failover.md) | SQL Server failover procedure |
152+
| [Dev DB Anonymization](./docs/operations/runbooks/dev-db-anonymization.md) | PII anonymization for dev environments |
153+
| [GDPR Backup Retention](./docs/operations/runbooks/gdpr-backup-retention-policy.md) | Backup retention compliance |
154+
155+
### QA & Testing
156+
157+
| Document | Description |
158+
|---|---|
159+
| [QA Report](./docs/qa/qa_report.md) | Overall QA status |
160+
| [Unit Testing Results](./docs/governance/testing/unit-testing-results.md) | Unit test coverage and results |
161+
| [Integration Testing Results](./docs/governance/testing/integration-testing-results.md) | Integration test status |
162+
| [Performance Testing Plan](./docs/governance/testing/performance-testing-plan.md) | Load testing strategy |
163+
| [Performance Testing Results](./docs/governance/testing/performance-testing-results.md) | Load test outcomes |
164+
| [QA Evidences: Tenants](./docs/qa/evidences/tenants/US-001-Create-Tenant-Success.md) | US-001 through US-004 |
165+
| [QA Evidences: Users](./docs/qa/evidences/users/US-005-Create-User.md) | US-005 through US-008 |
39166

40-
## Local Workflows
167+
### Infrastructure
41168

42-
All technical commands should be run from `src/`.
169+
| Document | Description |
170+
|---|---|
171+
| [Infrastructure Plan](./infra/infrastructure_plan.md) | Kubernetes infrastructure design |
172+
| [Implementation Plan](./infra/implementation_plan.md) | Deployment implementation steps |
173+
| [K8s Deployment Plan](./infra/UMS_K8s_Deployment_Plan.md) | Full K8s deployment guide |
174+
| [Local Access Guide](./infra/accesos_local.md) | Local environment endpoints |
43175

44-
### Frontend
176+
### Standards & Governance
45177

46-
```bash
47-
cd src
48-
npm install
49-
npx nx run app-web:dev
50-
```
51-
52-
### Backend
178+
| Document | Description |
179+
|---|---|
180+
| [Standards](./docs/STANDARDS.md) | Engineering standards reference |
181+
| [Documentation Version Log](./docs/releases/documentation-version-log.md) | Doc change history |
182+
| [Release Checklist](./docs/releases/docs-v1.0.0-checklist.md) | v1.0.0 release gates |
183+
| [Validation Summary](./docs/releases/validation-summary.md) | Documentation validation status |
184+
| [Evolith Framework](https://github.com/beyondnetcode/evolith_arch32) | Upstream architecture reference |
53185

54-
```bash
55-
cd src/apps/ums.api
56-
dotnet build
57-
dotnet run
58-
```
186+
---
59187

60-
### Validation and context
188+
## Quick Start
61189

62190
```bash
63-
cd src
64-
python ../.bmad-core/scripts/validate_docs_consistency.py README.md docs/
65-
```
191+
# Frontend
192+
cd src && npm install && npx nx run app-web:dev
66193

67-
## What to Expect
194+
# Backend
195+
cd src/apps/ums.api && dotnet build && dotnet run
68196

69-
- The root README stays short and executive.
70-
- `docs/README.md` and `docs/README.es.md` are the bilingual home pages for documentation.
71-
- `docs/MASTER_INDEX.md` and `docs/MASTER_INDEX.es.md` are the full lifecycle maps.
72-
- UMS-specific evidence belongs in `docs/`, while reusable standards remain in Evolith.
73-
74-
## Governance Notes
197+
# Validate docs consistency
198+
cd src && python ../.bmad-core/scripts/validate_docs_consistency.py README.md docs/
199+
```
75200

76-
- Bilingual documentation must stay synchronized.
77-
- Markdown files must remain clean, professional, and free of decorative icons.
78-
- Architecture decisions must stay aligned with the approved ADRs and the Evolith baseline.
79-
- Reusable enterprise standards belong to Evolith; UMS documents applied evidence and approved local deviations.
80-
- Root documentation should stay short and navigable. Detailed content belongs in `docs/`.
201+
---
81202

82203
## License
83204

0 commit comments

Comments
 (0)