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

OmniRoute Codebase Documentation (Português (Brasil))

🌐 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 · 🇷🇴 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 com o OmniRoute ou criam integrações sobre ele.

Para diagramas de arquitetura de alto nível e a justificativa por trás de cada subsistema, leia ARCHITECTURE.md. Para análises aprofundadas de subsistemas individuais (Auto Combo, servidor MCP, servidor A2A, Skills, Memory, Cloud Agents, Resilience, Compression etc.), consulte seus arquivos dedicados neste diretório docs/.

Este arquivo descreve o que existe atualmente no repositório para que um novo engenheiro possa navegar pela árvore, entender as camadas de runtime e saber onde adicionar código sem criar novos módulos.

---

1. Stack de tecnologias

Aspecto	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 por engines + SUPPORTED_NODE_RANGE)
Banco de dados	SQLite via 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)
Build	Next.js autônomo via scripts/build/build-next-isolated.mjs
Lint/formatação	Configuração flat do ESLint + Prettier (lint-staged via pre-commit do Husky)
Sistema de módulos	ESM em todos os lugares ("type": "module")
Workspaces	Workspace npm — open-sse é o único sub-workspace

Aliases de caminho (tsconfig.json):

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

Porta HTTP padrão: 20128 (a API e o dashboard compartilham o mesmo processo). O diretório de dados é definido pela variável de ambiente DATA_DIR, com o padrão ~/.omniroute/.

---

2. Estrutura do repositório

OmniRoute/
├── src/                  Aplicação Next.js (App Router, bibliotecas, domínio, servidor, compartilhados)
├── open-sse/             Workspace do mecanismo 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, de integração, e2e, protocols-e2e, tradutor, segurança, fixtures
├── scripts/              Scripts auxiliares de build, sincronização, verificação, migração e runtime
├── docs/                 Documentação pública (este diretório)
├── public/               Recursos estáticos, manifesto PWA, service worker
├── config/               Exemplos de configuração de runtime
├── images/               Recursos de marketing/capturas de tela
├── _ideia/, _references/, _mono_repo/, _tasks/   Rascunhos/planejamento internos (não distribuídos)
├── CLAUDE.md             Regras do repositório para o Claude Code
├── AGENTS.md             Referência de arquitetura mais detalhada para agentes
├── package.json          v3.8.51, raiz do workspace
└── tsconfig.json         Aliases de caminho + opções principais do compilador

---

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

src/
├── app/                  Páginas do App Router + rotas de API
├── lib/                  Bibliotecas principais (BD, autenticação, OAuth, habilidades, memória, …)
├── domain/               Camada de domínio pura (política, fallback, custo, bloqueio, …)
├── server/               Módulos exclusivos do servidor (autorização, CORS, autenticação)
├── shared/               Tipos, constantes, validação, contratos, utilitários (seguros entre fronteiras)
├── mitm/                 Auxiliares de proxy man-in-the-middle para integração com CLI
├── models/               Metadados / aliases de modelos locais
├── sse/                  Manipuladores SSE legados que ainda residem em src/ (não em open-sse/)
├── store/                Stores de estado do lado do cliente
├── middleware/           Utilitários de middleware no nível da rota (não o middleware global do Next.js)
├── scripts/              Scripts internos à árvore importáveis pelo código da aplicação
├── types/                Tipos TS globais e compartilhados
├── i18n/                 Pacotes de localização
├── instrumentation.ts    Hook de instrumentação do Next.js
├── instrumentation-node.ts
└── proxy.ts              Auxiliar de inicialização do proxy no nível superior

3.1 src/app/ — App Router

O App Router expõe tanto a interface do dashboard quanto a API HTTP pública/de gerenciamento. Não há middleware global — a interceptação é feita por rota.

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

