Add comprehensive documentation for users-service microservice

[Copilot]

Reverse-engineered and documented an undocumented .NET 8.0 microservice with Clean Architecture implementing user management via PostgreSQL and Keycloak integration.

Documentation Structure

• README.md (122 lines): Landing page with stack overview, 30-second Docker Compose quick start, and navigation to detailed docs
• docs/architecture.md (460 lines): Clean Architecture layer breakdown, CQRS data flow diagrams, external dependencies (PostgreSQL, Keycloak), data models, and technical debt analysis
• docs/api.md (541 lines): Complete REST API reference for 6 endpoints with request/response schemas, validation rules, cURL examples, and timeout configuration
• docs/setup.md (726 lines): Environment variables reference, Docker orchestration, .NET CLI commands, EF Core migrations, multi-environment configs, and production deployment checklist

Architecture Overview

The service implements a 4-layer Clean Architecture:

API Layer (Controllers) → Application Layer (CQRS Handlers) 
  → Domain Layer (Entities, Value Objects) → Infrastructure (Repositories, EF Core)

External integrations:

• PostgreSQL 16 for user persistence
• Keycloak 26.0 for OAuth2/OIDC authentication and role management

Endpoints documented:

• POST /api/users/registerUser - Creates user in both DB and Keycloak
• GET /api/users/getUser/{email} - Retrieves user profile
• POST /api/users/changePassword/{email} - Updates Keycloak credentials
• PUT /api/users/updateUser/{email} - Partial profile updates
• GET /api/users/getUsers - Lists all users (no pagination)
• GET /api/users/getIdUser/{email} - Returns user GUID

Technical Debt Identified

Critical:

• No JWT authentication/authorization on any endpoint
• HttpClient instantiated in method instead of injected (socket exhaustion risk)

Medium:

• Hardcoded Keycloak URLs bypassing configuration
• Missing pagination on list endpoint
• Admin/user token cache collision bug

Low:

• Console.WriteLine instead of ILogger
• Class name typo: KeycloakServiceInfrastracture (should be Infrastructure)
• Mixed Spanish/English namespaces

Each item includes file location, impact assessment, and recommended fix.

Example: User Registration Flow

curl -X POST http://localhost:7181/api/users/registerUser \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "juan.perez@example.com",
    "phoneNumber": "+573001234567",
    "address": "Calle 123 #45-67",
    "birthdate": "1990-05-15T00:00:00",
    "roleUser": "Usuario",
    "password": "SecurePass123!"
  }'

Metrics

• 1,849 lines, 5,744 words across 4 files
• 10 technical debt items prioritized by severity
• 35+ copy-paste ready code examples
• Bilingual approach (Spanish content, English technical terms)

Original prompt

Actúa como un Lead Technical Writer y Arquitecto de Software. Estoy haciendo ingeniería inversa a un microservicio desconocido y necesito documentarlo profesionalmente.

Basado en el código que te proporcionaré, genera el contenido para los siguientes 4 archivos. Por favor, separa claramente la respuesta para cada archivo:

1. README.md (La portada)

Debe ser breve y contener:

• Título y Descripción: ¿Qué problema de negocio resuelve este servicio?
• Tabla de Contenidos: Enlaces a los documentos de la carpeta docs/.
• Stack: Tecnologías principales.
• Quick Start: Comando rápido para levantar el servicio (ej. npm start o docker-compose up).

2. docs/architecture.md (Cómo funciona por dentro)

• Flujo de Datos: Explica narrativamente cómo entra una petición y qué capas atraviesa (Controller -> Service -> Repository).
• Dependencias Externas: ¿A qué otros microservicios, bases de datos o APIs de terceros llama? (Deducido de los imports o variables de entorno).
• Modelo de Datos: Breve descripción de las entidades principales detectadas.

3. docs/api.md (Contrato de interfaz)

• Endpoints: Lista los endpoints detectados.
• Ejemplos: Para el endpoint más complejo, genera un ejemplo de JSON de Request y Response (basado en la validación de tipos o modelos que veas).

4. docs/setup.md (Guía detallada de configuración)

• Variables de Entorno: Tabla completa de variables requeridas y para qué sirven.
• Docker: Si hay Dockerfile, explica cómo construir la imagen.
• Scripts: Explica qué hacen los scripts encontrados en package.json o Makefile.

---

IMPORTANTE: Si ves algo en el código que parece un "hack", código muerto o una vulnerabilidad potencial, añade una sección de "Deuda Técnica Detectada" al final de architecture.md.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.