Skip to content

Commit 2a4b032

Browse files
beyondnetPerubeyondnetPeru
authored
docs: add UMS API dotnet applied reference
Add UMS API Dotnet applied reference documentation.
1 parent 8946277 commit 2a4b032

6 files changed

Lines changed: 282 additions & 0 deletions

File tree

‎docs/architecture/api-dotnet/README.es.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Referencia Aplicada API Dotnet de UMS
2+
3+
> Idioma: [English](./README.md) | [Espanol](./README.es.md)
4+
5+
Esta seccion documenta como la implementacion API Dotnet de UMS aplica el Estandar API Dotnet de Evolith.
6+
7+
UMS es una referencia aplicada, no la fuente de estandares backend universales. Las reglas backend reutilizables pertenecen a Evolith. UMS conserva modulos concretos de producto, endpoints, headers, decisiones de persistencia, bounded contexts, seeds y decisiones locales de implementacion.
8+
9+
## Documentos
10+
11+
| Documento | Proposito |
12+
|---|---|
13+
| [Referencia Aplicada API Dotnet UMS](./ums-api-dotnet-applied-reference.es.md) | Mapeo basado en evidencia entre topicos API de Evolith y archivos fuente de UMS. |
14+
15+
## Limite de autoridad
16+
17+
| Aspecto | Evolith | UMS |
18+
|---|---|---|
19+
| Estandares API reutilizables | Posee principios, reglas boilerplate, quality gates y criterios de promocion | Consume estandares |
20+
| Implementacion de producto | Referencia ejemplos solamente | Posee codigo fuente concreto y decisiones locales |
21+
| Persistencia | Posee gobierno de providers y reglas de calidad de datos | Posee DbContext, repositorios, interceptores, migraciones y switches de provider concretos |
22+
| Superficie API | Posee reglas de responsabilidad REST y GraphQL | Posee endpoints, route groups, schemas y modulos de bounded context concretos |
23+
| Operaciones | Posee capacidades requeridas | Posee Serilog, OpenTelemetry, health checks, rate limits y valores runtime concretos |
24+
25+
## Alcance de evidencia actual
26+
27+
Esta referencia se basa en la API Dotnet actual ubicada en:
28+
29+
```text
30+
src/apps/ums.api
31+
```
32+
33+
Las fuentes observadas incluyen bootstrap de host, service bootstrappers, pipeline middleware, mapeo de superficie API, DI de aplicacion, DI de infraestructura, configuracion de providers de persistencia, health checks, AOP, servicios background y controles operacionales.
34+
35+
---
36+
[Volver al Portal de Arquitectura](../index.es.md)

‎docs/architecture/api-dotnet/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# UMS API .NET Applied Reference
2+
3+
> Language: [English](./README.md) | [Espanol](./README.es.md)
4+
5+
This section documents how the UMS .NET API implementation applies the Evolith API Standard - .NET.
6+
7+
UMS is an applied reference, not the source of universal backend standards. Reusable backend rules belong in Evolith. UMS keeps concrete product modules, endpoints, headers, persistence choices, bounded contexts, seeds, and local implementation decisions.
8+
9+
## Documents
10+
11+
| Document | Purpose |
12+
|---|---|
13+
| [UMS API .NET Applied Reference](./ums-api-dotnet-applied-reference.md) | Evidence-based mapping between Evolith API topics and UMS source files. |
14+
15+
## Authority boundary
16+
17+
| Concern | Evolith | UMS |
18+
|---|---|---|
19+
| Reusable API standards | Owns principles, boilerplate rules, quality gates, and promotion criteria | Consumes standards |
20+
| Product implementation | References examples only | Owns concrete source code and local decisions |
21+
| Persistence | Owns provider governance and data-quality rules | Owns concrete DbContext, repositories, interceptors, migrations, and provider switches |
22+
| API surface | Owns REST/GraphQL responsibility rules | Owns concrete endpoints, route groups, schemas, and bounded-context modules |
23+
| Operations | Owns required capabilities | Owns concrete Serilog, OpenTelemetry, health checks, rate limits, and runtime values |
24+
25+
## Current evidence scope
26+
27+
This reference is based on the current .NET API under:
28+
29+
```text
30+
src/apps/ums.api
31+
```
32+
33+
Key observed sources include host bootstrap, service bootstrappers, middleware pipeline, API surface mapping, application DI, infrastructure DI, persistence provider configuration, health checks, AOP, background services, and operational controls.
34+
35+
---
36+
[Back to Architecture Portal](../index.md)

