@devtrack-solution/codesdd 1.2.2

package/.sdd/skills/curated/api-clean-flask-langgraph/SKILL.md

@@ -0,0 +1,2751 @@
+# Skill: API Clean Flask + SQLAlchemy + WebSocket + LangGraph Multiagente
+
+## Objetivo
+
+Use esta skill para gerar, revisar, refatorar ou evoluir um projeto Python com Flask seguindo Clean Architecture, com dois canais isolados de entrada:
+
+- HTTP REST
+- WebSocket
+
+A aplicação possui três domínios de negócio:
+
+- Clínicas
+- Serviços
+- Agendamentos
+
+E possui um sistema multiagente baseado em LangChain e LangGraph, acionado pela camada `application` e alimentado principalmente por mensagens recebidas via WebSocket.
+
+---
+
+## Stack técnica padrão
+
+Use esta stack, salvo decisão explícita em contrário:
+
+- Python 3.12+
+- Flask
+- Flask-Sock
+- SQLAlchemy 2.x, usando ORM tipado com `Mapped` e `mapped_column`
+- Alembic para migrations
+- Pydantic v2 para schemas de entrada/saída
+- PyJWT para validação explícita de tokens JWT
+- OpenAPI v3 para contrato HTTP
+- Swagger UI para documentação interativa
+- PostgreSQL como banco relacional recomendado para produção
+- MySQL como banco relacional suportado
+- SQLite apenas para desenvolvimento local leve e testes rápidos quando compatível
+- LangChain para tools e integração com modelos
+- LangGraph para orquestração stateful de agentes
+- Redis obrigatório para cache, pub/sub, fan-out de eventos, sessões WebSocket, locks distribuídos e checkpointer
+- Pytest para testes
+- Ruff, Black e Mypy para qualidade
+
+Não use Flask-SQLAlchemy por padrão. Nesta arquitetura, prefira SQLAlchemy puro para manter a persistência em `infrastructure`, sem acoplar o ORM ao objeto Flask.
+
+Todo código de persistência deve ser compatível com PostgreSQL e MySQL, salvo quando a skill declarar uma diferença explícita de dialeto.
+
+Todo código Python deve ser tipado e orientado a objetos por padrão.
+
+---
+
+## Tipagem Python e orientação a objetos
+
+Use Python tipado em todos os arquivos gerados.
+
+Regras obrigatórias:
+
+- Todo módulo deve usar type hints explícitos em funções, métodos, atributos e retornos públicos.
+- Use `from __future__ import annotations` quando melhorar legibilidade ou evitar imports circulares.
+- Use `dataclass(frozen=True)` para DTOs imutáveis de application quando Pydantic não for necessário.
+- Use Pydantic v2 para schemas de interface e validação de payload externo.
+- Use `Protocol` ou `ABC` para ports.
+- Use classes para use cases, repositories, Unit of Work, policies, services, adapters, controllers e orchestrators.
+- Evite lógica procedural espalhada em funções soltas.
+- Funções soltas são aceitáveis apenas para factories, builders, helpers puros pequenos, route handlers Flask e nodes simples do LangGraph.
+- Não retorne `Any` sem justificativa.
+- Não ignore Mypy sem comentário objetivo.
+- Prefira composição e injeção de dependência explícita em construtores.
+- Evite herança profunda; use herança principalmente para mixins ORM, exceptions e contracts abstratos.
+- Métodos de domínio devem expressar comportamento da entidade, não apenas getters/setters.
+
+Exemplo de port tipado:
+
+```python
+from typing import Protocol
+
+from src.domain.clinics.entities.clinic import Clinic
+
+
+class ClinicRepositoryPort(Protocol):
+    def get_by_id(self, tenant_id: int, clinic_id: int) -> Clinic | None:
+        ...
+
+    def save(self, clinic: Clinic) -> Clinic:
+        ...
+```
+
+Exemplo de use case orientado a objeto:
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class GetClinicInput:
+    tenant_id: int
+    clinic_id: int
+
+
+class GetClinicUseCase:
+    def __init__(self, clinic_repository: ClinicRepositoryPort):
+        self._clinic_repository = clinic_repository
+
+    def execute(self, input_data: GetClinicInput) -> ClinicOutput:
+        clinic = self._clinic_repository.get_by_id(
+            tenant_id=input_data.tenant_id,
+            clinic_id=input_data.clinic_id,
+        )
+        if clinic is None:
+            raise NotFoundAppError("Clinic not found")
+        return ClinicOutput.from_domain(clinic)
+```
+
+---
+
+## Regra central da arquitetura
+
+Nunca misture estas dimensões:
+
+```txt
+Canais de entrada:
+- HTTP REST
+- WebSocket
+
+Domínios de negócio:
+- Clínicas
+- Serviços
+- Agendamentos
+
+Sistema de IA:
+- Agentes
+- Tools
+- LangGraph
+- LLM provider
+
+SaaS segregation:
+- JWT
+- tenant_id
+- autorização por escopo
+- isolamento por query, índice e constraint
+
+Continuidade operacional:
+- exceptions globais
+- erro normalizado
+- fallback sem derrubar conexão/processo
+- Redis cache/pub-sub
+
+Documentação de API:
+- OpenAPI v3
+- Swagger UI
+- Bearer JWT authorization
+- persistência local do token na interface Swagger
+```
+
+HTTP, WebSocket e LangGraph são adapters/orquestradores.
+
+Os domínios são a regra de negócio.
+
+`tenant_id` é o identificador obrigatório de segregação SaaS.
+
+JWT autentica o usuário e carrega o `tenant_id` canônico.
+
+Redis é infraestrutura compartilhada para cache, publish/subscribe e entrega resiliente de eventos.
+
+Swagger UI é adapter de documentação HTTP e deve autenticar via Bearer JWT sem conhecer regras de negócio.
+
+O sistema multiagente deve ser agnóstico a modelos e providers de LLM.
+
+---
+
+## Agnosticismo de modelos
+
+A skill não deve acoplar o projeto a um provider ou modelo específico.
+
+Regras:
+
+- Não hardcode `OpenAI`, `Anthropic`, `Gemini`, `Bedrock`, `Azure OpenAI` ou outro provider em `domain` ou `application`.
+- Não hardcode nome de modelo em use case, tool, node ou prompt.
+- Provider, modelo, temperatura, timeout e limites devem vir de configuração.
+- `application/agents` conhece apenas ports, DTOs e contratos.
+- Implementações concretas de LLM ficam em `infrastructure/ai/llm`.
+- LangGraph nodes recebem dependências abstratas ou factories injetadas.
+- Tools devem continuar chamando use cases, independentemente do modelo usado.
+- Prompts devem ser escritos de forma portável, sem instruções específicas de vendor salvo quando uma feature pedir explicitamente.
+- Testes devem usar fake LLM/model stub, não provider real.
+
+Crie um port de provider:
+
+```txt
+application/agents/ports/chat_model_port.py
+```
+
+Exemplo:
+
+```python
+from typing import Protocol
+
+
+class ChatModelPort(Protocol):
+    def invoke(self, messages: list[dict[str, str]]) -> str:
+        ...
+```
+
+Implementações possíveis:
+
+```txt
+infrastructure/ai/llm/langchain_chat_model_provider.py
+infrastructure/ai/llm/fake_chat_model_provider.py
+infrastructure/ai/llm/provider_factory.py
+```
+
+`provider_factory.py` escolhe o adapter por configuração, por exemplo:
+
+```txt
+LLM_PROVIDER=openai|anthropic|gemini|bedrock|azure|fake
+LLM_MODEL=<model-name>
+```
+
+O valor default para testes deve ser `fake`.
+
+---
+
+## Limites obrigatórios
+
+### Permitido
+
+```txt
+interfaces/http        -> application
+interfaces/websocket   -> application
+application            -> domain
+application            -> application ports
+infrastructure         -> application ports
+infrastructure/ai      -> application/agents ports
+infrastructure/ai/tools -> application use cases
+infrastructure/security -> application/security ports
+infrastructure/cache   -> application/shared ports
+infrastructure/events  -> application event publisher ports
+```
+
+### Proibido
+
+```txt
+domain -> flask
+domain -> sqlalchemy
+domain -> langchain
+domain -> langgraph
+domain -> websocket
+
+application -> flask
+application -> flask_sock
+application -> sqlalchemy models
+application -> langchain concrete classes
+application -> langgraph concrete classes
+application -> redis concrete client
+application -> jwt concrete library
+application -> provider concreto de LLM
+domain -> provider concreto de LLM
+
+interfaces -> repositories diretamente
+interfaces -> SQLAlchemy Session diretamente
+websocket controller -> banco diretamente
+LangGraph node -> banco diretamente
+LangGraph tool -> repository diretamente
+controller -> redis diretamente
+controller -> decodificação manual de JWT
+repository -> query sem tenant_id
+```
+
+## Python/Flask Clean Architecture boundary contract
+
+Use this matrix as a hard contract for generated or reviewed code:
+
+| Layer | Owns | Can depend on | Must not depend on |
+| --- | --- | --- | --- |
+| Domain | Entities, value objects, domain services, business invariants | Python standard library, domain modules | Flask, flask_sock, SQLAlchemy, Redis clients, JWT libraries, LangChain, LangGraph, provider SDKs |
+| Application | Use cases, orchestration, DTOs, ports, transaction boundaries | Domain, application DTOs, application ports | Flask request/response, SQLAlchemy models/session, Redis concrete client, JWT concrete verifier, LangChain/LangGraph concrete classes |
+| Interfaces (HTTP/WebSocket) | Transport adapters, schema validation, auth context extraction, response serialization | Application use cases and DTOs, interface schemas | ORM models, raw SQL, direct Redis usage, direct provider calls |
+| Infrastructure | Repositories, persistence models, cache/security/AI adapters, external integrations | Application ports, domain entities for mapping, concrete frameworks/libs | Reverse dependency into interface controllers/routes |
+
+Invariants that must hold:
+
+- Domain methods receive business data and enforce business rules; they do not parse transport payloads.
+- Application use cases orchestrate domain and ports; they do not import transport or persistence frameworks.
+- Flask controllers and WebSocket handlers only adapt inbound/outbound transport data.
+- Infrastructure adapters implement ports and can use frameworks, but never redefine business rules that belong to domain/application.
+
+Leakage example (do not do this):
+
+```python
+from flask import request
+from sqlalchemy.orm import Session
+
+
+class CreateAppointmentUseCase:
+    def __init__(self, db: Session):
+        self._db = db
+
+    def execute(self) -> None:
+        tenant_id = int(request.json["tenant_id"])
+        self._db.execute("INSERT INTO appointments ...")
+```
+
+Boundary-safe split (preferred):
+
+```python
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class CreateAppointmentInput:
+    tenant_id: int
+    clinic_id: int
+    service_id: int
+
+
+class AppointmentRepositoryPort(Protocol):
+    def create(self, input_data: CreateAppointmentInput) -> int:
+        ...
+
+
+class CreateAppointmentUseCase:
+    def __init__(self, repository: AppointmentRepositoryPort):
+        self._repository = repository
+
+    def execute(self, input_data: CreateAppointmentInput) -> int:
+        return self._repository.create(input_data)
+```
+
+---
+
+## OpenSDD decision-support mode (never runtime dependency)
+
+Use this mode when the target repository already has a `.sdd/` root and the team is using OpenSDD planning artifacts.
+
+The goal is to improve architecture decisions with explicit traceability, not to add OpenSDD runtime dependencies to generated Flask code.
+
+### Mandatory OpenSDD workflow for architecture decisions
+
+1. Run `opensdd sdd onboard system` before broad design work.
+2. Run `opensdd sdd next` and select active or ready work.
+3. Run `opensdd sdd context <FEAT-ID>` before drafting architecture changes.
+4. Keep `.sdd/active/<FEAT-ID>/5-quality.yaml` updated with decision evidence and risks.
+5. Declare interface impact with `opensdd sdd frontend-impact <FEAT-ID> ...` even when status is `none`.
+6. Run `opensdd sdd check --render` after updates; run `opensdd sdd diagnose` when structure drift is suspected.
+7. Consolidate with `opensdd sdd finalize --ref <FEAT-ID>` only after quality evidence is recorded.
+
+### How to use INS/DEB/EPIC/FEAT as decision layers
+
+- `INS`: register ambiguity, contradiction, or unknown constraints before implementation.
+- `DEB`: compare options and trade-offs with explicit risks and reversal conditions.
+- `EPIC`: define capability boundaries and non-goals.
+- `FEAT`: execute a bounded slice with concrete acceptance criteria and validation evidence.
+
+Do not collapse open questions directly into implementation steps.
+
+### Architecture decision prompts (required)
+
+Use these prompts and record answers in FEAT notes/quality evidence:
+
+| Decision area | Prompt | Minimum evidence artifact |
+| --- | --- | --- |
+| REST vs WebSocket | Is this interaction request/response, stream, or bidirectional session? | FEAT spec note + acceptance criteria |
+| Use case vs background task | Does business completion require synchronous response, or can it be deferred safely? | FEAT plan + risk note |
+| Pub/Sub vs Streams/outbox | Is at-least-once replay/idempotency required, or is fire-and-forget enough? | FEAT quality risk matrix |
+| Inferred intent vs confirmed action | Can the agent suggest only, or is explicit user confirmation required before side effects? | FEAT quality critical-flow evidence |
+| Model routing strategy | Which model/provider policy is needed by use case class, and where is fallback defined? | FEAT architecture decision note |
+| Checkpointer strategy | What state persistence and resume guarantees are required for orchestration? | FEAT plan + operational risk note |
+| Production exceptions | Which quality/security exceptions are allowed, approved, and time-bounded? | `5-quality.yaml` exception fields |
+
+### Runtime-boundary guardrails
+
+- OpenSDD files and commands are planning/governance tools only.
+- Generated Flask code must not import from `.sdd`, parse OpenSDD YAML, or shell out to `opensdd`.
+- Domain and application layers must stay independent of OpenSDD metadata and CLI semantics.
+- If a project does not use OpenSDD, keep the same architecture rules and capture decisions in equivalent project docs.
+
+### Quality-contract usage in this mode
+
+For each major architecture decision, update the active FEAT quality artifact with:
+
+- requirement being protected;
+- selected option and rejected options;
+- accepted risks and compensating controls;
+- command evidence (`check --render`, tests, build) and timestamped results.
+
+This keeps decision history auditable without leaking OpenSDD concerns into runtime code.
+
+---
+
+## Production-readiness guidance (safe and version-aware)
+
+Use this section to normalize production hardening without turning the skill into a promise of concrete package APIs that were not validated in the target environment.
+
+### Mandatory baseline versus optional advanced
+
+| Area | Mandatory baseline | Optional advanced |
+| --- | --- | --- |
+| Multi-agent orchestration | Clear boundary between intent inference and transactional actions; explicit tool-to-use-case wiring | Multi-agent specialization with orchestrator-level arbitration and escalation policies |
+| Multi-LLM execution | Provider/model selected by configuration; no hardcoded vendor/model names in domain/application | Dynamic routing by intent/cost/latency with explicit fallback policy |
+| Streaming and HITL | Streaming responses stay non-authoritative; mutating actions require explicit confirmation | Partial streaming checkpoints, supervisor queue, or delayed approval workflows |
+| Tenant/security authority | `tenant_id`, `user_id`, roles, and scopes come from validated principal only | Fine-grained policy engine, adaptive controls, and tenant-specific hardening |
+| Redis messaging | Pub/Sub for transient notifications; Streams/outbox for replay-critical events | Exactly-once approximation with dedupe and replay controls per tenant |
+| Resilience | Bounded retries, timeout budget, and deterministic fallback path | Circuit breaker, adaptive retry tiers, and workload-aware throttling |
+| Observability and health | Correlation IDs, structured logs, metrics/traces, and readiness/liveness endpoints | SLO-driven alerting, error budgets, and trace sampling controls |
+| Delivery operations | Reproducible container build and CI gates for lint/type/unit/integration/e2e | Progressive delivery, canary checks, and rollback automation |
+
+### Version-sensitive API policy (validated or conceptual)
+
+- Mark integration examples as one of: `VALIDATED` or `CONCEPTUAL`.
+- `VALIDATED` examples are allowed only when tested against the target environment/package versions.
+- `CONCEPTUAL` examples must avoid exact import paths that may drift between package versions.
+- Do not reference private/internal package modules for LangGraph, LangChain, observability, checkpointers, or provider SDKs.
+- Keep provider/model placeholders generic (`provider`, `model`) unless project-level validation proves a concrete choice.
+
+Minimal labeling pattern:
+
+```txt
+[VALIDATED] Uses package API confirmed in this repository/environment.
+[CONCEPTUAL] Illustrative flow only; verify imports/signatures before implementation.
+```
+
+### Redis Pub/Sub versus Streams and outbox
+
+- Use Redis Pub/Sub for ephemeral fan-out where message loss is acceptable.
+- Use Redis Streams (or equivalent durable queue) when replay, consumer groups, or delayed recovery is required.
+- Use domain events + outbox for transactional consistency when business side effects must survive process restarts.
+- Keep tenant boundaries explicit in channels, stream keys, and outbox records.
+
+### Resilience, idempotency, and checkpointing
+
+- Mutating operations must define idempotency keys and dedupe behavior.
+- Retries must be bounded and classify retryable versus non-retryable failures.
+- Fallback paths must preserve business safety and avoid hidden side effects.
+- Checkpointer strategy must define resume semantics, tenant partitioning, and stale-state cleanup policy.
+
+### Security hardening baseline
+
+- Enforce JWT expiry, issuer/audience validation, and key rotation readiness.
+- Define refresh/revocation strategy for long-lived sessions.
+- Apply CORS policy, rate limiting, and security headers at interface boundaries.
+- Never treat request body/query/WebSocket payload/LLM output as identity or tenant authority.
+
+### Typed settings, DI, and operational boundaries
+
+- Runtime settings are typed, validated at startup, and environment-specific.
+- Dependency injection composes adapters at startup; domain/application never read environment variables directly.
+- Background workers and async pipelines use the same use-case contracts and tenant security invariants.
+- Docker and CI/CD guidance remain infrastructure concerns, not domain/application code.
+
+---
+
+## JWT e segregação SaaS obrigatória
+
+Todo request HTTP e toda conexão ou mensagem WebSocket autenticada deve carregar um JWT válido.
+
+O JWT deve conter, no mínimo:
+
+```json
+{
+  "sub": "user_123",
+  "tenant_id": 42,
+  "roles": ["clinic_admin"],
+  "scopes": ["appointments:write"],
+  "iss": "api-clean-flask",
+  "aud": "api-clean-flask-client",
+  "iat": 1730000000,
+  "exp": 1730003600
+}
+```
+
+Regras:
+
+- `tenant_id` do JWT é a fonte canônica de segregação SaaS.
+- Nunca aceite `tenant_id` vindo do body como fonte de autoridade.
+- Payload pode repetir `tenant_id` apenas para validação defensiva; divergência deve gerar `AUTHORIZATION_ERROR`.
+- Toda query de entidade de negócio deve filtrar por `tenant_id`.
+- Todo repository deve exigir `tenant_id` como argumento explícito ou recebê-lo via DTO de application.
+- Todo índice de busca operacional deve começar por `tenant_id` quando a tabela for tenant-scoped.
+- Toda unique constraint de entidade tenant-scoped deve incluir `tenant_id`.
+- Rotas continuam escopadas por `clinic_id`, mas `clinic_id` nunca substitui `tenant_id`.
+- WebSocket deve validar JWT na abertura da conexão ou no primeiro evento de autenticação antes de processar mensagens de negócio.
+- Agent tools devem receber `tenant_id` no contexto e repassá-lo aos use cases.
+
+### Ports de segurança
+
+Crie ports em `application/security/ports`:
+
+```txt
+application/security/ports/token_verifier_port.py
+application/security/ports/permission_checker_port.py
+```
+
+`TokenVerifierPort` deve retornar um principal de aplicação, não claims brutas do framework:
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CurrentPrincipal:
+    user_id: str
+    tenant_id: int
+    roles: tuple[str, ...]
+    scopes: tuple[str, ...]
+```
+
+Implementação concreta fica em `infrastructure/security/jwt_token_verifier.py`.
+
+Controllers HTTP e WebSocket podem ler o principal do adapter de interface, mas só devem passar `tenant_id`, `user_id`, roles/scopes ou DTO equivalente para a camada `application`.
+
+---
+
+## OpenAPI v3 e Swagger UI obrigatórios
+
+A API HTTP deve publicar contrato OpenAPI v3 e documentação interativa com Swagger UI.
+
+Rotas obrigatórias:
+
+```txt
+GET /openapi.json
+GET /docs
+```
+
+Regras:
+
+- O documento deve seguir OpenAPI v3.
+- Todo endpoint REST público deve aparecer no OpenAPI.
+- Endpoints protegidos devem declarar security scheme `bearerAuth`.
+- Swagger UI deve exibir botão `Authorize` para Bearer JWT.
+- Swagger UI deve preservar o token autorizado durante reload da página com `persistAuthorization: true`.
+- Todo serviço/endereço HTTP exposto deve ter exemplos de uso no OpenAPI para facilitar testes diretos pela Swagger UI.
+- Exemplos devem incluir request body, path/query params, headers relevantes e response de sucesso.
+- Endpoints protegidos devem deixar claro no Swagger que exigem Bearer JWT.
+- O token pode ser salvo pelo Swagger UI em storage local do navegador, mas nunca deve ser registrado em log.
+- Em produção, `/docs` pode exigir autenticação, allowlist ou feature flag, conforme política do produto.
+- O contrato OpenAPI não deve importar domain/application; ele pertence a `interfaces/http`.
+- Schemas OpenAPI podem ser derivados dos schemas Pydantic de interface, mas não devem expor modelos ORM.
+
+Exemplo mínimo de security scheme:
+
+```json
+{
+  "openapi": "3.0.3",
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      }
+    }
+  },
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ]
+}
+```
+
+Exemplo conceitual de Swagger UI:
+
+```python
+SWAGGER_UI_CONFIG = {
+    "url": "/openapi.json",
+    "dom_id": "#swagger-ui",
+    "deepLinking": True,
+    "persistAuthorization": True,
+    "displayRequestDuration": True,
+}
+```
+
+Se gerar HTML manualmente, configure `SwaggerUIBundle` com `persistAuthorization: true`.
+
+Exemplo de template de uso por operação:
+
+```json
+{
+  "paths": {
+    "/api/v1/clinics/{clinic_id}/services": {
+      "post": {
+        "summary": "Create service",
+        "security": [{ "bearerAuth": [] }],
+        "parameters": [
+          {
+            "name": "clinic_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "integer" },
+            "example": 1
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/CreateServiceRequest" },
+              "examples": {
+                "default": {
+                  "summary": "Create a standard service",
+                  "value": {
+                    "name": "Consulta inicial",
+                    "description": "Primeira consulta da clínica",
+                    "duration_minutes": 45,
+                    "price_cents": 15000,
+                    "currency": "BRL"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Service created",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "created": {
+                    "value": {
+                      "id": 10,
+                      "clinic_id": 1,
+                      "name": "Consulta inicial",
+                      "duration_minutes": 45,
+                      "price_cents": 15000,
+                      "currency": "BRL",
+                      "status": "active"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Exceptions globais e continuidade de serviço
+
+A aplicação deve ter uma hierarquia única de exceptions de aplicação.
+
+Crie `src/shared/errors.py` com, no mínimo:
+
+```python
+class AppError(Exception):
+    code = "APP_ERROR"
+    status_code = 500
+    retryable = False
+
+    def __init__(self, message: str, *, details: list[dict] | None = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or []
+
+
+class ValidationAppError(AppError):
+    code = "VALIDATION_ERROR"
+    status_code = 400
+
+
+class AuthenticationAppError(AppError):
+    code = "AUTHENTICATION_ERROR"
+    status_code = 401
+
+
+class AuthorizationAppError(AppError):
+    code = "AUTHORIZATION_ERROR"
+    status_code = 403
+
+
+class ConflictAppError(AppError):
+    code = "CONFLICT_ERROR"
+    status_code = 409
+
+
+class ExternalDependencyAppError(AppError):
+    code = "EXTERNAL_DEPENDENCY_ERROR"
+    status_code = 503
+    retryable = True
+```
+
+Regras de continuidade:
+
+- REST deve converter toda exception conhecida em resposta JSON normalizada.
+- REST deve capturar exception desconhecida, registrar com `correlation_id`, retornar erro genérico e manter o processo vivo.
+- WebSocket deve capturar erro por mensagem, publicar evento `error.*` e continuar a conexão quando o erro for recuperável.
+- Erro fatal de autenticação WebSocket deve encerrar a conexão com evento de erro normalizado.
+- LangGraph node deve transformar falhas recuperáveis em estado de fallback, não em crash do grafo inteiro.
+- Redis indisponível deve degradar cache/pub-sub de forma controlada quando o fluxo principal puder continuar.
+- Falha de cache nunca pode impedir leitura/escrita transacional principal.
+- Falha de pub/sub deve ser registrada e retornar erro retryable apenas quando a entrega do evento for parte da consistência do caso de uso.
+
+---
+
+## Redis obrigatório para cache e publish/subscribe
+
+Redis deve ser acessado apenas por adapters em `infrastructure`.
+
+Crie ports:
+
+```txt
+application/shared/ports/cache_port.py
+application/shared/ports/pubsub_port.py
+```
+
+Contrato mínimo de cache:
+
+```python
+from typing import Protocol
+
+
+class CachePort(Protocol):
+    def get_json(self, key: str) -> dict | list | str | int | float | bool | None:
+        ...
+
+    def set_json(self, key: str, value: object, ttl_seconds: int) -> None:
+        ...
+
+    def delete(self, key: str) -> None:
+        ...
+```
+
+Contrato mínimo de pub/sub:
+
+```python
+from typing import Protocol
+
+
+class PubSubPort(Protocol):
+    def publish(self, channel: str, payload: dict) -> None:
+        ...
+
+    def subscribe(self, channel: str):
+        ...
+```
+
+Regras:
+
+- Cache keys devem incluir `tenant_id`.
+- Pub/sub channels devem incluir `tenant_id` quando carregarem evento tenant-scoped.
+- Eventos de agendamento devem ser publicados em canal por tenant e por clínica quando necessário.
+- WebSocket fan-out deve consumir eventos por canal e entregar para conexões registradas do mesmo tenant.
+- Não publique payload bruto sensível.
+- Não use Redis como fonte de verdade para entidades de negócio.
+- Use Redis para cache, locks distribuídos, presença/conexões WebSocket, pub/sub de notificações e checkpointer do LangGraph.
+- Use TTL explícito em todo cache.
+- Falhas Redis devem ser encapsuladas como `ExternalDependencyAppError` quando afetarem o fluxo principal.
+
+Exemplos de chaves e canais:
+
+```txt
+cache:tenant:{tenant_id}:clinic:{clinic_id}:services:active
+cache:tenant:{tenant_id}:appointment:{appointment_id}
+pubsub:tenant:{tenant_id}:clinic:{clinic_id}:appointments
+pubsub:tenant:{tenant_id}:ws:notifications
+lock:tenant:{tenant_id}:clinic:{clinic_id}:professional:{professional_id}:slot:{slot_start_at}
+```
+
+---
+
+## Árvore de diretórios obrigatória
+
+```txt
+api-clean-flask/
+├── README.md
+├── pyproject.toml
+├── .env.example
+├── Dockerfile
+├── docker-compose.yml
+├── alembic.ini
+├── migrations/
+│   ├── env.py
+│   └── versions/
+├── tests/
+│   ├── unit/
+│   │   ├── domain/
+│   │   ├── application/
+│   │   ├── security/
+│   │   ├── cache/
+│   │   └── agents/
+│   ├── integration/
+│   │   ├── http/
+│   │   ├── websocket/
+│   │   ├── persistence/
+│   │   ├── redis/
+│   │   └── security/
+│   └── e2e/
+│       ├── appointment_flow_test.py
+│       └── websocket_agent_flow_test.py
+│
+└── src/
+    ├── main.py
+    ├── container.py
+    │
+    ├── config/
+    │   ├── settings.py
+    │   ├── logging.py
+    │   └── dependency_injection.py
+    │
+    ├── interfaces/
+    │   ├── http/
+    │   │   ├── app_factory.py
+    │   │   ├── error_handlers.py
+    │   │   ├── openapi/
+    │   │   │   ├── openapi_factory.py
+    │   │   │   ├── swagger_ui.py
+    │   │   │   ├── security_schemes.py
+    │   │   │   └── examples/
+    │   │   │       ├── clinic_examples.py
+    │   │   │       ├── service_examples.py
+    │   │   │       ├── appointment_examples.py
+    │   │   │       └── agent_examples.py
+    │   │   ├── middlewares/
+    │   │   │   ├── correlation_middleware.py
+    │   │   │   └── auth_middleware.py
+    │   │   ├── routes/
+    │   │   │   ├── docs_routes.py
+    │   │   │   ├── health_routes.py
+    │   │   │   ├── clinic_routes.py
+    │   │   │   ├── service_routes.py
+    │   │   │   ├── appointment_routes.py
+    │   │   │   └── agent_routes.py
+    │   │   ├── controllers/
+    │   │   │   ├── health_controller.py
+    │   │   │   ├── clinic_http_controller.py
+    │   │   │   ├── service_http_controller.py
+    │   │   │   ├── appointment_http_controller.py
+    │   │   │   └── agent_http_controller.py
+    │   │   └── schemas/
+    │   │       ├── clinic_http_schema.py
+    │   │       ├── service_http_schema.py
+    │   │       ├── appointment_http_schema.py
+    │   │       ├── auth_http_schema.py
+    │   │       └── agent_http_schema.py
+    │   │
+    │   └── websocket/
+    │       ├── socket_factory.py
+    │       ├── websocket_event_dispatcher.py
+    │       ├── connection_registry.py
+    │       ├── websocket_auth.py
+    │       ├── websocket_error_boundary.py
+    │       ├── routes/
+    │       │   ├── chat_ws_routes.py
+    │       │   ├── appointment_ws_routes.py
+    │       │   └── notification_ws_routes.py
+    │       ├── controllers/
+    │       │   ├── chat_ws_controller.py
+    │       │   ├── appointment_ws_controller.py
+    │       │   └── notification_ws_controller.py
+    │       └── schemas/
+    │           ├── websocket_envelope_schema.py
+    │           ├── chat_ws_schema.py
+    │           └── appointment_ws_schema.py
+    │
+    ├── application/
+    │   ├── security/
+    │   │   ├── dto/
+    │   │   │   └── current_principal.py
+    │   │   ├── ports/
+    │   │   │   ├── token_verifier_port.py
+    │   │   │   └── permission_checker_port.py
+    │   │   └── use_cases/
+    │   │       └── verify_access_token_use_case.py
+    │   │
+    │   ├── shared/
+    │   │   ├── dto/
+    │   │   │   └── tenant_context.py
+    │   │   └── ports/
+    │   │       ├── cache_port.py
+    │   │       └── pubsub_port.py
+    │   │
+    │   ├── clinics/
+    │   │   ├── dto/
+    │   │   │   ├── create_clinic_input.py
+    │   │   │   ├── update_clinic_input.py
+    │   │   │   └── clinic_output.py
+    │   │   ├── ports/
+    │   │   │   ├── clinic_repository_port.py
+    │   │   │   └── clinic_reader_port.py
+    │   │   └── use_cases/
+    │   │       ├── create_clinic_use_case.py
+    │   │       ├── update_clinic_use_case.py
+    │   │       ├── get_clinic_use_case.py
+    │   │       ├── activate_clinic_use_case.py
+    │   │       └── deactivate_clinic_use_case.py
+    │   │
+    │   ├── services/
+    │   │   ├── dto/
+    │   │   │   ├── create_service_input.py
+    │   │   │   ├── update_service_input.py
+    │   │   │   └── service_output.py
+    │   │   ├── ports/
+    │   │   │   ├── service_repository_port.py
+    │   │   │   └── service_reader_port.py
+    │   │   └── use_cases/
+    │   │       ├── create_service_use_case.py
+    │   │       ├── update_service_use_case.py
+    │   │       ├── get_service_use_case.py
+    │   │       ├── list_services_by_clinic_use_case.py
+    │   │       ├── activate_service_use_case.py
+    │   │       └── deactivate_service_use_case.py
+    │   │
+    │   ├── appointments/
+    │   │   ├── dto/
+    │   │   │   ├── create_appointment_input.py
+    │   │   │   ├── reschedule_appointment_input.py
+    │   │   │   ├── appointment_output.py
+    │   │   │   └── available_slot_output.py
+    │   │   ├── ports/
+    │   │   │   ├── appointment_repository_port.py
+    │   │   │   ├── appointment_reader_port.py
+    │   │   │   ├── schedule_lock_port.py
+    │   │   │   └── appointment_event_publisher_port.py
+    │   │   └── use_cases/
+    │   │       ├── search_available_slots_use_case.py
+    │   │       ├── create_appointment_use_case.py
+    │   │       ├── confirm_appointment_use_case.py
+    │   │       ├── cancel_appointment_use_case.py
+    │   │       ├── reschedule_appointment_use_case.py
+    │   │       ├── complete_appointment_use_case.py
+    │   │       └── register_no_show_use_case.py
+    │   │
+    │   └── agents/
+    │       ├── dto/
+    │       │   ├── agent_input.py
+    │       │   ├── agent_output.py
+    │       │   ├── agent_context.py
+    │       │   └── agent_stream_event.py
+    │       ├── ports/
+    │       │   ├── agent_orchestrator_port.py
+    │       │   ├── agent_memory_port.py
+    │       │   ├── chat_model_port.py
+    │       │   └── agent_event_publisher_port.py
+    │       └── use_cases/
+    │           ├── process_agent_message_use_case.py
+    │           ├── continue_agent_conversation_use_case.py
+    │           └── stream_agent_response_use_case.py
+    │
+    ├── domain/
+    │   ├── clinics/
+    │   │   ├── entities/
+    │   │   │   └── clinic.py
+    │   │   ├── value_objects/
+    │   │   │   ├── clinic_id.py
+    │   │   │   ├── clinic_document.py
+    │   │   │   └── clinic_status.py
+    │   │   ├── services/
+    │   │   │   └── clinic_policy.py
+    │   │   └── exceptions.py
+    │   │
+    │   ├── services/
+    │   │   ├── entities/
+    │   │   │   └── service.py
+    │   │   ├── value_objects/
+    │   │   │   ├── service_id.py
+    │   │   │   ├── service_duration.py
+    │   │   │   ├── service_price.py
+    │   │   │   └── service_status.py
+    │   │   ├── services/
+    │   │   │   └── service_policy.py
+    │   │   └── exceptions.py
+    │   │
+    │   └── appointments/
+    │       ├── entities/
+    │       │   ├── appointment.py
+    │       │   └── appointment_slot.py
+    │       ├── value_objects/
+    │       │   ├── appointment_id.py
+    │       │   ├── appointment_status.py
+    │       │   ├── appointment_period.py
+    │       │   └── appointment_reason.py
+    │       ├── services/
+    │       │   ├── appointment_policy.py
+    │       │   └── appointment_conflict_checker.py
+    │       └── exceptions.py
+    │
+    ├── infrastructure/
+    │   ├── persistence/
+    │   │   ├── database.py
+    │   │   ├── base.py
+    │   │   ├── models/
+    │   │   │   ├── clinic_model.py
+    │   │   │   ├── service_model.py
+    │   │   │   ├── appointment_model.py
+    │   │   │   └── schedule_slot_lock_model.py
+    │   │   ├── repositories/
+    │   │   │   ├── sqlalchemy_clinic_repository.py
+    │   │   │   ├── sqlalchemy_service_repository.py
+    │   │   │   └── sqlalchemy_appointment_repository.py
+    │   │   └── unit_of_work/
+    │   │       └── sqlalchemy_unit_of_work.py
+    │   │
+    │   ├── websocket/
+    │   │   ├── websocket_connection_manager.py
+    │   │   └── websocket_event_publisher.py
+    │   │
+    │   ├── events/
+    │   │   ├── domain_event_bus.py
+    │   │   ├── event_publisher.py
+    │   │   ├── redis_pubsub.py
+    │   │   ├── redis_event_publisher.py
+    │   │   └── event_handlers/
+    │   │       ├── appointment_created_handler.py
+    │   │       ├── appointment_confirmed_handler.py
+    │   │       └── appointment_cancelled_handler.py
+    │   │
+    │   ├── ai/
+    │   │   ├── llm/
+    │   │   │   ├── chat_model_provider.py
+    │   │   │   ├── langchain_chat_model_provider.py
+    │   │   │   ├── fake_chat_model_provider.py
+    │   │   │   └── provider_factory.py
+    │   │   │
+    │   │   └── langgraph/
+    │   │       ├── graph_factory.py
+    │   │       ├── state.py
+    │   │       ├── checkpoints/
+    │   │       │   ├── checkpoint_factory.py
+    │   │       │   └── redis_checkpointer.py
+    │   │       ├── orchestrator/
+    │   │       │   └── langgraph_agent_orchestrator.py
+    │   │       ├── nodes/
+    │   │       │   ├── load_context_node.py
+    │   │       │   ├── guardrail_node.py
+    │   │       │   ├── router_node.py
+    │   │       │   ├── clinic_agent_node.py
+    │   │       │   ├── service_agent_node.py
+    │   │       │   ├── appointment_agent_node.py
+    │   │       │   ├── fallback_agent_node.py
+    │   │       │   ├── response_composer_node.py
+    │   │       │   └── publish_response_node.py
+    │   │       ├── tools/
+    │   │       │   ├── clinic_tools.py
+    │   │       │   ├── service_tools.py
+    │   │       │   └── appointment_tools.py
+    │   │       └── prompts/
+    │   │           ├── router_prompt.py
+    │   │           ├── clinic_agent_prompt.py
+    │   │           ├── service_agent_prompt.py
+    │   │           ├── appointment_agent_prompt.py
+    │   │           └── response_composer_prompt.py
+    │   │
+    │   ├── security/
+    │   │   ├── jwt_token_verifier.py
+    │   │   └── jwt_permission_checker.py
+    │   │
+    │   └── cache/
+    │       ├── redis_client.py
+    │       ├── redis_cache_adapter.py
+    │       ├── redis_session_store.py
+    │       └── redis_lock_adapter.py
+    │
+    └── shared/
+        ├── errors.py
+        ├── result.py
+        ├── clock.py
+        ├── correlation.py
+        ├── pagination.py
+        ├── id_generator.py
+        └── serialization.py
+```
+
+---
+
+## Convenção de IDs sequenciais
+
+Este projeto usa IDs sequenciais nas tabelas relacionais.
+
+Regras:
+
+1. Toda tabela de negócio deve ter `id` sequencial como chave primária.
+2. Use `BIGINT` como padrão para chaves primárias.
+3. Em SQLite de desenvolvimento, use variante `Integer` para preservar autoincremento compatível.
+4. Não use UUID como chave primária por padrão.
+5. Não gere IDs na aplicação para as entidades relacionais principais.
+6. O banco deve gerar o ID.
+7. Endpoints com ID sequencial devem ser sempre escopados por clínica, tenant ou permissão.
+8. Toda entity ORM de negócio deve ter `tenant_id` obrigatório, não nulo e indexado.
+9. `tenant_id` deve vir do JWT validado, nunca do body como fonte de autoridade.
+10. Nunca consulte `clinic_id`, `appointment_id`, `service_id`, `professional_id` ou qualquer ID sequencial isolado sem filtrar também por `tenant_id`.
+11. Queries por `clinic_id` continuam obrigatórias quando a rota for de clínica, mas `clinic_id` não substitui `tenant_id`.
+
+Exemplo de rotas preferidas:
+
+```txt
+GET /api/v1/clinics/{clinic_id}/services/{service_id}
+GET /api/v1/clinics/{clinic_id}/appointments/{appointment_id}
+PATCH /api/v1/clinics/{clinic_id}/appointments/{appointment_id}/cancel
+```
+
+Evite como padrão:
+
+```txt
+GET /api/v1/appointments/{appointment_id}
+```
+
+A exceção só é aceita se houver validação forte de autorização e escopo.
+
+---
+
+## Paginação obrigatória em listagens
+
+Todo endpoint ou use case de listagem deve aceitar paginação por query:
+
+```txt
+?limit=20&offset=0&search=consulta
+```
+
+Regras:
+
+- `limit` define o tamanho máximo da página.
+- `offset` define quantos registros devem ser pulados.
+- `search` é opcional; quando ausente, vazio ou só whitespace, não aplica filtro textual.
+- Quando `search` vier preenchido, aplique condição equivalente a `LIKE '%<search>%'` em todos os campos de texto pesquisáveis da listagem.
+- O filtro textual deve ser construído com bind parameters do SQLAlchemy; nunca interpole string manualmente em SQL.
+- Escape `%`, `_` e caractere de escape quando o comportamento esperado for busca literal.
+- Para PostgreSQL, `ilike` pode ser usado para busca case-insensitive.
+- Para MySQL, valide collation; se a collation já for case-insensitive, `like` pode ser suficiente.
+- Use `offset`, não `office`.
+- Defina limite padrão seguro, por exemplo `limit=20`.
+- Defina limite máximo, por exemplo `limit<=100`.
+- `count` deve representar o total de registros que satisfazem o filtro, sem aplicar `limit/offset`.
+- `pages` deve ser calculado como `ceil(count / limit)`.
+- `data` deve conter apenas os itens da página atual.
+- Toda query paginada deve manter filtro por `tenant_id`.
+- Toda query com `search` deve manter filtro por `tenant_id`.
+- Ordenação padrão deve ser determinística, por exemplo `created_at desc, id desc`.
+
+Envelope obrigatório de resposta:
+
+```json
+{
+  "pages": 5,
+  "count": 95,
+  "limit": 20,
+  "offset": 0,
+  "data": []
+}
+```
+
+Exemplo de campos textuais pesquisáveis:
+
+```txt
+clinics: name, document, status
+services: name, description, currency, status
+appointments: status, cancellation_reason
+```
+
+Crie helper tipado em `src/shared/pagination.py`:
+
+```python
+from dataclasses import dataclass
+from math import ceil
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    pages: int
+    count: int
+    limit: int
+    offset: int
+    data: list[T]
+
+    @classmethod
+    def create(cls, *, count: int, limit: int, offset: int, data: list[T]) -> "Page[T]":
+        pages = ceil(count / limit) if limit > 0 else 0
+        return cls(pages=pages, count=count, limit=limit, offset=offset, data=data)
+```
+
+Regra para repositories:
+
+```txt
+Correto:
+- find_by_id(tenant_id, clinic_id, service_id)
+- list_by_clinic(tenant_id, clinic_id)
+- exists_conflict(tenant_id, clinic_id, professional_id, period)
+
+Proibido:
+- find_by_id(service_id)
+- list_by_clinic(clinic_id) sem tenant_id
+- exists_conflict(professional_id, period) sem tenant_id e clinic_id
+```
+
+---
+
+## Base ORM obrigatória
+
+Crie `src/infrastructure/persistence/base.py`:
+
+```python
+from datetime import UTC, datetime
+
+from sqlalchemy import BigInteger, DateTime, Integer, MetaData, func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy.schema import Identity
+
+NAMING_CONVENTION = {
+    "ix": "ix_%(table_name)s_%(column_0_name)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+# SQLite exige INTEGER PRIMARY KEY para o comportamento de autoincremento mais previsível.
+ID_TYPE = BigInteger().with_variant(Integer, "sqlite")
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+
+
+class SequentialIdMixin:
+    id: Mapped[int] = mapped_column(
+        ID_TYPE,
+        Identity(always=False),
+        primary_key=True,
+    )
+
+
+class TenantScopedMixin:
+    tenant_id: Mapped[int] = mapped_column(
+        ID_TYPE,
+        nullable=False,
+        index=True,
+    )
+
+
+class AuditMixin:
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+    deleted_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+        nullable=True,
+    )
+
+    def mark_deleted(self) -> None:
+        self.deleted_at = datetime.now(UTC)
+```
+
+Regras:
+
+- Todo modelo ORM de negócio deve herdar `TenantScopedMixin`.
+- Todo modelo ORM de negócio deve herdar `AuditMixin`.
+- `created_at` deve ser preenchido automaticamente na criação pelo banco.
+- `updated_at` deve ser preenchido automaticamente na criação e atualizado automaticamente a cada update.
+- `deleted_at` deve representar soft delete; não remova fisicamente registros de negócio por padrão.
+- Soft delete deve alterar `deleted_at` e fazer a operação passar pelo Unit of Work para atualizar `updated_at`.
+- `tenant_id` deve ser preenchido pela camada `application` a partir do principal JWT validado.
+- `tenant_id` não deve ser opcional, nullable ou calculado pelo banco.
+- Índices compostos de leitura devem começar com `tenant_id`.
+- Constraints únicas tenant-scoped devem incluir `tenant_id`.
+- Soft delete não remove a obrigação de filtrar por `tenant_id`.
+
+---
+
+## Database engine e session factory
+
+Crie `src/infrastructure/persistence/database.py`:
+
+```python
+from collections.abc import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+
+class Database:
+    def __init__(self, database_url: str, echo: bool = False):
+        self.engine: Engine = create_engine(
+            database_url,
+            echo=echo,
+            pool_pre_ping=True,
+            future=True,
+        )
+        self.session_factory = sessionmaker(
+            bind=self.engine,
+            autoflush=False,
+            autocommit=False,
+            expire_on_commit=False,
+            class_=Session,
+        )
+
+    def session(self) -> Generator[Session, None, None]:
+        db_session = self.session_factory()
+        try:
+            yield db_session
+        finally:
+            db_session.close()
+```
+
+Regras:
+
+- Nunca injete `Session` diretamente em controller.
+- Nunca armazene `Session` em conexão WebSocket.
+- Nunca faça `commit()` dentro de repository.
+- Use Unit of Work para controlar transação.
+- Para WebSocket, abra uma Unit of Work por mensagem processada, não por conexão.
+
+---
+
+## Bancos relacionais suportados
+
+A skill deve gerar código compatível com:
+
+- PostgreSQL
+- MySQL
+- SQLite apenas para desenvolvimento local leve ou testes rápidos
+
+Regras:
+
+- `DATABASE_URL` deve aceitar pelo menos:
+  - `postgresql+psycopg://user:pass@host:5432/dbname`
+  - `mysql+pymysql://user:pass@host:3306/dbname`
+  - `sqlite:///local.db`
+- Models devem evitar tipos e constraints que funcionem apenas em um dialeto, salvo migration manual explícita.
+- `DateTime(timezone=True)` deve ser normalizado na aplicação quando o dialeto não preservar timezone nativamente.
+- Tamanho de índices compostos deve considerar limites de MySQL.
+- Constraints de status podem usar `CheckConstraint`, mas migrations devem validar suporte real no MySQL alvo.
+- Testes de repository e Unit of Work devem rodar contra SQLite rápido e devem ter perfil de integração para PostgreSQL e MySQL.
+- Em produção, prefira PostgreSQL quando houver conflito entre recursos avançados de banco.
+- Diferenças de dialeto devem ficar em migrations ou adapters de infrastructure, nunca em domain/application.
+
+---
+
+## Modelos ORM mínimos
+
+### ClinicModel
+
+`src/infrastructure/persistence/models/clinic_model.py`:
+
+```python
+from sqlalchemy import CheckConstraint, Index, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.infrastructure.persistence.base import AuditMixin, Base, SequentialIdMixin, TenantScopedMixin
+
+
+class ClinicModel(Base, SequentialIdMixin, TenantScopedMixin, AuditMixin):
+    __tablename__ = "clinics"
+
+    name: Mapped[str] = mapped_column(String(180), nullable=False)
+    document: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="active")
+
+    services = relationship(
+        "ServiceModel",
+        back_populates="clinic",
+        lazy="selectin",
+    )
+
+    appointments = relationship(
+        "AppointmentModel",
+        back_populates="clinic",
+        lazy="selectin",
+    )
+
+    __table_args__ = (
+        CheckConstraint(
+            "status in ('active', 'inactive', 'suspended')",
+            name="clinic_status_valid",
+        ),
+        UniqueConstraint("tenant_id", "document", name="uq_clinics_tenant_document"),
+        Index("ix_clinics_tenant_id", "tenant_id"),
+        Index("ix_clinics_tenant_status", "tenant_id", "status"),
+        Index("ix_clinics_tenant_document", "tenant_id", "document"),
+    )
+```
+
+### ServiceModel
+
+`src/infrastructure/persistence/models/service_model.py`:
+
+```python
+from sqlalchemy import CheckConstraint, ForeignKey, Index, Integer, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.infrastructure.persistence.base import AuditMixin, Base, ID_TYPE, SequentialIdMixin, TenantScopedMixin
+
+
+class ServiceModel(Base, SequentialIdMixin, TenantScopedMixin, AuditMixin):
+    __tablename__ = "services"
+
+    clinic_id: Mapped[int] = mapped_column(
+        ID_TYPE,
+        ForeignKey("clinics.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    name: Mapped[str] = mapped_column(String(180), nullable=False)
+    description: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    duration_minutes: Mapped[int] = mapped_column(Integer, nullable=False)
+    price_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    currency: Mapped[str] = mapped_column(String(3), nullable=False, default="BRL")
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="active")
+
+    clinic = relationship("ClinicModel", back_populates="services", lazy="joined")
+    appointments = relationship("AppointmentModel", back_populates="service", lazy="selectin")
+
+    __table_args__ = (
+        CheckConstraint("duration_minutes > 0", name="service_duration_positive"),
+        CheckConstraint("price_cents >= 0", name="service_price_non_negative"),
+        CheckConstraint(
+            "status in ('active', 'inactive', 'archived')",
+            name="service_status_valid",
+        ),
+        UniqueConstraint("tenant_id", "clinic_id", "name", name="uq_services_tenant_clinic_name"),
+        Index("ix_services_tenant_clinic", "tenant_id", "clinic_id"),
+        Index("ix_services_tenant_clinic_status", "tenant_id", "clinic_id", "status"),
+    )
+```
+
+### AppointmentModel
+
+`src/infrastructure/persistence/models/appointment_model.py`:
+
+```python
+from datetime import datetime
+
+from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.infrastructure.persistence.base import AuditMixin, Base, ID_TYPE, SequentialIdMixin, TenantScopedMixin
+
+
+class AppointmentModel(Base, SequentialIdMixin, TenantScopedMixin, AuditMixin):
+    __tablename__ = "appointments"
+
+    clinic_id: Mapped[int] = mapped_column(
+        ID_TYPE,
+        ForeignKey("clinics.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    service_id: Mapped[int] = mapped_column(
+        ID_TYPE,
+        ForeignKey("services.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    customer_id: Mapped[int] = mapped_column(ID_TYPE, nullable=False)
+    professional_id: Mapped[int] = mapped_column(ID_TYPE, nullable=False)
+
+    start_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    end_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="reserved")
+    cancellation_reason: Mapped[str | None] = mapped_column(String(500), nullable=True)
+
+    clinic = relationship("ClinicModel", back_populates="appointments", lazy="joined")
+    service = relationship("ServiceModel", back_populates="appointments", lazy="joined")
+    slot_locks = relationship(
+        "ScheduleSlotLockModel",
+        back_populates="appointment",
+        lazy="selectin",
+    )
+
+    __table_args__ = (
+        CheckConstraint("end_at > start_at", name="appointment_period_valid"),
+        CheckConstraint(
+            "status in ('requested', 'reserved', 'confirmed', 'rescheduled', 'cancelled', 'completed', 'no_show', 'expired')",
+            name="appointment_status_valid",
+        ),
+        Index("ix_appointments_tenant_clinic", "tenant_id", "clinic_id"),
+        Index("ix_appointments_tenant_service", "tenant_id", "service_id"),
+        Index("ix_appointments_tenant_customer", "tenant_id", "customer_id"),
+        Index(
+            "ix_appointments_tenant_professional_period",
+            "tenant_id",
+            "professional_id",
+            "start_at",
+            "end_at",
+        ),
+        Index("ix_appointments_tenant_clinic_status", "tenant_id", "clinic_id", "status"),
+    )
+```
+
+### ScheduleSlotLockModel
+
+Use uma tabela de locks por slot discreto para evitar conflito de agendamento de forma portável entre bancos relacionais.
+
+`src/infrastructure/persistence/models/schedule_slot_lock_model.py`:
+
+```python
+from datetime import datetime
+
+from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.infrastructure.persistence.base import AuditMixin, Base, ID_TYPE, SequentialIdMixin, TenantScopedMixin
+
+
+class ScheduleSlotLockModel(Base, SequentialIdMixin, TenantScopedMixin, AuditMixin):
+    __tablename__ = "schedule_slot_locks"
+
+    clinic_id: Mapped[int] = mapped_column(
+        ID_TYPE,
+        ForeignKey("clinics.id", ondelete="RESTRICT"),
+        nullable=False,
+    )
+    professional_id: Mapped[int] = mapped_column(ID_TYPE, nullable=False)
+    appointment_id: Mapped[int | None] = mapped_column(
+        ID_TYPE,
+        ForeignKey("appointments.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    slot_start_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    status: Mapped[str] = mapped_column(String(32), nullable=False, default="locked")
+
+    appointment = relationship("AppointmentModel", back_populates="slot_locks", lazy="joined")
+
+    __table_args__ = (
+        UniqueConstraint(
+            "tenant_id",
+            "clinic_id",
+            "professional_id",
+            "slot_start_at",
+            name="uq_schedule_slot_locks_tenant_resource_slot",
+        ),
+        CheckConstraint(
+            "status in ('locked', 'confirmed', 'released', 'expired')",
+            name="schedule_slot_lock_status_valid",
+        ),
+        Index(
+            "ix_schedule_slot_locks_tenant_clinic_professional",
+            "tenant_id",
+            "clinic_id",
+            "professional_id",
+        ),
+        Index("ix_schedule_slot_locks_tenant_expires_at", "tenant_id", "expires_at"),
+        Index("ix_schedule_slot_locks_tenant_appointment", "tenant_id", "appointment_id"),
+    )
+```
+
+Regra de negócio para locks:
+
+- Converta o período do agendamento em slots discretos, por exemplo, de 15 em 15 minutos.
+- Insira uma linha em `schedule_slot_locks` para cada slot.
+- Cada lock deve carregar o mesmo `tenant_id` do agendamento.
+- A constraint única por `tenant_id`, `clinic_id`, `professional_id` e `slot_start_at` impede dois agendamentos para o mesmo profissional no mesmo slot dentro do tenant.
+- A operação deve ocorrer em transação.
+- Se qualquer insert falhar por violação da constraint única, reverta a transação e retorne conflito de agenda.
+- Se Redis lock distribuído for usado antes da transação, ele é otimização de concorrência, não substitui a constraint relacional.
+
+---
+
+## Unit of Work obrigatório
+
+`src/infrastructure/persistence/unit_of_work/sqlalchemy_unit_of_work.py`:
+
+```python
+from types import TracebackType
+from typing import Self
+
+from sqlalchemy.orm import Session, sessionmaker
+
+from src.infrastructure.persistence.repositories.sqlalchemy_appointment_repository import (
+    SqlAlchemyAppointmentRepository,
+)
+from src.infrastructure.persistence.repositories.sqlalchemy_clinic_repository import (
+    SqlAlchemyClinicRepository,
+)
+from src.infrastructure.persistence.repositories.sqlalchemy_service_repository import (
+    SqlAlchemyServiceRepository,
+)
+
+
+class SqlAlchemyUnitOfWork:
+    def __init__(self, session_factory: sessionmaker[Session]):
+        self._session_factory = session_factory
+        self.session: Session | None = None
+
+    def __enter__(self) -> Self:
+        self.session = self._session_factory()
+        self.clinics = SqlAlchemyClinicRepository(self.session)
+        self.services = SqlAlchemyServiceRepository(self.session)
+        self.appointments = SqlAlchemyAppointmentRepository(self.session)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        if self.session is None:
+            return
+
+        if exc_type is not None:
+            self.rollback()
+
+        self.session.close()
+
+    def commit(self) -> None:
+        if self.session is None:
+            raise RuntimeError("UnitOfWork session was not initialized")
+        self.session.commit()
+
+    def rollback(self) -> None:
+        if self.session is None:
+            raise RuntimeError("UnitOfWork session was not initialized")
+        self.session.rollback()
+```
+
+Regras:
+
+- Use case abre Unit of Work.
+- Use case decide quando commitar.
+- Repository nunca commita.
+- Repository pode usar `flush()` quando precisa obter `id` antes do commit.
+- Erro de banco deve ser convertido em erro de aplicação na camada de infrastructure ou application.
+
+---
+
+## App Factory Flask
+
+`src/interfaces/http/app_factory.py`:
+
+```python
+from flask import Flask
+from flask_sock import Sock
+
+from src.config.settings import Settings
+from src.container import build_container
+from src.interfaces.http.error_handlers import register_error_handlers
+from src.interfaces.http.routes.agent_routes import agent_bp
+from src.interfaces.http.routes.appointment_routes import appointment_bp
+from src.interfaces.http.routes.clinic_routes import clinic_bp
+from src.interfaces.http.routes.health_routes import health_bp
+from src.interfaces.http.routes.service_routes import service_bp
+from src.interfaces.websocket.routes.chat_ws_routes import register_chat_ws_routes
+
+
+def create_app(settings: Settings | None = None) -> Flask:
+    app = Flask(__name__)
+    settings = settings or Settings.from_env()
+    container = build_container(settings)
+
+    app.config["SETTINGS"] = settings
+    app.extensions["container"] = container
+
+    app.register_blueprint(health_bp, url_prefix="/health")
+    app.register_blueprint(clinic_bp, url_prefix="/api/v1/clinics")
+    app.register_blueprint(service_bp, url_prefix="/api/v1/clinics")
+    app.register_blueprint(appointment_bp, url_prefix="/api/v1/clinics")
+    app.register_blueprint(agent_bp, url_prefix="/api/v1/agents")
+
+    register_error_handlers(app)
+
+    sock = Sock()
+    sock.init_app(app)
+    register_chat_ws_routes(sock, app)
+
+    return app
+```
+
+`src/main.py`:
+
+```python
+from src.interfaces.http.app_factory import create_app
+
+app = create_app()
+```
+
+---
+
+## Rotas REST
+
+As rotas devem ser finas.
+
+Exemplo: `src/interfaces/http/routes/appointment_routes.py`:
+
+```python
+from flask import Blueprint, current_app, request
+
+from src.interfaces.http.controllers.appointment_http_controller import (
+    AppointmentHttpController,
+)
+
+appointment_bp = Blueprint("appointments", __name__)
+
+
+@appointment_bp.post("/<int:clinic_id>/appointments")
+def create_appointment(clinic_id: int):
+    container = current_app.extensions["container"]
+    controller: AppointmentHttpController = container.appointment_http_controller()
+    return controller.create(clinic_id=clinic_id, payload=request.get_json(silent=False))
+
+
+@appointment_bp.patch("/<int:clinic_id>/appointments/<int:appointment_id>/cancel")
+def cancel_appointment(clinic_id: int, appointment_id: int):
+    container = current_app.extensions["container"]
+    controller: AppointmentHttpController = container.appointment_http_controller()
+    return controller.cancel(
+        clinic_id=clinic_id,
+        appointment_id=appointment_id,
+        payload=request.get_json(silent=True) or {},
+    )
+```
+
+Controller REST:
+
+```python
+from flask import jsonify
+
+from src.application.appointments.dto.create_appointment_input import (
+    CreateAppointmentInput,
+)
+from src.interfaces.http.schemas.appointment_http_schema import (
+    CreateAppointmentRequest,
+)
+
+
+class AppointmentHttpController:
+    def __init__(self, create_appointment_use_case, cancel_appointment_use_case):
+        self._create_appointment_use_case = create_appointment_use_case
+        self._cancel_appointment_use_case = cancel_appointment_use_case
+
+    def create(self, clinic_id: int, payload: dict):
+        request_data = CreateAppointmentRequest.model_validate(payload)
+
+        result = self._create_appointment_use_case.execute(
+            CreateAppointmentInput(
+                clinic_id=clinic_id,
+                service_id=request_data.service_id,
+                customer_id=request_data.customer_id,
+                professional_id=request_data.professional_id,
+                start_at=request_data.start_at,
+            )
+        )
+
+        return jsonify(result.model_dump(mode="json")), 201
+
+    def cancel(self, clinic_id: int, appointment_id: int, payload: dict):
+        result = self._cancel_appointment_use_case.execute(
+            clinic_id=clinic_id,
+            appointment_id=appointment_id,
+            reason=payload.get("reason"),
+        )
+        return jsonify(result.model_dump(mode="json")), 200
+```
+
+---
+
+## WebSocket
+
+O WebSocket deve receber eventos, validar envelope e chamar use case.
+
+Não deve acessar banco.
+
+Não deve chamar LangGraph diretamente.
+
+### Envelope padrão
+
+```json
+{
+  "type": "chat.message",
+  "correlation_id": "corr_123",
+  "payload": {
+    "clinic_id": 1,
+    "user_id": 10,
+    "message": "Quero marcar uma consulta amanhã de manhã"
+  }
+}
+```
+
+### Schema
+
+`src/interfaces/websocket/schemas/websocket_envelope_schema.py`:
+
+```python
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class WebSocketEnvelopeSchema(BaseModel):
+    type: str = Field(min_length=1)
+    correlation_id: str = Field(min_length=1)
+    payload: dict[str, Any]
+```
+
+### Controller
+
+`src/interfaces/websocket/controllers/chat_ws_controller.py`:
+
+```python
+from src.application.agents.dto.agent_input import AgentInput
+from src.interfaces.websocket.schemas.websocket_envelope_schema import (
+    WebSocketEnvelopeSchema,
+)
+
+
+class ChatWebSocketController:
+    def __init__(self, connection_registry, process_agent_message_use_case):
+        self._connection_registry = connection_registry
+        self._process_agent_message_use_case = process_agent_message_use_case
+
+    def handle(self, ws) -> None:
+        connection_id = self._connection_registry.register(ws)
+
+        try:
+            while True:
+                raw_message = ws.receive()
+
+                if raw_message is None:
+                    break
+
+                event = WebSocketEnvelopeSchema.model_validate_json(raw_message)
+
+                if event.type != "chat.message":
+                    self._connection_registry.send_json(
+                        connection_id,
+                        {
+                            "type": "error.unsupported_event",
+                            "correlation_id": event.correlation_id,
+                            "payload": {"message": f"Unsupported event type: {event.type}"},
+                        },
+                    )
+                    continue
+
+                self._process_agent_message_use_case.execute(
+                    AgentInput(
+                        correlation_id=event.correlation_id,
+                        tenant_id=self._connection_registry.get_principal(connection_id).tenant_id,
+                        clinic_id=int(event.payload["clinic_id"]),
+                        user_id=int(event.payload["user_id"]),
+                        channel="websocket",
+                        connection_id=connection_id,
+                        message=str(event.payload["message"]),
+                    )
+                )
+        finally:
+            self._connection_registry.unregister(connection_id)
+```
+
+### Route
+
+`src/interfaces/websocket/routes/chat_ws_routes.py`:
+
+```python
+from flask import Flask
+from flask_sock import Sock
+
+
+def register_chat_ws_routes(sock: Sock, app: Flask) -> None:
+    @sock.route("/ws/chat")
+    def chat(ws):
+        container = app.extensions["container"]
+        controller = container.chat_ws_controller()
+        controller.handle(ws)
+```
+
+---
+
+## Application Agents
+
+### DTO
+
+`src/application/agents/dto/agent_input.py`:
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class AgentInput:
+    correlation_id: str
+    tenant_id: int
+    clinic_id: int
+    user_id: int
+    channel: Literal["websocket", "rest"]
+    message: str
+    connection_id: str | None = None
+```
+
+`src/application/agents/dto/agent_output.py`:
+
+```python
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AgentOutput:
+    correlation_id: str
+    message: str
+    intent: str | None
+    requires_user_input: bool = False
+
+    def to_dict(self) -> dict:
+        return {
+            "correlation_id": self.correlation_id,
+            "message": self.message,
+            "intent": self.intent,
+            "requires_user_input": self.requires_user_input,
+        }
+```
+
+### Port
+
+`src/application/agents/ports/agent_orchestrator_port.py`:
+
+```python
+from abc import ABC, abstractmethod
+
+from src.application.agents.dto.agent_input import AgentInput
+from src.application.agents.dto.agent_output import AgentOutput
+
+
+class AgentOrchestratorPort(ABC):
+    @abstractmethod
+    def process(self, input_data: AgentInput) -> AgentOutput:
+        raise NotImplementedError
+```
+
+### Use case
+
+`src/application/agents/use_cases/process_agent_message_use_case.py`:
+
+```python
+from src.application.agents.dto.agent_input import AgentInput
+
+
+class ProcessAgentMessageUseCase:
+    def __init__(self, agent_orchestrator, agent_event_publisher):
+        self._agent_orchestrator = agent_orchestrator
+        self._agent_event_publisher = agent_event_publisher
+
+    def execute(self, input_data: AgentInput):
+        result = self._agent_orchestrator.process(input_data)
+
+        if input_data.channel == "websocket" and input_data.connection_id:
+            self._agent_event_publisher.publish(
+                connection_id=input_data.connection_id,
+                event_type="chat.response",
+                correlation_id=input_data.correlation_id,
+                payload=result.to_dict(),
+            )
+
+        return result
+```
+
+---
+
+## LangGraph
+
+LangGraph fica em infrastructure.
+
+A camada application só conhece `AgentOrchestratorPort`.
+
+### State
+
+`src/infrastructure/ai/langgraph/state.py`:
+
+```python
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+class AgentGraphState(TypedDict):
+    correlation_id: str
+    tenant_id: int
+    clinic_id: int
+    user_id: int
+    channel: Literal["websocket", "rest"]
+    user_message: str
+    connection_id: NotRequired[str | None]
+
+    normalized_intent: NotRequired[str]
+    selected_service_id: NotRequired[int | None]
+    selected_professional_id: NotRequired[int | None]
+    selected_appointment_id: NotRequired[int | None]
+
+    application_context: NotRequired[dict[str, Any]]
+    tool_results: NotRequired[list[dict[str, Any]]]
+    final_response: NotRequired[str]
+    requires_user_input: NotRequired[bool]
+```
+
+### Orchestrator Adapter
+
+`src/infrastructure/ai/langgraph/orchestrator/langgraph_agent_orchestrator.py`:
+
+```python
+from src.application.agents.dto.agent_input import AgentInput
+from src.application.agents.dto.agent_output import AgentOutput
+from src.application.agents.ports.agent_orchestrator_port import AgentOrchestratorPort
+
+
+class LangGraphAgentOrchestrator(AgentOrchestratorPort):
+    def __init__(self, graph):
+        self._graph = graph
+
+    def process(self, input_data: AgentInput) -> AgentOutput:
+        state = {
+            "correlation_id": input_data.correlation_id,
+            "tenant_id": input_data.tenant_id,
+            "clinic_id": input_data.clinic_id,
+            "user_id": input_data.user_id,
+            "channel": input_data.channel,
+            "connection_id": input_data.connection_id,
+            "user_message": input_data.message,
+        }
+
+        result = self._graph.invoke(
+            state,
+            config={
+                "configurable": {
+                    "thread_id": (
+                        f"tenant:{input_data.tenant_id}:"
+                        f"clinic:{input_data.clinic_id}:"
+                        f"user:{input_data.user_id}"
+                    ),
+                }
+            },
+        )
+
+        return AgentOutput(
+            correlation_id=input_data.correlation_id,
+            message=result.get("final_response", "Não consegui processar a solicitação."),
+            intent=result.get("normalized_intent"),
+            requires_user_input=result.get("requires_user_input", False),
+        )
+```
+
+### Graph Factory
+
+`src/infrastructure/ai/langgraph/graph_factory.py`:
+
+```python
+from langgraph.graph import END, START, StateGraph
+
+from src.infrastructure.ai.langgraph.nodes.appointment_agent_node import appointment_agent_node
+from src.infrastructure.ai.langgraph.nodes.clinic_agent_node import clinic_agent_node
+from src.infrastructure.ai.langgraph.nodes.fallback_agent_node import fallback_agent_node
+from src.infrastructure.ai.langgraph.nodes.guardrail_node import guardrail_node
+from src.infrastructure.ai.langgraph.nodes.load_context_node import load_context_node
+from src.infrastructure.ai.langgraph.nodes.response_composer_node import response_composer_node
+from src.infrastructure.ai.langgraph.nodes.router_node import router_node
+from src.infrastructure.ai.langgraph.nodes.service_agent_node import service_agent_node
+from src.infrastructure.ai.langgraph.state import AgentGraphState
+
+
+def route_by_intent(state: AgentGraphState) -> str:
+    intent = state.get("normalized_intent")
+
+    if intent in {"clinic_info", "clinic_status"}:
+        return "clinic_agent"
+
+    if intent in {"service_catalog", "service_detail"}:
+        return "service_agent"
+
+    if intent in {
+        "appointment_create",
+        "appointment_reschedule",
+        "appointment_cancel",
+        "appointment_status",
+    }:
+        return "appointment_agent"
+
+    return "fallback_agent"
+
+
+def build_agent_graph(checkpointer=None):
+    graph = StateGraph(AgentGraphState)
+
+    graph.add_node("load_context", load_context_node)
+    graph.add_node("guardrail", guardrail_node)
+    graph.add_node("router", router_node)
+    graph.add_node("clinic_agent", clinic_agent_node)
+    graph.add_node("service_agent", service_agent_node)
+    graph.add_node("appointment_agent", appointment_agent_node)
+    graph.add_node("fallback_agent", fallback_agent_node)
+    graph.add_node("response_composer", response_composer_node)
+
+    graph.add_edge(START, "load_context")
+    graph.add_edge("load_context", "guardrail")
+    graph.add_edge("guardrail", "router")
+
+    graph.add_conditional_edges(
+        "router",
+        route_by_intent,
+        {
+            "clinic_agent": "clinic_agent",
+            "service_agent": "service_agent",
+            "appointment_agent": "appointment_agent",
+            "fallback_agent": "fallback_agent",
+        },
+    )
+
+    graph.add_edge("clinic_agent", "response_composer")
+    graph.add_edge("service_agent", "response_composer")
+    graph.add_edge("appointment_agent", "response_composer")
+    graph.add_edge("fallback_agent", "response_composer")
+    graph.add_edge("response_composer", END)
+
+    return graph.compile(checkpointer=checkpointer)
+```
+
+---
+
+## Tools dos agentes
+
+Tools devem chamar use cases.
+
+Não chame repository diretamente.
+
+### Service tools
+
+`src/infrastructure/ai/langgraph/tools/service_tools.py`:
+
+```python
+from langchain.tools import tool
+
+
+def build_service_tools(list_services_by_clinic_use_case):
+    @tool("list_services_by_clinic")
+    def list_services_by_clinic(
+        clinic_id: int,
+        limit: int = 20,
+        offset: int = 0,
+        search: str | None = None,
+    ) -> dict:
+        """List active services available for a clinic."""
+        result = list_services_by_clinic_use_case.execute(
+            clinic_id=clinic_id,
+            limit=limit,
+            offset=offset,
+            search=search,
+        )
+        return {
+            "pages": result.pages,
+            "count": result.count,
+            "limit": result.limit,
+            "offset": result.offset,
+            "data": [item.model_dump(mode="json") for item in result.data],
+        }
+
+    return [list_services_by_clinic]
+```
+
+### Appointment tools
+
+`src/infrastructure/ai/langgraph/tools/appointment_tools.py`:
+
+```python
+from langchain.tools import tool
+
+
+def build_appointment_tools(search_available_slots_use_case, create_appointment_use_case):
+    @tool("search_available_slots")
+    def search_available_slots(
+        clinic_id: int,
+        service_id: int,
+        desired_date: str,
+        professional_id: int | None = None,
+    ) -> list[dict]:
+        """Search available appointment slots for a clinic, service and date."""
+        result = search_available_slots_use_case.execute(
+            clinic_id=clinic_id,
+            service_id=service_id,
+            desired_date=desired_date,
+            professional_id=professional_id,
+        )
+        return [item.model_dump(mode="json") for item in result]
+
+    @tool("create_appointment")
+    def create_appointment(
+        clinic_id: int,
+        service_id: int,
+        customer_id: int,
+        professional_id: int,
+        start_at: str,
+    ) -> dict:
+        """Create an appointment after all required fields are known."""
+        result = create_appointment_use_case.execute_from_agent(
+            clinic_id=clinic_id,
+            service_id=service_id,
+            customer_id=customer_id,
+            professional_id=professional_id,
+            start_at=start_at,
+        )
+        return result.model_dump(mode="json")
+
+    return [search_available_slots, create_appointment]
+```
+
+Regra crítica:
+
+```txt
+O agente pode inferir intenção.
+O agente pode coletar dados.
+O agente pode sugerir próximos passos.
+O agente não confirma disponibilidade por conta própria.
+O caso de uso de agendamento valida disponibilidade, conflito, regras da clínica e status do serviço.
+```
+
+---
+
+## Fluxo correto do chat via WebSocket
+
+```txt
+Cliente WebSocket
+  -> interfaces/websocket/controllers/chat_ws_controller.py
+  -> application/agents/use_cases/process_agent_message_use_case.py
+  -> application/agents/ports/agent_orchestrator_port.py
+  -> infrastructure/ai/langgraph/orchestrator/langgraph_agent_orchestrator.py
+  -> infrastructure/ai/langgraph/graph_factory.py
+  -> nodes/*
+  -> tools/*
+  -> application/clinics | application/services | application/appointments
+  -> domain/*
+  -> infrastructure/persistence/*
+  -> application/agents/use_cases/process_agent_message_use_case.py
+  -> infrastructure/websocket/websocket_event_publisher.py
+  -> Cliente WebSocket
+```
+
+---
+
+## Convenções de domínio
+
+### Domain
+
+Use entidades puras.
+
+Não use Pydantic em entidades de domínio.
+
+Não use SQLAlchemy em entidades de domínio.
+
+Exemplo:
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class Appointment:
+    id: int | None
+    clinic_id: int
+    service_id: int
+    customer_id: int
+    professional_id: int
+    start_at: datetime
+    end_at: datetime
+    status: str
+
+    def confirm(self) -> None:
+        if self.status not in {"reserved", "requested"}:
+            raise ValueError("Only reserved or requested appointments can be confirmed")
+        self.status = "confirmed"
+
+    def cancel(self, reason: str | None) -> None:
+        if self.status in {"completed", "cancelled"}:
+            raise ValueError("Appointment cannot be cancelled")
+        self.status = "cancelled"
+```
+
+### Application
+
+Use explicit DTOs and ports.
+
+Application rules:
+
+- Each use case has one orchestration responsibility and explicit input/output contracts.
+- Use cases can coordinate multiple ports, but must not know adapter internals.
+- Transaction control (Unit of Work) lives in application orchestration boundaries.
+- Tenant and authorization context enters via DTO/principal contracts, never through Flask globals.
+
+Use-case contract example:
+
+```python
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class ListServicesInput:
+    tenant_id: int
+    clinic_id: int
+    limit: int
+    offset: int
+    search: str | None
+
+
+class ServiceReaderPort(Protocol):
+    def list_by_clinic(self, input_data: ListServicesInput) -> list[dict]:
+        ...
+
+
+class ListServicesByClinicUseCase:
+    def __init__(self, service_reader: ServiceReaderPort):
+        self._service_reader = service_reader
+
+    def execute(self, input_data: ListServicesInput) -> list[dict]:
+        return self._service_reader.list_by_clinic(input_data)
+```
+
+### Infrastructure
+
+Implements application ports with concrete adapters.
+
+Infrastructure rules:
+
+- Repositories map ORM models to domain/application contracts.
+- Security adapters validate JWT and produce application principal objects.
+- Cache/pubsub adapters hide Redis protocol details from application/domain.
+- AI adapters implement model/provider orchestration behind ports.
+- Infrastructure can fail with external dependency errors, but error translation to business meaning stays explicit in application boundaries.
+
+---
+
+## Regras de mapeamento ORM <-> Domain
+
+Repository deve mapear explicitamente.
+
+Não retorne `AppointmentModel` para application.
+
+Exemplo:
+
+```python
+from src.domain.appointments.entities.appointment import Appointment
+from src.infrastructure.persistence.models.appointment_model import AppointmentModel
+
+
+class AppointmentMapper:
+    @staticmethod
+    def to_domain(model: AppointmentModel) -> Appointment:
+        return Appointment(
+            id=model.id,
+            clinic_id=model.clinic_id,
+            service_id=model.service_id,
+            customer_id=model.customer_id,
+            professional_id=model.professional_id,
+            start_at=model.start_at,
+            end_at=model.end_at,
+            status=model.status,
+        )
+
+    @staticmethod
+    def to_model(entity: Appointment) -> AppointmentModel:
+        return AppointmentModel(
+            clinic_id=entity.clinic_id,
+            service_id=entity.service_id,
+            customer_id=entity.customer_id,
+            professional_id=entity.professional_id,
+            start_at=entity.start_at,
+            end_at=entity.end_at,
+            status=entity.status,
+        )
+```
+
+---
+
+## Agendamento e conflito de agenda
+
+Estratégia padrão:
+
+1. Serviço define duração.
+2. Caso de uso calcula `end_at`.
+3. Caso de uso quebra o período em slots discretos.
+4. Caso de uso tenta inserir locks dos slots.
+5. Banco garante unicidade por `clinic_id`, `professional_id`, `slot_start_at`.
+6. Se houver conflito, a transação falha e o use case retorna erro de agenda indisponível.
+
+Exemplo conceitual:
+
+```txt
+Consulta de 45 minutos
+Slot base: 15 minutos
+Início: 10:00
+Fim: 10:45
+Locks:
+- 10:00
+- 10:15
+- 10:30
+```
+
+Nunca confie apenas no LLM para validar conflito.
+
+---
+
+## Migrations
+
+Regras:
+
+- Toda mudança de modelo precisa de migration.
+- Use autogenerate como ponto de partida, nunca como verdade final.
+- Revise constraints, indexes, defaults e checks manualmente.
+- Nunca rode migration gerada automaticamente em produção sem revisão.
+- Nomeie constraints para facilitar diff e rollback.
+- Se usar PostgreSQL e quiser validação de intervalo real, adicione constraint específica por migration manual, não por modelo genérico.
+- Se usar MySQL, revise tamanho de índice, charset/collation, suporte de check constraints e comportamento de timezone.
+- Quando uma migration tiver caminhos diferentes para PostgreSQL e MySQL, deixe a decisão explícita no arquivo da migration e teste os dois dialetos.
+
+---
+
+## pyproject.toml base
+
+```toml
+[project]
+name = "api-clean-flask"
+version = "0.1.0"
+description = "Clean Architecture Flask API with REST, WebSocket and LangGraph multi-agent orchestration"
+requires-python = ">=3.12"
+dependencies = [
+    "Flask>=3.1,<4",
+    "flask-sock>=0.7,<1",
+    "SQLAlchemy>=2.0,<3",
+    "alembic>=1.13,<2",
+    "pydantic>=2.8,<3",
+    "pydantic-settings>=2.4,<3",
+    "PyJWT>=2.8,<3",
+    "apispec>=6.6,<7",
+    "swagger-ui-bundle>=1.1,<2",
+    "langchain>=1,<2",
+    "langgraph>=1,<2",
+    "redis>=5,<7",
+    "python-dotenv>=1,<2",
+    "gunicorn>=22,<24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<9",
+    "pytest-cov>=5,<7",
+    "ruff>=0.6,<1",
+    "black>=24,<26",
+    "mypy>=1.10,<2",
+]
+postgres = [
+    "psycopg[binary]>=3.2,<4",
+]
+mysql = [
+    "pymysql>=1.1,<2",
+]
+databases = [
+    "psycopg[binary]>=3.2,<4",
+    "pymysql>=1.1,<2",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.black]
+line-length = 100
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unused_ignores = true
+warn_return_any = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+```
+
+Ajuste versões conforme compatibilidade real do ambiente.
+
+---
+
+## Tratamento de erros
+
+### REST
+
+Formato:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid request payload",
+    "details": []
+  }
+}
+```
+
+### WebSocket
+
+Formato:
+
+```json
+{
+  "type": "error.validation",
+  "correlation_id": "corr_123",
+  "payload": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid websocket message",
+    "details": []
+  }
+}
+```
+
+### Agente
+
+Formato:
+
+```json
+{
+  "type": "chat.response",
+  "correlation_id": "corr_123",
+  "payload": {
+    "message": "Preciso saber qual serviço você deseja agendar.",
+    "intent": "appointment_create",
+    "requires_user_input": true
+  }
+}
+```
+
+---
+
+## Observabilidade
+
+Todo fluxo deve carregar:
+
+- `correlation_id`
+- `clinic_id`
+- `user_id`, quando disponível
+- `connection_id`, quando WebSocket
+- `intent`, quando fluxo de agente
+- duração da operação
+- status final
+- erro normalizado, quando houver
+
+Não registre dados sensíveis em log.
+
+Não registre prompt completo sem sanitização.
+
+Não registre payload bruto do WebSocket em produção.
+
+---
+
+## Testes obrigatórios
+
+### Unitários
+
+- Entidades de domínio.
+- Políticas de domínio.
+- Use cases.
+- Verificação de JWT com token válido, expirado, inválido e sem `tenant_id`.
+- Propagação de `tenant_id` nos DTOs de application.
+- Cálculo de paginação `pages`, `count`, `limit`, `offset` e `data`.
+- Normalização de `search` opcional em listagens.
+- Mappers ORM/domain.
+- Nodes determinísticos do LangGraph.
+- Tools com use cases mockados.
+- Provider de LLM fake/stub.
+- Factory de provider sem acoplar application a vendor.
+- Normalização de exceptions globais.
+- Cache key builder com `tenant_id`.
+- Pub/sub channel builder com `tenant_id`.
+- OpenAPI factory contendo `bearerAuth`.
+- Swagger UI config com `persistAuthorization`.
+- OpenAPI examples/templates para cada operação HTTP exposta.
+
+### Integração
+
+- Repositories com banco de teste.
+- Unit of Work com commit e rollback.
+- Repositories filtrando obrigatoriamente por `tenant_id`.
+- Auditoria ORM criando `created_at`, atualizando `updated_at` e aplicando `deleted_at` em soft delete.
+- Migrations em SQLite e, no perfil de integração, PostgreSQL e MySQL.
+- Rotas HTTP.
+- Endpoints de listagem com query `limit` e `offset`.
+- Endpoints de listagem com query `search` aplicando `LIKE '%search%'` nos campos textuais.
+- WebSocket controller com conexão fake.
+- Middleware JWT HTTP.
+- Autenticação JWT no WebSocket.
+- `GET /openapi.json` retornando OpenAPI v3 válido.
+- `GET /docs` retornando Swagger UI com autorização Bearer JWT.
+- OpenAPI de cada endpoint HTTP contendo exemplo de uso executável pela Swagger UI.
+- Redis cache adapter com Redis de teste ou fake compatível.
+- Redis pub/sub adapter com Redis de teste ou fake compatível.
+- Agent orchestrator com LLM fake.
+- LangGraph executando com provider fake configurado.
+
+### E2E
+
+- Login ou injeção controlada de JWT válido em ambiente de teste.
+- Criar clínica.
+- Criar serviço.
+- Listar serviços com paginação e busca textual, validando envelope `{pages, count, limit, offset, data}`.
+- Consultar disponibilidade.
+- Criar agendamento.
+- Confirmar agendamento.
+- Receber evento WebSocket.
+- Enviar mensagem via WebSocket e receber resposta do agente.
+- Abrir Swagger UI, salvar token via Authorize e executar request protegido com Bearer JWT.
+- Garantir que usuário de outro `tenant_id` não leia clínica, serviço, agendamento, cache nem evento pub/sub do tenant original.
+- Executar pelo menos um fluxo e2e com PostgreSQL e um fluxo e2e com MySQL no perfil de compatibilidade de banco.
+
+---
+
+## Quality gates for skill maintenance
+
+These gates keep the skill reviewable and traceable to EPIC-0016 without relying on brittle whole-file snapshots.
+
+| Gate ID | What must stay true | Traceability focus | Stable assertion anchors |
+| --- | --- | --- | --- |
+| GATE-ARCH-BOUNDARY | Domain/application remain framework-free; adapters stay in interface/infrastructure layers | Clean Architecture boundaries and dependency direction | `## Python/Flask Clean Architecture boundary contract`, `Must not depend on` |
+| GATE-SEC-AUTHORITY | Tenant/security authority comes from validated principal (JWT/context), never from payload or LLM output | Tenant isolation and security authority source | `tenant_id obrigatório`, `WebSocket payload is never authority` |
+| GATE-OPENSDD-BOUNDARY | OpenSDD is decision-support only; generated runtime code must not import OpenSDD artifacts | OpenSDD support with runtime boundary safety | `## OpenSDD decision-support mode (never runtime dependency)`, `must not import from `.sdd`` |
+| GATE-PROD-VERSIONING | Production guidance remains provider/model agnostic and version-sensitive APIs are labeled | Production readiness and version-aware guidance | `## Production-readiness guidance (safe and version-aware)`, `Version-sensitive API policy (validated or conceptual)` |
+| GATE-VALIDATION-STRATEGY | Validation uses stable required anchors/rules instead of prose snapshots | Maintainable quality gate evidence | `Avoid whole-document snapshots`, `Prefer required headings and key rules` |
+
+### Stable content assertion strategy
+
+- Assert required headings and critical boundary phrases only.
+- Avoid whole-document snapshots of `SKILL.md`.
+- Prefer assertions tied to gate anchors that are expected to remain stable across editorial rewrites.
+- If a heading or gate anchor changes intentionally, update both the skill and the targeted test in the same change.
+
+Recommended minimum anchors for seeded-skill tests:
+
+- `## Python/Flask Clean Architecture boundary contract`
+- `## OpenSDD decision-support mode (never runtime dependency)`
+- `## Production-readiness guidance (safe and version-aware)`
+- `Version-sensitive API policy (validated or conceptual)`
+- `Redis Pub/Sub versus Streams and outbox`
+- `## Quality gates for skill maintenance`
+
+---
+
+## Checklist antes de aceitar código gerado
+
+```txt
+[ ] Flask aparece apenas em interfaces/http ou interfaces/websocket.
+[ ] SQLAlchemy aparece apenas em infrastructure/persistence.
+[ ] LangChain e LangGraph aparecem apenas em infrastructure/ai.
+[ ] Nenhum provider/modelo de LLM está hardcoded em domain/application.
+[ ] Provider e modelo são escolhidos por configuração.
+[ ] Exemplos version-sensitive de LangGraph/LangChain/observabilidade/checkpointer estão marcados como VALIDATED ou CONCEPTUAL.
+[ ] Exemplos CONCEPTUAL não dependem de imports internos/privados de bibliotecas externas.
+[ ] Testes de agentes usam provider fake/stub.
+[ ] Código Python público está tipado com argumentos e retornos.
+[ ] Mypy roda em modo estrito ou equivalente acordado.
+[ ] Use cases, repositories, services, policies, controllers e adapters são classes.
+[ ] Ports usam `Protocol` ou `ABC`.
+[ ] Domain não importa frameworks.
+[ ] Application não importa modelos ORM.
+[ ] Controller não acessa repository diretamente.
+[ ] Repository não commita transação.
+[ ] Use case usa Unit of Work.
+[ ] IDs principais são sequenciais.
+[ ] Toda entity ORM de negócio possui `tenant_id` obrigatório.
+[ ] Toda entity ORM de negócio possui `created_at`, `updated_at` e `deleted_at`.
+[ ] `updated_at` atualiza automaticamente em update.
+[ ] Soft delete preenche `deleted_at` sem remover registro por padrão.
+[ ] Toda query de repository filtra por `tenant_id`.
+[ ] Toda unique constraint tenant-scoped inclui `tenant_id`.
+[ ] Rotas com IDs sequenciais validam escopo por `tenant_id` e `clinic_id`.
+[ ] Endpoints de listagem aceitam `limit` e `offset`.
+[ ] Endpoints de listagem aceitam `search` opcional.
+[ ] Respostas de listagem retornam `{pages, count, limit, offset, data}`.
+[ ] Queries paginadas continuam filtrando por `tenant_id`.
+[ ] Queries com `search` aplicam `LIKE '%search%'` nos campos textuais permitidos.
+[ ] Queries com `search` usam bind parameters, sem interpolação manual.
+[ ] JWT é validado por adapter de security e não manualmente em controller.
+[ ] WebSocket autentica antes de processar evento de negócio.
+[ ] WebSocket payload nunca é fonte de autoridade para `tenant_id`, `user_id` ou permissões.
+[ ] OpenAPI v3 expõe todos os endpoints REST públicos.
+[ ] OpenAPI declara `bearerAuth` para endpoints protegidos.
+[ ] Cada serviço HTTP possui exemplos/templates de uso no Swagger.
+[ ] Swagger UI está disponível e preserva token com `persistAuthorization`.
+[ ] Agendamento usa lock transacional por slot ou constraint equivalente.
+[ ] WebSocket abre transação por mensagem, não por conexão.
+[ ] Ações transacionais iniciadas por agente exigem confirmação explícita quando houver efeito colateral.
+[ ] Agent tool chama use case, não banco.
+[ ] ToolExecutionContext carrega `tenant_id` e `user_id` de contexto autenticado, não inferido pelo LLM.
+[ ] Redis é acessado somente por adapters em infrastructure.
+[ ] Cache keys e pub/sub channels incluem `tenant_id`.
+[ ] Eventos que exigem replay/recovery usam Streams/outbox em vez de apenas Pub/Sub efêmero.
+[ ] Operações mutáveis têm estratégia explícita de idempotência/deduplicação.
+[ ] Exceptions globais normalizam erro sem derrubar o processo.
+[ ] Observabilidade inclui logs estruturados, métricas/traces e health checks de readiness/liveness.
+[ ] Migrations foram revisadas manualmente.
+[ ] Testes cobrem conflito de agenda.
+[ ] Testes unitários cobrem JWT, tenant_id, cache/pub-sub e exception mapping.
+[ ] Testes e2e cobrem REST, WebSocket, Redis e isolamento entre tenants.
+[ ] Pipeline CI/CD executa ao menos lint/type/unit/integration e, quando aplicável, e2e.
+[ ] Perfil de compatibilidade cobre PostgreSQL e MySQL.
+```
+
+---
+
+## Como responder quando pedirem implementação
+
+Ao gerar código para este projeto:
+
+1. Mostre primeiro o arquivo alvo.
+2. Gere código completo do arquivo.
+3. Não gere arquivos gigantes sem necessidade.
+4. Quando houver dependência entre arquivos, gere na ordem:
+   - domain
+   - application DTO/ports
+   - application use case
+   - infrastructure model/repository
+   - interface schema/controller/route
+   - tests
+5. Preserve os limites da arquitetura.
+6. Use IDs inteiros sequenciais.
+7. Sempre inclua teste quando a mudança envolver regra de negócio.
+8. Em agendamento, sempre trate concorrência.
+9. Em agente, sempre separe intenção inferida de decisão transacional.
+
+---
+
+## Decisão final da skill
+
+Este projeto deve ser tratado como:
+
+```txt
+Clean Architecture Flask API
+com REST e WebSocket isolados,
+Python tipado e orientado a objetos,
+três domínios puros,
+SQLAlchemy tipado na infraestrutura,
+IDs relacionais sequenciais,
+tenant_id obrigatório em toda entity ORM para segregação SaaS,
+auditoria ORM obrigatória com created_at, updated_at e deleted_at,
+JWT como fonte canônica de autenticação, autorização e tenant,
+OpenAPI v3 e Swagger UI com Bearer JWT persistido na interface,
+Unit of Work para transações,
+slot locks para conflito de agenda,
+PostgreSQL e MySQL suportados por SQLAlchemy/Alembic,
+Redis obrigatório para cache, publish/subscribe, sessões e locks distribuídos,
+exceptions globais para continuidade de serviço,
+testes unitários, integração e e2e cobrindo isolamento multi-tenant,
+guidance de produção classificada entre baseline obrigatório e capacidades avançadas opcionais,
+APIs sensíveis a versão tratadas como VALIDATED ou CONCEPTUAL conforme evidência real,
+e LangGraph/LangChain como adapter de IA agnóstico a modelos e controlado pela application layer.
+```