OmniRoute/docs/i18n/pt/docs/architecture/CODEBASE_DOCUMENTATION.md

OmniRoute Codebase Documentation (Português (Portugal))

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

---

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. 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.
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.

Fonte: 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/ — Workspace do motor de streaming

Workspace npm separado, publicado como @omniroute/open-sse. Responsável pelo processamento de pedidos, executores, tradutores, serviços, transformer e servidor MCP.

open-sse/
├── index.ts                Exportações públicas
├── package.json            Manifesto do workspace
├── tsconfig.json
├── types.d.ts
├── config/                 Registos de fornecedores, perfis de cabeçalhos, identidade, …
├── handlers/               Processadores de pedidos (chat, embeddings, áudio, imagem, …)
├── executors/              108 executores HTTP específicos de fornecedores
├── translator/             Conversão de formatos (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformer de streams da Responses API ↔ Chat Completions
├── services/               Mais de 80 módulos de serviço (combinações, fallback, 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 chat (cache, limite de taxa, encaminhamento de combinações, despacho do executor)
responsesHandler.ts	Ponto de entrada da Responses API da OpenAI
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/

108 executores de fornecedores, cada um derivado de BaseExecutor (base.ts):

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 a OpenAI. O catálogo completo de fornecedores (355 fornecedores) encontra-se em src/shared/constants/providers.ts.

4.3 open-sse/translator/

Tradução segundo o modelo hub-and-spoke (a OpenAI é o hub).

• 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).
• No nível superior: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — Conversor da Responses API ↔ Chat Completions baseado em TransformStream (utilizado pelo catch-all da rota responses/).

4.5 open-sse/services/

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

Aspeto	Ficheiros
Encaminhamento Combo	combo.ts (19 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, 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, 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
Gestão 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 é a 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 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.
• 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)

Fonte: 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 e a secção dedicada em 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.

Adicionar uma nova competência A2A

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