hanifalkauni/uml-architect

Instruções da Skill UML-Architect

Estas instruções configuram o Agente de IA para gerar saídas de análise de arquitetura e diagramas UML que são 100% idênticos e consistentes com a saída do mecanismo determinístico do Servidor MCP UML-Architect.

---

1. Protocolo de Execução em 5 Etapas (Pipeline de Execução)

Etapa 1: Resolução de Alvo e Detecção da Base de Código

1. Identificar o Alvo:
   • A entrada é um Endpoint de API (ex: POST /api/v1/orders/checkout), um Nome de Função (ex: processPayment), ou um Caminho de Arquivo/Módulo (ex: src/controllers/order.controller.ts)?
2. Varredura de Manifesto (Sem Compilação):
   • Verifique os arquivos de manifesto do projeto: package.json, go.mod, pom.xml, pyproject.toml, Cargo.toml, composer.json, Gemfile ou *.csproj.
   • Identifique o framework utilizado: Express/NestJS, FastAPI/Django, Gin/Fiber, Spring Boot, Axum/Actix, ASP.NET, Laravel ou Rails.

Etapa 2: Rastreamento Real do Grafo de Chamadas (Strict Tracing - Zero Hallucination)

Rastreie o fluxo de execução a partir do código-fonte real:

1. Ponto de Entrada (Entrypoint): Abra o arquivo de rota/controlador correspondente.
2. Middlewares e Guards: Rastreie verificações de token JWT, sessão, validação de esquema de requisição (Zod, Joi, Pydantic, validador de DTO).
3. Controller / Handler: Verifique a lógica de extração de parâmetros da requisição e delegação para a camada de serviço (service layer).
4. Service / Domain Layer: Rastreie o fluxo de negócios principal, chamadas a helpers e cálculos de dados.
5. Database & ORM: Rastreie operações de consulta/mutação (SELECT, INSERT, UPDATE, transações commit/rollback).
6. Integração Externa: Rastreie chamadas HTTP (Stripe, API Bancária, SendGrid, OAuth) ou chamadas RPC.
7. Fila de Mensagens / Evento: Rastreie a publicação de eventos assíncronos para Kafka, RabbitMQ, SQS, Redis PubSub ou Celery.
8. Ramos de Erro: Mapeie blocos try/catch, if err != nil, except ou guards de erro para ramos alternativos (alt).

---

2. Padrão de Participantes e Alias de Diagrama

Use o esquema de nomenclatura de participantes padrão para manter os diagramas limpos, consistentes e fáceis de ler:

Categoria	ID do Participante	Formato do Rótulo do Participante	Tipo do Participante
Cliente / Chamador	Client	Client / Frontend App (ou User / Mobile App)	actor
Controller / Handler	Ctrl	<NomeDoArquivo/Controller> (Controller)	participant
Camada de Serviço	Svc	<NomeDoServiço> (exemplo: OrderService)	participant
Terceiros / Externo	ExtAPI	<NomeDoFornecedor/Gateway> (External API) (exemplo: Stripe API)	participant
Banco de Dados / Armazenamento	DB	Database (Storage / ORM) (exemplo: Banco de Dados PostgreSQL)	participant
Fila / Broker de Eventos	Queue	Message Broker (Kafka / Queue)	participant

---

3. Regras de Sintaxe e Tema Visual do Mermaid.js

1. Diretiva de Tema (Obrigatória na Primeira Linha do Diagrama): Use o tema moderno tokyo-night como padrão:

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

2. Diagrama de Sequência:
   • Sempre inclua sequenceDiagram e autonumber.
   • Use seta ->> para síncrono, -->> para retorno/resposta, e -) para assíncrono/evento de fila.
   • Coloque a ramificação de validação falha versus sucesso dentro de blocos alt e else:

     alt Validação de Entrada / Auth Falhou
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else Validação Bem-sucedida (Caminho Feliz)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. Autocorreção de Sintaxe (Anti-Erro):
   • Evite caracteres de colchetes sem aspas dentro das mensagens.
   • Não use caractere de barra (/) diretamente no ID do participante (sempre use alias limpos como Ctrl, Svc).

---

4. Formato de Contrato de Saída Obrigatório (Contrato Canônico de Saída)

Cada resposta de criação de diagrama DEVE seguir a estrutura Markdown exatamente como o modelo abaixo para ser idêntica à saída do Servidor MCP:

# Diagrama UML: <Nome do Alvo / Endpoint>

> *Gerado automaticamente 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 <NomeDoControlador> (Controller)
    participant Svc as <NomeDoServiço>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <METODO_HTTP> <CAMINHO_URL>
    alt Validação de Entrada / Auth Falhou
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else Validação Bem-sucedida (Caminho Feliz)
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: Save / Query Transaction Record
        DB-->>Svc: DB Commit Success
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (Success Payload)
    end
```

<details>
<summary>Ver Formato Alternativo (PlantUML)</summary>

```puml
@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Frontend App" as Client
participant "<NomeDoControlador> (Controller)" as Ctrl
participant "<NomeDoServiço>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <METODO_HTTP> <CAMINHO_URL>
alt Validação de Entrada / Auth Falhou
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else Validação Bem-sucedida (Caminho Feliz)
Ctrl -> Svc: processRequest(payload)
Svc -> DB: Save / Query Transaction Record
DB --> Svc: DB Commit Success
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (Success Payload)
end
@enduml
```
</details>

### Explicação do Fluxo Arquitetural (<Nome do Alvo / Endpoint>)

Este fluxo de execução envolve **<N> componentes principais**:

* **Client / Frontend App** (`Client`): Atua como entidade usuária/chamadora.
* **<NomeDoControlador> (Controller)** (`Ctrl`): Atua como entidade controladora de requisição e resposta.
* **<NomeDoServiço>** (`Svc`): Atua como provedor de lógica de negócios do domínio.
* **Database (Storage / ORM)** (`DB`): Atua como meio de persistência de dados de transação.
* **Message Broker (Kafka / Queue)** (`Queue`): Atua como receptor de eventos assíncronos.

#### Detalhamento das Etapas de Execução:
1. **Client** envia requisição `<METODO_HTTP> <CAMINHO_URL>` para **Ctrl**.
   * *Verificação de Condição*: Se os parâmetros forem inválidos ou a autenticação falhar, o fluxo é interrompido imediatamente com resposta HTTP 400/401.
2. **Ctrl** delega o payload válido para **Svc**.
3. **Svc** executa consulta/mutação no **DB** e recebe confirmação de armazenamento.
4. **Ctrl** emite evento de notificação para o **Queue**.
5. **Ctrl** retorna resposta de sucesso HTTP 200/201 para **Client**.

#### Tratamento de Erros e Exceções (Caminhos de Erro):
* **ValidationException**: Gera resposta HTTP `400` se o payload não atender aos requisitos do esquema.
* **UnauthorizedException**: Gera resposta HTTP `401` se o token de autorização for inválido ou estiver expirado.
* **InternalException**: Gera resposta HTTP `500` se ocorrer falha de rede ou rollback de banco de dados.

---

5. Outros Tipos de Diagrama (Se Solicitado pelo Usuário)

• Fluxograma / Diagrama de Atividades: Use flowchart TD com nós de início/fim arredondados ([ ... ]), losango de decisão { "Condição?" } e caixa de processo [ ... ].
• Diagrama de Máquina de Estados: Use stateDiagram-v2 com estado inicial [*], estados de transição, guardas e estado terminal [*].
• Diagrama de Componentes / Arquitetura: Use graph TD com subgraph aninhados (Camada de Apresentação, Camada de Lógica de Negócios, Camada de Dados e Persistência).