Skip to content

Commit c6a5fd0

Browse files
beyondnetPerubeyondnetPeru
committed
docs: restore Spanish documents and implement absolute language symmetry across READMEs
1 parent 20559a3 commit c6a5fd0

22 files changed

Lines changed: 1280 additions & 183 deletions

‎MASTER_INDEX.es.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,18 @@ Navegacion por fases de la documentacion del Sistema de Gestion de Usuarios (UMS
88

99
### Fase 00 -- Vision de Producto
1010

11-
- [Vision del Producto](./governance/product/product-vision.md)
12-
- [Contexto de Negocio](./governance/product/business-context.md)
13-
- [Alcance y Limites](./governance/product/scope.md)
14-
- [Objetivos (OKRs)](./governance/product/objectives.md)
15-
- [Interesados](./governance/product/stakeholders.md)
11+
- [Vision del Producto](./governance/product-es/product-vision.md)
12+
- [Contexto de Negocio](./governance/product-es/business-context.md)
13+
- [Alcance y Limites](./governance/product-es/scope.md)
14+
- [Objetivos (OKRs)](./governance/product-es/objectives.md)
15+
- [Interesados](./governance/product-es/stakeholders.md)
1616

1717
### Fase 01 -- Requisitos de Dominio
1818

19-
- [Glosario (Lenguaje Ubicuo)](./governance/requirements/glossary.md)
20-
- [Modelo de Datos Conceptual](./governance/requirements/conceptual-data-model.md)
21-
- [Matriz de Permisos](./governance/requirements/permission-matrix-example.md)
22-
- [Historias Funcionales](./governance/requirements/functional-stories/index.md)
19+
- [Glosario (Lenguaje Ubicuo)](./governance/requirements-es/glossary.md)
20+
- [Modelo de Datos Conceptual](./governance/requirements-es/conceptual-data-model.md)
21+
- [Matriz de Permisos](./governance/requirements-es/permission-matrix-example.md)
22+
- [Historias Funcionales](./governance/requirements-es/functional-stories/index.md)
2323

2424
### Fase 02 -- Arquitectura
2525

‎README.es.md‎

Lines changed: 19 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -2,107 +2,39 @@
22

33
> **Monolito Modular de alta escala para Gestión de Identidad y Autorización Unificada.**
44
>
5-
> ![Arquitectura](https://img.shields.io/badge/Arquitectura-Monolito_Modular-blue) ![Lenguaje](https://img.shields.io/badge/Lenguaje-.NET_8_/_React-informational) ![Metodología](https://img.shields.io/badge/Metodología-BMAD--METHOD-success)
5+
> ![Estado](https://img.shields.io/badge/Estado-Activo-success) ![Arch](https://img.shields.io/badge/Arquitectura-Monolito_Modular-blue)
66
77
---
88

9-
## 🌍 Language / Bilingüe
10-
- 🇺🇸 [English](./README.md)
11-
- 🇪🇸 [Español](./README.es.md)
9+
### 🌍 Selector de Idioma
10+
- [English](./README.md) | **Español**
1211

13-
---
14-
15-
## 🚀 Inicio Rápido
16-
Para desarrolladores listos para levantar el entorno:
12+
### 🚀 Inicio Rápido
1713
```powershell
18-
# Entrar al Engine Room
1914
cd src
20-
# Iniciar Frontend
2115
npm install; npx nx run app-web:dev
22-
# Compilar Backend
23-
dotnet build ./apps/app-api-dotnet/Ums.sln
2416
```
2517

2618
---
2719

28-
## 🏛️ Arquitectura y Principios
29-
Construido bajo **Clean Architecture**, **DDD** y patrones **Hexagonales**.
30-
- **Patrón**: Monolito Modular/Progresivo con Contextos Delimitados estrictos.
31-
- **Persistencia**: PostgreSQL 16 con Seguridad a Nivel de Fila (RLS).
32-
- **Seguridad**: OAuth2/OIDC + Grafo de Autorización Multi-tenant.
33-
34-
---
35-
36-
## 📍 Hub de Documentación Global
20+
### 📍 Hub de Conocimiento (Español)
21+
Explora las capas del proyecto por dominio:
3722

38-
| Dominio | Descripción | Contenido |
39-
| :--- | :--- | :--- |
40-
| [⚖️ **Gobernanza**](./governance/) | Estrategia de Negocio y Producto | Visión, Roadmap, Requisitos (Fases 00, 01, 05). |
41-
| [🏗️ **Arquitectura**](./architecture/) | Planos Técnicos | ADRs, Modelos C4, Estándares de Ingeniería (Fases 02, 03, 04). |
42-
| [🛠️ **Infraestructura**](./infrastructure/) | Plataforma e IaC | Docker, Kong Gateway, configs de Kubernetes. |
43-
| [🚀 **Operaciones**](./operations/) | Monitoreo y SRE | Observabilidad (OTel/Tempo), Grafana Dashboards, SQL init. |
44-
| [🎓 **Conocimiento**](./knowledge/) | Centro de Aprendizaje | POCs, Guías de Onboarding, Investigación de referencia. |
45-
| [💻 **Código Fuente**](./src/) | Implementación | Código Fuente del Producto (`apps/` y `libs/`). |
23+
- [⚖️ **Gobernanza**](./governance/product-es/) — Visión, Roadmap y Alcance del Producto.
24+
- [🏗️ **Arquitectura**](./architecture/adrs-es/) — ADRs, Planos y Espec. de Ingeniería.
25+
- [🛠️ **Infraestructura**](./infrastructure/) — Configuración de Docker, Kong y K8s.
26+
- [🚀 **Operaciones**](./operations/) — Observabilidad, Monitoreo y SRE.
27+
- [💻 **Código Fuente**](./src/) — La Implementación (Apps y Libs).
4628

4729
---
4830

49-
## 👥 Lectura Recomendada por Rol
50-
Selecciona tu perfil para una ruta de onboarding personalizada:
51-
52-
<details>
53-
<summary><b>📦 Product Owner / Negocio</b></summary>
54-
55-
1. [Visión del Producto](./governance/product/product-vision.md)
56-
2. [Contexto de Negocio y Solución](./governance/product/business-context.md)
57-
3. [Historias Funcionales](./governance/requirements/functional-stories/)
58-
4. [Roadmap del Producto](./governance/roadmap/versioning-and-audit-strategy.md)
59-
</details>
60-
61-
<details>
62-
<summary><b>🏗️ Arquitecto de Software</b></summary>
63-
64-
1. [Espec. de Arquitectura (Modelos C4)](./architecture/blueprints-es/architecture-spec.md)
65-
2. [Registro de ADRs](./architecture/adrs-es/)
66-
3. [Stack Tecnológico](./architecture/blueprints-es/stack.md)
67-
4. [Mapa de Contextos](./architecture/blueprints-es/bounded-context-map.md)
68-
</details>
69-
70-
<details>
71-
<summary><b>⚙️ Desarrollador Backend</b></summary>
72-
73-
1. [Estándares de Ingeniería](./architecture/artifacts-es/engineering-standards.md)
74-
2. [Código Fuente Backend](./src/apps/app-api-dotnet/)
75-
3. [Habilitadores Técnicos](./architecture/blueprints-es/technical-enablers/)
76-
4. [Plan de Migración .NET](./architecture/blueprints-es/dotnet-migration-and-tech-stack-plan.md)
77-
</details>
78-
79-
<details>
80-
<summary><b>💻 Desarrollador Frontend</b></summary>
81-
82-
1. [Código Fuente Frontend](./src/apps/app-web/)
83-
2. [Alcance del Producto (Web Console)](./architecture/artifacts-es/ums-web-console-product-scope.md)
84-
3. [Estándares de Ingeniería](./architecture/artifacts-es/engineering-standards.md)
85-
</details>
86-
87-
<details>
88-
<summary><b>☁️ DevOps / SRE</b></summary>
89-
90-
1. [Configuración de Infraestructura](./infrastructure/)
91-
2. [Estrategia de Observabilidad](./architecture/artifacts-es/observability-strategy.md)
92-
3. [Activos Operacionales](./operations/)
93-
4. [Guía de Configuración de Kong](./architecture/artifacts-es/kong-plugins-configuration-guide.md)
94-
</details>
95-
96-
<details>
97-
<summary><b>🛡️ Seguridad / QA</b></summary>
98-
99-
1. [Espec. IAM Empresarial](./architecture/artifacts-es/enterprise-iam-ums-specification.md)
100-
2. [Plan de Contract Testing](./architecture/artifacts-es/contract-testing-plan.md)
101-
3. [Espec. MFA y Seguridad](./architecture/artifacts-es/mfa-passwordless-security-spec.md)
102-
4. [Gobernanza Multi-Tenant](./architecture/artifacts-es/enterprise-multitenant-governance-report.md)
103-
</details>
31+
### 👥 Lectura Recomendada por Rol
32+
| Rol | Ruta Recomendada |
33+
| :--- | :--- |
34+
| **Product Owner** | [Visión](./governance/product-es/product-vision.md) → [Contexto](./governance/product-es/business-context.md) → [Roadmap](./governance/roadmap/) |
35+
| **Arquitecto** | [Planos](./architecture/blueprints-es/architecture-spec.md) → [ADRs](./architecture/adrs-es/) → [Stack](./architecture/blueprints-es/stack.md) |
36+
| **Desarrollador** | [Estándares](./architecture/artifacts-es/engineering-standards.md) → [Código](./src/) → [Planos](./architecture/blueprints-es/architecture-spec.md) |
37+
| **DevOps / QA** | [Infra](./infrastructure/) → [Ops](./operations/) → [Espec. IAM](./architecture/artifacts-es/enterprise-iam-ums-specification.md) |
10438

10539
---
106-
107-
## 🤝 Contribuir
108-
Por favor lee el [**Indice Maestro**](./MASTER_INDEX.es.md) y las [**Reglas de Agentes**](./AGENTS.md) antes de realizar cambios. Este proyecto sigue el **BMAD-METHOD** para desarrollo dirigido por especificaciones.
40+
*Para navegación profunda, visita el [**Índice Maestro**](./MASTER_INDEX.es.md).*

‎README.md‎

Lines changed: 19 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -2,107 +2,39 @@
22

33
> **High-scale Modular Monolith for Unified Identity & Authorization.**
44
>
5-
> ![Architecture](https://img.shields.io/badge/Architecture-Modular_Monolith-blue) ![Language](https://img.shields.io/badge/Language-.NET_8_/_React-informational) ![Methodology](https://img.shields.io/badge/Methodology-BMAD--METHOD-success)
5+
> ![Status](https://img.shields.io/badge/Status-Active-success) ![Arch](https://img.shields.io/badge/Architecture-Modular_Monolith-blue)
66
77
---
88

9-
## 🌍 Language / Bilingüe
10-
- 🇺🇸 [English](./README.md)
11-
- 🇪🇸 [Español](./README.es.md)
9+
### 🌍 Language Selector
10+
- **English** | [Español](./README.es.md)
1211

13-
---
14-
15-
## 🚀 Quick Start
16-
For developers ready to spin up the environment:
12+
### 🚀 Quick Start
1713
```powershell
18-
# Enter the Engine Room
1914
cd src
20-
# Start Frontend
2115
npm install; npx nx run app-web:dev
22-
# Build Backend
23-
dotnet build ./apps/app-api-dotnet/Ums.sln
2416
```
2517

2618
---
2719

28-
## 🏛️ Architecture & Principles
29-
Built on **Clean Architecture**, **DDD**, and **Hexagonal** patterns.
30-
- **Pattern**: Progressive/Modular Monolith with strict Bounded Contexts.
31-
- **Persistence**: PostgreSQL 16 with Row-Level Security (RLS).
32-
- **Security**: OAuth2/OIDC + Multi-tenant Authorization Graph.
33-
34-
---
35-
36-
## 📍 Global Documentation Hub
20+
### 📍 Knowledge Hub (English)
21+
Explore the project layers by domain:
3722

38-
| Domain | Description | Content |
39-
| :--- | :--- | :--- |
40-
| [⚖️ **Governance**](./governance/) | Business & Product Strategy | Vision, Roadmap, Requirements (Phases 00, 01, 05). |
41-
| [🏗️ **Architecture**](./architecture/) | Technical Blueprint | ADRs, C4 Models, Engineering Standards (Phases 02, 03, 04). |
42-
| [🛠️ **Infrastructure**](./infrastructure/) | Platform & IaC | Docker, Kong Gateway, Kubernetes configs. |
43-
| [🚀 **Operations**](./operations/) | Monitoring & SRE | Observability (OTel/Tempo), Grafana Dashboards, SQL init. |
44-
| [🎓 **Knowledge**](./knowledge/) | Learning Center | POCs, Onboarding guides, Reference research. |
45-
| [💻 **Source Code**](./src/) | Implementation | Product Source (`apps/` and `libs/`). |
23+
- [⚖️ **Governance**](./governance/) — Vision, Roadmap, and Product Scope.
24+
- [🏗️ **Architecture**](./architecture/) — ADRs, Blueprints, and Engineering Specs.
25+
- [🛠️ **Infrastructure**](./infrastructure/) — Docker, Kong, and K8s configuration.
26+
- [🚀 **Operations**](./operations/) — Observability, Monitoring, and SRE.
27+
- [💻 **Source Code**](./src/) — The Implementation (Apps & Libs).
4628

4729
---
4830

49-
## 👥 Recommended Reading by Role
50-
Select your profile for a tailored onboarding path:
51-
52-
<details>
53-
<summary><b>📦 Product Owner / Business</b></summary>
54-
55-
1. [Product Vision](./governance/product/product-vision.md)
56-
2. [Business Context & Solution](./governance/product/business-context.md)
57-
3. [Functional Stories](./governance/requirements/functional-stories/)
58-
4. [Product Roadmap](./governance/roadmap/versioning-and-audit-strategy.md)
59-
</details>
60-
61-
<details>
62-
<summary><b>🏗️ Software Architect</b></summary>
63-
64-
1. [Architecture Spec (C4 Models)](./architecture/blueprints/architecture-spec.md)
65-
2. [ADR Registry](./architecture/adrs/)
66-
3. [Technology Stack](./architecture/blueprints/stack.md)
67-
4. [Context Map](./architecture/blueprints/bounded-context-map.md)
68-
</details>
69-
70-
<details>
71-
<summary><b>⚙️ Backend Developer</b></summary>
72-
73-
1. [Engineering Standards](./architecture/artifacts/engineering-standards.md)
74-
2. [Backend Source Code](./src/apps/app-api-dotnet/)
75-
3. [Technical Enablers](./architecture/blueprints/technical-enablers/)
76-
4. [.NET Migration Plan](./architecture/blueprints/dotnet-migration-and-tech-stack-plan.md)
77-
</details>
78-
79-
<details>
80-
<summary><b>💻 Frontend Developer</b></summary>
81-
82-
1. [Frontend Source Code](./src/apps/app-web/)
83-
2. [Web Console Product Scope](./architecture/artifacts/ums-web-console-product-scope.md)
84-
3. [Engineering Standards](./architecture/artifacts/engineering-standards.md)
85-
</details>
86-
87-
<details>
88-
<summary><b>☁️ DevOps / SRE</b></summary>
89-
90-
1. [Infrastructure Setup](./infrastructure/)
91-
2. [Observability Strategy](./architecture/artifacts/observability-strategy.md)
92-
3. [Operational Assets](./operations/)
93-
4. [Kong Gateway Config](./architecture/artifacts/kong-plugins-configuration-guide.md)
94-
</details>
95-
96-
<details>
97-
<summary><b>🛡️ Security / QA</b></summary>
98-
99-
1. [Enterprise IAM Spec](./architecture/artifacts/enterprise-iam-ums-specification.md)
100-
2. [Contract Testing Plan](./architecture/artifacts/contract-testing-plan.md)
101-
3. [MFA & Security Spec](./architecture/artifacts/mfa-passwordless-security-spec.md)
102-
4. [Multi-Tenant Governance](./architecture/artifacts/enterprise-multitenant-governance-report.md)
103-
</details>
31+
### 👥 Recommended Reading by Role
32+
| Role | Recommended Path |
33+
| :--- | :--- |
34+
| **Product Owner** | [Vision](./governance/product/product-vision.md) → [Context](./governance/product/business-context.md) → [Roadmap](./governance/roadmap/) |
35+
| **Architect** | [Specs](./architecture/blueprints/architecture-spec.md) → [ADRs](./architecture/adrs/) → [Stack](./architecture/blueprints/stack.md) |
36+
| **Developer** | [Standards](./architecture/artifacts/engineering-standards.md) → [Source](./src/) → [Specs](./architecture/blueprints/architecture-spec.md) |
37+
| **DevOps / QA** | [Infra](./infrastructure/) → [Ops](./operations/) → [IAM Spec](./architecture/artifacts/enterprise-iam-ums-specification.md) |
10438

10539
---
106-
107-
## 🤝 Contributing
108-
Please read the [**Master Index**](./MASTER_INDEX.md) and the [**Agent Rules**](./AGENTS.md) before making any changes. This project follows the **BMAD-METHOD** for spec-driven development.
40+
*For deep-dive navigation, visit the [**Master Index**](./MASTER_INDEX.md).*

‎governance/product-es/business-context.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
> ?? **Nota de Arquitectura:** Este documento se encuentra actualmente en su versi�n original (Ingl�s) y est� programado para traducci�n oficial en la hoja de ruta.
2+
3+
# 💼 Business Context - User Management System (UMS)
4+
5+
## 1. Problem Statement
6+
Historically, corporate software ecosystems suffer from fragmented identity and access governance. Each system (TMS, WMS, CRM) manages its own local database of users, password hashes, and authorization roles. This results in:
7+
- **Severe Security Vulnerabilities**: Fragmented password databases increase the attack surface and make password policy enforcement impossible.
8+
- **High Administrative Overhead**: Employees must be manually onboarded and offboarded across multiple applications, leading to "orphan accounts" with active access.
9+
- **Lack of Central Auditability**: Tracking "who did what" and "who has access to what" across multiple isolated databases is practically impossible, violating regulatory compliance.
10+
- **Inefficient Multi-Tenancy**: B2B clients cannot self-manage their organizations, causing continuous support ticket overhead for the primary software vendor.
11+
12+
---
13+
14+
## 2. Proposed Solution
15+
UMS resolves these issues by serving as an **abstract, sovereign Authorization & Identity Gateway** for any downstream client system or integrated enterprise suite.
16+
17+
```mermaid
18+
graph TD
19+
User["Multi-Tenant User (Client Staff)"] -->|1. Request Login / Action| App["Downstream Client Application"]
20+
21+
%% AUTHENTICATION CORNER (Optional & Pluggable)
22+
App -->|2. Delegate Auth & Query Config| UMS["UMS Sovereign Authorization Kernel"]
23+
UMS -.->|IAuthenticationPort_Pluggable| IdP_Providers["Identity Providers (Internal bcrypt / Zitadel / Azure AD / Okta)"]
24+
UMS -.->|IFeatureFlagPort_Pluggable| FF_Providers["Feature Flag Engines (Internal PostgreSQL-Redis / LaunchDarkly / Unleash)"]
25+
26+
%% RESOLUTION & PERSISTENCE CORNER
27+
UMS -->|3. Read context-aware overrides| DB["PostgreSQL 16 (RLS Isolated)"]
28+
DB -->|4. Resolve dynamic rules| UMS
29+
30+
%% RESPONSE CORNER
31+
UMS -->|5. Cache effective payload| Cache["Redis Cache (cfg, flags, auth_graph)"]
32+
UMS -->|6. Unified API Payload| App
33+
```
34+
35+
UMS separates **Authentication**, **Authorization**, and **Dynamic Configuration**:
36+
1. **Authentication (Identity)**: Treated as an abstract, pluggable service layer. UMS validates "who" the user is using secure, federated Single Sign-On (SSO), SAML, OIDC, WebAuthn (Passkeys), or an internal credentials database, dynamically routing to external Identity Providers (such as Zitadel, AWS Cognito, Microsoft Entra ID, Okta, or Keycloak) on a per-tenant basis without impacting business logic.
37+
2. **Authorization (Permissions)**: Controlled centrally by UMS. UMS stores the definitions of client systems, modules, menus, permission graphs, roles, and profiles, injecting authorization tokens and dynamic modules and menus into downstream applications on demand.
38+
3. **Dynamic Configuration & Feature Flags**: UMS governs the runtime behavior of downstream systems via a hierarchical multi-tenant configuration model and an extensible feature flag framework (LaunchDarkly, Unleash, Internal), enabling zero-deployment behavioral shifts and progressive rollouts.
39+
40+
---
41+
42+
## 3. Executive Business Rationale
43+
Standardizing access under UMS provides three massive business benefits:
44+
- **Zero Ticket Onboarding**: Clients self-manage their administrative scopes through delegable profiles and tenant-specific settings.
45+
- **Zero-Deployment Agility**: Real-time feature flags and dynamic hierarchical configuration overrides (Tenant > System > Org > Environment) allow immediate business adjustments without code releases.
46+
- **Compliance Ready**: Immutable business audit logs (CDC/Subscribers) track all critical permission mutations and configuration state changes, making the system instantly ready for SOC 2 and ISO 27001 certifications.
47+
- **Enterprise-Grade Security**: Passwordless cryptography completely eliminates brute-force vectors and credentials theft.
48+
49+
---
50+
51+
## 4. Reference Operational Model
52+
To illustrate the real-world operational execution of UMS, our specifications utilize the **Business Analyst** scenario as the primary reference model. This role represents high-concurrency B2B access to the *Route Planner* under the context of specific tenants (e.g., *Logistics Corp*) and localized branches (e.g., *Callao Terminal, Peru*).
53+
54+
The detailed architectural specs, sequence diagrams, and dynamic API contracts for this reference model are fully detailed in **[enterprise-iam-ums-specification.md](../04-artifacts/enterprise-iam-ums-specification.md)**.
55+
56+
57+

0 commit comments

Comments
 (0)