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

OmniRoute Codebase Documentation (Polski)

🌐 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 · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

title: "Dokumentacja bazy kodu OmniRoute" version: 3.8.40 lastUpdated: 2026-06-28

Dokumentacja bazy kodu OmniRoute

Wersja: v3.8.0 Ostatnia aktualizacja: 2026-06-28 Odbiorcy: Inżynierowie współtworzący OmniRoute lub budujący na nim integracje.

Diagramy architektury wysokiego poziomu i uzasadnienie każdego podsystemu znajdziesz w ARCHITECTURE.md. Szczegółowe opracowania poszczególnych podsystemów (Auto Combo, serwer MCP, serwer A2A, Skills, Memory, Cloud Agents, Resilience, Compression, itd.) są w dedykowanych plikach w tym katalogu docs/.

Ten plik opisuje to, co dziś jest w repozytorium, żeby nowy inżynier mógł przejść drzewo katalogów, zrozumieć warstwy runtime i wiedzieć, gdzie dodać kod bez wymyślania nowych modułów.

---

1. Stos technologiczny

Zagadnienie	Wybór
Web framework	Next.js 16 (App Router, stialone output, brak globalnego middleware)
Język	TypeScript 6.0+ — target ES2022, module: esnext, moduleResolution: bundler, strict: false
Runtime	Node.js >=22.22.2 <23 lub >=24.0.0 <27 (wymuszane przez engines + SUPPORTED_NODE_RANGE)
Baza danych	SQLite przez better-sqlite3 (singleton, journalowanie WAL)
Desktop	Electron 41 + electron-builder 26.10 (osobny workspace w electron/)
Testy	Node native test runner (unit/integration), Vitest (MCP, autoCombo, cache), Playwright (e2e + protocols-e2e)
Build	Next.js stialone przez scripts/build/build-next-isolated.mjs
Lint/format	ESLint flat config + Prettier (lint-staged przez Husky pre-commit)
System modułów	ESM wszędzie ("type": "module")
Workspaces	npm workspace — open-sse to jedyny pod-workspace

Aliasy ścieżek (tsconfig.json):

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

Domyślny port HTTP: 20128 (API i dashboard współdzielą ten sam proces). Katalog danych to zmienna środowiskowa DATA_DIR, domyślnie ~/.omniroute/.

---

2. Układ repozytorium

OmniRoute/
├── src/                  Aplikacja Next.js (App Router, libs, domain, server, shared)
├── open-sse/             Workspace silnika streamingu (@omniroute/open-sse)
├── electron/             Opakowanie desktopowe (Electron 41 main + preload)
├── bin/                  Punkty wejścia CLI (omniroute, reset-password)
├── tests/                Unit, integration, e2e, protocols-e2e, translator, security, fixtures
├── scripts/              Skrypty build, sync, check, migracji i pomocnicze runtime
├── docs/                 Dokumentacja publiczna (ten katalog)
├── public/               Zasoby statyczne, manifest PWA, service worker
├── config/               Przykłady konfiguracji runtime
├── images/               Zasoby marketingowe / zrzuty ekranu
├── _ideia/, _references/, _mono_repo/, _tasks/   Wewnętrzne notatki / planowanie (nie wydawane)
├── CLAUDE.md             Reguły repo dla Claude Code
├── AGENTS.md             Głębsza referencja architektury dla agentów
├── package.json          v3.8.0, korzeń workspace
└── tsconfig.json         Aliasy ścieżek + główne opcje kompilatora

---

3. src/ — Aplikacja Next.js

src/
├── app/                  Strony App Routera i trasy API
├── lib/                  Podstawowe biblioteki (baza danych, uwierzytelnianie, OAuth, umiejętności, pamięć, …)
├── domain/               Czysta warstwa domenowa (zasady, mechanizmy awaryjne, koszty, blokady, …)
├── server/               Moduły przeznaczone wyłącznie dla serwera (autoryzacja, CORS, uwierzytelnianie)
├── shared/               Typy, stałe, walidacja, kontrakty, narzędzia (bezpieczne między granicami)
├── mitm/                 Pomocnicze moduły proxy typu man-in-the-middle do integracji z CLI
├── models/               Metadane i aliasy modeli lokalnych
├── sse/                  Starsze procedury obsługi SSE, które nadal znajdują się w src/ (nie w open-sse/)
├── store/                Magazyny stanu po stronie klienta
├── middleware/           Narzędzia middleware na poziomie tras (nie globalne middleware Next.js)
├── scripts/              Skrypty w drzewie projektu, które mogą być importowane przez kod aplikacji
├── types/                Globalne i współdzielone typy TS
├── i18n/                 Pakiety lokalizacyjne
├── instrumentation.ts    Hak instrumentacji Next.js
├── instrumentation-node.ts
└── proxy.ts              Pomocniczy moduł najwyższego poziomu do inicjalizacji proxy

3.1 src/app/ — App Router

