# Arquitetura do Sistema ## Visão Geral O **Newsletter Platform** adota os princípios de **Domain-Driven Design (DDD)** e **Clean Architecture**, organizando o código por módulos funcionais (*feature-based modules*) desacoplados. O fluxo de dependências é rigorosamente unidirecional: a camada de infraestrutura e apresentação depende da camada de aplicação e domínio, enquanto o domínio é mantido livre de dependências diretas de frameworks web. ``` ┌────────────────────────────────────────────────────────┐ │ Camada de Apresentação │ │ (src/app: Server Components & Route Groups) │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Server Actions │ │ (src/modules/*/actions) │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Casos de Uso │ │ (src/modules/*/use-cases) │ └──────────────┬───────────────────────────┬─────────────┘ │ │ ▼ ▼ ┌─────────────────────────────┐ ┌────────────────────────┐ │ Interfaces de Repositório │ │ Entidades & Validações│ │ (src/modules/*/repositories│ │ (src/modules/*/entities│ │ /contract.ts) │ │ /dtos) │ └──────────────┬──────────────┘ └────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ Implementação de Infraestrutura │ │ (Prisma ORM, AWS SES v2, Nodemailer, In-Memory Repos) │ └────────────────────────────────────────────────────────┘ ``` --- ## Princípios Arquiteturais 1. **Módulos Baseados em Features (`src/modules/`)**: O código é organizado pelo contexto de negócio (ex.: `campaigns`, `contacts`, `domains`), reunindo ações, casos de uso, repositórios e componentes no mesmo domínio. 2. **Server Actions para Mutations**: Alterações de estado iniciadas pela interface utilizam Server Actions nativas do React 19 / Next.js 15. Não há rotas API REST customizadas para formulários ou operações de CRUD. 3. **Server Components para Data Fetching**: As páginas (`page.tsx`) são Server Components que invocam diretamente os use-cases do domínio para carregar dados, aproveitando a renderização no servidor e reduzindo o JS enviado ao cliente. 4. **Repository Pattern com Abstração Dupla**: Cada repositório define uma interface TypeScript (`*Repository`). O sistema fornece duas implementações: - `Prisma*Repository`: Para execução real integrada ao banco PostgreSQL. - `InMemory*Repository`: Para testes unitários ultrarrápidos e sem dependências de I/O. 5. **Use-Cases Isolados**: Toda a regra de negócio vive em classes com método único `execute()`. Eles recebem os repositórios e serviços via injeção de dependência no construtor. 6. **Dependência Unidirecional**: `src/app` → `src/modules` → `src/shared`. Módulos não acessam diretamente as rotas HTTP de `src/app`. --- ## Estrutura de um Módulo Dentro de `src/modules//`, as seguintes pastas podem existir, mantendo a estrutura sem subpastas aninhadas profundas: | Pasta | Responsabilidade | Exemplo | | :--- | :--- | :--- | | `actions/` | Funções com `'use server'` que autenticam a sessão e invocam use-cases | `create-campaign-action.ts` | | `use-cases/` | Classes contendo a regra de negócio pura da aplicação | `create-campaign-use-case.ts` | | `repositories/` | Interfaces de repositório e suas implementações Prisma e In-Memory | `campaigns-repository.ts`, `prisma-campaigns-repository.ts` | | `dtos/` | Schemas Zod e definições de tipos para payloads de entrada/saída | `create-campaign-dto.ts` | | `entities/` | Regras puras de transformação, sanitização ou cálculos do domínio | `sanitize-html.ts`, `build-email-content.ts` | | `providers/` | Interfaces e implementações para serviços externos de terceiros | `mail-provider.ts`, `ses-mail-provider.ts` | | `components/` | Componentes React de UI específicos do domínio | `campaign-form.tsx`, `contacts-table.tsx` | | `hooks/` | Custom hooks React específicos da funcionalidade | `use-campaign-wizard.ts` | | `utils/` | Helpers puros utilizados no âmbito do módulo | `parse-csv.ts` | --- ## Fluxo de Dados ### 1. Leitura de Dados (Data Fetching / GET) As páginas do dashboard realizam a leitura de dados diretamente no servidor através de Server Components: ``` [Cliente navega para /campaigns] │ ▼ [src/app/(dashboard)/campaigns/page.tsx (Server Component)] │ ├─► Obtém sessão do usuário via auth() │ ├─► Instancia o Use-Case com PrismaRepository: │ new GetCampaignsByUserUseCase(new PrismaCampaignsRepository()) │ ├─► Executa useCase.execute({ userId }) │ └─► Renderiza a página enviando os dados como props para os componentes React ``` ### 2. Mutação de Dados (Server Actions / POST, PUT, DELETE) As ações do usuário no front-end invocam Server Actions tipadas: ``` [Usuário clica em "Salvar Campanha" no Form] │ ▼ [Server Action: createCampaignAction(formData)] │ ├─► Valida autenticação da sessão com auth() │ ├─► Instancia o Use-Case: │ new CreateCampaignUseCase(new PrismaCampaignsRepository()) │ ├─► Executa useCase.execute(parsedData) │ └─► Executa revalidatePath('/campaigns') e retorna { success: true, campaign } ``` ### 3. Chamadas Externas (Webhooks & Public Endpoints) Casos em que sistemas externos (ex.: AWS SNS ou navegadores baixando pixels) chamam o sistema utilizam API Routes dedicadas em `src/app/api/`: ``` [AWS SNS publica um evento em /api/webhooks/ses] │ ▼ [src/app/api/webhooks/ses/route.ts (HTTP POST)] │ ├─► Valida o envelope SNS e a assinatura de segurança via verifySnsMessage │ ├─► Instancia HandleSesNotificationUseCase com os repositórios Prisma necessários │ ├─► Executa o processamento do evento (Bounce, Complaint, Delivery) │ └─► Retorna resposta HTTP 200 OK estática para o serviço da AWS ``` --- ## Camada de Apresentação (`src/app/`) A camada de apresentação é organizada utilizando os **Route Groups** do Next.js: - `(auth)/`: Agrupa rotas públicas de autenticação (`/login`, `/register`) sob um layout limpo sem barra lateral. - `(dashboard)/`: Agrupa todas as rotas autenticadas (`/`, `/campaigns`, `/contacts`, `/settings/domains`) sob um layout comum com navegação e controle de sessão. - `unsubscribe/`: Página pública para descadastro de e-mails via token ou parâmetro URL. - `api/`: API Routes restritas a callbacks e webhooks externos. --- ## Camada de Domínio (`src/modules/`) O sistema é dividido nos seguintes módulos de domínio: - **`auth`**: Registro de novos usuários e autorização de credenciais. - **`campaigns`**: Criação de rascunhos, agendamento, disparo de e-mails em lotes com rate limiting, relatórios de abertura/falha e métricas do dashboard. - **`contacts`**: Gerenciamento de contatos, membros de listas de transmissão, tags, cálculo de engajamento, importação de CSV em lote e exportação assíncrona. - **`domains`**: Registro de domínios para envio SES, geração de registros DNS (DKIM, SPF, Mail From) e verificação periódica. - **`senders`**: Gerenciamento de remetentes SMTP e SES com criptografia AES-256-GCM para credenciais de acesso. - **`ses-webhooks`**: Recepção e processamento de eventos do AWS SES/SNS (send, delivery, bounce, complaint, open, click) e pixel de rastreamento HTTP. - **`suppression`**: Controle de e-mails na lista de supressão por bounce ou rejeição manual. --- ## Camada Compartilhada (`src/shared/`) Contém código utilitário e infraestrutura comum: - `src/shared/components/`: Componentes visuais genéricos (botões, modais, inputs, toasters). - `src/shared/infra/crypto/`: Criptografia reversível AES-256-GCM usada na proteção de senhas SMTP. - `src/shared/infra/http/`: Helper `ResponseHelper` para respostas de API HTTP padronizadas. - `src/shared/infra/prisma/`: Instância singleton do Prisma Client (`prisma.ts`). --- ## Autenticação A autenticação é gerenciada pelo **NextAuth.js v5 (Auth.js)** com estratégia de **JWT (JSON Web Tokens)**: - Configuração centralizada em `src/config/auth.ts`. - Validação de credenciais via `AuthenticateUserUseCase` e `PrismaUsersRepository`. - **Middleware (`src/middleware.ts`)**: Intercepta requisições de página, redirecionando usuários não autenticados para `/login` e bloqueando o acesso a rotas públicas quando autenticado. - As rotas em `/api/` tratam suas próprias checagens de sessão para retornar erros JSON `401 Unauthorized` adequados. --- ## Providers (Serviços Externos) Os provedores de integração com serviços externos utilizam o padrão de fábrica (*Factory Pattern*): - **Mail Provider (`MailProviderFactory`)**: Seleciona dinamicamente a implementação de envio conforme a configuração do remetente (`SenderProvider`): - `NodemailerMailProvider`: Envio via servidor SMTP (ou Mailpit em dev). - `SesMailProvider`: Envio de alto desempenho utilizando a API AWS SES v2. - `InMemoryMailProvider`: Provedor simulado para testes unitários. - **SES Identity Provider (`SesIdentityProviderImpl`)**: Interage com a AWS para criar identidades de domínio, consultar DKIM e validar DNS. - **SES Suppression Provider (`SesSuppressionProviderImpl`)**: Adiciona e-mails rejeitados automaticamente à lista de supressão da conta AWS SES. --- ## Estratégia de Testes Os testes da aplicação priorizam a velocidade e o desacoplamento de infraestrutura real: - **Testes Unitários de Use-Cases**: Testam as regras de negócio passando instâncias de `InMemoryRepository` e `InMemoryMailProvider`. - Sem necessidade de banco PostgreSQL ativo para rodar `npm run test`. - Cobertura completa de casos de borda: rejeição de e-mails duplicados, contatos suprimidos, rate-limiting e falhas de envio.