Add comprehensive technical documentation for complementary-service microservice

[Copilot]

Professional documentation suite generated through codebase reverse engineering. Provides architectural overview, API contracts, and operational guides for the complementary services microservice (Transport/Catering/Merchandising orchestration).

Documentation Structure

README.md

• Business context: async service orchestration via RabbitMQ with real-time SignalR notifications
• Stack: .NET 8, PostgreSQL, RabbitMQ, SignalR, Hexagonal Architecture + DDD
• Quick start: docker-compose up -d → http://localhost:5050/swagger

docs/architecture.md

• Data flow: Request → Controller → AppService → Domain Entity → Repository → MediatR → RabbitMQ Publisher → External Provider → Consumer → SignalR Hub
• Dependencies: PostgreSQL (persistence), RabbitMQ (3 topic queues), SignalR Hub (/hubs/service-notifications), Keycloak (JWT)
• Domain model: ComplementaryService aggregate with ServiceType/ServiceStatus value objects, state machine (Requested → Pending → Confirmed/Rejected/Cancelled)
• Technical debt section: 6 issues identified
  • In-memory reservation repository (non-production)
  • GetMetricsAsync() loads full dataset (O(n) aggregation)
  • X-User-Id auth bypass without environment guard
  • Missing RabbitMQ retry policy
  • Generic exception swallowing
  • No Dead Letter Queue

docs/api.md

• 6 REST endpoints with JSON examples
• SignalR Hub integration (ReceiveServiceUpdate events)
• Complete usage scenarios with curl commands

Example request flow:

# Create service request
POST /api/v1/ComplementaryServices/request
{
  "reservationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "serviceType": "Transport",
  "details": "15 passengers, Hotel Plaza → Convention Center, 17:30"
}

# Response: 202 Accepted with serviceId
# SignalR notification received when provider confirms/rejects

docs/setup.md

• 25+ environment variables documented (PostgreSQL, RabbitMQ, Keycloak, CORS)
• Docker multi-stage build explanation
• 15 utility scripts from docker_scripts.sh (build, migrate, backup, health, etc.)
• Local development without Docker
• Troubleshooting guide

Statistics

• 1,697 lines of documentation
• 4 files modified/created
• Spanish language (per requirement)

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.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.