‎docs/architecture/api-dotnet/ums-api-dotnet-applied-reference.es.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Referencia Aplicada API Dotnet UMS
2+
3+
> Idioma: [English](./ums-api-dotnet-applied-reference.md) | [Espanol](./ums-api-dotnet-applied-reference.es.md)
4+
5+
## 1. Proposito
6+
7+
Este documento mapea la implementacion API Dotnet de UMS contra el Estandar API Dotnet de Evolith. Es una referencia aplicada de producto, no un estandar universal.
8+
9+
Las reglas backend reutilizables pertenecen a Evolith. Los detalles especificos de UMS permanecen aqui salvo que se promuevan mediante un ADR de Evolith, estandar de gobierno o patron canonico.
10+
11+
## 2. Alcance de fuente
12+
13+
La referencia aplicada cubre:
14+
15+
```text
16+
src/apps/ums.api
17+
```
18+
19+
Perfil observado:
20+
21+
| Aspecto | Implementacion UMS |
22+
|---|---|
23+
| Host | ASP.NET Core minimal host |
24+
| Composicion | Bootstrappers de Presentation |
25+
| Frontera de aplicacion | MediatR y FluentValidation |
26+
| Superficie API | Comandos REST y consultas GraphQL |
27+
| Versionado | Versionado API por segmento URL |
28+
| Persistencia | EF Core con baseline SQL Server y soporte SQLite local |
29+
| Operaciones | Logs estructurados, registro de telemetria, health checks, rate limits, background workers |
30+
| Politicas transversales | Aspectos para auditoria, transacciones, validacion de tenant y logging |
31+
32+
## 3. Mapeo
33+
34+
| Topico Evolith | Evidencia fuente UMS | Clasificacion |
35+
|---|---|---|
36+
| Bootstrap de host | `Ums.Presentation/Program.cs` | Evidencia aplicada |
37+
| Composicion modular de servicios | `Ums.Presentation/Bootstrapping/UmsApiServiceBootstrappers.cs` | Patron reutilizable |
38+
| Frontera de aplicacion | `Ums.Application/DependencyInjection.cs` | Patron reutilizable |
39+
| Pipeline middleware | `UseUmsApiPipeline` | Evidencia aplicada |
40+
| Mapeo de superficie API | `MapUmsApiSurface` y route groups por bounded context | Evidencia aplicada; modulos concretos locales |
41+
| Superficie GraphQL de consultas | `MapGraphQlSurface` | Candidato a estandar de gobierno Evolith |
42+
| Modelo de health | `MapHealthSurface` y health checks de infraestructura | Patron operacional reutilizable |
43+
| Setup de provider de persistencia | `Ums.Infrastructure/DependencyInjection.cs` | Patron reutilizable; matriz de providers local |
44+
| Perfil EF Core SQL Server | Setup DbContext, retries, interceptors y tabla de historial de migraciones | Candidato a perfil de persistencia Evolith |
45+
| Background workers | Hosted services de persistencia de auditoria y outbox dispatcher | Patron de confiabilidad reutilizable |
46+
| Aspectos transversales | Setup AOP y registro de proxies MediatR | Candidato a patron canonico |
47+
48+
## 4. Items que deben permanecer locales en UMS
49+
50+
| Item | Razon |
51+
|---|---|
52+
| Bounded contexts y modulos de agregados | Modelo de dominio del producto. |
53+
| Grupos de endpoints y nombres de rutas concretas | Superficie API de UMS. |
54+
| Metadata de documentacion del producto | Identidad del producto UMS. |
55+
| Nombres concretos de headers y claims | Contrato API local. |
56+
| Helpers solo de desarrollo | Soporte de desarrollo local. |
57+
| Valores runtime de limites y retries | Politica operacional del producto. |
58+
| Nombres de schemas y clases de repositorio | Implementacion de persistencia UMS. |
59+
| Clases de estrategia especificas del producto | Implementacion de capacidades UMS. |
60+
| Seed data de desarrollo | Comportamiento de entorno local. |
61+
62+
## 5. Items a promover a Evolith
63+
64+
| Candidato | Destino de promocion |
65+
|---|---|
66+
| Minimal host mas composicion con bootstrappers nombrados | Estandar de bootstrap API Evolith |
67+
| Gobierno de comandos REST y consultas GraphQL | Estandar de superficie API Evolith o ADR |
68+
| MediatR mas pipeline de validacion | Perfil de capa de aplicacion Evolith |
69+
| Problem Details y contexto de error seguro para usuario | Estandar de errores API Evolith |
70+
| Perfil EF Core SQL Server | Estandar de persistencia Evolith |
71+
| Abstracciones de request context y execution context | Estandar de tenancy y observabilidad Evolith |
72+
| Modelo de liveness, readiness y backlog health | Estandar operacional Evolith |
73+
| Outbox y procesamiento background de auditoria | Estandar de confiabilidad Evolith |
74+
| Politicas transversales basadas en aspectos o decoradores | Patron canonico Evolith o ADR |
75+
76+
## 6. Items que requieren ADR o promocion formal
77+
78+
| Item | Accion requerida |
79+
|---|---|
80+
| Dotnet 10 como baseline runtime backend | ADR Evolith o actualizacion de stack autoritativo |
81+
| Comandos REST y consultas GraphQL en un solo API tier | ADR de gobierno API Evolith |
82+
| MediatR como frontera de aplicacion por defecto | ADR Evolith o perfil backend opcional |
83+
| FluentValidation como estandar de pipeline de validacion | Estandar de ingenieria Evolith |
84+
| EF Core mas SQL Server como perfil de persistencia por defecto | ADR de persistencia Evolith o estandar de stack |
85+
| Libreria shell AOP como mecanismo transversal | Patron canonico Evolith y ADR |
86+
| Perfil de retry y circuit breaker para persistencia | Estandar de resiliencia Evolith |
87+
| Requisito de idempotencia para comandos | Estandar de confiabilidad API Evolith |
88+
89+
## 7. Checklist de validacion
90+
91+
Antes de cambiar la arquitectura API de UMS, validar:
92+
93+
- Clasificar el cambio como estandar Evolith, decision local UMS o candidato de promocion.
94+
- Mantener patrones backend compartidos independientes del lenguaje de producto UMS.
95+
- Mantener rutas, headers, seed data, schemas y clases de estrategia de producto en UMS.
96+
- Proponer primero en Evolith las reglas reutilizables.
97+
- Actualizar documentacion en ingles y espanol en conjunto.
98+
- Mantener Markdown UTF-8 limpio y sin iconos decorativos.
99+
- No modificar workflows ni hooks sin autorizacion explicita.
100+
101+
---
102+
[Volver al Portal API Dotnet](./README.es.md)

