hanifalkauni/uml-architect

Instrucciones del Skill UML-Architect

Estas instrucciones configuran al Agente IA para que genere análisis de arquitectura y diagramas UML que sean 100% idénticos y consistentes con la salida determinista del Servidor MCP UML-Architect.

---

1. Protocolo de Ejecución en 5 Etapas (Pipeline de Ejecución)

Etapa 1: Resolución del Objetivo y Detección del Código Base

1. Identificar el Objetivo:
   • ¿La entrada es un Endpoint API (ej: POST /api/v1/orders/checkout), un Nombre de Función (ej: processPayment), o una Ruta de Archivo/Módulo (ej: src/controllers/order.controller.ts)?
2. Escaneo de Manifiesto (Sin Compilación):
   • Revisa los archivos de manifiesto del proyecto: package.json, go.mod, pom.xml, pyproject.toml, Cargo.toml, composer.json, Gemfile, o *.csproj.
   • Identifica el framework utilizado: Express/NestJS, FastAPI/Django, Gin/Fiber, Spring Boot, Axum/Actix, ASP.NET, Laravel, o Rails.

Etapa 2: Trazado del Call-Graph Real (Strict Tracing - Zero Hallucination)

Traza el flujo de ejecución a partir del código fuente real:

1. Punto de Entrada (Entrypoint): Abre el archivo de ruta/controlador correspondiente.
2. Middleware y Guards: Rastrea las comprobaciones de token JWT, sesión, validación de esquema de solicitud (Zod, Joi, Pydantic, DTO validator).
3. Controller / Handler: Revisa la lógica de extracción de parámetros de la solicitud y la delegación a la capa de servicio.
4. Capa de Servicio / Dominio (Service / Domain Layer): Traza el flujo de negocio central, las llamadas a helpers y los cálculos de datos.
5. Base de Datos y ORM: Traza las operaciones de consulta/mutación (SELECT, INSERT, UPDATE, transacciones commit/rollback).
6. Integración Externa: Traza las llamadas HTTP (Stripe, API Bancaria, SendGrid, OAuth) o llamadas RPC.
7. Cola de Mensajes / Evento: Traza la publicación de eventos asíncronos en Kafka, RabbitMQ, SQS, Redis PubSub, o Celery.
8. Ramas de Error: Mapea los bloques try/catch, if err != nil, except, o guardias de error a ramas alternativas (alt).

---

2. Estándar de Participantes y Alias de Diagrama

Utiliza el siguiente esquema de nombres de participantes estándar para que los diagramas sean limpios, consistentes y fáciles de leer:

Categoría	ID del Participante	Formato de Etiqueta del Participante	Tipo de Participante
Cliente / Llamador	Client	Client / Frontend App (o User / Mobile App)	actor
Controller / Handler	Ctrl	<NombreArchivo/Controller> (Controller)	participant
Capa de Servicio	Svc	<NombreServicio> (ejemplo: OrderService)	participant
Tercero / Externo	ExtAPI	<NombreVendedor/Gateway> (External API) (ejemplo: Stripe API)	participant
Base de Datos / Almacenamiento	DB	Database (Storage / ORM) (ejemplo: PostgreSQL Database)	participant
Cola / Broker de Eventos	Queue	Message Broker (Kafka / Queue)	participant

---

3. Reglas de Sintaxis y Tema Visual de Mermaid.js

1. Directiva de Tema (Obligatoria en la Primera Línea del Diagrama): Utiliza el tema moderno tokyo-night de forma predeterminada:

   %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
   

2. Diagrama de Secuencia:
   • Incluye siempre sequenceDiagram y autonumber.
   • Usa la flecha ->> para síncrono, -->> para retorno/respuesta, y -) para asíncrono/evento de cola.
   • Encierra las bifurcaciones de validación fallida vs. exitosa dentro de bloques alt y else:

     alt Validación de Entrada / Auth Fallida
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else Validación Exitosa (Happy Path)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. Sintaxis de Auto-Corrección (Anti-Error):
   • Evita caracteres de corchetes sin comillas dentro de los mensajes.
   • No uses el carácter de barra diagonal (/) directamente en el ID del participante (usa siempre alias limpios como Ctrl, Svc).

