diff --git a/README.md b/README.md index 2a97e2bb..8cd06a8c 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,137 @@ -# UMS — Enterprise User Management System +# UMS - Enterprise User Management System -> **[OPEN STANDARDS](./docs/STANDARDS.md) • [OPEN MASTER INDEX](./docs/MASTER_INDEX.md) • [LEER EN ESPAÑOL](./docs/README.es.md) • [ARCHITECTURE PORTAL](./docs/architecture/index.md)** -> *Note: GitHub displays source files first. To skip the code and read the documentation, click the links above.* +> [Open standards](./docs/STANDARDS.md) | [Master index](./docs/MASTER_INDEX.md) | [Architecture portal](./docs/architecture/index.md) | [Leer en espanol](./docs/README.es.md) + +UMS is the official executable product reference for Evolith. It demonstrates how Evolith standards can be applied in a real modular monolith for unified identity, authorization, audit, governance, and enterprise user management. + +UMS owns product-specific implementation evidence. Evolith owns reusable enterprise standards. --- -> **Standardized Modular Monolith for Unified Identity & Authorization.** -> -> ![Status](https://img.shields.io/badge/Status-Active-success) ![Architecture](https://img.shields.io/badge/Architecture-Modular_Monolith-blue) ![Methodology](https://img.shields.io/badge/Methodology-BMAD--METHOD-success) +## Start here + +| Need | Go to | +|---|---| +| Find React, Web, C# or .NET standards | [Standards Quick Access](./docs/STANDARDS.md) | +| Understand the architecture | [Architecture Portal](./docs/architecture/index.md) | +| Review UMS architectural decisions | [ADR Registry](./docs/architecture/adrs/index.md) | +| Understand product scope | [Product Vision](./docs/governance/product/product-vision.md) | +| Review requirements | [Requirements Index](./docs/governance/requirements/index.md) | +| Review delivery plan | [MVP Product Backlog](./docs/governance/project/mvp-product-backlog.md) | +| Explore domain design | [Construction Portal](./docs/governance/construction/index.md) | +| Operate or observe UMS | [Operations Portal](./docs/operations/index.md) | +| Browse all documents | [Master Index](./docs/MASTER_INDEX.md) | --- -## Standards Quick Access +## Quick paths by role -| Need | Direct path | -| :--- | :--- | -| UMS applied React Web reference | [UMS React Web Applied Reference](./docs/architecture/web-frontend/ums-react-applied-reference.md) | -| UMS applied .NET API reference | [UMS API .NET Applied Reference](./docs/architecture/api-dotnet/ums-api-dotnet-applied-reference.md) | -| Upstream Evolith React standard | [Evolith React Web Frontend Standard](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.md) | -| Upstream Evolith .NET API standard | [Evolith .NET API Standard](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/api-dotnet/api-dotnet-standard.md) | -| All standards in one page | [Standards Quick Access](./docs/STANDARDS.md) | +| Role | Start with | Then read | +|---|---|---| +| Backend engineer | [UMS API .NET Applied Reference](./docs/architecture/api-dotnet/ums-api-dotnet-applied-reference.md) | [Construction Portal](./docs/governance/construction/index.md) | +| Frontend engineer | [UMS React Web Applied Reference](./docs/architecture/web-frontend/ums-react-applied-reference.md) | [Evolith React Web Frontend Standard](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.md) | +| Architect | [Architecture Portal](./docs/architecture/index.md) | [Traceability Matrix](./docs/architecture/traceability-matrix.md) | +| Product owner or QA | [Functional Stories](./docs/governance/requirements/functional-stories/index.md) | [MVP Backlog](./docs/governance/project/mvp-product-backlog.md) | +| DevOps or operations | [Operations Portal](./docs/operations/index.md) | [Solution Metrics Dashboard](./docs/operations/metrics/index.md) | +| Governance reviewer | [Standards Quick Access](./docs/STANDARDS.md) | [Architecture Portal](./docs/architecture/index.md) | --- -## Master Navigation Index -Start here if you are new to UMS. This index gives each reader a fast route into the repository without needing to know the folder structure. +## Standards and applied references -### Quick Route by Persona +| Area | UMS applied reference | Upstream Evolith standard | +|---|---|---| +| React Web frontend | [UMS React Web Applied Reference](./docs/architecture/web-frontend/ums-react-applied-reference.md) | [Evolith React Web Frontend Standard](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.md) | +| .NET API backend | [UMS API .NET Applied Reference](./docs/architecture/api-dotnet/ums-api-dotnet-applied-reference.md) | [Evolith .NET API Standard](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/api-dotnet/api-dotnet-standard.md) | +| All standards | [UMS Standards Quick Access](./docs/STANDARDS.md) | [Evolith Quick Access by Stack](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/quick-access/README.md) | -| I am a… | Start here | Then read | -| :--- | :--- | :--- | -| **Backend Engineer** | [Standards Quick Access](./docs/STANDARDS.md) · [Construction Portal](./docs/governance/construction/index.md) · [Domain Aggregate Index](./docs/domain/index.md) | [UMS API .NET Applied Reference](./docs/architecture/api-dotnet/ums-api-dotnet-applied-reference.md) → [DDD Design Portal](./docs/governance/construction/ddd-design/index.md) | -| **Frontend Engineer** | [Standards Quick Access](./docs/STANDARDS.md) · [UMS React Web Applied Reference](./docs/architecture/web-frontend/ums-react-applied-reference.md) | [Evolith React Web Frontend Standard](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.md) | -| **Architect** | [Architecture Portal](./docs/architecture/index.md) · [ADR Registry](./docs/architecture/adrs/index.md) | [Standards Quick Access](./docs/STANDARDS.md) → [Traceability Matrix](./docs/architecture/traceability-matrix.md) | -| **Product Owner / QA** | [Master Index](./docs/MASTER_INDEX.md) · [Functional Stories](./docs/governance/requirements/functional-stories/index.md) | [MVP Backlog](./docs/governance/project/mvp-product-backlog.md) → [Glossary](./docs/governance/requirements/glossary.md) | -| **DevOps / Ops** | [Operations Portal](./docs/operations/index.md) · [Runbooks](./docs/operations/runbooks/) | [ADR-0053 OpenTelemetry](./docs/architecture/adrs/0053-opentelemetry-observability.md) → [ADR-0054 Shell Library Isolation](./docs/architecture/adrs/0054-shell-library-isolation.md) | +--- -### I want to… +## UMS vs Evolith -| Goal | Start Here | Then Read | -| :--- | :--- | :--- | -| Find standards for React, Web, C# or .NET | [Standards Quick Access](./docs/STANDARDS.md) | [Architecture Portal](./docs/architecture/index.md) | -| Understand the product | [Product Vision](./docs/governance/product/product-vision.md) | [Business Context](./docs/governance/product/business-context.md) → [Scope](./docs/governance/product/scope.md) | -| See Epics & Priorities | [MVP Product Backlog](./docs/governance/project/mvp-product-backlog.md) | [Requirements Index](./docs/governance/requirements/index.md) → [Functional Stories](./docs/governance/requirements/functional-stories/index.md) | -| Review functional requirements | [Requirements Index](./docs/governance/requirements/index.md) | [Functional Stories](./docs/governance/requirements/functional-stories/index.md) → [Glossary](./docs/governance/requirements/glossary.md) | -| Validate the data and domain model | [Conceptual Data Model](./docs/governance/requirements/conceptual-data-model.md) | [ER Export Formats](./docs/architecture/blueprints/er-export-formats.md) → [Database Design ER](./docs/architecture/blueprints/database-design-er.md) | -| Understand the architecture | [Architecture Portal](./docs/architecture/index.md) | [Database Design ER](./docs/architecture/blueprints/database-design-er.md) | -| Browse everything | [Master Index](./docs/MASTER_INDEX.md) | Complete document tree by lifecycle phase. | +| Question | UMS | Evolith | +|---|---|---| +| What belongs here? | Product-specific source evidence, applied examples, local decisions, routes, modules, schemas, runtime values | Reusable enterprise standards, principles, ADRs, canonical patterns, quality gates | +| What should not be generalized here? | Local implementation choices that only apply to UMS | Product-specific implementation evidence | +| How does a UMS practice become a standard? | It provides implementation evidence | It is promoted through ADR, governance standard, or canonical pattern | --- -## Architecture Overview +## Technology snapshot -### Technology Stack | Layer | Technology | -| :--- | :--- | -| **Backend** | .NET 10, HotChocolate (GraphQL), Minimal APIs (REST) | -| **Frontend** | React 18, Vite 5, TypeScript, TailwindCSS, Zustand, TanStack Query | -| **Database** | SQL Server 2022, Entity Framework Core | -| **Monorepo** | Nx, npm Workspaces | -| **Methodology** | BMAD-METHOD, Clean Architecture (Hexagonal), DDD | - -### Project Structure -``` -src/ -├── apps/ -│ ├── ums.api/ # .NET Backend (Clean Architecture) -│ │ ├── Domain/ # Pure POCOs, zero NuGet references -│ │ ├── Application/ # Use cases, interfaces -│ │ ├── Infrastructure/ # EF Core, external services -│ │ └── Presentation/ # GraphQL/REST endpoints -│ └── ums.web-app/ # React Frontend (Clean Architecture) -│ ├── src/ -│ │ ├── domain/ # Enterprise entities, value objects -│ │ ├── application/ # Hooks, stores, use cases -│ │ ├── infrastructure/ # HTTP clients, GraphQL client -│ │ └── presentation/ # Components, screens, layouts -│ └── ... -└── ... -``` - -### Key Architectural Decisions -- **GraphQL for Queries, REST for Commands**: All read operations use HotChocolate GraphQL; writes use REST Minimal APIs for transactional clarity. -- **Clean Architecture**: Strict layer boundaries. Domain layer is pure (no external dependencies). Application layer contains use cases and interfaces. Infrastructure handles external concerns. -- **Result Pattern**: No exceptions for flow control. All operations return `Result` for explicit error handling. -- **Bounded Contexts**: Identity, Access, Audit, etc. Each context has its own aggregates, services, and presentation modules. +|---|---| +| Backend | .NET 10, HotChocolate GraphQL, Minimal APIs REST | +| Frontend | React 18, Vite 5, TypeScript, TailwindCSS, Zustand, TanStack Query | +| Database | SQL Server 2022, Entity Framework Core | +| Monorepo | Nx, npm Workspaces | +| Methodology | BMAD-METHOD, Clean Architecture, DDD | --- -## Quick Start (Engine Room) +## Quick start ### Prerequisites + - Node.js 20+ - .NET 10 SDK -- SQL Server 2022 (or Docker: `docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourPassword123!" -p 1433:1433 mcr.microsoft.com/mssql/server:2022-latest`) +- SQL Server 2022 or Docker + +### Backend + +```bash +cd src/apps/ums.api +dotnet build +dotnet run +``` ### Frontend + ```bash cd src/apps/ums.web-app npm install npm run dev ``` -### Backend -```bash -cd src/apps/ums.api -dotnet build -dotnet run -``` +### Full stack -### Full Stack (Frontend + Backend) ```bash -# Terminal 1 — Backend (port 7114) +# Terminal 1 - Backend cd src/apps/ums.api && dotnet run -# Terminal 2 — Frontend (port 5173) +# Terminal 2 - Frontend cd src/apps/ums.web-app && npm run dev ``` --- -## Development Commands +## Repository map -| Command | Description | -| :--- | :--- | -| `npm install` | Install all frontend dependencies (run from `src/apps/ums.web-app`) | -| `npm run dev` | Start frontend dev server (port 5173) | -| `npm run build` | Build frontend for production | -| `npm run lint` | Run ESLint | -| `npm run test` | Run Vitest tests | -| `dotnet build` | Build backend solution (run from `src/apps/ums.api`) | -| `dotnet test` | Run backend tests | -| `dotnet run` | Start backend API (port 7114) | +| Area | Entry point | Purpose | +|---|---|---| +| Standards | [docs/STANDARDS.md](./docs/STANDARDS.md) | Direct links to Evolith standards and UMS applied references | +| Architecture | [docs/architecture](./docs/architecture/index.md) | ADRs, blueprints, applied API/Web references, traceability | +| Governance | [docs/governance](./docs/governance/index.md) | Product vision, scope, requirements, delivery documentation | +| Construction | [docs/governance/construction](./docs/governance/construction/index.md) | DDD design, bounded contexts, aggregates, events, commands | +| Operations | [docs/operations](./docs/operations/index.md) | Metrics, runbooks, operational documentation | +| Source | [src/apps](./src/apps) | API and Web application source code | +| Full navigation | [docs/MASTER_INDEX.md](./docs/MASTER_INDEX.md) | Complete document tree | --- -## Knowledge Hub -| Domain | Portal Index | Contents | -| :--- | :--- | :--- | -| **Standards** | [Standards Quick Access](./docs/STANDARDS.md) | Direct links to Evolith standards and UMS applied references for React Web and .NET API. | -| **Governance** | [Governance Portal](./docs/governance/index.md) | Product direction, business scope, and functional requirements. | -| **Project Delivery** | [Project Backlog](./docs/governance/project/index.md) | MVP epics, user stories, and functional design of core modules. | -| **Requirements** | [Requirements Index](./docs/governance/requirements/index.md) | Functional stories, business glossary, and conceptual data model. | -| **Architecture** | [Architecture Portal](./docs/architecture/index.md) | Database ER design, entity maps, and interactive viewers. | -| **Construction** | [Construction Portal](./docs/governance/construction/index.md) | DDD domain layer design (bounded contexts, aggregates, events, commands). | -| **Metrics** | [Solution Metrics Dashboard](./docs/operations/metrics/index.md) | Engineering metrics by solution type: coding, security, quality, tests, AI usage. | +## Security and quality notes + +- CSP, CSRF, security headers, and runtime input validation are part of the implementation baseline. +- React Web and .NET API decisions are documented as applied references under `docs/architecture/`. +- Reusable enterprise standards must be promoted upstream to Evolith. --- -## Security & Compliance +## Contribution and governance + +Before changing architecture or documentation, check: -- **Content Security Policy**: Restrictive CSP with `unsafe-eval` removed (production-ready). -- **CSRF Protection**: Double-submit cookie pattern with token refresh. -- **Security Headers**: HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy via Nginx. -- **Input Validation**: Zod schemas as single source of truth for runtime validation. +- [Standards Quick Access](./docs/STANDARDS.md) +- [Architecture Portal](./docs/architecture/index.md) +- [Master Index](./docs/MASTER_INDEX.md) +- [AGENTS.md](./AGENTS.md) diff --git a/docs/README.es.md b/docs/README.es.md index e0e0adf7..d372fa87 100644 --- a/docs/README.es.md +++ b/docs/README.es.md @@ -1,95 +1,88 @@ -# UMS — Sistema de Gestión de Usuarios Empresarial +# UMS - Sistema de Gestion de Usuarios Empresarial -> **[ABRIR ESTÁNDARES](./STANDARDS.es.md) • [ABRIR ÍNDICE MAESTRO](./MASTER_INDEX.es.md) • [READ IN ENGLISH](../README.md) • [PORTAL DE ARQUITECTURA](./architecture/index.es.md)** -> *Nota: GitHub muestra los archivos de código primero. Para saltar el código y leer la documentación, haz clic en los enlaces de arriba.* +> [Abrir estandares](./STANDARDS.es.md) | [Indice maestro](./MASTER_INDEX.es.md) | [Portal de arquitectura](./architecture/index.es.md) | [Read in English](../README.md) ---- +UMS es la referencia ejecutable oficial de producto para Evolith. Demuestra como aplicar estandares Evolith en un monolito modular real para identidad, autorizacion, auditoria, gobierno y gestion empresarial de usuarios. -> **Monolito modular estandarizado para identidad y autorización unificada.** -> -> ![Status](https://img.shields.io/badge/Status-Activo-success) ![Architecture](https://img.shields.io/badge/Architecture-Modular_Monolith-blue) ![Methodology](https://img.shields.io/badge/Methodology-BMAD--METHOD-success) +UMS posee la evidencia de implementacion especifica del producto. Evolith posee los estandares empresariales reutilizables. --- -## Acceso rápido a estándares +## Empieza aqui -| Necesidad | Ruta directa | -| :--- | :--- | -| Referencia aplicada React Web UMS | [Referencia Aplicada React Web UMS](./architecture/web-frontend/ums-react-applied-reference.es.md) | -| Referencia aplicada API .NET UMS | [Referencia Aplicada API .NET UMS](./architecture/api-dotnet/ums-api-dotnet-applied-reference.es.md) | -| Estándar React upstream Evolith | [Estandar Web Frontend React Evolith](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.es.md) | -| Estándar API .NET upstream Evolith | [Estandar API .NET Evolith](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/api-dotnet/api-dotnet-standard.es.md) | -| Todos los estándares en una página | [Acceso Rápido a Estándares](./STANDARDS.es.md) | +| Necesidad | Ir a | +|---|---| +| Encontrar estandares React, Web, C# o .NET | [Acceso rapido a estandares](./STANDARDS.es.md) | +| Entender la arquitectura | [Portal de arquitectura](./architecture/index.es.md) | +| Revisar decisiones arquitectonicas UMS | [Registro ADR](./architecture/adrs/index.md) | +| Entender el alcance del producto | [Vision del producto](./governance/product-es/product-vision.md) | +| Revisar requerimientos | [Indice de requerimientos](./governance/requirements-es/index.md) | +| Revisar plan de entrega | [MVP Product Backlog](./governance/project-es/mvp-product-backlog.md) | +| Explorar diseno de dominio | [Portal de construccion](./governance/construction/index.es.md) | +| Operar u observar UMS | [Portal de operaciones](./operations/index.md) | +| Explorar todos los documentos | [Indice maestro](./MASTER_INDEX.es.md) | --- -## Índice maestro de navegación +## Rutas rapidas por rol + +| Rol | Empezar con | Luego leer | +|---|---|---| +| Ingeniero backend | [Referencia aplicada API .NET UMS](./architecture/api-dotnet/ums-api-dotnet-applied-reference.es.md) | [Portal de construccion](./governance/construction/index.es.md) | +| Ingeniero frontend | [Referencia aplicada React Web UMS](./architecture/web-frontend/ums-react-applied-reference.es.md) | [Estandar Web Frontend React Evolith](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.es.md) | +| Arquitecto | [Portal de arquitectura](./architecture/index.es.md) | [Matriz de trazabilidad](./architecture/traceability-matrix.md) | +| Product owner o QA | [Historias funcionales](./governance/requirements-es/functional-stories/index.md) | [MVP Product Backlog](./governance/project-es/mvp-product-backlog.md) | +| DevOps u operaciones | [Portal de operaciones](./operations/index.md) | [Dashboard de metricas](./operations/metrics/index.md) | +| Revisor de gobierno | [Acceso rapido a estandares](./STANDARDS.es.md) | [Portal de arquitectura](./architecture/index.es.md) | + +--- -Comience aquí si es nuevo en UMS. Este índice ofrece a cada lector una ruta rápida al repositorio sin necesidad de conocer la estructura de carpetas. +## Estandares y referencias aplicadas -| Quiero... | Empezar aquí | Luego leer | -| :--- | :--- | :--- | -| Encontrar estándares React, Web, C# o .NET | [Acceso Rápido a Estándares](./STANDARDS.es.md) | [Portal de Arquitectura](./architecture/index.es.md) | -| Entender el producto | [Visión del Producto](./governance/product-es/product-vision.md) | [Contexto de Negocio](./governance/product-es/business-context.md) → [Alcance](./governance/product-es/scope.md) | -| Ver épicas y prioridades | [MVP Product Backlog](./governance/project-es/mvp-product-backlog.md) | [Índice de Requerimientos](./governance/requirements-es/index.md) → [Historias Funcionales](./governance/requirements-es/functional-stories/index.md) | -| Revisar requerimientos funcionales | [Índice de Requerimientos](./governance/requirements-es/index.md) | [Historias Funcionales](./governance/requirements-es/functional-stories/index.md) → [Glosario](./governance/requirements-es/glossary.md) | -| Validar el modelo de datos y dominio | [Modelo de Datos Conceptual](./governance/requirements-es/conceptual-data-model.md) | [Formatos de Exportación ER](./architecture/blueprints-es/er-export-formats.md) → [Diseño de Base de Datos ER](./architecture/blueprints-es/database-design-er.md) | -| Entender la arquitectura | [Portal de Arquitectura](./architecture/index.es.md) | [Diseño de Base de Datos ER](./architecture/blueprints-es/database-design-er.md) | -| Explorar todo | [Índice Maestro](./MASTER_INDEX.es.md) | Árbol completo de documentos por fase del ciclo de vida. | +| Area | Referencia aplicada UMS | Estandar upstream Evolith | +|---|---|---| +| Frontend React Web | [Referencia aplicada React Web UMS](./architecture/web-frontend/ums-react-applied-reference.es.md) | [Estandar Web Frontend React Evolith](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/web-frontend/react/react-web-frontend-standard.es.md) | +| Backend API .NET | [Referencia aplicada API .NET UMS](./architecture/api-dotnet/ums-api-dotnet-applied-reference.es.md) | [Estandar API .NET Evolith](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/governance/standards/engineering/api-dotnet/api-dotnet-standard.es.md) | +| Todos los estandares | [Acceso rapido a estandares UMS](./STANDARDS.es.md) | [Acceso rapido por stack Evolith](https://github.com/beyondnetcode/evolith_arch32/blob/main/reference/quick-access/README.es.md) | --- -## Resumen de arquitectura - -### Stack tecnológico - -| Capa | Tecnología | -| :--- | :--- | -| **Backend** | .NET 10, HotChocolate (GraphQL), Minimal APIs (REST) | -| **Frontend** | React 18, Vite 5, TypeScript, TailwindCSS, Zustand, TanStack Query | -| **Base de datos** | SQL Server 2022, Entity Framework Core | -| **Monorepo** | Nx, npm Workspaces | -| **Metodología** | BMAD-METHOD, Arquitectura Limpia (Hexagonal), DDD | - -### Estructura del proyecto - -```text -src/ -├── apps/ -│ ├── ums.api/ # Backend .NET (Arquitectura Limpia) -│ │ ├── Domain/ # POCOs puros, sin referencias NuGet -│ │ ├── Application/ # Casos de uso, interfaces -│ │ ├── Infrastructure/ # EF Core, servicios externos -│ │ └── Presentation/ # Endpoints GraphQL/REST -│ └── ums.web-app/ # Frontend React (Arquitectura Limpia) -│ ├── src/ -│ │ ├── domain/ # Entidades empresariales, value objects -│ │ ├── application/ # Hooks, stores, casos de uso -│ │ ├── infrastructure/ # Clientes HTTP, cliente GraphQL -│ │ └── presentation/ # Componentes, pantallas, layouts -│ └── ... -└── ... -``` +## UMS vs Evolith + +| Pregunta | UMS | Evolith | +|---|---|---| +| Que pertenece aqui? | Evidencia de fuente especifica del producto, ejemplos aplicados, decisiones locales, rutas, modulos, schemas, valores runtime | Estandares empresariales reutilizables, principios, ADRs, patrones canonicos, quality gates | +| Que no debe generalizarse aqui? | Decisiones locales que solo aplican a UMS | Evidencia de implementacion especifica de producto | +| Como una practica UMS se vuelve estandar? | Aporta evidencia de implementacion | Se promueve mediante ADR, estandar de gobierno o patron canonico | -### Decisiones arquitectónicas clave +--- + +## Snapshot tecnologico -- **GraphQL para consultas, REST para comandos**: Todas las operaciones de lectura usan HotChocolate GraphQL; las escrituras usan REST Minimal APIs para claridad transaccional. -- **Arquitectura limpia**: Límites estrictos entre capas. La capa de dominio es pura, sin dependencias externas. -- **Patrón Result**: Sin excepciones para control de flujo. Todas las operaciones retornan `Result`. -- **Bounded Contexts**: Identity, Access, Audit, etc. Cada contexto tiene sus propios agregados, servicios y módulos de presentación. +| Capa | Tecnologia | +|---|---| +| Backend | .NET 10, HotChocolate GraphQL, Minimal APIs REST | +| Frontend | React 18, Vite 5, TypeScript, TailwindCSS, Zustand, TanStack Query | +| Base de datos | SQL Server 2022, Entity Framework Core | +| Monorepo | Nx, npm Workspaces | +| Metodologia | BMAD-METHOD, Arquitectura Limpia, DDD | --- -## Inicio rápido (Engine Room) +## Inicio rapido ### Prerrequisitos - Node.js 20+ - .NET 10 SDK -- SQL Server 2022 o Docker: +- SQL Server 2022 o Docker + +### Backend ```bash -docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourPassword123!" -p 1433:1433 mcr.microsoft.com/mssql/server:2022-latest +cd src/apps/ums.api +dotnet build +dotnet run ``` ### Frontend @@ -100,67 +93,45 @@ npm install npm run dev ``` -### Backend - -```bash -cd src/apps/ums.api -dotnet build -dotnet run -``` - -### Full stack (Frontend + Backend) +### Full stack ```bash -# Terminal 1 — Backend (puerto 7114) +# Terminal 1 - Backend cd src/apps/ums.api && dotnet run -# Terminal 2 — Frontend (puerto 5173) -cd src/apps/ums.web-app && npm install && npm run dev +# Terminal 2 - Frontend +cd src/apps/ums.web-app && npm run dev ``` --- -## Comandos de desarrollo +## Mapa del repositorio -| Comando | Descripción | -| :--- | :--- | -| `npm install` | Instalar dependencias frontend desde `src/apps/ums.web-app` | -| `npm run dev` | Iniciar servidor de desarrollo frontend (puerto 5173) | -| `npm run build` | Compilar frontend para producción | -| `npm run lint` | Ejecutar ESLint | -| `npm run test` | Ejecutar tests Vitest | -| `dotnet build` | Compilar backend desde `src/apps/ums.api` | -| `dotnet test` | Ejecutar tests backend | -| `dotnet run` | Iniciar API backend (puerto 7114) | +| Area | Entrada | Proposito | +|---|---|---| +| Estandares | [docs/STANDARDS.es.md](./STANDARDS.es.md) | Enlaces directos a estandares Evolith y referencias aplicadas UMS | +| Arquitectura | [docs/architecture](./architecture/index.es.md) | ADRs, blueprints, referencias aplicadas API/Web, trazabilidad | +| Gobernanza | [docs/governance](./governance/index.es.md) | Vision, alcance, requerimientos y documentacion de entrega | +| Construccion | [docs/governance/construction](./governance/construction/index.es.md) | Diseno DDD, bounded contexts, agregados, eventos, comandos | +| Operaciones | [docs/operations](./operations/index.md) | Metricas, runbooks y documentacion operacional | +| Fuente | [src/apps](../src/apps) | Codigo fuente API y Web | +| Navegacion completa | [docs/MASTER_INDEX.es.md](./MASTER_INDEX.es.md) | Arbol documental completo | --- -## Centro de conocimiento +## Notas de seguridad y calidad -| Dominio | Índice del portal | Contenido | -| :--- | :--- | :--- | -| **Estándares** | [Acceso Rápido a Estándares](./STANDARDS.es.md) | Enlaces directos a estándares Evolith y referencias aplicadas UMS para React Web y API .NET. | -| **Gobernanza** | [Portal de Gobernanza](./governance/index.es.md) | Dirección del producto, alcance de negocio y requerimientos funcionales. | -| **Entrega del proyecto** | [Backlog del Proyecto](./governance/project-es/index.md) | Épicas MVP, historias de usuario y diseño funcional de módulos core. | -| **Requerimientos** | [Índice de Requerimientos](./governance/requirements-es/index.md) | Historias funcionales, glosario de negocio y modelo de datos conceptual. | -| **Arquitectura** | [Portal de Arquitectura](./architecture/index.es.md) | Diseño ER de base de datos, entity maps y visores interactivos. | -| **Construcción** | [Portal de Construcción](./governance/construction/index.es.md) | Diseño DDD de la capa de dominio: bounded contexts, agregados, eventos y comandos. | +- CSP, CSRF, security headers y validacion runtime forman parte del baseline de implementacion. +- Las decisiones React Web y API .NET estan documentadas como referencias aplicadas en `docs/architecture/`. +- Los estandares empresariales reutilizables deben promoverse upstream a Evolith. --- -## Seguridad y cumplimiento - -- **Content Security Policy**: CSP restrictiva sin `unsafe-eval`, lista para producción. -- **Protección CSRF**: Patrón double-submit cookie con refresco de token. -- **Headers de seguridad**: HSTS, X-Frame-Options, X-Content-Type-Options y Referrer-Policy vía Nginx. -- **Validación de inputs**: Schemas Zod como fuente única de verdad para validación runtime. - ---- +## Contribucion y gobierno -## Contribución y gobernanza +Antes de cambiar arquitectura o documentacion, revisa: -- **Flujo de trabajo**: Este repositorio utiliza [BMAD-METHOD](../AGENTS.md) para documentación orientada a especificaciones. -- **Navegación**: Visite el [Índice Maestro](./MASTER_INDEX.es.md) para el árbol completo de documentos. -- **Estándares aplicados**: Visite [Acceso Rápido a Estándares](./STANDARDS.es.md) para React Web, API .NET y referencias Evolith. -- **Estándares de código**: ESLint + TypeScript strict mode. Cero errores requeridos antes de commit. -- **Testing**: Vitest con React Testing Library. Umbrales de cobertura: 60% líneas/sentencias. +- [Acceso rapido a estandares](./STANDARDS.es.md) +- [Portal de arquitectura](./architecture/index.es.md) +- [Indice maestro](./MASTER_INDEX.es.md) +- [AGENTS.md](../AGENTS.md)