‎docs/architecture/api-dotnet/ums-api-dotnet-applied-reference.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# UMS API .NET Applied Reference
2+
3+
> Language: [English](./ums-api-dotnet-applied-reference.md) | [Espanol](./ums-api-dotnet-applied-reference.es.md)
4+
5+
## 1. Purpose
6+
7+
This document maps the UMS .NET API implementation to the Evolith API Standard - .NET. It is an applied product reference, not a universal standard.
8+
9+
Reusable backend rules belong in Evolith. UMS-specific details remain here unless promoted through an Evolith ADR, governance standard, or canonical pattern.
10+
11+
## 2. Source scope
12+
13+
The applied reference covers:
14+
15+
```text
16+
src/apps/ums.api
17+
```
18+
19+
Observed profile:
20+
21+
| Concern | UMS implementation |
22+
|---|---|
23+
| Host | ASP.NET Core minimal host |
24+
| Composition | Presentation bootstrappers |
25+
| Application boundary | MediatR and FluentValidation |
26+
| API surface | REST commands and GraphQL queries |
27+
| Versioning | URL segment API versioning |
28+
| Persistence | EF Core with SQL Server baseline and local SQLite support |
29+
| Operations | Structured logs, telemetry registration, health checks, rate limits, background workers |
30+
| Cross-cutting policies | Aspects for audit, transactions, tenant validation, and logging |
31+
32+
## 3. Mapping
33+
34+
| Evolith topic | UMS source evidence | Classification |
35+
|---|---|---|
36+
| Host bootstrap | `Ums.Presentation/Program.cs` | Applied evidence |
37+
| Modular service composition | `Ums.Presentation/Bootstrapping/UmsApiServiceBootstrappers.cs` | Reusable pattern |
38+
| Application boundary | `Ums.Application/DependencyInjection.cs` | Reusable pattern |
39+
| Middleware pipeline | `UseUmsApiPipeline` | Applied evidence |
40+
| API surface mapping | `MapUmsApiSurface` and bounded-context route groups | Applied evidence; concrete modules local |
41+
| GraphQL query surface | `MapGraphQlSurface` | Candidate Evolith governance standard |
42+
| Health model | `MapHealthSurface` and infrastructure health checks | Reusable operations pattern |
43+
| Persistence provider setup | `Ums.Infrastructure/DependencyInjection.cs` | Pattern reusable; provider matrix local |
44+
| SQL Server EF Core profile | DbContext setup, retries, interceptors, migration history table | Candidate Evolith persistence profile |
45+
| Background workers | Audit persistence and outbox dispatcher hosted services | Reusable reliability pattern |
46+
| Cross-cutting aspects | AOP setup and MediatR proxy registration | Candidate canonical pattern |
47+
48+
## 4. Items that should remain UMS-local
49+
50+
| Item | Reason |
51+
|---|---|
52+
| Bounded contexts and aggregate modules | Product domain model. |
53+
| Concrete endpoint groups and route names | UMS API surface. |
54+
| Product documentation metadata | UMS product identity. |
55+
| Concrete header and claim names | Local API contract. |
56+
| Development-only helpers | Local development support. |
57+
| Runtime values for limits and retries | Product operations policy. |
58+
| Schema names and repository class names | UMS persistence implementation. |
59+
| Product-specific strategy classes | UMS capability implementation. |
60+
| Development seed data | Local environment behavior. |
61+
62+
## 5. Items to promote to Evolith
63+
64+
| Candidate | Promotion target |
65+
|---|---|
66+
| Minimal host plus named bootstrapper composition | Evolith API bootstrap standard |
67+
| REST commands plus GraphQL query governance | Evolith API surface standard or ADR |
68+
| MediatR plus validation pipeline | Evolith application-layer profile |
69+
| Problem Details and user-safe error context | Evolith API error standard |
70+
| SQL Server EF Core profile | Evolith persistence standard |
71+
| Request and execution context abstractions | Evolith tenancy and observability standard |
72+
| Liveness, readiness, and backlog health model | Evolith operations standard |
73+
| Outbox and audit background processing | Evolith reliability standard |
74+
| Aspect or decorator based cross-cutting policies | Evolith canonical pattern or ADR |
75+
76+
## 6. Items requiring ADR or formal promotion
77+
78+
| Item | Required action |
79+
|---|---|
80+
| .NET 10 backend runtime baseline | Evolith ADR or authoritative stack update |
81+
| REST commands and GraphQL queries in one API tier | Evolith API governance ADR |
82+
| MediatR as default application boundary | Evolith ADR or optional backend profile |
83+
| FluentValidation as validation pipeline standard | Evolith engineering standard |
84+
| EF Core plus SQL Server as default persistence profile | Evolith persistence ADR or stack standard |
85+
| AOP shell library as cross-cutting implementation mechanism | Evolith canonical pattern and ADR |
86+
| Retry and circuit breaker profile for persistence | Evolith resilience standard |
87+
| Idempotency requirement for commands | Evolith API reliability standard |
88+
89+
## 7. Validation checklist
90+
91+
Before changing UMS API architecture, validate:
92+
93+
- Classify the change as Evolith standard, UMS local decision, or promotion candidate.
94+
- Keep shared backend patterns independent from UMS product language.
95+
- Keep product routes, headers, seed data, schemas, and strategy classes in UMS.
96+
- Propose reusable rules in Evolith first.
97+
- Update English and Spanish documentation together.
98+
- Keep Markdown UTF-8 clean and free from decorative icons.
99+
- Do not modify workflows or hooks without explicit authorization.
100+
101+
---
102+
[Back to API .NET Portal](./README.md)