Caminho	Finalidade
api/	Todas as rotas da API HTTP (veja os 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 dashboard (grupo de rotas, sem prefixo de URL)
auth/, login/, forgot-password/, callback/	Fluxos de autenticação
landing/	Página de marketing/landing page
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 do 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 arquivos 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/   Gerenciamento de serviços integrados (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         API pública compatível com OpenAI
├── v1beta/     Compatibilidade no estilo Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Gerenciamento de serviços integrados

Rotas para instalar, iniciar, interromper e monitorar o 9Router e o CLIProxyAPI. Todos os caminhos são classificados como LOCAL_ONLY (somente loopback, regra rígida nº 17), pois podem executar npm install e gerar processos filhos.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             auxiliar getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install via 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 uma nova chave de API + reiniciar
│   ├── status/route.ts     GET  — status em tempo real + no banco de dados + 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  — status em tempo real + no banco de dados + metadados da versão
│   └── auto-start/route.ts POST — alternar o sinalizador auto_start
└── [name]/
    └── logs/route.ts       GET  — acompanhamento de logs via SSE (compartilhado por todos os serviços)

Interface correspondente do painel: src/app/(dashboard)/dashboard/providers/services/ — página com duas abas (CLIProxyAPI + 9Router). Proxy reverso para a interface incorporada do 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

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

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

v1/
├── accounts/[id]/                       consulta de conta
├── agents/tasks/[id]/, agents/tasks/    endpoints de tarefas no estilo A2A
├── api/                                 auxiliares internos da API expostos em v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      API de lotes da OpenAI
├── chat/completions/                    conclusões de chat (o endpoint principal)
├── completions/                         conclusões de texto legadas
├── embeddings/                          embeddings
├── files/[id]/, files/                  API de arquivos
├── _helpers/                            auxiliares de rota compartilhados (sem URL pública)
├── images/{edits, generations}/         geração + edição de imagens
├── issues/                              endpoints auxiliares de triagem
├── management/{proxies}/                rotas com escopo de gerenciamento dentro de v1
├── messages/{count_tokens}/             compatibilidade com mensagens no estilo Anthropic
├── models/                              listagem de modelos (`route.ts`, `catalog.ts`)
├── moderations/                         moderação
├── music/                               geração de música
├── providers/[provider]/                operações por provedor
├── quotas/{check}                       verificações de cota
├── registered-keys/                     administração de chaves registradas
├── rerank/                              reclassificação
├── responses/[...path]/                 API de respostas da OpenAI (rota abrangente)
├── search/                              pesquisa na Web
├── videos/                              geração de vídeos
├── ws/                                  ponte WebSocket
└── route.ts                             manipulador de índice

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

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

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

3.2 src/lib/ — Bibliotecas principais

Sempre importe dados, sincronização, OAuth, habilidades, memória etc. por meio desses módulos. A tabela agrupa os diretórios reais e os arquivos de nível superior mais relevantes.

Módulo	Finalidade
a2a/	Servidor do protocolo A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 habilidades: análise de custos, relatório de integridade, descoberta de provedores, gerenciamento de cotas, roteamento inteligente, list-capabilities)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Utilitários da API interna: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (redefinição de senha / hashing)
batches/	Serviço da API de lotes da OpenAI (service.ts)
catalog/	Sincronização do catálogo do OpenRouter (openrouterCatalog.ts)
cloudAgent/	Registro de agentes de 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 combos
compliance/	Auditoria + auditoria de provedores: index.ts, providerAudit.ts
config/	Integração da configuração de runtime
db/	Módulos de domínio do SQLite (consulte §3.2.1)
display/	Utilitários de UI/exibição usados pelas respostas da API
embeddings/	Registro de serviços de embedding
env/	Carregamento + introspecção de variáveis de 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 de OAuth/importação de provedores (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 gerenciados: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Utilitários de provedores: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — configurações para circuit breaker, cooldown e bloqueio
runtime/	Detecção de recursos do runtime
search/	executeWebSearch.ts
services/	Framework de serviços incorporados: ServiceSupervisor.ts (supervisor genérico de processos filhos com bloqueio de operações, buffer circular e verificador de integridade), bootstrap.ts (registro no nível do processo e inicialização automática), registry.ts (mapa de ferramenta → supervisor), apiKey.ts (armazenamento de chaves AES-256-GCM), modelSync.ts (sincronização periódica de modelos), ringBuffer.ts (buffer circular de logs de 5 MB), healthCheck.ts (sonda HTTP de integridade), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Consulte docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Catálogo + gerador de habilidades de agentes: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → grava em skills/{id}/SKILL.md), openapiParser.ts (extrai endpoints REST da especificação OpenAPI), cliRegistryParser.ts (extrai subcomandos de 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 habilidade A2A list-capabilities. Consulte AGENT-SKILLS.md.
skills/	Framework de habilidades: 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 gravação adiada)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Utilitários no nível do sistema
translator/	Integração do tradutor de nível superior (delega para open-sse/translator/)
usage/	Contabilização de uso: 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

Arquivos 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/

Banco de dados SQLite singleton (getDbInstance() em core.ts, registro em diário WAL). Nunca escreva SQL bruto em rotas ou manipuladores — utilize estes módulos.

Fonte: diagrams/db-schema-overview.mmd

Módulos de domínio (cada um gerencia 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 arquivos .sql versionados (idempotentes e transacionais) e é executado por migrationRunner.ts durante a inicialização.

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 busca de memórias).

3.3 src/domain/ — Camada de domínio

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

Arquivo	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	Roteamento baseado em tags
comboResolver.ts	Resolução de combos da solicitação → lista de destinos
connectionModelRules.ts	Filtros de modelos por conexão
modelAvailability.ts	Verificação de disponibilidade de modelos
degradation.ts	Transições de modo degradado
providerExpiration.ts	Detecção de contas/chaves expiradas
quotaCache.ts	Decisões de cota armazenadas em cache
responses.ts, omnirouteResponseMeta.ts	Auxiliares de formato de resposta
configAudit.ts	Auditoria de alterações de configuração
assessment/	Avaliação de modelos (conforme RFC, parcialmente implementada)
types.ts	Tipos de domínio compartilhados

3.4 src/server/ — Exclusivo do servidor

Não pode ser importado por componentes do cliente.

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

3.5 src/shared/ — Seguro para compartilhamento

Dividido em subdiretórios específicos:

• constants/ — providers.ts (catálogo de provedores 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 distribuídos no npm.
• types/ — tipos TS compartilhados.
• 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 mecanismo de streaming

Workspace npm separado, publicado como @omniroute/open-sse. Responsável pelo processamento de solicitações, 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/                 Registros de provedores, perfis de cabeçalhos, identidade, …
├── handlers/               Manipuladores de solicitações (chat, embeddings, áudio, imagem, …)
├── executors/              108 executores HTTP específicos de provedores
├── translator/             Conversão de formatos (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformer de stream da Responses API ↔ Chat Completions
├── services/               Mais de 80 módulos de serviço (combinações, fallback, cotas, identidade, …)
├── utils/                  Utilitários de streaming, cliente TLS, AWS SigV4, fetch via proxy, …
└── mcp-server/             Servidor MCP (3 transportes, 33 escopos, 110 ferramentas)

4.1 open-sse/handlers/

Manipulador	Finalidade
chatCore.ts	Pipeline principal de chat (cache, limite de taxa, roteamento combinado, 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 fala
audioTranscription.ts	Conversão de fala em texto
videoGeneration.ts	Geração de vídeos
musicGeneration.ts	Geração de música
rerank.ts	Reclassificação
moderations.ts	Moderação
search.ts	Pesquisa na web
sseParser.ts	Analisador de eventos SSE
usageExtractor.ts	Extrai contagens de tokens de streams upstream
responseSanitizer.ts	Remove ruídos específicos do provedor
responseTranslator.ts	Integração entre a resposta do provedor e a camada de tradução

4.2 open-sse/executors/

108 executores de provedores, cada um estendendo 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 (utilitário de identidade compartilhado) e index.ts (registro).

Observação: os provedores não listados aqui são atendidos por default.ts usando o executor genérico compatível com OpenAI. O catálogo completo de provedores (355 provedores) está em src/shared/constants/providers.ts.

4.3 open-sse/translator/

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

• 9 tradutores de solicitações (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 utilitários (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, além de testes dos utilitários.
• Utilitários 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 da Responses API ↔ Chat Completions baseado em TransformStream (usado pelo catch-all da rota responses/).

4.5 open-sse/services/

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

Área	Arquivos
Roteamento de combos	combo.ts (19 estratégias), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Mecanismo 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 (tempo de espera + bloqueio), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Cotas	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Cache	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Inteligência de roteamento	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Tratamento 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 mecanismo de compressão
Token + sessão	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
Uso	usage.ts

4.6 open-sse/mcp-server/

• 110 ferramentas exclusivas integradas em server.ts (45 canônicas em schemas/tools.ts + módulos de memória, habilidades, habilidades do GitHub, pool, gamificação, plugins, Notion, Obsidian, corpus local e compressão — união contabilizada por countUniqueMcpTools).
• 3 transportes: stdio, HTTP Streamable, SSE.
• 33 escopos aplicados em tempo de execução — lista base em src/shared/constants/mcpScopes.ts; o conjunto completo é a união dos escopos declarados por cada módulo de ferramentas.
• Tabela de auditoria: mcp_tool_audit (preenchida por audit.ts).
• Arquivos: 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/

Registros de provedores (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), registros 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 provedores: 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/ — Wrapper para desktop

electron/
├── main.js                  Processo principal do Electron
├── preload.js               Ponte de pré-carregamento (contextIsolation habilitado)
├── types.d.ts
├── package.json             Configuração do electron-builder, versão 3.8.51
├── README.md
├── assets/                  Recursos de build (ícones, entitlements, …)
├── node_modules/            node_modules dedicado (better-sqlite3, electron-updater)
└── dist-electron/           Saída do build (não versionada)

Cinco scripts npm na raiz do workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. A atualização automática é feita via electron-updater, apontando para o feed de releases do GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Entrada principal da CLI (Node ESM)
├── reset-password.mjs      Redefine a senha de gerenciamento pela CLI
├── mcp-server.mjs          Inicializador do servidor MCP (stdio)
├── nodeRuntimeSupport.mjs  Verificação da versão do Node
└── cli/
    ├── program.mjs         Construtor do programa Commander
    ├── runtime.mjs         Auxiliar withRuntime (servidor primeiro/fallback para banco de dados)
    ├── output.mjs          Formatadores de saída (json/jsonl/table/csv)
    ├── i18n.mjs            Auxiliar t() com localidades
    ├── api.mjs             Auxiliar de fetch da API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Registro de comandos
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (um arquivo por comando/grupo)

Dois binários são expostos 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 pelo executor de testes nativo do Node (1821 arquivos, além dos subdiretórios api/, auth/, authz/)
tests/integration/	Testes entre módulos e do estado do banco de dados
tests/e2e/	Testes de interface 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 / estresse
tests/golden-set/	Saídas 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 pelo executor de testes do Node (concorrência 10)
npm run test:vitest	Suíte Vitest (MCP, autoCombo, cache)
npm run test:e2e	Suíte de interface do Playwright
npm run test:protocols:e2e	Testes e2e dos protocolos MCP + A2A
npm run test:coverage	Limite mínimo de cobertura (≥60% de linhas/instruções/funções/ramificações)
node --import tsx/esm --test tests/unit/<file>.test.ts	Execução de um único arquivo

---

8. scripts/

Organizado 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 requisições (resumo)

Fonte: diagrams/request-pipeline.mmd

Requisição 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)
     Mecanismo de políticas (src/server/authz/pipeline.ts)
     Proteções (mascarador de PII, injeção de prompt, ponte de visão)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Verificação de cache (cache semântico + cache de leitura)
     Limitação de taxa (rateLimitManager, accountSemaphore)
     Roteamento combinado (se o modelo for resolvido como uma combinação)
       comboResolver → loop por destino → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       fetch upstream → nova tentativa/recuo via accountFallback
     translateResponse() (open-sse/translator/response/*)
     Stream SSE OU resposta JSON
     Se for a Responses API: TransformStream via open-sse/transformer/responsesTransformer.ts
  → Auditoria de conformidade (src/lib/compliance/)
  → Resposta ao cliente

Estado de resiliência em tempo de execução (três mecanismos)

Mecanismo	Escopo	Onde
Disjuntor do provedor	Provedor inteiro	src/shared/utils/circuitBreaker.ts, persistido em domain_circuit_breakers
Tempo de espera da conexão	Uma conta/chave	markAccountUnavailable() em src/sse/services/auth.ts; consumido por accountFallback.checkFallbackError()
Bloqueio de modelo	Provedor + conexão + modelo	open-sse/services/accountFallback.ts, persistido em domain_lockout_state

Consulte RESILIENCE_GUIDE.md e a seção dedicada em CLAUDE.md.

---

10. Como contribuir

Adicionar um novo provedor

1. Registre em src/shared/constants/providers.ts (validado pelo Zod durante o carregamento).
2. Adicione um executor em open-sse/executors/ se for necessária uma lógica personalizada (estenda BaseExecutor).
3. Adicione um tradutor em open-sse/translator/ se ele 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. Registre os modelos em open-sse/config/providerRegistry.ts (ou no registro específico do formato em open-sse/config/).
6. Escreva testes em tests/unit/.

Adicionar uma nova rota de 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 um novo formato de requisição: adicione o esquema Zod em src/shared/validation/schemas.ts.
4. Se for exclusiva para gerenciamento: adicione o caminho a src/shared/constants/publicApiRoutes.ts (lista de bloqueio para a superfície da API pública).
5. Adicione testes em tests/unit/.
6. Atualize docs/reference/API_REFERENCE.md e docs/openapi.yaml.

Adicionar um novo módulo de banco de dados

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 importadores usam importações diretas de @/lib/db/yourModule (sem arquivo agregador — 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) escopo(s) apropriado(s) em src/shared/constants/mcpScopes.ts.
3. Registre 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 habilidade A2A

Consulte A2A-SERVER.md § Adicionando uma nova habilidade. As habilidades ficam em src/lib/a2a/skills/ e são registradas por meio do gerenciador de tarefas A2A.

---

11. Convenções

• Estilo de código: recuo de 2 espaços, aspas duplas, largura de 100 caracteres, ponto e vírgula, vírgulas finais no estilo es5 — aplicados pelo Prettier por meio do lint-staged.
• Importações: externas → internas (@/, @omniroute/open-sse) → relativas.
• Nomenclatura: arquivos em camelCase ou kebab-case, componentes em PascalCase, constantes em UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error em todos os lugares; no-explicit-any = warn em open-sse/ e tests/, erro nos demais locais.
• TypeScript: strict: false (postura herdada). Prefira tipos explícitos em vez de inferência nos limites entre módulos.
• Banco de dados: nunca escreva SQL bruto em rotas ou manipuladores — sempre utilize módulos de src/lib/db/. Nunca importe por meio de um arquivo agregador — use diretamente módulos específicos de src/lib/db/*.
• Tipagem de entidades do banco de dados (#3512): uma função que grava ou lê o formato de linha de uma tabela do banco de dados deve receber/retornar uma interface TS nomeada que espelhe as colunas dessa tabela na proporção 1:1, não any nem um tipo anônimo em linha no local da chamada. Coloque a interface ao lado da função (por exemplo, export interface UsageEntry em src/lib/usage/usageHistory.ts acima de saveRequestUsage), mantenha campos individuais opcionais/anuláveis quando diferentes gravadores preencherem a linha de forma incremental e prefira unknown a any para um campo cujo formato varie entre os chamadores (documentado no campo; por exemplo, UsageEntry.tokens aceita tanto o uso bruto no formato do provedor quanto o formato normalizado). Quando a contagem de any de um arquivo chegar a zero dessa forma, adicione-o à lista de permissões de check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0) para evitar regressões. Esta é uma convenção para a primeira etapa — a remoção mais ampla de "any anônimo" é iterativa no restante da base de código.
• Erros: use try/catch com tipos de erro específicos e registre logs com contexto do pino. Nunca ignore silenciosamente erros em fluxos SSE; use sinais de cancelamento para a limpeza.
• Segurança: nunca use eval() / new Function() / eval implícito. Valide todas as entradas com Zod. Criptografe credenciais em repouso (AES-256-GCM). Mantenha a lista de bloqueio src/shared/constants/upstreamHeaders.ts alinhada com a camada de sanitização/validação.
• Commits: Conventional Commits — feat(scope): subject. Escopos permitidos: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branches: 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 (do CLAUDE.md)

1. Nunca faça commit de segredos ou credenciais.
2. Nunca faça barrel import — use diretamente módulos específicos de src/lib/db/*.
3. Nunca use eval() / new Function() / eval implícito.
4. Nunca faça commit diretamente na main.
5. Nunca escreva SQL bruto em rotas — sempre use os módulos de src/lib/db/.
6. Nunca ignore silenciosamente erros em fluxos SSE.
7. Sempre valide as entradas com esquemas Zod.
8. Sempre inclua testes ao alterar código de produção.
9. A cobertura deve permanecer ≥ 60% (instruções, linhas, funções e ramificações).

---

13. Veja Também

• ARCHITECTURE.md — arquitetura de alto nível e responsabilidades dos módulos.
• API_REFERENCE.md — referência das APIs pública e de gerenciamento.
• FEATURES.md — matriz de recursos e destaques das versões.
• RESILIENCE_GUIDE.md — análise detalhada de circuit breaker, cooldown e lockout.
• AUTO-COMBO.md — pontuação e estratégias do Auto Combo.
• MCP-SERVER.md — catálogo completo de ferramentas MCP + transportes.
• A2A-SERVER.md — habilidades e descoberta do protocolo A2A.
• COMPRESSION_GUIDE.md — compactação RTK + Caveman.
• CLI-TOOLS.md — integrações de 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 implantaçã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 oficial para muitas das convenções acima).
• AGENTS.md — referência de arquitetura mais detalhada usada pelos agentes.