App Router udostępnia zarówno interfejs panelu, jak i publiczne oraz administracyjne API HTTP. Nie ma globalnego middleware — przechwytywanie odbywa się osobno dla każdej trasy.

Segmenty najwyższego poziomu w src/app/:

Ścieżka	Przeznaczenie
api/	Wszystkie trasy API HTTP (zobacz podział poniżej)
a2a/	Punkt końcowy A2A JSON-RPC 2.0 (POST /a2a)
.well-known/agent.json/	Dokument wykrywania Agent Card A2A
(dashboard)/	Interfejs panelu (grupa tras, bez prefiksu URL)
auth/, login/, forgot-password/, callback/	Przepływy uwierzytelniania
landing/	Strona marketingowa/docelowa
docs/	Osadzona przeglądarka dokumentacji API
status/, maintenance/, offline/	Strony operacyjne
privacy/, terms/	Strony prawne
400/, 401/, 403/, 408/, 429/, 500/, 502/, 503/	Statyczne strony błędów
error.tsx, global-error.tsx, not-found.tsx, forbidden/, loading.tsx	Granice błędów i ładowania frameworka
layout.tsx, page.tsx, globals.css, manifest.ts	Główna powłoka

3.1.1 src/app/(dashboard)/dashboard/ — Strony interfejsu użytkownika

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, a także główne pliki page.tsx, HomePageClient.tsx, BootstrapBanner.tsx.

3.1.2 src/app/api/ — Grupy API najwyższego poziomu

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/   Zarządzanie osadzonymi usługami (9router, cliproxy) — LOCAL_ONLY
├── upstream-proxy/
├── usage/
├── v1/         Publiczne API zgodne z OpenAI
├── v1beta/     Warstwa zgodności w stylu Gemini
├── version-manager/
└── webhooks/

3.1.2a src/app/api/services/ — Zarządzanie osadzonymi usługami

Trasy służące do instalowania, uruchamiania, zatrzymywania i monitorowania 9Router oraz CLIProxyAPI. Wszystkie ścieżki są sklasyfikowane jako LOCAL_ONLY (wyłącznie interfejs pętli zwrotnej, reguła bezwzględna nr 17), ponieważ mogą wywoływać npm install i uruchamiać procesy potomne.

src/app/api/services/
├── 9router/
│   ├── _lib.ts             pomocnik getOrInitSupervisor()
│   ├── install/route.ts    POST — npm install przez 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 nowszej wersji
│   ├── rotate-key/route.ts POST — wygenerowanie nowego klucza API + ponowne uruchomienie
│   ├── status/route.ts     GET  — stan na żywo + stan bazy danych + metadane wersji
│   └── auto-start/route.ts POST — przełączenie flagi auto_start
├── cliproxy/
│   ├── _lib.ts             pomocnik 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 nowszej wersji
│   ├── status/route.ts     GET  — stan na żywo + stan bazy danych + metadane wersji
│   └── auto-start/route.ts POST — przełączenie flagi auto_start
└── [name]/
    └── logs/route.ts       GET  — strumień SSE logów (współdzielony przez wszystkie usługi)

Odpowiadający interfejs użytkownika panelu: src/app/(dashboard)/dashboard/providers/services/ — strona z dwiema kartami (CLIProxyAPI + 9Router). Odwrotne proxy dla osadzonego interfejsu użytkownika 9Router: src/app/(dashboard)/dashboard/providers/services/[name]/embed/[[...path]]/route.ts

Szczegółowy opis: docs/frameworks/EMBEDDED-SERVICES.md

3.1.3 src/app/api/v1/ — publiczne API zgodne z OpenAI

v1/
├── accounts/[id]/                       wyszukiwanie konta
├── agents/tasks/[id]/, agents/tasks/    punkty końcowe zadań w stylu A2A
├── api/                                 wewnętrzne pomocniki API udostępniane pod v1/api
├── audio/{speech, transcriptions}/      TTS + STT
├── batches/[id]/{cancel}, batches/      OpenAI Batches API
├── chat/completions/                    Chat Completions (główny punkt końcowy)
├── completions/                         starszy mechanizm uzupełniania tekstu
├── embeddings/                          osadzenia
├── files/[id]/, files/                  Files API
├── _helpers/                            współdzielone pomocniki tras (bez publicznego adresu URL)
├── images/{edits, generations}/         generowanie + edycja obrazów
├── issues/                              pomocnicze punkty końcowe segregacji zgłoszeń
├── management/{proxies}/                trasy zarządzania wewnątrz v1
├── messages/{count_tokens}/             zgodność z wiadomościami w stylu Anthropic
├── models/                              lista modeli (`route.ts`, `catalog.ts`)
├── moderations/                         moderacja
├── music/                               generowanie muzyki
├── providers/[provider]/                operacje dla poszczególnych dostawców
├── quotas/{check}                       sprawdzanie limitów
├── registered-keys/                     administracja zarejestrowanymi kluczami
├── rerank/                              ponowne szeregowanie
├── responses/[...path]/                 OpenAI Responses API (trasa przechwytująca)
├── search/                              wyszukiwanie w internecie
├── videos/                              generowanie wideo
├── ws/                                  most WebSocket
└── route.ts                             procedura obsługi indeksu

