# OmniRoute Codebase Documentation (Português (Portugal))

🌐 **Languages:** 🇺🇸 [English](../../../../architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇹 [am](../../../am/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇦 [ar](../../../ar/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇿 [az](../../../az/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇬 [bg](../../../bg/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇩 [bn](../../../bn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇦 [bs](../../../bs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇿 [cs](../../../cs/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇰 [da](../../../da/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇩🇪 [de](../../../de/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇷 [el](../../../el/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇸 [es](../../../es/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇪🇪 [et](../../../et/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇷 [fa](../../../fa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇮 [fi](../../../fi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇫🇷 [fr](../../../fr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇪 [ga](../../../ga/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [gu](../../../gu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ha](../../../ha/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇱 [he](../../../he/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [hi](../../../hi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇷 [hr](../../../hr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇭🇺 [hu](../../../hu/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇦🇲 [hy](../../../hy/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇩 [id](../../../id/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [ig](../../../ig/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇹 [it](../../../it/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇯🇵 [ja](../../../ja/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇬🇪 [ka](../../../ka/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇭 [km](../../../km/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [kn](../../../kn/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇷 [ko](../../../ko/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇹 [lt](../../../lt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇻 [lv](../../../lv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ml](../../../ml/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [mr](../../../mr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇾 [ms](../../../ms/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇹 [mt](../../../mt/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇲🇲 [my](../../../my/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇵 [ne](../../../ne/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇱 [nl](../../../nl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇴 [no](../../../no/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [or](../../../or/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [pa](../../../pa/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇭 [phi](../../../phi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇱 [pl](../../../pl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇴 [ro](../../../ro/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇺 [ru](../../../ru/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇱🇰 [si](../../../si/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇰 [sk](../../../sk/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇮 [sl](../../../sl/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇷🇸 [sr](../../../sr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇸🇪 [sv](../../../sv/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇰🇪 [sw](../../../sw/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [ta](../../../ta/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇮🇳 [te](../../../te/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇭 [th](../../../th/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇷 [tr](../../../tr/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇵🇰 [ur](../../../ur/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇺🇿 [uz](../../../uz/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇻🇳 [vi](../../../vi/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇳🇬 [yo](../../../yo/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/architecture/CODEBASE_DOCUMENTATION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/architecture/CODEBASE_DOCUMENTATION.md)

---

> **Versão:** v3.8.51
> **Última atualização:** 2026-06-28
> **Público-alvo:** Engenheiros que contribuem para o OmniRoute ou desenvolvem integrações sobre o mesmo.
>
> Para diagramas de arquitetura de alto nível e a fundamentação de cada subsistema, consulte
> [ARCHITECTURE.md](./ARCHITECTURE.md). Para análises aprofundadas de subsistemas individuais
> (Auto Combo, servidor MCP, servidor A2A, Skills, Memory, Cloud Agents, Resilience,
> Compression, etc.), consulte os respetivos ficheiros neste diretório `docs/`.

Este ficheiro descreve **o que existe atualmente no repositório**, para que um novo engenheiro
possa navegar pela estrutura, compreender as camadas de execução e saber onde adicionar código
sem inventar novos módulos.

---

## 1. Stack tecnológica

| Área               | Escolha                                                                                                                                |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Framework Web      | **Next.js 16** (App Router, saída autónoma, sem middleware global)                                                                     |
| Linguagem          | **TypeScript 6.0+** — alvo `ES2022`, `module: esnext`, `moduleResolution: bundler`, `strict: false`                                    |
| Runtime            | **Node.js** `>=22.22.2 <23` ou `>=24.0.0 <27` (imposto através de `engines` + `SUPPORTED_NODE_RANGE`)                                  |
| Base de dados      | **SQLite** através de `better-sqlite3` (singleton, journaling WAL)                                                                     |
| Desktop            | **Electron 41** + `electron-builder` 26.10 (workspace separado em `electron/`)                                                         |
| Testes             | **Executor de testes nativo do Node** (unitários/integração), **Vitest** (MCP, autoCombo, cache), **Playwright** (e2e + protocols-e2e) |
| Compilação         | Next.js autónomo através de `scripts/build/build-next-isolated.mjs`                                                                    |
| Lint/formatação    | Configuração plana do ESLint + Prettier (`lint-staged` através do pre-commit do Husky)                                                 |
| Sistema de módulos | ESM em todo o projeto (`"type": "module"`)                                                                                             |
| Workspaces         | workspace npm — `open-sse` é o único sub-workspace                                                                                     |

Aliases de caminhos (`tsconfig.json`):

- `@/*` → `src/*`
- `@omniroute/open-sse` → `open-sse/index.ts`
- `@omniroute/open-sse/*` → `open-sse/*`

Porta HTTP predefinida: **`20128`** (a API e o dashboard partilham o mesmo processo). O diretório
de dados é definido pela variável de ambiente `DATA_DIR`, tendo como predefinição `~/.omniroute/`.

---

## 2. Estrutura do repositório

```
OmniRoute/
├── src/                  Aplicação Next.js (App Router, bibliotecas, domínio, servidor, código partilhado)
├── open-sse/             Workspace do motor de streaming (@omniroute/open-sse)
├── electron/             Wrapper para desktop (processo principal do Electron 41 + preload)
├── bin/                  Pontos de entrada da CLI (omniroute, reset-password)
├── tests/                Testes unitários, integração, e2e, protocols-e2e, tradutor, segurança, fixtures
├── scripts/              Scripts auxiliares de compilação, sincronização, verificação, migração e execução
├── docs/                 Documentação pública (este diretório)
├── public/               Recursos estáticos, manifesto PWA, service worker
├── config/               Exemplos de configuração de execução
├── images/               Recursos de marketing/capturas de ecrã
├── _ideia/, _references/, _mono_repo/, _tasks/   Rascunhos internos / planeamento (não distribuídos)
├── CLAUDE.md             Regras do repositório para o Claude Code
├── AGENTS.md             Referência de arquitetura mais aprofundada para agentes
├── package.json          v3.8.51, raiz do workspace
└── tsconfig.json         Aliases de caminhos + opções principais do compilador
```

---

## 3. `src/` — Aplicação Next.js

```
src/
├── app/                  Páginas do App Router + rotas da API
├── lib/                  Bibliotecas principais (BD, autenticação, OAuth, competências, memória, …)
├── domain/               Camada de domínio pura (políticas, contingência, custos, bloqueio, …)
├── server/               Módulos exclusivos do servidor (autorização, CORS, autenticação)
├── shared/               Tipos, constantes, validação, contratos e utilitários (seguros entre fronteiras)
├── mitm/                 Auxiliares de proxy intermediário para integração com a CLI
├── models/               Metadados/aliases de modelos locais
├── sse/                  Processadores SSE legados que ainda residem em src/ (não em open-sse/)
├── store/                Armazenamentos de estado do lado do cliente
├── middleware/           Utilitários de middleware ao nível das rotas (não middleware global do Next.js)
├── scripts/              Scripts na árvore que podem ser importados pelo código da aplicação
├── types/                Tipos TS globais e partilhados
├── i18n/                 Pacotes de idiomas
├── instrumentation.ts    Hook de instrumentação do Next.js
├── instrumentation-node.ts
└── proxy.ts              Auxiliar de inicialização do proxy de nível superior
```

### 3.1 `src/app/` — App Router

O App Router expõe tanto a interface do painel como a API HTTP pública/de gestão.
**Não existe middleware global** — a interceção é realizada por rota.

Segmentos de nível superior em `src/app/`:

| Caminho                                                                       | Finalidade                                               |
| ----------------------------------------------------------------------------- | -------------------------------------------------------- |
| `api/`                                                                        | Todas as rotas da API HTTP (ver detalhes abaixo)         |
| `a2a/`                                                                        | Endpoint A2A JSON-RPC 2.0 (`POST /a2a`)                  |
| `.well-known/agent.json/`                                                     | Documento de descoberta do Agent Card A2A                |
| `(dashboard)/`                                                                | Interface do painel (grupo de rotas, sem prefixo de URL) |
| `auth/`, `login/`, `forgot-password/`, `callback/`                            | Fluxos de autenticação                                   |
| `landing/`                                                                    | Página de marketing/apresentação                         |
| `docs/`                                                                       | Visualizador integrado da documentação da API            |
| `status/`, `maintenance/`, `offline/`                                         | Páginas operacionais                                     |
| `privacy/`, `terms/`                                                          | Páginas jurídicas                                        |
| `400/`, `401/`, `403/`, `408/`, `429/`, `500/`, `502/`, `503/`                | Páginas de erro estáticas                                |
| `error.tsx`, `global-error.tsx`, `not-found.tsx`, `forbidden/`, `loading.tsx` | Limites de erro/carregamento da framework                |
| `layout.tsx`, `page.tsx`, `globals.css`, `manifest.ts`                        | Estrutura raiz                                           |

#### 3.1.1 `src/app/(dashboard)/dashboard/` — Páginas da interface

`agents`, `analytics`, `api-manager`, `audit`, `auto-combo`, `batch`, `cache`,
`changelog`, `cli-tools`, `cloud-agents`, `combos`, `compression`, `context`,
`costs`, `endpoint`, `health`, `limits`, `logs`, `memory`, `onboarding`,
`playground`, `providers`, `search-tools`, `settings`, `skills`, `system`,
`translator`, `usage`, `webhooks`, além dos ficheiros raiz `page.tsx`, `HomePageClient.tsx`,
`BootstrapBanner.tsx`.

#### 3.1.2 `src/app/api/` — Grupos de API de nível superior

```
src/app/api/
├── a2a/{status, tasks}
├── acp/
├── admin/
├── analytics/
├── assess/
├── auth/
├── batches/
├── cache/
├── cli-tools/
├── cloud/{codex-responses-ws}
├── combos/
├── compliance/
├── compression/
├── context/
├── db/, db-backups/
├── evals/
├── fallback/
├── files/
├── health/
├── init/
├── internal/{concurrency}
├── keys/
├── logs/
├── mcp/{audit, sse, status, stream, tools}
├── memory/{health, [id]/, route.ts}
├── model-combo-mappings/
├── models/
├── monitoring/
├── oauth/
├── openapi/
├── policies/
├── pricing/
├── provider-metrics/, provider-models/, provider-nodes/
├── providers/
├── rate-limit/, rate-limits/
├── resilience/
├── restart/, shutdown/
├── search/
├── sessions/
├── settings/
├── skills/{executions, [id], install, marketplace, route.ts, skillssh}
├── storage/
├── sync/, synced-available-models/
├── system/
├── tags/
├── telemetry/
├── token-health/
├── translator/
├── tunnels/
├── services/   Gestão de serviços integrados (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API pública compatível com OpenAI
├── v1beta/     Compatibilidade ao estilo Gemini
├── version-manager/
└── webhooks/
```

#### 3.1.2a `src/app/api/services/` — Gestão de Serviços Integrados

Rotas para instalar, iniciar, parar e monitorizar o 9Router e o CLIProxyAPI.
Todos os caminhos estão classificados como **LOCAL_ONLY** (apenas loopback, regra estrita n.º 17), porque podem
invocar `npm install` e criar processos subordinados.

```
src/app/api/services/
├── 9router/
│   ├── _lib.ts             auxiliar getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install através de execFile
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install de uma versão mais recente
│   ├── rotate-key/route.ts POST — gerar nova chave de API + reiniciar
│   ├── status/route.ts     GET  — estado em tempo real + BD + metadados da versão
│   └── auto-start/route.ts POST — alternar o sinalizador auto_start
├── cliproxy/
│   ├── _lib.ts             auxiliar getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install
│   ├── start/route.ts      POST — supervisor.start()
│   ├── stop/route.ts       POST — supervisor.stop()
│   ├── restart/route.ts    POST — supervisor.restart()
│   ├── update/route.ts     POST — npm install de uma versão mais recente
│   ├── status/route.ts     GET  — estado em tempo real + BD + metadados da versão
│   └── auto-start/route.ts POST — alternar o sinalizador auto_start
└── [name]/
    └── logs/route.ts       GET  — acompanhamento de registos por SSE (partilhado por todos os serviços)
```

IU correspondente do painel:
`src/app/(dashboard)/dashboard/providers/services/` — página com dois separadores (CLIProxyAPI + 9Router).
Proxy inverso para a IU incorporada do 9Router:
`src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts`

Análise aprofundada: `docs/frameworks/EMBEDDED-SERVICES.md`

#### 3.1.3 `src/app/api/v1/` — API pública compatível com OpenAI

```
v1/
├── accounts/[id]/                       consulta de conta
├── agents/tasks/[id]/, agents/tasks/    endpoints de tarefas ao estilo A2A
├── api/                                 auxiliares internos da API expostos em v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API de lotes OpenAI
├── chat/completions/                    conclusões de conversação (o endpoint principal)
├── completions/                         conclusões de texto legadas
├── embeddings/                          incorporações
├── files/[id]/, files/                  API de ficheiros
├── _helpers/                            auxiliares de rotas partilhados (sem URL público)
├── images/{edits, generations}/         geração + edição de imagens
├── issues/                              endpoints auxiliares de triagem
├── management/{proxies}/                rotas do âmbito de gestão dentro de v1
├── messages/{count_tokens}/             compatibilidade com mensagens ao estilo Anthropic
├── models/                              listagem de modelos (`route.ts`, `catalog.ts`)
├── moderations/                         moderação
├── music/                               geração de música
├── providers/[provider]/                operações por fornecedor
├── quotas/{check}                       sondagens de quotas
├── registered-keys/                     administração de chaves registadas
├── rerank/                              reordenação
├── responses/[...path]/                 API de respostas OpenAI (rota genérica)
├── search/                              pesquisa na Web
├── videos/                              geração de vídeo
├── ws/                                  ponte WebSocket
└── route.ts                             processador do índice
```

Todos os ficheiros de rota seguem o mesmo padrão:

```
Rota → preflight CORS → validação do corpo com Zod → autenticação opcional
     → aplicação da política de chaves de API → delegação ao processador (open-sse)
```

`v1beta/` é a superfície de compatibilidade ao estilo Gemini (um wrapper simples que traduz para
o mesmo pipeline `open-sse/handlers/`).

### 3.2 `src/lib/` — Bibliotecas principais

Importe sempre dados, sincronização, OAuth, competências, memória, etc. através destes módulos. A
tabela agrupa os diretórios reais e os ficheiros de nível superior mais relevantes.

| Módulo            | Finalidade                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a2a/`            | Servidor do protocolo A2A: `taskManager.ts`, `streaming.ts`, `taskExecution.ts`, `routingLogger.ts`, `skills/` (6 competências: análise de custos, relatório de estado, descoberta de fornecedores, gestão de quotas, encaminhamento inteligente, list-capabilities)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `acp/`            | Protocolo de Controlo de Agentes: `index.ts`, `manager.ts`, `registry.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `api/`            | Utilitários internos da API: `requireManagementAuth.ts`, `requireCliToolsAuth.ts`, `errorResponse.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `auth/`           | `managementPassword.ts` (reposição de palavra-passe / hashing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `batches/`        | Serviço da API OpenAI Batches (`service.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `catalog/`        | Sincronização do catálogo OpenRouter (`openrouterCatalog.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `cloudAgent/`     | Registo de agentes na nuvem: `api.ts`, `baseAgent.ts`, `db.ts`, `index.ts`, `registry.ts`, `types.ts`, `agents/{codex, devin, jules}.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `combos/`         | Utilitários de resolução de combinações                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `compliance/`     | Auditoria + auditoria de fornecedores: `index.ts`, `providerAudit.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `config/`         | Integração da configuração de runtime                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `db/`             | Módulos de domínio SQLite (ver §3.2.1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `display/`        | Utilitários de interface/apresentação utilizados pelas respostas da API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `embeddings/`     | Registo de serviços de embeddings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `env/`            | Carregamento + introspeção do ambiente                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `evals/`          | Runtime de avaliações                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `guardrails/`     | `piiMasker.ts`, `promptInjection.ts`, `visionBridge.ts`, `visionBridgeHelpers.ts`, `registry.ts`, `base.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `jobs/`           | Tarefas em segundo plano (`autoUpdate.ts`, …)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `memory/`         | Memória persistente: `store.ts`, `cache.ts`, `retrieval.ts`, `summarization.ts`, `extraction.ts`, `injection.ts`, `qdrant.ts`, `settings.ts`, `verify.ts`, `schemas.ts`, `types.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `monitoring/`     | `observability.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `oauth/`          | Módulos OAuth/de importação de fornecedores (22): `agy`, `antigravity`, `claude`, `cline`, `codebuddy-cn`, `codex`, `cursor`, `devin-desktop`, `ghe-copilot`, `github`, `gitlab-duo`, `grok-cli-oauth`, `grok-cli`, `kilocode`, `kimi-coding`, `kiro`, `openference`, `qoder`, `trae`, `xai-oauth`, `zed-hosted`, `zed`, além de `services/`, `utils/` e `constants/oauth.ts`                                                                                                                                                                                                                                                                                                                                     |
| `plugins/`        | Carregador de plugins (`index.ts`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `promptCache/`    | `prefixAnalyzer.ts`, `index.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `providerModels/` | Ciclo de vida de modelos geridos: `modelDiscovery.ts`, `managedModelImport.ts`, `managedAvailableModels.ts`, `cursorAgent.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `providers/`      | Utilitários de fornecedores: `catalog.ts`, `validation.ts`, `imageValidation.ts`, `claudeExtraUsage.ts`, `codexConnectionDefaults.ts`, `codexFastTier.ts`, `webCookieAuth.ts`, `managedAvailableModels.ts`, `requestDefaults.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `resilience/`     | `settings.ts` — definições para disjuntor, período de espera e bloqueio                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `runtime/`        | Deteção de funcionalidades em runtime                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `search/`         | `executeWebSearch.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `services/`       | Framework de serviços incorporados: `ServiceSupervisor.ts` (supervisor genérico de processos-filho com bloqueio de operações, buffer circular e verificador de estado), `bootstrap.ts` (registo ao nível do processo e arranque automático), `registry.ts` (mapa ferramenta → supervisor), `apiKey.ts` (armazenamento de chaves AES-256-GCM), `modelSync.ts` (sincronização periódica de modelos), `ringBuffer.ts` (buffer circular de registos de 5 MB), `healthCheck.ts` (sonda HTTP de estado), `types.ts`, `embedWsProxy.ts` (proxy WebSocket), `installers/{ninerouter,cliproxy}.ts`. Ver `docs/frameworks/EMBEDDED-SERVICES.md`                                                                             |
| `agentSkills/`    | Catálogo + gerador de Competências de Agentes: `catalog.ts` (getCatalog/getSkillById/filterCatalog/computeCoverage), `generator.ts` (generateAgentSkills → escreve em `skills/{id}/SKILL.md`), `openapiParser.ts` (extrai endpoints REST da especificação OpenAPI), `cliRegistryParser.ts` (extrai subcomandos CLI de bin/cli-registry), `schemas.ts` (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), `types.ts` (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Utilizado por rotas REST (`/api/agent-skills/*`), ferramentas MCP (`omniroute_agent_skills_*`) e pela competência A2A `list-capabilities`. Ver [AGENT-SKILLS.md](../frameworks/AGENT-SKILLS.md). |
| `skills/`         | Framework de competências: `registry.ts`, `executor.ts`, `interception.ts`, `injection.ts`, `sandbox.ts`, `custom.ts`, `hybrid.ts`, `builtins.ts`, `a2a.ts`, `providerSettings.ts`, `schemas.ts`, `skillssh.ts`, `types.ts`, além de `builtin/browser.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `spend/`          | `batchWriter.ts` (buffer de escrita diferida)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `sync/`           | `bundle.ts`, `tokens.ts` (Sincronização na Nuvem)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `system/`         | Utilitários ao nível do sistema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `translator/`     | Integração do tradutor de nível superior (delega para `open-sse/translator/`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `usage/`          | Contabilização da utilização: `costCalculator.ts`, `tokenAccounting.ts`, `usageHistory.ts`, `aggregateHistory.ts`, `usageStats.ts`, `callLogs.ts`, `callLogArtifacts.ts`, `fetcher.ts`, `providerLimits.ts`, `migrations.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `versionManager/` | Atualização automática + manifesto de versões                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ws/`             | Ponte WebSocket                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `zed-oauth/`      | Fluxo OAuth do editor Zed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

Ficheiros de nível superior em `src/lib/`:

- O antigo barrel `localDb.ts` foi removido — os consumidores importam diretamente módulos específicos de `src/lib/db/*`.
- `proxyHealth.ts`, `proxyLogger.ts`, `tokenHealthCheck.ts`, `localHealthCheck.ts`
- `apiBridgeServer.ts`, `cacheLayer.ts`, `semanticCache.ts`, `settingsCache.ts`
- `cloudSync.ts`, `initCloudSync.ts`
- `cloudflaredTunnel.ts`, `ngrokTunnel.ts`, `tailscaleTunnel.ts`
- `consoleInterceptor.ts`, `container.ts`, `gracefulShutdown.ts`, `idempotencyLayer.ts`
- `ipUtils.ts`, `logEnv.ts`, `logPayloads.ts`, `logRotation.ts`
- `modelAliasSeed.ts`, `modelCapabilities.ts`, `modelMetadataRegistry.ts`, `modelsDevSync.ts`
- `piiSanitizer.ts`, `pricingSync.ts`
- `apiKeyExposure.ts`, `cacheControlSettings.ts`, `dataPaths.ts`, `toolPolicy.ts`
- `translatorEvents.ts`, `usageDb.ts`, `usageAnalytics.ts`, `webhookDispatcher.ts`

#### 3.2.1 `src/lib/db/`

Base de dados SQLite singleton (`getDbInstance()` em `core.ts`, registo WAL).
**Nunca escreva SQL em bruto em rotas ou handlers** — utilize estes módulos.

![Visão geral do esquema da base de dados (tabelas principais selecionadas)](../diagrams/exported/db-schema-overview.svg)

> Fonte: [diagrams/db-schema-overview.mmd](../diagrams/db-schema-overview.mmd)

Módulos de domínio (cada um gere uma ou mais tabelas): `apiKeys.ts`, `backup.ts`,
`batches.ts`, `cleanup.ts`, `cliToolState.ts`, `combos.ts`,
`commandCodeAuth.ts`, `compression.ts`, `compressionAnalytics.ts`,
`compressionCacheStats.ts`, `compressionCombos.ts`, `compressionScheduler.ts`,
`contextHandoffs.ts`, `core.ts`, `creditBalance.ts`, `databaseSettings.ts`,
`detailedLogs.ts`, `domainState.ts`, `encryption.ts`, `evals.ts`, `files.ts`,
`healthCheck.ts`, `jsonMigration.ts`, `migrationRunner.ts`,
`modelComboMappings.ts`, `models.ts`, `oneproxy.ts`, `prompts.ts`,
`providers.ts`, `providerLimits.ts`, `proxies.ts`, `quotaSnapshots.ts`,
`readCache.ts`, `reasoningCache.ts`, `registeredKeys.ts`, `secrets.ts`,
`sessionAccountAffinity.ts`, `settings.ts`, `stateReset.ts`, `stats.ts`,
`syncTokens.ts`, `tierConfig.ts`, `upstreamProxy.ts`, `versionManager.ts`,
`webhooks.ts`.

`migrations/` contém 168 ficheiros `.sql` com controlo de versão (idempotentes e transacionais) e é
executado por `migrationRunner.ts` no arranque.

Tabelas criadas ao longo das migrações (123 no total):

`a`, `account_key_limits`, `api_keys`, `batches`, `call_logs`,
`combo_adaptation_state`, `combos`, `command_code_auth_sessions`,
`compression_analytics`, `compression_cache_stats`,
`compression_combo_assignments`, `compression_combos`, `context_handoffs`,
`daily_usage_summary`, `db_meta`, `domain_budgets`, `domain_circuit_breakers`,
`domain_cost_history`, `domain_fallback_chains`, `domain_lockout_state`,
`eval_cases`, `eval_runs`, `eval_suites`, `files`, `hourly_usage_summary`,
`key_value`, `mcp_tool_audit`, `memories`, `model_combo_mappings`,
`provider_connections`, `provider_key_limits`, `provider_nodes`,
`proxy_assignments`, `proxy_logs`, `proxy_registry`, `quota_snapshots`,
`reasoning_cache`, `registered_keys`, `request_detail_logs`,
`routing_decisions`, `semantic_cache`, `session_account_affinity`,
`skill_executions`, `skills`, `sync_tokens`, `tier_assignments`,
`tier_config`, `upstream_proxy_config`, `usage_history`, `version_manager`,
`webhooks` (além de tabelas virtuais FTS5 para pesquisa de memória).

### 3.3 `src/domain/` — Camada de domínio

Lógica de negócio pura, sem E/S. Importada por rotas e handlers.

| Ficheiro                                   | Finalidade                                                      |
| ------------------------------------------ | --------------------------------------------------------------- |
| `policyEngine.ts`                          | Resolvedor de políticas de nível superior                       |
| `fallbackPolicy.ts`                        | Árvore de decisão de fallback                                   |
| `costRules.ts`                             | Regras de cálculo de custos                                     |
| `lockoutPolicy.ts`                         | Decisões de bloqueio de modelos                                 |
| `tagRouter.ts`                             | Encaminhamento baseado em etiquetas                             |
| `comboResolver.ts`                         | Resolução de combinações desde o pedido → lista de destinos     |
| `connectionModelRules.ts`                  | Filtros de modelos por ligação                                  |
| `modelAvailability.ts`                     | Verificação da disponibilidade de modelos                       |
| `degradation.ts`                           | Transições para o modo degradado                                |
| `providerExpiration.ts`                    | Deteção de contas/chaves expiradas                              |
| `quotaCache.ts`                            | Decisões de quota em cache                                      |
| `responses.ts`, `omnirouteResponseMeta.ts` | Auxiliares para a estrutura de respostas                        |
| `configAudit.ts`                           | Auditoria de alterações à configuração                          |
| `assessment/`                              | Avaliação de modelos (segundo o RFC, parcialmente implementada) |
| `types.ts`                                 | Tipos de domínio partilhados                                    |

### 3.4 `src/server/` — Exclusivo do servidor

Não pode ser importado a partir de componentes de cliente.

```
server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Classifica as rotas como públicas ou de gestão
│   ├── assertAuth.ts      Auxiliar de asserção
│   ├── context.ts         Contexto de authz por pedido
│   ├── headers.ts
│   ├── pipeline.ts        Pipeline de authz
│   ├── policies/          Políticas concretas
│   └── types.ts
└── cors/origins.ts        Lista de origens CORS permitidas
```

### 3.5 `src/shared/` — Seguro para partilhar

Dividido em subdiretórios específicos:

- `constants/` — `providers.ts` (catálogo de fornecedores validado pelo Zod), `models.ts`,
  `modelSpecs.ts`, `modelCompat.ts`, `pricing.ts`, `cliTools.ts`,
  `cliCompatProviders.ts`, `routingStrategies.ts`, `comboConfigMode.ts`,
  `headers.ts`, `upstreamHeaders.ts` (lista de bloqueio), `mcpScopes.ts`,
  `errorCodes.ts`, `publicApiRoutes.ts`, `batch.ts`, `batchEndpoints.ts`,
  `bodySize.ts`, `colors.ts`, `appConfig.ts`, `config.ts`,
  `sidebarVisibility.ts`, `visionBridgeDefaults.ts`.
- `validation/` — `schemas.ts` (~80 esquemas Zod), `compressionConfigSchemas.ts`,
  `providerSchema.ts`, `settingsSchemas.ts`, `helpers.ts`.
- `contracts/` — contratos da API pública disponibilizados no npm.
- `types/` — tipos TS partilhados.
- `utils/` — `circuitBreaker.ts`, `apiAuth.ts`, `apiKey.ts`, `apiKeyPolicy.ts`,
  `api.ts`, `classify429.ts`, `cliCompat.ts`, `clipboard.ts`, `cloud.ts`, `cn.ts`,
  `cors.ts`, `featureFlags.ts`,
  `fetchTimeout.ts`, `formatting.ts`, `inputSanitizer.ts`, `logger.ts`,
  `machine.ts`, `machineId.ts`, `maskEmail.ts`, `modelCatalogSearch.ts`,
  `nodeRuntimeSupport.ts`, `parseApiKeys.ts`, `providerHints.ts`,
  `providerModelAliases.ts`, `rateLimiter.ts`, `releaseNotes.ts`,
  `a11yAudit.ts`, além de hooks/componentes do painel em `services/`, `network/`,
  `middleware/`, `schemas/`, `hooks/`, `components/`.

---

## 4. `open-sse/` — Área de trabalho do motor de streaming

Área de trabalho npm separada, publicada como `@omniroute/open-sse`. Responsável pelo processamento
de pedidos, executores, tradutores, serviços, transformador e servidor MCP.

```
open-sse/
├── index.ts                Exportações públicas
├── package.json            Manifesto da área de trabalho
├── tsconfig.json
├── types.d.ts
├── config/                 Registos de fornecedores, perfis de cabeçalhos, identidade, …
├── handlers/               Processadores de pedidos (conversação, embeddings, áudio, imagem, …)
├── executors/              156 módulos executores de fornecedores (classes de executor + auxiliares por fornecedor)
├── translator/             Conversão de formatos (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformador de streams da Responses API ↔ Chat Completions
├── services/               Mais de 80 módulos de serviço (combinações, recurso, quotas, identidade, …)
├── utils/                  Auxiliares de streaming, cliente TLS, AWS SigV4, obtenção via proxy, …
└── mcp-server/             Servidor MCP (3 transportes, 33 âmbitos, 110 ferramentas)
```

### 4.1 `open-sse/handlers/`

| Processador             | Finalidade                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `chatCore.ts`           | Pipeline principal de conversação (cache, limite de pedidos, encaminhamento de combinações, despacho de executores) |
| `responsesHandler.ts`   | Ponto de entrada da OpenAI Responses API                                                                            |
| `embeddings.ts`         | Embeddings                                                                                                          |
| `imageGeneration.ts`    | Geração de imagens                                                                                                  |
| `audioSpeech.ts`        | Conversão de texto em voz                                                                                           |
| `audioTranscription.ts` | Conversão de voz em texto                                                                                           |
| `videoGeneration.ts`    | Geração de vídeo                                                                                                    |
| `musicGeneration.ts`    | Geração de música                                                                                                   |
| `rerank.ts`             | Reordenação                                                                                                         |
| `moderations.ts`        | Moderação                                                                                                           |
| `search.ts`             | Pesquisa na Web                                                                                                     |
| `sseParser.ts`          | Analisador de eventos SSE                                                                                           |
| `usageExtractor.ts`     | Extrai contagens de tokens dos streams a montante                                                                   |
| `responseSanitizer.ts`  | Remove ruído específico do fornecedor                                                                               |
| `responseTranslator.ts` | Ligação entre a resposta do fornecedor e a camada de tradução                                                       |

### 4.2 `open-sse/executors/`

156 módulos executores de nível superior (`*.ts` menos `base.ts`, `index.ts` e testes — a contagem
é medida por `npm run check:docs-counts`). Cada classe de executor estende `BaseExecutor` (`base.ts`),
diretamente ou através de `DefaultExecutor` ou de outro executor; os restantes módulos são auxiliares
por fornecedor (esquemas de ferramentas, adaptadores de obtenção/TTS, processadores de particularidades). Os executores incluem:

`antigravity`, `azure-openai`, `blackbox-web`, `cliproxyapi`,
`chatgpt-web-codex`, `cloudflare-ai`, `codex`, `commandCode`, `cursor`, `default`, `devin-cli`,
`muse-spark-web`, `nlpcloud`, `opencode`, `perplexity-web`, `petals`,
`pollinations`, `qoder`, `vertex`, `devin-desktop`, além de `claudeIdentity.ts`
(auxiliar de identidade partilhado) e `index.ts` (registo).

> Nota: os fornecedores não indicados aqui são servidos por `default.ts`, utilizando o executor
> genérico compatível com OpenAI. O catálogo completo de fornecedores (375 fornecedores) encontra-se em
> `src/shared/constants/providers.ts`.

### 4.3 `open-sse/translator/`

Tradução em topologia radial (OpenAI é o núcleo).

- **9 tradutores de pedidos** (`translator/request/`):
  `antigravity-to-openai`, `claude-to-gemini`, `claude-to-openai`,
  `gemini-to-openai`, `openai-responses`, `openai-to-claude`,
  `openai-to-cursor`, `openai-to-gemini`, `openai-to-kiro`.
- **9 tradutores de respostas** (`translator/response/`):
  `claude-to-openai`, `cursor-to-openai`, `gemini-to-claude`, `gemini-to-openai`,
  `kiro-to-openai`, `openai-responses`, `openai-to-antigravity`,
  `openai-to-claude`.
- **9 auxiliares** (`translator/helpers/`):
  `claudeHelper`, `geminiHelper`, `geminiToolsSanitizer`, `maxTokensHelper`,
  `openaiHelper`, `responsesApiHelper`, `schemaCoercion`, `toolCallHelper`, além
  de testes dos auxiliares.
- **Auxiliares de imagem** (`translator/image/sizeMapper.ts`).
- Nível superior: `bootstrap.ts`, `formats.ts`, `registry.ts`, `index.ts`.

### 4.4 `open-sse/transformer/`

- `responsesTransformer.ts` — conversor baseado em `TransformStream` entre a Responses API ↔ Chat
  Completions (utilizado pela rota genérica `responses/`).

### 4.5 `open-sse/services/`

Destaques (lista completa em `open-sse/services/`):

| Área                           | Ficheiros                                                                                                                                                                                                                                                |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Encaminhamento Combo           | `combo.ts` (20 estratégias), `comboConfig.ts`, `comboMetrics.ts`, `comboManifestMetrics.ts`, `comboAgentMiddleware.ts`                                                                                                                                   |
| Motor Auto Combo               | `autoCombo/` — `engine.ts`, `scoring.ts`, `taskFitness.ts`, `virtualFactory.ts`, `modePacks.ts`, `autoPrefix.ts`, `persistence.ts`, `providerDiversity.ts`, `providerRegistryAccessor.ts`, `routerStrategy.ts`, `selfHealing.ts`, `index.ts`             |
| Resiliência                    | `accountFallback.ts` (período de espera + bloqueio), `errorClassifier.ts`, `requestRejectedStreak.ts`, `emergencyFallback.ts`, `rateLimitManager.ts`, `rateLimitSemaphore.ts`, `accountSemaphore.ts`, `accountSelector.ts`                               |
| Quotas                         | `quotaMonitor.ts`, `quotaPreflight.ts`, `bailianQuotaFetcher.ts`, `codexQuotaFetcher.ts`, `deepseekQuotaFetcher.ts`, `openrouterQuotaFetcher.ts`, `openrouterFreeWindow.ts`, `llmgatewayQuotaFetcher.ts`, `crofUsageFetcher.ts`, `antigravityCredits.ts` |
| Colocação em cache             | `reasoningCache.ts`, `searchCache.ts`, `signatureCache.ts`, `requestDedup.ts`                                                                                                                                                                            |
| Inteligência de encaminhamento | `intentClassifier.ts`, `taskAwareRouter.ts`, `backgroundTaskDetector.ts`, `volumeDetector.ts`, `wildcardRouter.ts`, `workflowFSM.ts`, `specificityDetector.ts`, `specificityRules.ts`, `specificityTypes.ts`                                             |
| Processamento de modelos       | `modelCapabilities.ts`, `modelDeprecation.ts`, `modelFamilyFallback.ts`, `modelStrip.ts`, `model.ts`, `provider.ts`, `providerRequestDefaults.ts`, `providerCostData.ts`, `payloadRules.ts`                                                              |
| Compressão                     | `compression/` — integração completa do motor de compressão                                                                                                                                                                                              |
| Tokens + sessões               | `tokenRefresh.ts`, `sessionManager.ts`, `apiKeyRotator.ts`, `contextManager.ts`, `contextHandoff.ts`, `systemPrompt.ts`, `roleNormalizer.ts`, `responsesInputSanitizer.ts`, `toolSchemaSanitizer.ts`, `toolLimitDetector.ts`, `thinkingBudget.ts`        |
| Nível / manifesto              | `tierResolver.ts`, `tierConfig.ts`, `tierDefaults.json`, `tierTypes.ts`, `manifestAdapter.ts`                                                                                                                                                            |
| IP / rede                      | `ipFilter.ts`, `webSearchFallback.ts`                                                                                                                                                                                                                    |
| Lotes                          | `batchProcessor.ts`                                                                                                                                                                                                                                      |
| Utilização                     | `usage.ts`                                                                                                                                                                                                                                               |

### 4.6 `open-sse/mcp-server/`

- **110 ferramentas únicas** integradas em `server.ts` (45 canónicas em `schemas/tools.ts` +
  módulos de memória, competências, competências do GitHub, pool, gamificação, plug-ins, Notion, Obsidian,
  corpus local e compressão — união contabilizada por `countUniqueMcpTools`).
- **3 transportes**: stdio, HTTP Streamable, SSE.
- **33 âmbitos** aplicados em tempo de execução — lista base em `src/shared/constants/mcpScopes.ts`; o conjunto completo corresponde à união dos âmbitos declarados por cada módulo de ferramentas.
- Tabela de auditoria: `mcp_tool_audit` (preenchida por `audit.ts`).
- Ficheiros: `server.ts`, `index.ts`, `httpTransport.ts`, `audit.ts`, `scopeEnforcement.ts`,
  `runtimeHeartbeat.ts`, `descriptionCompressor.ts`, `schemas/{tools, a2a, audit, index}.ts`,
  `tools/{advancedTools, compressionTools, memoryTools, skillTools}.ts`,
  além dos testes em `__tests__/`.
- Consulte [MCP-SERVER.md](../frameworks/MCP-SERVER.md) para ver o catálogo completo de ferramentas.

### 4.7 `open-sse/config/`

Registos de fornecedores (`providerRegistry.ts`, `providerModels.ts`,
`providerHeaderProfiles.ts`), registos de modelos por formato (`audioRegistry.ts`,
`embeddingRegistry.ts`, `imageRegistry.ts`, `moderationRegistry.ts`,
`musicRegistry.ts`, `rerankRegistry.ts`, `searchRegistry.ts`, `videoRegistry.ts`),
auxiliares de identidade (`codexIdentity.ts`, `codexInstructions.ts`,
`anthropicHeaders.ts`, `antigravityUpstream.ts`, `antigravityModelAliases.ts`,
`cliFingerprints.ts`, `toolCloaking.ts`, `defaultThinkingSignature.ts`),
auxiliares de credenciais (`credentialLoader.ts`, `codexClient.ts`) e adaptadores
de nuvem (`azureAi.ts`, `bedrock.ts`, `datarobot.ts`, `glmProvider.ts`,
`maritalk.ts`, `oci.ts`, `petals.ts`, `runway.ts`, `sap.ts`, `watsonx.ts`,
`ollamaModels.ts`, `errorConfig.ts`, `constants.ts`, `registryUtils.ts`).

### 4.8 `open-sse/utils/`

Primitivas de streaming e auxiliares de fornecedores: `stream.ts`, `streamHandler.ts`,
`streamHelpers.ts`, `streamPayloadCollector.ts`, `streamReadiness.ts`,
`sseHeartbeat.ts`, `proxyFetch.ts`, `proxyDispatcher.ts`, `tlsClient.ts`,
`networkProxy.ts`, `awsSigV4.ts`, `cacheControlPolicy.ts`,
`cursorChecksum.ts`, `cursorAgentProtobuf.ts`, `cursorVersionDetector.ts`,
`comfyuiClient.ts`, `kieTask.ts`, `bypassHandler.ts`, `aiSdkCompat.ts`,
`thinkTagParser.ts`, `urlSanitize.ts`, `usageTracking.ts`, `requestLogger.ts`,
`progressTracker.ts`, `cors.ts`, `error.ts`, `logger.ts`, `sleep.ts`,
`ollamaTransform.ts`.

---

## 5. `electron/` — Invólucro de ambiente de trabalho

```
electron/
├── main.js                  Processo principal do Electron
├── preload.js               Ponte de pré-carregamento (contextIsolation ativado)
├── types.d.ts
├── package.json             Configuração do electron-builder, versão 3.8.51
├── README.md
├── assets/                  Recursos de compilação (ícones, direitos, …)
├── node_modules/            node_modules dedicado (better-sqlite3, electron-updater)
└── dist-electron/           Resultado da compilação (não incluído no repositório)
```

Cinco scripts npm na raiz do espaço de trabalho: `electron:dev`, `electron:build`,
`electron:build:{win,mac,linux}`, `electron:smoke:packaged`. A atualização automática é efetuada através do
`electron-updater`, que aponta para o feed de versões do GitHub.

---

## 6. `bin/` — CLI

```
bin/
├── omniroute.mjs           Ponto de entrada principal da CLI (Node ESM)
├── reset-password.mjs      Repor a palavra-passe de gestão a partir da CLI
├── mcp-server.mjs          Iniciador do servidor MCP (stdio)
├── nodeRuntimeSupport.mjs  Verificação da versão do Node
└── cli/
    ├── program.mjs         Construtor do programa Commander
    ├── runtime.mjs         Auxiliar withRuntime (primeiro o servidor/recurso à BD em alternativa)
    ├── output.mjs          Formatadores de saída (json/jsonl/table/csv)
    ├── i18n.mjs            Auxiliar t() com idiomas
    ├── api.mjs             Auxiliar de pedidos à API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Registo de comandos
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (um ficheiro por comando/grupo)
```

São expostos dois binários em `package.json` → `bin`:

- `omniroute` → `bin/omniroute.mjs`
- `omniroute-reset-password` → `bin/reset-password.mjs`

---

## 7. `tests/`

| Diretório                                            | Tipo                                                                                                                             |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`                                        | Testes unitários através do executor de testes nativo do Node (1821 ficheiros, além dos subdiretórios `api/`, `auth/`, `authz/`) |
| `tests/integration/`                                 | Testes entre módulos e do estado da BD                                                                                           |
| `tests/e2e/`                                         | Testes de IU com Playwright                                                                                                      |
| `tests/e2e/protocol-clients.test.ts`                 | Testes e2e dos protocolos MCP/A2A                                                                                                |
| `tests/translator/`                                  | Testes específicos do tradutor                                                                                                   |
| `tests/security/`                                    | Regressões de segurança                                                                                                          |
| `tests/load/`                                        | Testes de carga/esforço                                                                                                          |
| `tests/golden-set/`                                  | Resultados de referência para regressões do tradutor                                                                             |
| `tests/helpers/`, `tests/fixtures/`, `tests/manual/` | Suporte                                                                                                                          |

Comandos comuns:

| Comando                                                  | O que executa                                                                           |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `npm run test:unit`                                      | Todos os `tests/unit/*.test.ts` através do executor de testes do Node (concorrência 10) |
| `npm run test:vitest`                                    | Conjunto de testes Vitest (MCP, autoCombo, cache)                                       |
| `npm run test:e2e`                                       | Conjunto de testes de IU Playwright                                                     |
| `npm run test:protocols:e2e`                             | Testes e2e dos protocolos MCP + A2A                                                     |
| `npm run test:coverage`                                  | Limite de cobertura (≥60% de linhas/instruções/funções/ramos)                           |
| `node --import tsx/esm --test tests/unit/<file>.test.ts` | Execução de um único ficheiro                                                           |

---

## 8. `scripts/`

Organizada em 6 subpastas por finalidade.

- **`scripts/build/`** — `build-next-isolated.mjs`, `prepublish.ts`,
  `prepare-electron-standalone.mjs`, `pack-artifact-policy.ts`,
  `validate-pack-artifact.ts`, `postinstall.mjs`, `postinstallSupport.mjs`,
  `uninstall.mjs`, `bootstrap-env.mjs`, `runtime-env.mjs`,
  `native-binary-compat.mjs`.
- **`scripts/dev/`** — `run-next.mjs`, `run-next-playwright.mjs`,
  `run-standalone.mjs`, `standalone-server-ws.mjs`, `responses-ws-proxy.mjs`,
  `v1-ws-bridge.mjs`, `smoke-electron-packaged.mjs`,
  `run-playwright-tests.mjs`, `run-ecosystem-tests.mjs`,
  `run-protocol-clients-tests.mjs`, `sync-env.mjs`, `healthcheck.mjs`,
  `system-info.mjs`, além dos auxiliares só de leitura para acompanhamento de PRs
  `ci-discriminate.sh` (classifica as assinaturas das verificações falhadas de um PR como próprias /
  herdadas / desconhecidas, comparando-as com um PR de referência ou com a issue relativa a falhas
  na base) e `audit-worktree.sh`
  (ficheiros alterados, superfícies protegidas, asserções removidas, contagens de supressões,
  tsconfigs temporários remanescentes, head do PR face ao HEAD local — antes de o PR de um worker ser aceite).
- **`scripts/check/`** — `check-cycles.mjs`, `check-docs-sync.mjs`,
  `check-docs-counts-sync.mjs`, `check-env-doc-sync.mjs`,
  `check-deprecated-versions.mjs`, `check-route-validation.mjs`,
  `check-t11-any-budget.mjs`, `check-pr-test-policy.mjs`,
  `check-supported-node-runtime.ts`, `test-report-summary.mjs`.
- **`scripts/docs/`** — `generate-docs-index.mjs`, `gen-provider-reference.ts`.
- **`scripts/i18n/`** — `generate-multilang.mjs`, `run-visual-qa.mjs`,
  `generate-qa-checklist.mjs`, `apply-priority-overrides.mjs`,
  `validate_translation.py`, `check_translations.py`, `i18n_autotranslate.py`,
  `untranslatable-keys.json`.
- **`scripts/ad-hoc/`** — `cursor-tap.cjs`, `sync-cursor-models.mjs`,
  `migrate-env.mjs`, `dbsetup.js`.

---

## 9. Pipeline de pedidos (resumo)

![Pipeline de pedidos (/v1/chat/completions)](../diagrams/exported/request-pipeline.svg)

> Fonte: [diagrams/request-pipeline.mmd](../diagrams/request-pipeline.mmd)

```
Pedido do cliente
  → /v1/chat/completions (route.ts)
     Verificação de preflight CORS
     Validação Zod (chatCompletionsSchema em shared/validation/schemas.ts)
     Autenticação (extractApiKey + isValidApiKey OU requireManagementAuth)
     Motor de políticas (src/server/authz/pipeline.ts)
     Medidas de proteção (mascarador de PII, injeção de prompts, ponte de visão)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Verificação da cache (cache semântica + cache de leitura)
     Limitação de taxa (rateLimitManager, accountSemaphore)
     Encaminhamento combinado (se o modelo for resolvido para uma combinação)
       comboResolver → ciclo por destino → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       pedido fetch a montante → nova tentativa/recuo através de accountFallback
     translateResponse() (open-sse/translator/response/*)
     Stream SSE OU resposta JSON
     Se for a Responses API: TransformStream através de open-sse/transformer/responsesTransformer.ts
  → Auditoria de conformidade (src/lib/compliance/)
  → Resposta ao cliente
```

### Estado de execução da resiliência (três mecanismos)

| Mecanismo                    | Âmbito                        | Onde                                                                                                           |
| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Disjuntor do fornecedor      | Fornecedor completo           | `src/shared/utils/circuitBreaker.ts`, persistido em `domain_circuit_breakers`                                  |
| Período de espera da ligação | Uma conta/chave               | `markAccountUnavailable()` em `src/sse/services/auth.ts`; utilizado por `accountFallback.checkFallbackError()` |
| Bloqueio do modelo           | Fornecedor + ligação + modelo | `open-sse/services/accountFallback.ts`, persistido em `domain_lockout_state`                                   |

Consulte [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) e a secção dedicada em
[CLAUDE.md](../../CLAUDE.md).

---

## 10. Como contribuir

### Adicionar um novo fornecedor

1. Registe-o em `src/shared/constants/providers.ts` (validado pelo Zod durante o carregamento).
2. Adicione um executor em `open-sse/executors/` se for necessária lógica personalizada
   (estenda `BaseExecutor`).
3. Adicione um tradutor em `open-sse/translator/` se não utilizar o formato da OpenAI.
4. Se for baseado em OAuth, adicione a configuração em `src/lib/oauth/providers/` e
   `src/lib/oauth/services/`.
5. Registe os modelos em `open-sse/config/providerRegistry.ts` (ou no registo específico
   do formato em `open-sse/config/`).
6. Escreva testes em `tests/unit/`.

### Adicionar uma nova rota da API

1. Crie `src/app/api/your-route/route.ts`.
2. Siga o padrão: CORS → validação do corpo com Zod → autenticação → delegação ao manipulador.
3. Se houver uma nova estrutura de pedido: adicione o esquema Zod em `src/shared/validation/schemas.ts`.
4. Se for apenas para gestão: adicione o caminho a `src/shared/constants/publicApiRoutes.ts`
   (lista de exclusão da superfície pública da API).
5. Adicione testes em `tests/unit/`.
6. Atualize `docs/reference/API_REFERENCE.md` e `docs/openapi.yaml`.

### Adicionar um novo módulo de BD

1. Crie `src/lib/db/yourModule.ts` e importe `getDbInstance()` de `./core.ts`.
2. Exporte funções CRUD para o seu domínio.
3. Se houver novas tabelas: adicione uma migração em `src/lib/db/migrations/`, numerada
   sequencialmente, idempotente e transacional.
4. Os módulos que importam utilizam importações diretas de `@/lib/db/yourModule` (sem barrel — a antiga camada de reexportação `localDb.ts` foi removida).
5. Adicione testes em `tests/unit/`.

### Adicionar uma nova ferramenta MCP

1. Adicione a definição da ferramenta em `open-sse/mcp-server/tools/` (ou estenda
   `open-sse/mcp-server/schemas/tools.ts`).
2. Atribua o(s) âmbito(s) adequado(s) em `src/shared/constants/mcpScopes.ts`.
3. Registe a ferramenta em `open-sse/mcp-server/server.ts`.
4. Adicione testes em `open-sse/mcp-server/__tests__/`.
5. Atualize [MCP-SERVER.md](../frameworks/MCP-SERVER.md).

### Adicionar uma nova competência A2A

Consulte [A2A-SERVER.md § Adicionar uma nova competência](../frameworks/A2A-SERVER.md). As competências encontram-se em
`src/lib/a2a/skills/` e são registadas através do gestor de tarefas A2A.

---

## 11. Convenções

- **Estilo de código**: indentação de 2 espaços, aspas duplas, largura de 100 caracteres, pontos e vírgulas,
  vírgulas finais `es5` — imposto pelo Prettier através de `lint-staged`.
- **Importações**: externas → internas (`@/`, `@omniroute/open-sse`) → relativas.
- **Nomenclatura**: ficheiros em `camelCase` ou `kebab-case`, componentes em `PascalCase`,
  constantes em `UPPER_SNAKE`.
- **ESLint**: `no-eval`, `no-implied-eval`, `no-new-func` = `error` em todo o lado;
  `no-explicit-any` = `warn` em `open-sse/` e `tests/`, erro nos restantes locais.
- **TypeScript**: `strict: false` (postura herdada). Prefira tipos explícitos à
  inferência nos limites entre módulos.
- **Base de dados**: nunca escreva SQL em bruto em rotas ou manipuladores — utilize sempre
  os módulos de `src/lib/db/`. Nunca importe através de um barrel — utilize diretamente módulos `src/lib/db/*` específicos.
- **Tipagem de entidades da BD (#3512)**: uma função que escreva ou leia a estrutura
  de uma linha de uma tabela da BD deve receber/devolver uma interface TS com nome que corresponda
  às colunas dessa tabela numa relação 1:1, e não `any` nem um tipo anónimo inline no local da chamada. Coloque
  a interface junto da função (por exemplo, `export interface UsageEntry` em
  `src/lib/usage/usageHistory.ts`, acima de `saveRequestUsage`), mantenha os campos
  individuais opcionais/anuláveis quando diferentes processos de escrita preencherem a linha
  incrementalmente e prefira `unknown` a `any` para um campo cuja estrutura
  varie entre chamadores (documentado no campo; por exemplo, `UsageEntry.tokens`
  aceita tanto a utilização em bruto com a estrutura do fornecedor como a estrutura normalizada). Quando a
  contagem de `any` de um ficheiro chegar a zero desta forma, adicione-o à lista de permissões
  `check:any-budget:t11` (`scripts/check/check-t11-any-budget.mjs`,
  `maxAny: 0`) para impedir regressões. Esta é uma convenção inicial — a
  limpeza mais abrangente de «nenhum `any` anónimo» é iterativa no restante
  código-base.
- **Erros**: utilize try/catch com tipos de erro específicos e registe com contexto pino. Nunca
  ignore silenciosamente erros em fluxos SSE; utilize sinais de cancelamento para a limpeza.
- **Segurança**: nunca utilize `eval()` / `new Function()` / eval implícito. Valide
  todas as entradas com Zod. Encripte as credenciais armazenadas (AES-256-GCM). Mantenha
  a lista de exclusão `src/shared/constants/upstreamHeaders.ts` alinhada com a
  camada de sanitização/validação.
- **Commits**: Conventional Commits — `feat(scope): subject`. Âmbitos permitidos:
  `db`, `sse`, `oauth`, `dashboard`, `api`, `cli`, `docker`, `ci`, `mcp`,
  `a2a`, `memory`, `skills`.
- **Ramos**: prefixos `feat/`, `fix/`, `refactor/`, `docs/`, `test/`,
  `chore/`. Nunca faça commits diretamente em `main`.
- **Husky**: o pre-commit executa `lint-staged` + `check:docs-sync` +
  `check:any-budget:t11`; o pre-push executa `check:any-budget:t11` + `check:tracked-artifacts` (verificações rápidas; exclui `test:unit`).

---

## 12. Regras Rígidas (de CLAUDE.md)

1. Nunca faça commit de segredos ou credenciais.
2. Nunca utilize importações agregadas — utilize diretamente módulos específicos de `src/lib/db/*`.
3. Nunca utilize `eval()` / `new Function()` / eval implícito.
4. Nunca faça commits diretamente em `main`.
5. Nunca escreva SQL em bruto nas rotas — utilize sempre os módulos de `src/lib/db/`.
6. Nunca ignore silenciosamente erros em fluxos SSE.
7. Valide sempre as entradas com esquemas Zod.
8. Inclua sempre testes ao alterar código de produção.
9. A cobertura deve manter-se ≥ 60% (instruções, linhas, funções, ramificações).

---

## 13. Consulte Também

- [ARCHITECTURE.md](./ARCHITECTURE.md) — arquitetura de alto nível e responsabilidades
  dos módulos.
- [API_REFERENCE.md](../reference/API_REFERENCE.md) — referência da API pública e de gestão.
- [FEATURES.md](../guides/FEATURES.md) — matriz de funcionalidades e destaques das versões.
- [RESILIENCE_GUIDE.md](./RESILIENCE_GUIDE.md) — análise aprofundada do disjuntor, período de espera
  e bloqueio.
- [AUTO-COMBO.md](../routing/AUTO-COMBO.md) — pontuação e estratégias do Auto Combo.
- [MCP-SERVER.md](../frameworks/MCP-SERVER.md) — catálogo completo de ferramentas MCP e transportes.
- [A2A-SERVER.md](../frameworks/A2A-SERVER.md) — competências e descoberta do protocolo A2A.
- [COMPRESSION_GUIDE.md](../compression/COMPRESSION_GUIDE.md) — compressão RTK e Caveman.
- [CLI-TOOLS.md](../reference/CLI-TOOLS.md) — integrações CLI.
- [ELECTRON_GUIDE.md](../guides/ELECTRON_GUIDE.md) (se presente), [DOCKER_GUIDE.md](../guides/DOCKER_GUIDE.md), [FLY_IO_DEPLOYMENT_GUIDE.md](../ops/FLY_IO_DEPLOYMENT_GUIDE.md), [VM_DEPLOYMENT_GUIDE.md](../ops/VM_DEPLOYMENT_GUIDE.md), [TERMUX_GUIDE.md](../guides/TERMUX_GUIDE.md), [PWA_GUIDE.md](../guides/PWA_GUIDE.md) — destinos de implementação.
- [TROUBLESHOOTING.md](../guides/TROUBLESHOOTING.md) — problemas operacionais comuns.
- [CONTRIBUTING.md](../../CONTRIBUTING.md) — fluxo de trabalho dos colaboradores.
- [CLAUDE.md](../../CLAUDE.md) — regras do repositório para o Claude Code (a fonte de verdade
  para muitas das convenções acima).
- [AGENTS.md](../../AGENTS.md) — referência de arquitetura mais aprofundada utilizada pelos agentes.