Adicionar API overview

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.