Każdy plik trasy jest zgodny z tym samym wzorcem:

Trasa → obsługa żądania wstępnego CORS → walidacja treści przez Zod → opcjonalne uwierzytelnianie
      → egzekwowanie zasad klucza API → delegowanie do procedury obsługi (open-sse)

v1beta/ to warstwa zgodności w stylu Gemini (cienka otoczka, która tłumaczy żądania na ten sam potok open-sse/handlers/).

3.2 src/lib/ — biblioteki podstawowe

Dane, synchronizację, OAuth, umiejętności, pamięć itd. należy zawsze importować za pośrednictwem tych modułów. Tabela grupuje rzeczywiste katalogi i istotne pliki najwyższego poziomu.

Moduł	Przeznaczenie
a2a/	Serwer protokołu A2A: taskManager.ts, streaming.ts, taskExecution.ts, routingLogger.ts, skills/ (6 umiejętności: analiza kosztów, raport o stanie, wykrywanie dostawców, zarządzanie limitami, inteligentne trasowanie, list-capabilities)
acp/	Agent-Control-Protocol: index.ts, manager.ts, registry.ts
api/	Wewnętrzne funkcje pomocnicze API: requireManagementAuth.ts, requireCliToolsAuth.ts, errorResponse.ts
auth/	managementPassword.ts (resetowanie hasła / haszowanie)
batches/	Usługa OpenAI Batches API (service.ts)
catalog/	Synchronizacja katalogu OpenRouter (openrouterCatalog.ts)
cloudAgent/	Rejestr agentów chmurowych: api.ts, baseAgent.ts, db.ts, index.ts, registry.ts, types.ts, agents/{codex, devin, jules}.ts
combos/	Funkcje pomocnicze do rozwiązywania kombinacji
compliance/	Audyt i audyt dostawców: index.ts, providerAudit.ts
config/	Warstwa integracyjna konfiguracji środowiska uruchomieniowego
db/	Moduły domenowe SQLite (zob. §3.2.1)
display/	Funkcje pomocnicze interfejsu użytkownika i wyświetlania używane w odpowiedziach API
embeddings/	Rejestr usług osadzania
env/	Wczytywanie i introspekcja zmiennych środowiskowych
evals/	Środowisko uruchomieniowe ewaluacji
guardrails/	piiMasker.ts, promptInjection.ts, visionBridge.ts, visionBridgeHelpers.ts, registry.ts, base.ts
jobs/	Zadania w tle (autoUpdate.ts, …)
memory/	Pamięć trwała: 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/	Moduły OAuth/importu dostawców (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, a także services/, utils/ i constants/oauth.ts
plugins/	Moduł ładujący wtyczki (index.ts)
promptCache/	prefixAnalyzer.ts, index.ts
providerModels/	Zarządzany cykl życia modeli: modelDiscovery.ts, managedModelImport.ts, managedAvailableModels.ts, cursorAgent.ts
providers/	Funkcje pomocnicze dostawców: catalog.ts, validation.ts, imageValidation.ts, claudeExtraUsage.ts, codexConnectionDefaults.ts, codexFastTier.ts, webCookieAuth.ts, managedAvailableModels.ts, requestDefaults.ts
resilience/	settings.ts — ustawienia wyłącznika awaryjnego, okresu karencji i blokady
runtime/	Wykrywanie funkcji środowiska uruchomieniowego
search/	executeWebSearch.ts
services/	Framework usług osadzonych: ServiceSupervisor.ts (ogólny nadzorca procesów podrzędnych z blokadą operacji, buforem pierścieniowym i mechanizmem sprawdzania stanu), bootstrap.ts (rejestracja na poziomie procesu i automatyczne uruchamianie), registry.ts (mapowanie narzędzie → nadzorca), apiKey.ts (magazyn kluczy AES-256-GCM), modelSync.ts (okresowa synchronizacja modeli), ringBuffer.ts (kołowy bufor dziennika o rozmiarze 5 MB), healthCheck.ts (sonda stanu HTTP), types.ts, embedWsProxy.ts (proxy WebSocket), installers/{ninerouter,cliproxy}.ts. Zob. docs/frameworks/EMBEDDED-SERVICES.md
agentSkills/	Katalog i generator umiejętności agentów: catalog.ts (getCatalog/getSkillById/filterCatalog/computeCoverage), generator.ts (generateAgentSkills → zapisuje skills/{id}/SKILL.md), openapiParser.ts (wyodrębnia punkty końcowe REST ze specyfikacji OpenAPI), cliRegistryParser.ts (wyodrębnia podpolecenia CLI z bin/cli-registry), schemas.ts (Zod: AgentSkillSchema, SkillCoverageSchema, ListQuerySchema, GenerateBodySchema), types.ts (AgentSkill, SkillCoverage, SkillMarkdown, GeneratorReport). Używany przez trasy REST (/api/agent-skills/*), narzędzia MCP (omniroute_agent_skills_*) oraz umiejętność A2A list-capabilities. Zob. AGENT-SKILLS.md.
skills/	Framework umiejętności: 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, a także builtin/browser.ts
spend/	batchWriter.ts (bufor opóźnionego zapisu)
sync/	bundle.ts, tokens.ts (Cloud Sync)
system/	Funkcje pomocnicze na poziomie systemu
translator/	Warstwa integracyjna translatora najwyższego poziomu (deleguje do open-sse/translator/)
usage/	Rozliczanie użycia: costCalculator.ts, tokenAccounting.ts, usageHistory.ts, aggregateHistory.ts, usageStats.ts, callLogs.ts, callLogArtifacts.ts, fetcher.ts, providerLimits.ts, migrations.ts
versionManager/	Automatyczna aktualizacja i manifest wersji
ws/	Most WebSocket
zed-oauth/	Przepływ OAuth edytora Zed

Pliki najwyższego poziomu w src/lib/:

• Stary plik zbiorczy localDb.ts został usunięty — konsumenci importują bezpośrednio określone moduły 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/

Singletonowa baza danych SQLite (getDbInstance() w core.ts, rejestrowanie w trybie WAL). Nigdy nie zapisuj surowych zapytań SQL w trasach ani procedurach obsługi — korzystaj z tych modułów.

Źródło: diagrams/db-schema-overview.mmd

Moduły domenowe (każdy odpowiada za co najmniej jedną tabelę): 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.

Katalog migrations/ zawiera 168 wersjonowanych plików .sql (idempotentnych i transakcyjnych), które są wykonywane podczas uruchamiania przez migrationRunner.ts.

Tabele utworzone przez migracje (łącznie 123):

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 (oraz tabele wirtualne FTS5 do wyszukiwania w pamięci).

3.3 src/domain/ — Warstwa domenowa

Czysta logika biznesowa, bez operacji wejścia/wyjścia. Importowana przez trasy i procedury obsługi.

Plik	Przeznaczenie
policyEngine.ts	Główny mechanizm rozstrzygania zasad
fallbackPolicy.ts	Drzewo decyzyjne mechanizmu awaryjnego
costRules.ts	Reguły obliczania kosztów
lockoutPolicy.ts	Decyzje dotyczące blokowania modeli
tagRouter.ts	Routing oparty na znacznikach
comboResolver.ts	Przekształcanie kombinacji z żądania → w listę celów
connectionModelRules.ts	Filtry modeli dla poszczególnych połączeń
modelAvailability.ts	Sprawdzanie dostępności modelu
degradation.ts	Przejścia do trybu ograniczonego działania
providerExpiration.ts	Wykrywanie wygasłych kont/kluczy
quotaCache.ts	Buforowane decyzje dotyczące limitów
responses.ts, omnirouteResponseMeta.ts	Funkcje pomocnicze dotyczące struktury odpowiedzi
configAudit.ts	Audyt zmian konfiguracji
assessment/	Ocena modeli (zgodnie z RFC, częściowo zaimplementowana)
types.ts	Współdzielone typy domenowe

3.4 src/server/ — Tylko po stronie serwera

Nie można importować z komponentów klienckich.

server/
├── auth/loginGuard.ts
├── authz/
│   ├── classify.ts        Klasyfikuje trasy jako publiczne lub administracyjne
│   ├── assertAuth.ts      Funkcja pomocnicza do asercji
│   ├── context.ts         Kontekst autoryzacji dla każdego żądania
│   ├── headers.ts
│   ├── pipeline.ts        Potok autoryzacji
│   ├── policies/          Konkretne zasady
│   └── types.ts
└── cors/origins.ts        Lista dozwolonych źródeł CORS

3.5 src/shared/ — Bezpieczne do współdzielenia

Podzielone na wyspecjalizowane podkatalogi:

• constants/ — providers.ts (katalog dostawców walidowany przez Zod), models.ts, modelSpecs.ts, modelCompat.ts, pricing.ts, cliTools.ts, cliCompatProviders.ts, routingStrategies.ts, comboConfigMode.ts, headers.ts, upstreamHeaders.ts (lista blokowanych elementów), 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 schematów Zod), compressionConfigSchemas.ts, providerSchema.ts, settingsSchemas.ts, helpers.ts.
• contracts/ — publiczne kontrakty API publikowane w npm.
• types/ — współdzielone typy TS.
• 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, a także hooki/komponenty panelu w katalogach services/, network/, middleware/, schemas/, hooks/, components/.

---

4. open-sse/ — przestrzeń robocza silnika strumieniowania

Oddzielna przestrzeń robocza npm publikowana jako @omniroute/open-sse. Odpowiada za przetwarzanie żądań, moduły wykonawcze, translatory, usługi, transformator oraz serwer MCP.

open-sse/
├── index.ts                Eksporty publiczne
├── package.json            Manifest przestrzeni roboczej
├── tsconfig.json
├── types.d.ts
├── config/                 Rejestry dostawców, profile nagłówków, tożsamość, …
├── handlers/               Procedury obsługi żądań (czat, osadzanie, audio, obrazy, …)
├── executors/              108 modułów wykonawczych HTTP specyficznych dla dostawców
├── translator/             Konwersja formatów (OpenAI ↔ Claude ↔ Gemini ↔ Cursor ↔ Kiro)
├── transformer/            Transformator strumienia Responses API ↔ Chat Completions
├── services/               Ponad 80 modułów usług (kombinacje, mechanizmy zapasowe, limity, tożsamość, …)
├── utils/                  Narzędzia pomocnicze strumieniowania, klient TLS, AWS SigV4, pobieranie przez proxy, …
└── mcp-server/             Serwer MCP (3 transporty, 33 zakresy, 110 narzędzi)

4.1 open-sse/handlers/

Procedura obsługi	Przeznaczenie
chatCore.ts	Główny potok czatu (pamięć podręczna, limit szybkości, routing kombinacji, wywoływanie modułów wykonawczych)
responsesHandler.ts	Punkt wejścia OpenAI Responses API
embeddings.ts	Osadzanie
imageGeneration.ts	Generowanie obrazów
audioSpeech.ts	Zamiana tekstu na mowę
audioTranscription.ts	Zamiana mowy na tekst
videoGeneration.ts	Generowanie wideo
musicGeneration.ts	Generowanie muzyki
rerank.ts	Ponowne ustalanie rankingu
moderations.ts	Moderowanie
search.ts	Wyszukiwanie w sieci
sseParser.ts	Parser zdarzeń SSE
usageExtractor.ts	Wyodrębnianie liczby tokenów ze strumieni źródłowych
responseSanitizer.ts	Usuwanie zakłóceń specyficznych dla dostawcy
responseTranslator.ts	Warstwa łącząca odpowiedź dostawcy z warstwą translatora

4.2 open-sse/executors/

108 modułów wykonawczych dostawców, z których każdy rozszerza 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, a także claudeIdentity.ts (współdzielone narzędzie pomocnicze tożsamości) oraz index.ts (rejestr).

Uwaga: dostawcy niewymienieni tutaj są obsługiwani przez default.ts przy użyciu ogólnego modułu wykonawczego zgodnego z OpenAI. Pełny katalog dostawców (355 dostawców) znajduje się w src/shared/constants/providers.ts.

4.3 open-sse/translator/

Translacja w modelu „centrum i szprychy” (OpenAI pełni rolę centrum).

• 9 translatorów żądań (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 translatorów odpowiedzi (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 narzędzi pomocniczych (translator/helpers/): claudeHelper, geminiHelper, geminiToolsSanitizer, maxTokensHelper, openaiHelper, responsesApiHelper, schemaCoercion, toolCallHelper, a także testy narzędzi pomocniczych.
• Narzędzia pomocnicze obrazów (translator/image/sizeMapper.ts).
• Najwyższy poziom: bootstrap.ts, formats.ts, registry.ts, index.ts.

4.4 open-sse/transformer/

• responsesTransformer.ts — oparty na TransformStream konwerter Responses API ↔ Chat Completions (używany przez trasę przechwytującą responses/).

4.5 open-sse/services/

Najważniejsze elementy (pełna lista w open-sse/services/):

Obszar	Pliki
Routing Combo	combo.ts (19 strategii), comboConfig.ts, comboMetrics.ts, comboManifestMetrics.ts, comboAgentMiddleware.ts
Silnik 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
Odporność	accountFallback.ts (czas karencji + blokada), errorClassifier.ts, emergencyFallback.ts, rateLimitManager.ts, rateLimitSemaphore.ts, accountSemaphore.ts, accountSelector.ts
Limity	quotaMonitor.ts, quotaPreflight.ts, bailianQuotaFetcher.ts, codexQuotaFetcher.ts, deepseekQuotaFetcher.ts, openrouterQuotaFetcher.ts, openrouterFreeWindow.ts, crofUsageFetcher.ts, antigravityCredits.ts
Buforowanie	reasoningCache.ts, searchCache.ts, signatureCache.ts, requestDedup.ts
Inteligentny routing	intentClassifier.ts, taskAwareRouter.ts, backgroundTaskDetector.ts, volumeDetector.ts, wildcardRouter.ts, workflowFSM.ts, specificityDetector.ts, specificityRules.ts, specificityTypes.ts
Obsługa modeli	modelCapabilities.ts, modelDeprecation.ts, modelFamilyFallback.ts, modelStrip.ts, model.ts, provider.ts, providerRequestDefaults.ts, providerCostData.ts, payloadRules.ts
Kompresja	compression/ — kompletne połączenie komponentów silnika kompresji
Tokeny i sesje	tokenRefresh.ts, sessionManager.ts, apiKeyRotator.ts, contextManager.ts, contextHandoff.ts, systemPrompt.ts, roleNormalizer.ts, responsesInputSanitizer.ts, toolSchemaSanitizer.ts, toolLimitDetector.ts, thinkingBudget.ts
Poziom / manifest	tierResolver.ts, tierConfig.ts, tierDefaults.json, tierTypes.ts, manifestAdapter.ts
IP / sieć	ipFilter.ts, webSearchFallback.ts
Przetwarzanie wsadowe	batchProcessor.ts
Użycie	usage.ts

4.6 open-sse/mcp-server/

• 110 unikatowych narzędzi połączonych w server.ts (45 kanonicznych w schemas/tools.ts + moduły pamięci, umiejętności, umiejętności GitHub, puli, grywalizacji, wtyczek, Notion, Obsidian, lokalnego korpusu i kompresji — suma zbiorów liczona przez countUniqueMcpTools).
• 3 mechanizmy transportu: stdio, HTTP Streamable, SSE.
• 33 zakresy wymuszane w czasie wykonywania — lista bazowa znajduje się w src/shared/constants/mcpScopes.ts, a pełny zestaw jest sumą zakresów deklarowanych przez każdy moduł narzędzi.
• Tabela audytu: mcp_tool_audit (wypełniana przez audit.ts).
• Pliki: 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, oraz testy w katalogu __tests__/.
• Pełny katalog narzędzi znajduje się w dokumencie MCP-SERVER.md.

4.7 open-sse/config/

Rejestry dostawców (providerRegistry.ts, providerModels.ts, providerHeaderProfiles.ts), rejestry modeli dla poszczególnych formatów (audioRegistry.ts, embeddingRegistry.ts, imageRegistry.ts, moderationRegistry.ts, musicRegistry.ts, rerankRegistry.ts, searchRegistry.ts, videoRegistry.ts), funkcje pomocnicze tożsamości (codexIdentity.ts, codexInstructions.ts, anthropicHeaders.ts, antigravityUpstream.ts, antigravityModelAliases.ts, cliFingerprints.ts, toolCloaking.ts, defaultThinkingSignature.ts), funkcje pomocnicze poświadczeń (credentialLoader.ts, codexClient.ts) oraz adaptery chmurowe (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/

Prymitywy strumieniowania i funkcje pomocnicze dostawców: 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/ — Opakowanie desktopowe

electron/
├── main.js                  Proces main Electron
├── preload.js               Most preload (contextIsolation włączony)
├── types.d.ts
├── package.json             konfiguracja electron-builder, wersja 3.8.0
├── README.md
├── assets/                  Zasoby build (ikony, entitlements, …)
├── node_modules/            Dedykowane node_modules (better-sqlite3, electron-updater)
└── dist-electron/           Wynik build (nie commitowany)

Pięć skryptów npm w korzeniu workspace: electron:dev, electron:build, electron:build:{win,mac,linux}, electron:smoke:packaged. Auto-update przez electron-updater wskazujący na feed wydań GitHub.

---

6. bin/ — CLI

bin/
├── omniroute.mjs           Główne wejście CLI (Node ESM)
├── reset-password.mjs      Reset hasła management z CLI
├── mcp-server.mjs          Launcher serwera MCP (stdio)
├── nodeRuntimeSupport.mjs  Strażnik wersji Node
└── cli/
    ├── program.mjs         Builder programu Commander
    ├── runtime.mjs         helper withRuntime (server-first/db-fallback)
    ├── output.mjs          Formattery wyjścia (json/jsonl/table/csv)
    ├── i18n.mjs            helper t() z locale
    ├── api.mjs             Helper fetch API
    ├── data-dir.mjs
    ├── encryption.mjs
    ├── sqlite.mjs
    └── commands/
        ├── registry.mjs    Rejestracja komend
        ├── setup.mjs
        ├── doctor.mjs
        ├── providers.mjs
        └── ...             (jeden plik na komendę/grupę)

Dwa binaria są wystawione w package.json → bin:

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

---

7. tests/

Katalog	Typ
tests/unit/	Testy jednostkowe przez Node native test runner (1821 plików, plus api/, auth/, authz/ podkatalogi)
tests/integration/	Testy cross-module + stan DB
tests/e2e/	Playwright UI tests
tests/protocols-e2e/	MCP/A2A protocol e2e
tests/translator/	Translator-specific tests
tests/security/	Security regressions
tests/load/	Load / stress tests
tests/golden-set/	Reference outputs for translator regressions
tests/helpers/, tests/fixtures/, tests/manual/	Support

Common commands:

Command	What it runs
npm run test:unit	All tests/unit/*.test.ts via Node test runner (concurrency 10)
npm run test:vitest	Vitest suite (MCP, autoCombo, cache)
npm run test:e2e	Pakiet UI Playwright
npm run test:protocols:e2e	e2e protokołów MCP + A2A
npm run test:coverage	Coverage gate (≥60% lines/statements/functions/branches)
node --import tsx/esm --test tests/unit/<file>.test.ts	Single file run

---

8. scripts/

Zorganizowane w 6 podkatalogów według przeznaczenia.

• 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 requestu (podsumowanie)

Źródło: diagrams/request-pipeline.mmd

Client request
  → /v1/chat/completions (route.ts)
     CORS preflight check
     Zod validation (chatCompletionsSchema in shared/validation/schemas.ts)
     Auth (extractApiKey + isValidApiKey OR requireManagementAuth)
     Policy engine (src/server/authz/pipeline.ts)
     Guardrails (PII masker, prompt injection, vision bridge)
  → handleChatCore() (open-sse/handlers/chatCore.ts)
     Cache check (semantic + read cache)
     Rate limit (rateLimitManager, accountSemaphore)
     Combo routing (if model resolves to a combo)
       comboResolver → loop per target → handleSingleModel()
     translateRequest()  (open-sse/translator/request/*)
     getExecutor(providerId).execute()  (open-sse/executors/*)
       fetch upstream → retry/backoff via accountFallback
     translateResponse() (open-sse/translator/response/*)
     SSE stream OR JSON response
     Jeśli Responses API: TransformStream via open-sse/transformer/responsesTransformer.ts
  → Compliance audit (src/lib/compliance/)
  → Odpowiedź do klienta

Stan runtime resilience (trzy mechanizmy)

Mechanizm	Zakres	Gdzie
Provider circuit breaker	Cały provider	src/shared/utils/circuitBreaker.ts, utrwalany w domain_circuit_breakers
Connection cooldown	Jedno konto/klucz	markAccountUnavailable() w src/sse/services/auth.ts; konsumowany przez accountFallback.checkFallbackError()
Model lockout	Provider + connection + model	open-sse/services/accountFallback.ts, utrwalany w domain_lockout_state

Zob. RESILIENCE_GUIDE.md oraz dedykowaną sekcję w CLAUDE.md.

---

10. Jak współtworzyć

Dodaj nowego providera

1. Zarejestruj w src/shared/constants/providers.ts (walidacja Zod przy ładowaniu).
2. Dodaj executor w open-sse/executors/, jeśli wymagana jest własna logika (rozszerz BaseExecutor).
3. Dodaj translator w open-sse/translator/, jeśli nie mówi formatem OpenAI.
4. Jeśli OAuth, dodaj konfigurację w src/lib/oauth/providers/ oraz src/lib/oauth/services/.
5. Zarejestruj modele w open-sse/config/providerRegistry.ts (lub w rejestrze specyficznym dla formatu w open-sse/config/).
6. Napisz testy w tests/unit/.

Dodaj nową trasę API

1. Utwórz src/app/api/your-route/route.ts.
2. Stosuj wzorzec: CORS → walidacja body Zod → auth → delegacja do handlera.
3. Jeśli nowy kształt requestu: dodaj schemat Zod w src/shared/validation/schemas.ts.
4. Jeśli tylko management: dodaj ścieżkę do src/shared/constants/publicApiRoutes.ts (denylist dla publicznej powierzchni API).
5. Dodaj testy w tests/unit/.
6. Zaktualizuj docs/reference/API_REFERENCE.md oraz docs/openapi.yaml.

Dodaj nowy moduł DB

1. Utwórz src/lib/db/yourModule.ts i importuj getDbInstance() z ./core.ts.
2. Eksportuj funkcje CRUD dla swojej domeny.
3. Jeśli nowe tabele: dodaj migrację w src/lib/db/migrations/, numerowaną sekwencyjnie, idempotentną, transakcyjną.
4. Re-export z src/lib/localDb.ts (tylko re-export — bez logiki).
5. Dodaj testy w tests/unit/.

Dodaj nowe narzędzie MCP

1. Dodaj definicję narzędzia w open-sse/mcp-server/tools/ (lub rozszerz open-sse/mcp-server/schemas/tools.ts).
2. Przypisz odpowiednie scope'y w src/shared/constants/mcpScopes.ts.
3. Zarejestruj narzędzie w open-sse/mcp-server/server.ts.
4. Dodaj testy w open-sse/mcp-server/__tests__/.
5. Zaktualizuj MCP-SERVER.md.

Dodaj nowy skill A2A

Zob. A2A-SERVER.md § Adding a New Skill. Skille żyją w src/lib/a2a/skills/ i są rejestrowane przez task manager A2A.

---

11. Konwencje

• Styl kodu: wcięcie 2 spacje, podwójne cudzysłowy, szerokość 100 znaków, średniki, trailing commas es5 — egzekwowane przez Prettier via lint-staged.
• Importy: external → internal (@/, @omniroute/open-sse) → relative.
• Nazewnictwo: pliki camelCase lub kebab-case, komponenty PascalCase, stałe UPPER_SNAKE.
• ESLint: no-eval, no-implied-eval, no-new-func = error wszędzie; no-explicit-any = warn w open-sse/ i tests/, error gdzie indziej.
• TypeScript: strict: false (postawa legacy). Preferuj jawne typy zamiast inferencji na granicach między modułami.
• Baza danych: nigdy nie pisz surowego SQL w trasach ani handlerach — zawsze idź przez moduły src/lib/db/. Nigdy nie dodawaj logiki do src/lib/localDb.ts.
• Typowanie encji DB (#3512): funkcja, która zapisuje lub czyta kształt wiersza tabeli DB, powinna przyjmować/zwracać nazwany interfejs TS odzwierciedlający kolumny tej tabeli 1:1, a nie any ani anonimowy typ inline w miejscu wywołania. Umieść interfejs obok funkcji (np. export interface UsageEntry w src/lib/usage/usageHistory.ts nad saveRequestUsage), trzymaj poszczególne pola opcjonalne/nullable, gdy różni writerzy wypełniają wiersz przyrostowo, i preferuj unknown zamiast any dla pola, którego kształt różni się między callerami (udokumentowane na polu, np. UsageEntry.tokens akceptuje zarówno surowe usage w kształcie providera, jak i znormalizowany kształt). Gdy liczba any w pliku spadnie w ten sposób do zera, dodaj go do allowlisty check:any-budget:t11 (scripts/check/check-t11-any-budget.mjs, maxAny: 0), żeby nie regresował. To konwencja first-slice — szersze sprzątanie „no anonymous any” jest iteracyjne w reszcie codebase.
• Błędy: try/catch ze specyficznymi typami błędów, loguj z kontekstem pino. Nigdy nie połykaj błędów w strumieniach SSE; używaj abort signal do cleanup.
• Bezpieczeństwo: nigdy nie używaj eval() / new Function() / implied eval. Waliduj wszystkie wejścia Zod. Szyfruj poświadczenia w spoczynku (AES-256-GCM). Trzymaj denylist src/shared/constants/upstreamHeaders.ts zsynchronizowaną z warstwą sanitize/validation.
• Commity: Conventional Commits — feat(scope): subject. Dozwolone scope'y: db, sse, oauth, dashboard, api, cli, docker, ci, mcp, a2a, memory, skills.
• Branche: prefiksy feat/, fix/, refactor/, docs/, test/, chore/. Nigdy nie commituj bezpośrednio do main.
• Husky: pre-commit uruchamia lint-staged + check:docs-sync + check:any-budget:t11; pre-push uruchamia check:any-budget:t11 + check:tracked-artifacts (szybkie bramki; wyklucza test:unit).

---

12. Twarde reguły (z CLAUDE.md)

1. Nigdy nie commituj sekretów ani poświadczeń.
2. Nigdy nie dodawaj logiki do src/lib/localDb.ts.
3. Nigdy nie używaj eval() / new Function() / implied eval.
4. Nigdy nie commituj bezpośrednio do main.
5. Nigdy nie pisz surowego SQL w trasach — zawsze idź przez moduły src/lib/db/.
6. Nigdy nie połykaj błędów w strumieniach SSE.
7. Zawsze waliduj wejścia schematami Zod.
8. Zawsze dołączaj testy przy zmianie kodu produkcyjnego.
9. Pokrycie musi pozostać ≥ 60% (statements, lines, functions, branches).

---

13. Zobacz też

• ARCHITECTURE.md — architektura wysokiego poziomu i odpowiedzialności modułów.
• API_REFERENCE.md — referencja publicznego + management API.
• FEATURES.md — macierz feature'ów i wyróżniki wersji.
• RESILIENCE_GUIDE.md — circuit breaker, cooldown, deep dive lockout.
• AUTO-COMBO.md — scoring i strategie Auto Combo.
• MCP-SERVER.md — pełny katalog narzędzi MCP + transporty.
• A2A-SERVER.md — skille protokołu A2A i discovery.
• COMPRESSION_GUIDE.md — kompresja RTK + Caveman.
• CLI-TOOLS.md — integracje CLI.
• ELECTRON_GUIDE.md (jeśli obecny), DOCKER_GUIDE.md, FLY_IO_DEPLOYMENT_GUIDE.md, VM_DEPLOYMENT_GUIDE.md, TERMUX_GUIDE.md, PWA_GUIDE.md — cele wdrożenia.
• TROUBLESHOOTING.md — typowe problemy operacyjne.
• CONTRIBUTING.md — workflow kontrybutora.
• CLAUDE.md — reguły repo dla Claude Code (źródło prawdy dla wielu powyższych konwencji).
• AGENTS.md — głębsza referencja architektury używana przez agentów.