# Arquitetura — Backend

## Visão geral

O backend segue uma arquitetura em camadas com bootstrap por factories. Cada domínio de negócio é encapsulado em um conjunto padronizado de arquivos.

```
index.js
└── CoreFactory.Iniciar()
    ├── BancoFactory   → conecta ao MySQL, valida conexão
    └── ServerFactory  → cria o Express app, registra middlewares, sobe o servidor
         └── Roteamento.IniciarRoteamento(app)
              └── Domínios: Auth · Chat · Conversations · Documents · Ingest · Search · Usuario
                   └── *.Rotas.js → *.Controller.js → *Service.js → Model (Objection)
```

## Camadas

### Factories (`src/factories/`)

Responsáveis pelo bootstrap da aplicação. Chamadas em sequência por `index.js` na raiz.

| Factory | Responsabilidade |
|---|---|
| `Core.factory.js` | Orquestra Banco + Server |
| `Banco.factory.js` | Conecta ao MySQL e valida a conexão |
| `Server.factory.js` | Cria o app Express, registra middlewares globais, sobe o servidor HTTP |

### Roteamento (`src/routes/index.js`)

A classe `Roteamento` registra todos os domínios no Express via `IniciarRoteamento(app)`. Cada domínio tem seu próprio arquivo `*.Rotas.js` que define as rotas e middlewares daquele domínio.

Todos os domínios são montados sob o prefixo `/api`, que recebe **dois middlewares globais** antes de qualquer rota: `rateLimitMiddleware` (`RateLimit.js`) e `authMiddleware` (`Validajwt.js`). Ou seja, o JWT é decodificado globalmente; os middlewares `requireUser`/`requireAdmin` por rota apenas verificam o resultado.

### Controllers (`src/controllers/`)

Recebem a requisição HTTP, extraem os dados necessários (params, body, user) e delegam ao Service correspondente. Não contêm lógica de negócio.

### Services (`src/services/`)

Contêm toda a lógica de negócio. São chamados pelos controllers. Podem chamar Models (Objection) ou clients externos (Qdrant, Ollama).

### Models (`src/models/`)

Modelos Objection.js. Mapeiam as tabelas do MySQL e definem relacionamentos.

| Model | Tabela |
|---|---|
| `Usuario.model.js` | `usuarios` |
| `RefreshToken.model.js` | `refresh_tokens` |
| `Conversation.model.js` | `conversations` |
| `Message.model.js` | `messages` |

### Middleware (`src/middleware/`)

| Arquivo | Função |
|---|---|
| `Validajwt.js` | Verifica e decodifica o JWT do header Authorization |
| `RequireUser.js` | Exige usuário autenticado (qualquer nível) |
| `RequireAdmin.js` | Exige nível "3" (administrador) |
| `Validate.js` | Valida body/params/query com schema zod (`schema.parse()`) |
| `ParseId.js` | Converte `req.params.id` para número e valida |
| `RateLimit.js` | Rate limiting por IP |
| `ErrorHandler.js` | Captura erros e formata a resposta de erro |

### Schemas de validação (`src/middleware/schemas/`)

Schemas **zod** usados com o middleware `Validate` (que chama `schema.parse()`). Um arquivo por domínio que exige validação:

| Arquivo | Domínio |
|---|---|
| `Chat.Schema.js` | Corpo do chat |
| `Ingest.Schema.js` | Corpo do ingest |
| `Search.Schema.js` | Corpo da busca |
| `Usuario.Schema.js` | Criar, atualizar e alterar senha de usuário |

## Padrão de arquivos por domínio

Todo domínio segue a convenção de nomenclatura abaixo:

```
src/
├── routes/        NomeDoModulo.Rotas.js
├── controllers/   NomeDoModulo.Controller.js
├── services/      nomeDoModuloService.js
├── models/        NomeDoModulo.model.js          (se houver tabela)
└── middleware/
    └── schemas/   NomeDoModulo.Schema.js         (se houver validação)
```

## Alias ESM (`#*`)

O `package.json` define um alias de importação para evitar caminhos relativos longos:

```json
"imports": {
  "#*": "./src/*"
}
```

Como ficaria:
```js
import { UsuarioController } from "#controllers/Usuario.Controller.js";
import { db } from "#config/db.config.js";
```

> **Estado atual:** o alias está definido e funciona, mas **ainda não é usado** em nenhum arquivo do `src/` — todo o código usa imports relativos (`../config/db.config.js`). Foi adicionado na refatoração para espelhar o `@` do `minha_back`, mas a migração dos imports não foi feita.

## Domínios existentes

| Domínio | Prefix da rota | Descrição |
|---|---|---|
| Auth | `/api/auth` | Login, logout, refresh de token |
| Chat | `/api/chat` | Envio de mensagens ao LLM |
| Conversations | `/api/conversations` | CRUD de conversas persistidas |
| Documents | `/api/documents` | Listagem e exclusão de documentos |
| Ingest | `/api/ingest` | Ingestão de conteúdo na base RAG |
| Search | `/api/search` | Busca semântica nos documentos |
| Usuario | `/api/users` | CRUD de usuários do sistema |

## Health check

`GET /health` — retorna o status de todos os serviços:

```json
{
  "ok": true,
  "checks": {
    "api": true,
    "db": true,
    "qdrant": true,
    "ollama": true
  }
}
```