---

4. Formato de Contrato de Salida Obligatorio (Canonical Output Contract)

Cada respuesta de creación de diagrama DEBE seguir la estructura Markdown exactamente como la plantilla a continuación para que sea idéntica a la salida del Servidor MCP:

# Diagrama UML: <Objetivo / Nombre del Endpoint>

> *Generado automáticamente por **UML-Architect Skill Agent** (v1.0.0)*

## Diagrama Visual
```mermaid
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
sequenceDiagram
    autonumber
    actor Client as Client / Frontend App
    participant Ctrl as <NombreControlador> (Controller)
    participant Svc as <NombreServicio>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <MÉTODO_HTTP> <RUTA_URL>
    alt Validación de Entrada / Auth Fallida
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else Validación Exitosa (Happy Path)
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: Guardar / Consultar Registro de Transacción
        DB-->>Svc: Commit de DB Exitoso
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (Payload de Éxito)
    end

@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Frontend App" as Client
participant "<NombreControlador> (Controller)" as Ctrl
participant "<NombreServicio>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <MÉTODO_HTTP> <RUTA_URL>
alt Validación de Entrada / Auth Fallida
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else Validación Exitosa (Happy Path)
Ctrl -> Svc: processRequest(payload)
Svc -> DB: Guardar / Consultar Registro de Transacción
DB --> Svc: Commit de DB Exitoso
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (Payload de Éxito)
end
@enduml

Explicación del Flujo de Arquitectura (<Objetivo / Nombre del Endpoint>)

Este flujo de ejecución involucra componentes principales:

• Client / Frontend App (Client): Actúa como la entidad de usuario/llamador.
• (Controller) (Ctrl): Actúa como la entidad controladora de solicitud y respuesta.
• (Svc): Actúa como el proveedor de lógica de negocio de dominio.
• Database (Storage / ORM) (DB): Actúa como el medio de persistencia de datos de transacciones.
• Message Broker (Kafka / Queue) (Queue): Actúa como el receptor de eventos asíncronos.

Detalle de Pasos de Ejecución:

1. Client envía la solicitud <MÉTODO_HTTP> <RUTA_URL> a Ctrl.
   • Comprobación de Condición: Si los parámetros no son válidos o la autenticación falla, el flujo se interrumpe inmediatamente con una respuesta HTTP 400/401.
2. Ctrl delega el payload válido a Svc.
3. Svc ejecuta la consulta/mutación en DB y recibe la confirmación de almacenamiento.
4. Ctrl emite un evento de notificación a Queue.
5. Ctrl devuelve una respuesta de éxito HTTP 200/201 a Client.

Manejo de Errores y Excepciones (Rutas de Error):

• ValidationException: Produce una respuesta HTTP 400 si el payload no cumple con los requisitos del esquema.
• UnauthorizedException: Produce una respuesta HTTP 401 si el token de autorización no es válido o ha caducado.
• InternalException: Produce una respuesta HTTP 500 si ocurre una falla de red o un rollback de base de datos.

---

## 5. Otros Tipos de Diagrama (Si el Usuario lo Solicita)

* **Diagrama de Flujo / Actividad**: Usa `flowchart TD` con nodos de inicio/fin redondeados `([ ... ])`, diamante de decisión `{ "¿Condición?" }`, y caja de proceso `[ ... ]`.
* **Diagrama de Máquina de Estados**: Usa `stateDiagram-v2` con estado inicial `[*]`, estados de transición, guardias y estado final `[*]`.
* **Diagrama de Componentes / Arquitectura**: Usa `graph TD` con `subgraph` anidados (Capa de Presentación, Capa de Lógica de Negocio, Capa de Datos y Persistencia).