‎docs/architecture/index.es.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ Planos detallados de ingeniería centrados en:
5252
- **[Formatos de Exportación ER](./blueprints-es/er-export-formats.md)**: Exportaciones SQL, Mermaid e imágenes del esquema.
5353
- **[Arquitectura de Librerías Shell](./blueprints-es/shell-library-architecture.md)**: Capa shell propia de UMS para patrones DDD y Factory heredados.
5454

55+
### [API Dotnet](./api-dotnet/README.es.md)
56+
Referencia aplicada backend API para UMS. Esta seccion mapea evidencia actual de codigo fuente Dotnet contra el Estandar API Dotnet de Evolith manteniendo los detalles especificos de producto dentro de UMS.
57+
5558
### [Web Frontend](./web-frontend/README.es.md)
5659
Referencia aplicada React Web para UMS. Esta seccion mapea evidencia actual de codigo fuente contra el Estandar Web Frontend React de Evolith manteniendo los detalles especificos de producto dentro de UMS.
5760

‎docs/architecture/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,9 @@ Detailed engineering blueprints focusing on:
6262
- **[Shell Library Developer Guides](./shell-libraries/README.md)**: Comprehensive developer guides for all four shell libraries with independent and combined usage examples.
6363
- [Ums.Shell.Ddd](./shell-libraries/ddd.md) · [Ums.Shell.Factory](./shell-libraries/factory.md) · [Ums.Shell.Aop](./shell-libraries/aop.md) · [Ums.Shell.Bootstrapper](./shell-libraries/bootstrapper.md) · [Combined Usage](./shell-libraries/combined-usage.md)
6464

65+
### [API .NET](./api-dotnet/README.md)
66+
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.
67+
6568
### [Web Frontend](./web-frontend/README.md)
6669
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.
6770

0 commit comments

Comments
 (0)