From 5cf6ff748653c9654106fdc678408c8baf9d2f2a Mon Sep 17 00:00:00 2001
From: Rafael Alves Lopes <rafael.lopes@sothis.com.br>
Date: Wed, 27 May 2026 16:42:08 -0300
Subject: [PATCH] Adicionar API overview

---
 API-overview.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 API-overview.md

diff --git a/API-overview.md b/API-overview.md
new file mode 100644
index 0000000..f8dfbe4
--- /dev/null
+++ b/API-overview.md
@@ -0,0 +1,48 @@
+# Visao Geral da API
+
+O backend e uma API NestJS que entrega autenticacao, administracao, agenda, operacao WhatsApp e fluxo do Agente Virtual.
+
+## Base URL local
+
+```txt
+http://localhost:3001
+```
+
+No Docker Compose da raiz, o backend fica exposto em:
+
+```txt
+http://localhost:4001
+```
+
+## Modulos HTTP
+
+| Prefixo | Modulo | Responsabilidade |
+|---|---|---|
+| `/auth` | Auth | Login LDAP/AD, OAuth Microsoft e JWT |
+| `/admin/access` | Admin Access | Usuarios, perfis, areas, auditoria, metricas e conteudos da IA |
+| `/admin/knowledge` | Knowledge Base | Fluxo do bot, arvore de decisao e keywords |
+| `/agent/presence` | Agent Presence | Presenca, pausa, retomada e offline |
+| `/agent/notes` | Agent Notes | Notas pessoais do agente |
+| `/contacts` | Contacts | Agenda e perfil do contato |
+| `/whatsapp` | WhatsApp | Chats, mensagens, templates, midia, atribuicao e abertura ativa |
+| `/health` | Health | Checagem simples da API |
+
+## Padrao de resposta
+
+A maior parte dos endpoints retorna JSON direto do service. Ainda nao existe envelope padrao unico como `{ data, error }`.
+
+## Autenticacao
+
+O login emite JWT e o frontend salva o token. Ponto importante: ainda falta validar esse JWT nos controllers via guard NestJS. Portanto, hoje o token existe, mas a API ainda nao esta protegida como deveria estar em producao.
+
+## Padrao de erro
+
+Alguns services lancam `Error`, `BadRequestException` ou excecoes do Nest. Ainda nao ha filter global padronizando respostas de erro.
+
+## Recomendacao de evolucao
+
+- Criar `JwtAuthGuard`.
+- Criar decorators/guards de perfil: Admin, Supervisor, Agente.
+- Extrair DTOs por endpoint.
+- Adicionar Swagger com `@nestjs/swagger`.
+- Criar testes de integracao para fluxos principais.