# Documentação Técnica — Newsletter Platform

Bem-vindo à documentação oficial consolidada da **Newsletter Platform**. Este documento serve como índice geral e visão arquitetural da plataforma full-stack de e-mail marketing.

---

## Índice Geral

1. **[README Principal](../README.md)**
   - Visão geral do projeto, Tech Stack e pré-requisitos.
   - Guia de setup local passo a passo (Node.js, PostgreSQL, Docker/Mailpit).
   - Tabela detalhada de variáveis de ambiente (`.env`).
   - Tabela de scripts do `package.json` e instruções de deploy (Vercel).

2. **[Arquitetura e Princípios](./architecture.md)**
   - Padrão Monólito Modular (*Feature-Based Modules*) & Clean Architecture / DDD.
   - Transição de API routes para **Server Actions** no React 19 / Next.js 15.
   - Fluxo de dados para leitura (Server Components), mutações (Server Actions) e eventos externos.
   - Camadas de Apresentação (`app/`), Domínio (`modules/`) e Infraestrutura Compartilhada (`shared/`).
   - Autenticação JWT via NextAuth v5 e middleware de proteção de rotas.

3. **[Banco de Dados e ORM](./database.md)**
   - Especificação do PostgreSQL e Prisma ORM v6.
   - Diagrama de Entidades (Mermaid ERD) cobrindo todos os 14 models.
   - Detalhamento de tabelas (`users`, `senders`, `campaigns`, `contacts`, `contact_lists`, `tags`, `campaign_logs`, `domains`, `suppressed_emails`, `email_events`, jobs de importação e exportação).
   - Definição dos 12 enums do schema.
   - Instruções de migrações (`prisma migrate`) e seed (`seed.ts`).

4. **[Módulos do Sistema](./modules.md)**
   - Mapeamento exaustivo dos 7 módulos em `src/modules/`: `auth`, `campaigns`, `contacts`, `domains`, `senders`, `ses-webhooks`, `suppression`.
   - Lista completa das 26 Server Actions do módulo de contatos, utilitários CSV, cálculo de engajamento e histórico de e-mails.
   - Módulo de campanhas (rascunhos, disparo em lotes, relatórios, analíticos de dashboard).
   - Repositórios em memória (`InMemoryRepository`) e integrados (`PrismaRepository`).

5. **[API Routes HTTP](./api.md)**
   - Especificação técnica dos endpoints HTTP remanescentes em `src/app/api/`.
   - Handler do NextAuth.js (`/api/auth/[...nextauth]`).
   - Webhook AWS SES/SNS (`/api/webhooks/ses`) com verificação de assinatura RSA.
   - Pixel estático de rastreamento de abertura (`/api/track/open/[token]`).
   - Descadastro "one-click" RFC 8058 (`/api/unsubscribe/[contactId]`).
   - Endpoints utilitários (`/api/domains/poll` e `/api/admin/ses-bootstrap`).

6. **[Motor de Envio (Email Engine)](./email-engine.md)**
   - Arquitetura de transportes de e-mail (`NodemailerMailProvider` para SMTP/Mailpit e `SesMailProvider` para AWS SES API v2).
   - Criptografia reversível AES-256-GCM para senhas SMTP em `crypto.ts`.
   - Algoritmo de envio em lotes concorrentes (`runInBatches`) e limitação de taxa (`RateLimiter`).
   - Rastreamento de aberturas via pixel e processamento de Hard Bounces / Complaints.
   - Lista de supressão de e-mails (`suppressed_emails`) e verificação de domínios DNS (DKIM/SPF).

---

## Estrutura de Documentos

```
newsletter-platform/
├── README.md               # Guia rápido, setup, env vars, scripts e deploy
└── docs/
    ├── DOCUMENTATION.md    # Este índice geral
    ├── README.md           # Índice dos guias modulares
    ├── architecture.md     # Princípios arquiteturais e fluxo de dados
    ├── database.md         # ERD, models Prisma, enums e migrations
    ├── modules.md          # Detalhamento de cada módulo e Server Actions
    ├── api.md              # Especificação de rotas HTTP de API
    └── email-engine.md     # Motor de disparo, rate-limiting e tracking
```

---

## Última Atualização

- **Data**: 31 de Julho de 2026
- **Status**: Documentação reescrita para refletir a arquitetura refatorada (Next.js 15 App Router, React 19 Server Actions, Prisma ORM v6, NextAuth v5).