Repository Map (한국어)

루트 파일

파일	용도
README.md	마케팅 랜딩 페이지 + 빠른 시작 + 기능 매트릭스(`llm.txt`도 참조)
CHANGELOG.md	릴리스별 변경 로그(`/version-bump-cc` 스킬로 자동 생성)
LICENSE	MIT 라이선스 텍스트
CLAUDE.md	Claude Code 에이전트를 위한 프로젝트 규칙(필수 규칙, 규약, 시나리오)
AGENTS.md	CLAUDE.md와 동일하지만 Claude 이외의 AI 에이전트(Codex, Cursor 등)를 위한 문서
GEMINI.md	Gemini 기반 에이전트를 위한 간결한 규칙(CLAUDE.md의 일부)
CONTRIBUTING.md	기여자 가이드: 설정, conventional commits, 테스트, PR 흐름
SECURITY.md	취약점 보고 정책, 지원 버전, 위협 모델
CODE_OF_CONDUCT.md	Contributor Covenant — 커뮤니티 행동 지침
llm.txt	LLM 크롤러에 최적화된 일반 텍스트 랜딩 페이지(AI 어시스턴트를 위한 SEO)
package.json	npm 매니페스트, 스크립트, 의존성, 엔진, c8 커버리지 게이트
package-lock.json	잠긴 의존성 트리
tsconfig.json	루트 TypeScript 설정
tsconfig.typecheck-core.json	`src/` 코어용 타입 검사 설정
tsconfig.typecheck-noimplicit-core.json	엄격한(`noImplicitAny`) 타입 검사
tsconfig.tsbuildinfo	TS 증분 빌드 캐시(gitignored)
next.config.mjs	Next.js 16 빌드 설정(standalone 출력)
next-env.d.ts	Next.js에서 자동 생성한 환경 타입
eslint.config.mjs	ESLint 플랫 설정(프로젝트 영역별 규칙)
prettier.config.mjs	Prettier 서식 지정 규칙
postcss.config.mjs	Tailwind/CSS 파이프라인용 PostCSS 설정
playwright.config.ts	Playwright E2E 테스트 설정
vitest.config.ts	Vitest 설정(기본 스위트)
vitest.mcp.config.ts	MCP 서버 / autoCombo / 캐시 스위트용 Vitest 설정
sonar-project.properties	SonarQube/SonarCloud 설정(코드 품질)
Dockerfile	멀티 스테이지 Docker 빌드(builder → runner-base → runner-cli)
docker-compose.yml	4개 프로필(base, cli, host, cliproxyapi) + redis 사이드카를 포함한 개발용 compose
docker-compose.prod.yml	프로덕션 compose(포트 20130, redis, 명명된 볼륨)
.dockerignore	Docker 컨텍스트에서 제외되는 파일
fly.toml	Fly.io 배포 설정(리전 `sin`, 포트 20128, /data 볼륨)
.env.example	환경 파일 템플릿(최초 설치 시 `.env`로 자동 복사)
.gitignore	Git 무시 패턴
.npmignore	npm 게시 제외 목록
.npmrc	npm 설정(레지스트리, lockfile 정책)
.node-version	Node 버전 고정(nvm 호환 도구에서 사용)
.nvmrc	nvm용 Node 버전 고정
eslint.complexity.config.mjs	복잡도 래칫용 ESLint 설정(`scripts/check/check-complexity.mjs --config`)
eslint.sonarjs.config.mjs	SonarJS 규칙용 ESLint 설정(인지 복잡도 / 중복)
source.config.ts	Fumadocs `defineDocs` 소스 설정(`.source/`에 제공)
knip.json	Knip 설정 — 미사용 파일/내보내기/의존성(데드 코드 게이트에 제공)
stryker.conf.json	Stryker 변이 테스트 설정
.size-limit.json	size-limit 번들 예산 설정
promptfooconfig.yaml	promptfoo 평가 설정
.gitleaks.toml	gitleaks 비밀 정보 스캔 규칙 세트
.zizmor.yml	zizmor GitHub-Actions 보안 린트 설정
socket.yml	Socket.dev 공급망 설정
news.json	현지화된 v2 공지 피드; Radar 출시 항목은 비활성 상태로 제공
flake.nix / flake.lock	Nix 개발 셸 정의 + 잠금
.env	로컬 비밀 정보(gitignored — `.env.example`에서 생성)

v3.8.26에서 루트 외부로 이동됨(정리):

→ config/quality/: quality-baseline.json, complexity-baseline.json, duplication-baseline.json, file-size-baseline.json, test-discovery-baseline.json, dependency-allowlist.json, .license-allowlist.json 및 생성된 quality-metrics.json(gitignored). ## config/을 참조하세요.

`src/` — Next.js 애플리케이션

src/
├── app/                 # App Router(페이지 + API 라우트 + 상태 페이지 + 랜딩 페이지)
├── lib/                 # 핵심 라이브러리 / 도메인 모듈(80개 하위 디렉터리 + 약 70개 최상위 파일)
├── domain/              # 순수 도메인 로직(정책 엔진, 폴백, 비용, 잠금, comboResolver, 평가)
├── server/              # 서버 전용 모듈(인가 파이프라인, cors, 인증 미들웨어) — 클라이언트에서 가져올 수 없음
├── shared/              # 안전한 경우 서버와 클라이언트 간 공유(상수, 타입, 유효성 검사, 계약, 유틸리티)
├── i18n/                # next-intl 구성 + 로케일별 메시지 JSON(42개 로케일)
├── middleware/          # Next.js 미들웨어(요청 보강, 로케일 감지)
├── mitm/                # MITM 프록시 핵심: 인증서 생성/설치, 핸들러, 대상, 검사기, 마스크, 패스스루
│   ├── handlers/        # MitmHandlerBase를 확장하는 9개의 IDE 에이전트 핸들러 클래스(antigravity, kiro, copilot, codex, cursor, zed, claudeCode, openCode, trae)
│   └── inspector/       # 트래픽 캡처 계층: 버퍼(인메모리 링), sseMerger, conversationNormalizer, kindDetector, contextKey, httpProxyServer, systemProxyConfig
├── models/              # 모델 어댑터 연결 코드(레거시 호환 계층)
├── scripts/             # 트리 내 유지 관리 스크립트(예: backfillAggregation)
├── sse/                 # 레거시 SSE 핸들러/서비스(chat.ts, chatHelpers.ts, services/auth.ts)
├── store/               # 레거시 인메모리 저장소(src/lib/db로 단계적 전환 중)
├── types/               # 공유 TS 타입 파일
├── instrumentation.ts   # Next.js 텔레메트리 훅(브라우저 + 엣지)
├── instrumentation-node.ts  # Node 전용 계측
└── proxy.ts             # HTTP 프록시 진입점 호환 계층

`src/app/` — App Router (Next.js 16)

경로	용도
`app/api/v1/`	공개 OpenAI 호환 API(약 25개의 하위 라우트: 채팅, 완성, 임베딩, 파일, 배치, 오디오, 이미지, 비디오, 음악, 재순위화, 모더레이션, 검색, WebSocket, 에이전트, 계정, 제공자 등)
`app/api/v1beta/`	Gemini 스타일 API 엔드포인트
`app/api/playground/`	Playground Studio 라우트: `improve-prompt/`(POST — LLM 프롬프트 재작성기), `presets/`(GET 목록 / POST 생성), `presets/[id]/`(GET / PUT / DELETE) — `docs/frameworks/PLAYGROUND_STUDIO.md` 참조
`app/api/` (v1 제외)	관리/관리자 라우트(약 60개 디렉터리: 제공자, 콤보, 설정, MCP, A2A, 평가, 메모리, 스킬, 웹훅, 규정 준수, 복원력, 모니터링, 터널, CLI 도구 등)
`app/api/tools/agent-bridge/`	AgentBridge REST API — 12개 라우트(서버 제어, 에이전트 상태/DNS/매핑, 우회, 인증서, 업스트림 CA). LOCAL_ONLY + SPAWN_CAPABLE. `docs/frameworks/AGENTBRIDGE.md §7` 참조.
`app/api/tools/traffic-inspector/`	Traffic Inspector REST + WebSocket API — 16개 이상의 라우트(요청, 세션, 호스트, 캡처 모드, 내보내기, WebSocket). LOCAL_ONLY + SPAWN_CAPABLE. `docs/frameworks/TRAFFIC_INSPECTOR.md §8` 참조.
`app/a2a/`	A2A JSON-RPC 2.0 진입점(`POST /a2a`)
`app/.well-known/agent.json/`	A2A Agent Card(검색)
`app/(dashboard)/dashboard/`	대시보드 UI 페이지(50개 이상의 섹션, 약 118개의 page.tsx 파일: 제공자, 콤보, 설정, 메모리, 스킬, 웹훅, 평가, 감사, 배치, 캐시, 비용, 상태, 시스템, 활동 등)
`app/(dashboard)/dashboard/search-tools/`	Search Tools Studio UI(3개 탭: 검색/스크래핑/비교 + SearchConceptCard + ProviderCatalog) — `docs/frameworks/SEARCH_TOOLS_STUDIO.md` 참조
`app/(dashboard)/dashboard/memory/`	Memory Studio(계획 21): `page.tsx`(3개 탭 셸), `components/`(MemoryConceptCard, MemoryEngineStatus, EmbeddingSourceSelector, EditMemoryModal, RetrievePreview, QdrantConfigCard, RerankConfigCard), `components/tabs/`(MemoriesTab, PlaygroundTab, EngineTab), `hooks/`(useEngineStatus, useMemorySettings)
`app/(dashboard)/dashboard/tools/agent-bridge/`	AgentBridge 대시보드 페이지 — 서버 카드, 9개 에이전트 카드, 설정 마법사, 모델 매핑, 우회 목록. i18n PT-BR + EN. `docs/frameworks/AGENTBRIDGE.md` 참조.
`app/(dashboard)/dashboard/tools/traffic-inspector/`	Traffic Inspector 대시보드 페이지 — DevTools 분할 화면, 7개 세부 정보 탭, 4개 캡처 모드 토글, 세션 레코더, 컨텍스트 색상화. i18n PT-BR + EN. `docs/frameworks/TRAFFIC_INSPECTOR.md` 참조.
`app/(dashboard)/dashboard/activity/`	활동 피드 페이지(그룹 B): `page.tsx`(서버) + `ActivityFeedClient.tsx` + `components/{ActivityFeed,ActivityItem,DayHeader,EventTypeFilter}.tsx` — `docs/architecture/MONITORING_SECTIONS.md` 참조
`app/(dashboard)/dashboard/costs/quota-share/`	할당량 공유 페이지(그룹 B): `QuotaSharePageClient.tsx` + `components/{PoolCard,DimensionBar,AllocationTable,BurnRateChart,QuotaConceptCard,CreatePoolModal,EditAllocationsModal}.tsx` + `hooks/{usePools,usePoolUsage,useLocalStoragePoolMigration}.ts`
`app/(dashboard)/dashboard/costs/quota-share/plans/`	공급자 플랜 구성 페이지(그룹 B): `page.tsx` + `ProviderPlanConfigClient.tsx` — 연결별 할당량 차원 재정의
`app/docs/`	내장 문서 뷰어(`docs/*.md` 렌더링)
`app/landing/`	마케팅 랜딩 페이지
`app/login/`, `forgot-password/`, `forbidden/`	인증 관련 페이지
`app/{400,401,403,408,429,500,502,503}/`	HTTP 오류 페이지
`app/maintenance/`, `offline/`, `status/`, `privacy/`, `terms/`, `callback/`	정적/상태 페이지
`app/layout.tsx`, `page.tsx`, `manifest.ts`, `globals.css`	루트 레이아웃, 홈, PWA 매니페스트, 전역 CSS
`app/error.tsx`, `global-error.tsx`, `not-found.tsx`, `loading.tsx`	오류 경계

`src/lib/` — 핵심 라이브러리(약 50개 모듈)

모듈	목적
`a2a/`	A2A 프로토콜 작업 관리자, 스킬(5개), 스트리밍
`acp/`	CLI 에이전트 레지스트리(로컬 CLI 검색 — `docs/frameworks/AGENT_PROTOCOLS_GUIDE.md` 참조)
`api/`	공유 API 헬퍼(`requireManagementAuth`, 유효성 검사)
`auth/`	세션, 비밀번호 해싱, 토큰 유효성 검사
`batches/`	OpenAI Batches API 핸들러
`catalog/`	공급자 카탈로그 Zod 유효성 검사 + 기능 확인
`cloudAgent/`	클라우드 에이전트(Codex Cloud, Devin, Jules) — `docs/frameworks/CLOUD_AGENT.md` 참조
`combos/`	콤보 확인 + 순서 재지정 헬퍼
`audit/`	활동 피드 헬퍼: `highLevelActions.ts`(허용 목록 + `isHighLevelAction()`), `activityIcons.ts`(작업 → 아이콘/동사 맵), `timeline.ts`(groupByDay/relativeTime) — `docs/architecture/MONITORING_SECTIONS.md` 참조
`compliance/`	감사 로그 + 공급자 감사 — `docs/security/COMPLIANCE.md` 참조
`compression/`	압축 엔진 연결 코드(엔진은 `open-sse/services/compression/`에 위치)
`config/`	런타임 구성 헬퍼
`db/`	120개 이상의 도메인 DB 모듈 + 168개 마이그레이션(SQLite의 경우 항상 이 모듈을 통해 접근)
`quota/`	할당량 공유 엔진: `dimensions.ts`(타입/Zod), `types.ts`(QuotaStore 인터페이스), `sqliteQuotaStore.ts`, `redisQuotaStore.ts`, `storeFactory.ts`, `fairShare.ts`, `burnRate.ts`, `planResolver.ts`, `planRegistry.ts`, `saturationSignals.ts`, `enforce.ts`, `spendRecorder.ts` — `docs/routing/QUOTA_SHARE.md` 참조
`radar/`	Radar 무료 모델 카탈로그 클라이언트: `feedSchema.ts`, `pinnedKeys.ts`, `verify.ts`, `sync.ts`, `applyFeed.ts`, `index.ts` (`getRadarCatalog()`) — `docs/frameworks/RADAR.md` 참조
`display/`	UI 형식 지정 헬퍼(비용, 지연 시간 등)
`embeddings/`	임베딩 서비스 헬퍼
`env/`	환경 변수 파싱 + 유효성 검사
`evals/`	평가 프레임워크(스위트, 러너, 런타임) — `docs/frameworks/EVALS.md` 참조
`guardrails/`	PII 마스커, 프롬프트 인젝션, 비전 브리지 — `docs/security/GUARDRAILS.md` 참조
`jobs/`	백그라운드 작업(cron 유사)
`memory/`	대화형 메모리(SQLite FTS5 + sqlite-vec 하이브리드 RRF + Qdrant 티어 2) — `docs/frameworks/MEMORY.md` 참조
`memory/embedding/`	다중 소스 임베딩 계층: `index.ts`(리졸버), `remote.ts`, `staticPotion.ts`, `transformersLocal.ts`, `cache.ts`, `types.ts`(계획 21)
`memory/vectorStore.ts`	sqlite-vec v0.1.9 래퍼 — KNN 완전 탐색 + 하이브리드 RRF(FTS5 + 벡터, k=60). 지연 초기화되며, sqlite-vec을 사용할 수 없는 경우에도 기능이 단계적으로 축소됩니다. (계획 21)
`memory/reindex.ts`	`runReindexBatch()` — 백그라운드에서 `needs_reindex=1`인 메모리를 처리합니다. `POST /api/memory/reindex` 및 지연 백필 경로에서 호출됩니다. (계획 21)
`monitoring/`	상태 검사, 메트릭 방출
`oauth/`	22개 제공자 모듈을 위한 OAuth/가져오기 흐름(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)
`plugins/`	플러그인 레지스트리
`promptCache/`	Anthropic 스타일 프롬프트 캐시 중단점
`skills/`	스킬 프레임워크(내장 + 마켓플레이스 + SkillsSH) — `docs/frameworks/SKILLS.md` 참조
`playground/`	Playground Studio 공유 헬퍼: `codeExport.ts`(curl/Python/TS 생성기), `promptImprover.ts`(메타 프롬프트 빌더), `streamMetrics.ts`(순수 TTFT/TPS), `types.ts`(요금표) — `docs/frameworks/PLAYGROUND_STUDIO.md` 참조
`webhookDispatcher.ts`	HMAC 웹훅 전송 — `docs/frameworks/WEBHOOKS.md` 참조
`cloudflaredTunnel.ts`, `ngrokTunnel.ts`	터널 관리자 — `docs/ops/TUNNELS_GUIDE.md` 참조
`cloudSync.ts`, `initCloudSync.ts`	선택적 상태 클라우드 동기화
`localDb.ts`	db 모듈용 재내보내기 배럴(로직 없음 — 재내보내기만 수행)
`cacheLayer.ts`, `idempotencyLayer.ts`	요청 캐싱 + 멱등성
(최상위 파일 약 30개 추가)	특수 목적 헬퍼(logEnv, modelsDevSync, piiSanitizer 등)

`src/lib/db/` — 데이터베이스(모듈 122개 + 마이그레이션 168개)

하위 디렉터리	용도
`db/core.ts`	WAL 저널링을 사용하는 `getDbInstance()` 싱글턴
`db/migrations/`	버전이 지정된 SQL 파일(멱등적, 트랜잭션 방식). `073_memory_vec.sql`은 `memory_vec_meta` + `needs_reindex` 열을 추가합니다(계획 21).
`db/playgroundPresets.ts`	Playground Studio 프리셋용 CRUD 모듈(`listPlaygroundPresets`, `getPlaygroundPreset`, `createPlaygroundPreset`, `updatePlaygroundPreset`, `deletePlaygroundPreset`)
`db/memoryVec.ts`	`memory_vec_meta`용 CRUD(active_dim, embedding_signature, last_reset_at, vec_loaded) + `markMemoryNeedsReindex`, `getMemoryReindexQueue` 등(계획 21)
`db/<domain>.ts`	도메인별 모듈 하나: providers, combos, apiKeys, users, sessions, usage, auditlog, webhooks, skills, memory_entries, cloud_agent_tasks, evals*, reasoning_cache 등

`src/domain/`

모듈	용도
`policy.ts`	정책 엔진
`fallbackPolicy.ts`	폴백 결정 트리
`costRules.ts`	비용 계산 규칙
`lockoutPolicy.ts`	모델/연결 잠금 정책
`tagRouter.ts`	태그 기반 라우팅
`comboResolver.ts`	콤보 해석(콤보 엔진에서 사용)
`modelAvailability.ts`	모델별 가용성 확인
`assessment/`	모델 평가(RFC-AUTO-ASSESSMENT 1단계)

`src/server/`

모듈	용도
`authz/`	권한 부여 파이프라인: `classify` → `policies` → `enforce` — `docs/architecture/AUTHZ_GUIDE.md` 참조
`cors/`	CORS 구성
`auth/`	세션 미들웨어

`src/shared/`

모듈	목적
`constants/providers.ts`	Zod 검증이 적용된 355개 제공자(단일 진실 공급원)
`constants/cliTools.ts`	외부 CLI 도구 레지스트리
`constants/routingStrategies.ts`	우선순위가 지정된 19개 라우팅 전략
`constants/publicApiRoutes.ts`	관리 인증이 아닌 Bearer 인증이 필요한 라우트
`constants/upstreamHeaders.ts`	업스트림 요청용 헤더 차단 목록
`validation/schemas.ts`	약 80개의 Zod 스키마(API 계약의 단일 진실 공급원)
`validation/helpers.ts`	Zod 검증 헬퍼(`validateBody` 등)
`types/`	공유 TS 타입
`contracts/`	공개 API 계약(`package.json`의 `files:`에서 사용)
`utils/circuitBreaker.ts`	제공자 서킷 브레이커(`docs/architecture/RESILIENCE_GUIDE.md` 참조)
`utils/apiAuth.ts`	API 키 검증 및 범위 확인
`utils/fetchTimeout.ts`	업스트림 fetch용 타임아웃/중단 래퍼
`utils/releaseNotes.ts`	종료된 v2/레거시 공지 파서, 현지화 및 ID 해제

`open-sse/` — 스트리밍 엔진 워크스페이스

별도의 npm 워크스페이스(@omniroute/open-sse)입니다. 요청 처리 및 공급자 실행을 담당합니다.

open-sse/
├── handlers/            # 16개 파일(핸들러 12개 + 헬퍼 4개): chatCore, responsesHandler, embeddings, audio, image, video, music, rerank, moderations, search 등
├── executors/           # 공급자별 실행기 67개(BaseExecutor 확장)
├── translator/          # 형식 변환기(요청 9개, 응답 9개, 헬퍼 9개)
├── transformer/         # Responses API ↔ Chat Completions(TransformStream)
├── services/            # 약 80개 이상의 서비스 모듈(combo, accountFallback, autoCombo, reasoningCache, claude code/chatgpt stealth, modelDeprecation, taskAwareRouter, workflowFSM 등)
├── mcp-server/          # MCP 서버(도구 110개, 전송 방식 3개, 범위 33개)
├── config/              # 공급자/모델 레지스트리, 헤더 구성, 모델 별칭
├── utils/               # TLS 클라이언트, 프록시 fetch/dispatcher, 네트워크 헬퍼
├── index.ts             # 워크스페이스 진입점
├── package.json         # 워크스페이스 매니페스트
├── tsconfig.json        # 워크스페이스 TS 구성
└── types.d.ts           # 워크스페이스 타입 선언

`open-sse/mcp-server/`

경로	용도
`server.ts`	MCP 서버 수명 주기(stdio + HTTP 전송 방식)
`httpTransport.ts`	HTTP Streamable + SSE 전송 방식(`/api/mcp/sse`, `/api/mcp/stream`)
`audit.ts`	`mcp_tool_audit` 테이블에 감사 로그 기록
`scopeEnforcement.ts`	도구별 범위 검증
`runtimeHeartbeat.ts`	`DATA_DIR/runtime/mcp-heartbeat.json`에 상태 하트비트 기록
`descriptionCompressor.ts`	컨텍스트 절약을 위한 도구 설명 메타데이터 압축
`schemas/tools.ts`	기본 도구 정의 36개 + 범위
`tools/advancedTools.ts`	고급 도구 구현
`tools/memoryTools.ts`	메모리 도구 3개(search/add/clear)
`tools/skillTools.ts`	스킬 도구 4개(list/enable/execute/executions)
`tools/compressionTools.ts`	압축 도구 5개
`README.md`	내부 MCP 서버 README(`docs/frameworks/MCP-SERVER.md`에서 상호 링크됨)

`electron/` — 데스크톱 래퍼

파일	용도
`main.js`	Electron 메인 프로세스(BrowserWindow, 임베디드 Next.js 서버, 트레이, 자동 업데이트)
`preload.js`	IPC 브리지(contextBridge → `window.omniroute`)
`package.json`	electron-builder 구성 + Electron 41 + electron-builder 26.10 의존성
`assets/`	앱 아이콘(Windows .ico, macOS .icns, Linux .png)
`dist-electron/`	빌드 출력(git에서 무시됨)
`types.d.ts`	렌더러 브리지용 타입 선언
`README.md`	내부 Electron README(`docs/guides/ELECTRON_GUIDE.md`도 참조)

`bin/` — CLI

파일	용도
`omniroute.mjs`	기본 CLI 진입점 — `omniroute serve`, `omniroute setup`, `omniroute doctor`, `omniroute providers`, `omniroute combos` 등
`reset-password.mjs`	독립형 비밀번호 재설정 CLI
`cli/commands/setup.mjs`	대화형 + 비대화형 설정 마법사
`cli/commands/doctor.mjs`	시스템 상태 진단(8개 이상의 검사)
`cli/commands/providers.mjs`	제공자 목록 조회/테스트/검증
`cli/{args,data-dir,encryption,io,provider-catalog,provider-store,provider-test,settings-store,sqlite}.mjs`	CLI 도우미 모듈
`cli/tray/tray.ts`	시스템 트레이 통합(크로스 플랫폼: Windows에서는 NotifyIcon, macOS/Linux에서는 systray2)
`cli/tray/tray.ps1`	PowerShell NotifyIcon 백엔드(Windows, 새로운 바이너리 추가 없음)
`cli/tray/autostart.ts`	크로스 플랫폼 자동 시작(LaunchAgent / .desktop / 레지스트리)
`cli/runtime/sqliteRuntime.mjs`	5단계 SQLite 드라이버 확인 체인(번들 → 런타임 → 지연 설치 → node:sqlite → sql.js)
`cli/runtime/magicBytes.mjs`	바이너리 매직 바이트 검증(ELF / Mach-O / Mach-O fat / PE)
`cli/runtime/index.mjs`	`warmUpRuntimes()` — postinstall / 최초 시작 시 드라이버를 미리 확인
`nodeRuntimeSupport.mjs`	설치 시 지원되는 Node.js 버전 검증

`skills/` — 공개 에이전트 스킬

파일	용도
`skills/omniroute*/SKILL.md`	외부 AI 에이전트(Claude Desktop, ChatGPT, Cursor, Cline)를 위한 10개의 스킬 매니페스트

`scripts/` — 빌드 및 검사 스크립트

스크립트	용도
`run-next.mjs`	환경 변수 로드 기능을 포함한 개발/시작 실행기
`build-next-isolated.mjs`	독립 실행형 빌드(Next.js 16 standalone)
`prepublish.ts`	`npm pack` 실행 전 패키지 준비
`postinstall.mjs`	최초 설치 시 `.env.example`에서 `.env` 자동 생성
`sync-env.mjs`	`.env` 키를 `.env.example`과 다시 동기화
`check-cycles.mjs`	순환 종속성 감지
`check-route-validation.mjs`	모든 API 라우트에 Zod 검증이 적용되었는지 확인
`check-t11-any-budget.mjs`	파일별 명시적 `any` 허용 한도 적용
`check-docs-sync.mjs`	문서 버전 동기화 검증(기존 pre-commit)
`check-env-doc-sync.mjs`	신규: 코드, `.env.example`, `ENVIRONMENT.md` 간 환경 변수 교차 검증
`check-docs-counts-sync.mjs`	신규: 실행기, 전략, OAuth, A2A 스킬 수가 문서와 일치하는지 검증
`check-deprecated-versions.mjs`	신규: 문서에서 오래된 버전/날짜 표시
`check-supported-node-runtime.ts`	현재 Node 버전의 지원 여부 검증
`check-pr-test-policy.mjs`	프로덕션 코드 변경 시 “테스트 필수” 규칙 적용
`gen-provider-reference.ts`	신규: 카탈로그에서 `docs/reference/PROVIDER_REFERENCE.md` 자동 생성
`i18n/generate-multilang.mjs`	Google Translate를 통해 UI 문자열 및 문서 번역
`i18n_autotranslate.py`	LLM 기반 문서 번역 파이프라인
`validate_translation.py`	로케일별 번역 검증
`check_translations.py`	코드 측 i18n 키 검사
`run-playwright-tests.mjs`	Playwright E2E 실행기
`run-protocol-clients-tests.mjs`	MCP/A2A E2E 실행기
`run-ecosystem-tests.mjs`	생태계(제공자 통합) 테스트
`test-report-summary.mjs`	커버리지 요약 마크다운 생성
`smoke-electron-packaged.mjs`	패키징된 Electron 빌드의 스모크 테스트
`native-binary-compat.mjs`	네이티브 종속성(`better-sqlite3`)이 Electron의 Node와 일치하는지 검증
`validate-pack-artifact.ts`	npm pack 출력 검증
`responses-ws-proxy.mjs`	Codex Responses API용 WebSocket 브리지
`v1-ws-bridge.mjs`	`/api/v1/ws` 엔드포인트용 WebSocket 브리지
`standalone-server-ws.mjs`	독립 실행형 WS 서버 실행기
`system-info.mjs`	지원을 위한 시스템/런타임 정보 출력
`healthcheck.mjs`	일회성 상태 검사(Docker HEALTHCHECK에서 사용)
`uninstall.mjs`	완전 제거 스크립트

`docs/` — 공개 문서 (루트 파일 7개 + 하위 디렉터리 17개)

최상위 가이드

문서	용도
`ARCHITECTURE.md`	상위 수준 아키텍처, 하위 시스템 맵, 대시보드 인터페이스
`CODEBASE_DOCUMENTATION.md`	엔지니어링 참조: 디렉터리, 모듈, 규칙
`FEATURES.md`	v3.8 주요 사항이 포함된 기능 매트릭스
`USER_GUIDE.md`	최종 사용자 매뉴얼(설정, 모델, 콤보, CLI, 오디오 등)
`API_REFERENCE.md`	인증 모델이 포함된 API 엔드포인트 참조
`openapi.yaml`	OpenAPI 3.0 사양(경로 121개)
`SETUP_GUIDE.md`	설치 방법(npm, npx, Docker, Electron, Termux, 소스)
`ENVIRONMENT.md`	모든 환경 변수(약 800개 문서화, `.env.example` 약 3,050줄)
`TROUBLESHOOTING.md`	일반적인 오류 + v3.8.0 알려진 문제
`RELEASE_CHECKLIST.md`	전체 릴리스 흐름(스킬, husky, conventional commits, 배포)
`COVERAGE_PLAN.md`	커버리지 목표 및 현재 상태
`FREE_TIERS.md`	엄선된 무료 티어 제공자(무료 48개 이상 + OAuth 11개)
`CLI-TOOLS.md`	외부 CLI 통합 + 내부 OmniRoute CLI
`I18N.md`	i18n 아키텍처, 언어 추가 방법, 42개 로케일
`UNINSTALL.md`	완전한 제거 절차
`PROVIDER_REFERENCE.md`	자동 생성된 355개 제공자 카탈로그(재생성: `npm run gen:provider-reference`)

하위 시스템 심층 가이드

문서	용도
`MCP-SERVER.md`	MCP 서버: 도구 110개, 전송 방식 3개, 범위 33개, REST 엔드포인트
`A2A-SERVER.md`	A2A v0.3: JSON-RPC, 스킬 6개, REST 헬퍼, 에이전트 카드
`AGENT_PROTOCOLS_GUIDE.md`	통합 가이드: A2A와 ACP와 Cloud Agents 비교
`CLOUD_AGENT.md`	Codex Cloud / Devin / Jules 오케스트레이션
`SKILLS.md`	스킬 프레임워크(내장 + 마켓플레이스 + SkillsSH + 샌드박스)
`RADAR.md`	Radar 무료 모델 카탈로그 오버레이(`RADAR_ENABLED`, 기본적으로 비활성화)
`MEMORY.md`	메모리 시스템(SQLite FTS5 + Qdrant)
`EVALS.md`	평가 프레임워크(스위트, 실행, 루브릭)
`GUARDRAILS.md`	PII 마스커, 프롬프트 인젝션, 비전 브리지
`COMPLIANCE.md`	감사 로그, 보존, noLog 옵트아웃
`WEBHOOKS.md`	HMAC 서명 웹후크 전송
`REASONING_REPLAY.md`	`reasoning_content`용 하이브리드 메모리/SQLite 캐시
`AUTHZ_GUIDE.md`	권한 부여 파이프라인(`classify` → `policies` → `enforce`)
`RESILIENCE_GUIDE.md`	서킷 브레이커 + 쿨다운 + 모델 잠금
`docs/security/STEALTH_GUIDE.md` (git에만 있음)	TLS 핑거프린팅(JA3/JA4), Claude Code CCH, MITM 인증서
`AUTO-COMBO.md`	Auto Combo 엔진(16개 요소 점수화, 6개 모드 팩, 가상 팩토리)

압축

문서	용도
`COMPRESSION_GUIDE.md`	압축 모드 개요 + 로드맵
`COMPRESSION_ENGINES.md`	Caveman + RTK 엔진, 레지스트리 계약
`COMPRESSION_RULES_FORMAT.md`	Caveman 규칙 팩 JSON 스키마
`COMPRESSION_LANGUAGE_PACKS.md`	언어별 규칙 팩 목록
`RTK_COMPRESSION.md`	RTK 선언형 파이프라인(필터 49개)

배포

문서	용도
`DOCKER_GUIDE.md`	Docker 빌드, 프로필(base/cli/host/cliproxyapi), Redis 사이드카
`VM_DEPLOYMENT_GUIDE.md`	일반 VM/VPS 배포(Ubuntu/Debian + nginx + systemd)
`FLY_IO_DEPLOYMENT_GUIDE.md`	Fly.io 배포(현재 중국어로만 제공)
`TERMUX_GUIDE.md`	Termux를 통한 Android 헤드리스 운영
`PWA_GUIDE.md`	프로그레시브 웹 앱 설치 + 서비스 워커
`ELECTRON_GUIDE.md`	데스크톱 앱 빌드 + 서명 + 배포
`TUNNELS_GUIDE.md`	Cloudflared + ngrok + Tailscale Funnel
`PROXY_GUIDE.md`	4단계 아웃바운드 프록시 + 1proxy 마켓플레이스

하위 디렉터리

하위 디렉터리	용도
`docs/i18n/`	현지화된 문서 번역(41개 로케일)
`docs/screenshots/`	가이드용 이미지 에셋
`_tasks/superpowers/`	superpowers(`writing-plans`/`brainstorming`)의 계획/사양 + 조사 자료 — 격리되어 별도로 버전 관리되는 저장소이며 기본 트리에서는 gitignore 처리됩니다. CLAUDE.md → “Planning & Research Artifacts”를 참조하세요.

`tests/` — 테스트 스위트

하위 디렉터리	유형	실행 도구
`tests/unit/`	단위 테스트(약 4,800개 파일, 가장 빠름)	Node 네이티브 테스트 실행 도구
`tests/integration/`	다중 모듈 + DB 통합 테스트	Node 네이티브 테스트 실행 도구(동시성 1)
`tests/e2e/`	UI + 워크플로 E2E	Playwright
`tests/e2e/protocol-clients.test.ts`	MCP + A2A 실제 클라이언트 E2E	사용자 정의 프로토콜 클라이언트
`tests/e2e/ecosystem.test.ts`	공급자 통합(네트워크 사용)	Node 네이티브 테스트 실행 도구

`public/` — 정적 자산

경로	용도
`public/` (루트)	파비콘, robots.txt, 매니페스트, 서비스 워커, 마케팅 이미지
`public/providers/`	공급자 로고 PNG/SVG(대시보드에서 사용)

`config/` — 정적 구성 + 품질 게이트 상태

배포되는 구성 템플릿과 커밋된 품질 게이트 기준선입니다. (루트 구성을 간소하게 유지하기 위해 v3.8.26에서 저장소 루트로부터 이곳으로 이동했습니다.)

경로	용도
`config/i18n.json`	로케일 목록 + 메타데이터(42개 로케일 수의 기준 소스)
`config/i18n-schema.json`	`i18n.json`의 유효성을 검사하는 JSON 스키마
`config/payloadRules.json`	업스트림 페이로드 정제 규칙
`config/quality/quality-baseline.json`	다중 메트릭 래칫 기준선(`scripts/quality/check-quality-ratchet.mjs`)
`config/quality/complexity-baseline.json`	고정된 ESLint 복잡도 기준선(`check-complexity.mjs`)
`config/quality/duplication-baseline.json`	고정된 jscpd 중복 기준선(`check-duplication.mjs`)
`config/quality/file-size-baseline.json`	고정된 파일별 크기 기준선(`check-file-size.mjs`)
`config/quality/test-discovery-baseline.json`	고정된 고립 테스트 기준선(`check-test-discovery.mjs`)
`config/quality/dependency-allowlist.json`	승인된 종속성 허용 목록(`check-deps.mjs`)
`config/quality/.license-allowlist.json`	SPDX 라이선스 허용 목록(`check-licenses.mjs`)
`config/quality/quality-metrics.json`	임시 수집 메트릭(`collect-metrics.mjs`에서 생성, gitignored)

`.github/` — GitHub 통합

경로	용도
`.github/workflows/`	GitHub Actions CI/CD 워크플로(lint, test, coverage, release)
`.github/ISSUE_TEMPLATE/`	버그/기능 이슈 템플릿
`.github/pull_request_template.md`	PR 템플릿
`.github/dependabot.yml`	의존성 업데이트 설정

`.husky/` — Git 훅

파일	용도
`pre-commit`	`lint-staged + check-docs-sync + check:any-budget:t11` 실행
`pre-push`	현재 비활성화됨(주석 처리). `npm run test:unit`을 수동으로 실행하세요.
`_/`	Husky 내부 파일

`.claude/` — Claude Code 슬래시 명령어

파일	용도
`commands/version-bump-cc.md`	`/version-bump-cc` — 버전 상향 + 변경 로그 자동 생성
`commands/generate-release-cc.md`	`/generate-release-cc` — 전체 릴리스 워크플로
`commands/deploy-vps-{local,akamai,both}-cc.md`	VPS에 배포
`commands/capture-release-evidences-cc.md`	새 기능을 브라우저에서 WebP로 녹화
`commands/review-{prs,discussions}-cc.md`	GitHub PR/토론 분류
`commands/{review-issues,implement-features}-cc.md`	이슈 워크플로
`settings.local.json`	프로젝트별 Claude Code 설정

`.agents/` — 범용 에이전트 워크플로(Codex / Cursor / 기타)

경로	용도
`workflows/*-ag.md`	11개 워크플로 정의(`.claude/commands/`의 미러)
`skills/<name>/SKILL.md`	Codex 실행 참고 사항이 포함된 9개 스킬 정의

참고: 현재 워크플로와 명령어는 바이트 단위로 동일합니다. .agents/가 다른 에이전트 런타임(Codex)을 대상으로 한다면, 각 변형은 유의미하게 달라야 합니다.

`_ideia/`, `_mono_repo/`, `_references/`, `_tasks/` — 트리 외부 콘텐츠

밑줄로 시작하는 이 디렉터리에는 배포되지 않는 콘텐츠가 저장됩니다.

_ideia/ — 설계 참고 사항(defer / notfit / viable 범주)
_mono_repo/ — 과거 하위 프로젝트(omnirouteCloud, omnirouteSite, vscode-extension)
_references/ — 개발 중 상호 참조를 위한 관련 OSS 프로젝트(LiteLLM, 9router, ClawRouter, CLIProxyAPI, modelrelay, new-api 등)의 읽기 전용 클론
_tasks/ — 릴리스별 작업 추적 파일(비공식)

npm pack 출력에는 포함되지 않습니다. .npmignore를 참조하세요.

생성됨 / Git에서 무시됨

경로	용도
`node_modules/`	npm 의존성
`.next/`	Next.js 빌드 출력
`coverage/`	c8 커버리지 보고서
`logs/`	런타임 로그
`package/`	npm pack 스테이징
`.playwright-mcp/`	Playwright MCP 테스트 산출물
`.issues/`	로컬 이슈 캐시
`tsconfig.tsbuildinfo`	TS 증분 빌드 캐시

탐색 팁

새로운 기여자인가요? CONTRIBUTING.md → CLAUDE.md → docs/architecture/ARCHITECTURE.md → docs/architecture/CODEBASE_DOCUMENTATION.md 순서로 읽어보세요.
프로바이더를 추가하나요? docs/architecture/ARCHITECTURE.md § Adding a New Provider를 따르고 docs/reference/PROVIDER_REFERENCE.md와 교차 확인하세요.
라우트를 추가하나요? docs/architecture/ARCHITECTURE.md § Adding a New API Route와 src/shared/validation/schemas.ts를 참조하세요.
MCP 도구를 추가하나요? docs/frameworks/MCP-SERVER.md § Adding a Tool을 참조하세요.
A2A 스킬을 추가하나요? docs/frameworks/A2A-SERVER.md § Adding a New Skill을 참조하세요.
로컬에서 실행하나요? docs/guides/SETUP_GUIDE.md를 참조하세요.
배포하나요? docs/guides/DOCKER_GUIDE.md / docs/ops/VM_DEPLOYMENT_GUIDE.md / docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md를 참조하세요.
릴리스하나요? docs/ops/RELEASE_CHECKLIST.md와 /generate-release-cc Claude Code 스킬을 참조하세요.

OmniRoute 소스 코드 (a58000c7685f)

HagiCode

HagiCode는 구조화된 워크플로, 다중 에이전트 실행, Hero Dungeon 뷰를 갖춘 에이전트 코딩 작업 공간입니다.

더 스마트하고 빠르며 즐거운 에이전트 워크플로로 유용한 소프트웨어를 만드세요.

Smart구조화된 워크플로는 의도를 아이디어부터 배포까지 실행 가능한 경로로 바꿉니다.
Efficient다중 에이전트 워크플로로 조사, 구현, 검토를 병렬로 진행합니다.
FunHero Dungeon은 긴 코딩 세션을 시각적이고 협업적인 경험으로 만듭니다.

HagiCode 방문

언어 선택

언어 선택

Repository Map (한국어)

루트 파일

`src/` — Next.js 애플리케이션

`src/app/` — App Router (Next.js 16)

`src/lib/` — 핵심 라이브러리(약 50개 모듈)

`src/lib/db/` — 데이터베이스(모듈 122개 + 마이그레이션 168개)

`src/domain/`

`src/server/`

`src/shared/`

`open-sse/` — 스트리밍 엔진 워크스페이스

`open-sse/mcp-server/`

`electron/` — 데스크톱 래퍼

`bin/` — CLI

`skills/` — 공개 에이전트 스킬

`scripts/` — 빌드 및 검사 스크립트

`docs/` — 공개 문서 (루트 파일 7개 + 하위 디렉터리 17개)

최상위 가이드

하위 시스템 심층 가이드

압축

배포

하위 디렉터리

`tests/` — 테스트 스위트

`public/` — 정적 자산

`config/` — 정적 구성 + 품질 게이트 상태

`.github/` — GitHub 통합

`.husky/` — Git 훅

`.claude/` — Claude Code 슬래시 명령어

`.agents/` — 범용 에이전트 워크플로(Codex / Cursor / 기타)

`_ideia/`, `_mono_repo/`, `_references/`, `_tasks/` — 트리 외부 콘텐츠

생성됨 / Git에서 무시됨

탐색 팁

HagiCode

Repository Map (한국어)

루트 파일

src/ — Next.js 애플리케이션

src/app/ — App Router (Next.js 16)

src/lib/ — 핵심 라이브러리(약 50개 모듈)

src/lib/db/ — 데이터베이스(모듈 122개 + 마이그레이션 168개)

src/domain/

src/server/

src/shared/

open-sse/ — 스트리밍 엔진 워크스페이스

open-sse/mcp-server/

electron/ — 데스크톱 래퍼

bin/ — CLI

skills/ — 공개 에이전트 스킬

scripts/ — 빌드 및 검사 스크립트

docs/ — 공개 문서 (루트 파일 7개 + 하위 디렉터리 17개)

최상위 가이드

하위 시스템 심층 가이드

압축

배포

하위 디렉터리

tests/ — 테스트 스위트

public/ — 정적 자산

config/ — 정적 구성 + 품질 게이트 상태

.github/ — GitHub 통합

.husky/ — Git 훅

.claude/ — Claude Code 슬래시 명령어

.agents/ — 범용 에이전트 워크플로(Codex / Cursor / 기타)

_ideia/, _mono_repo/, _references/, _tasks/ — 트리 외부 콘텐츠

생성됨 / Git에서 무시됨

탐색 팁

HagiCode

`src/` — Next.js 애플리케이션

`src/app/` — App Router (Next.js 16)

`src/lib/` — 핵심 라이브러리(약 50개 모듈)

`src/lib/db/` — 데이터베이스(모듈 122개 + 마이그레이션 168개)

`src/domain/`

`src/server/`

`src/shared/`

`open-sse/` — 스트리밍 엔진 워크스페이스

`open-sse/mcp-server/`

`electron/` — 데스크톱 래퍼

`bin/` — CLI

`skills/` — 공개 에이전트 스킬

`scripts/` — 빌드 및 검사 스크립트

`docs/` — 공개 문서 (루트 파일 7개 + 하위 디렉터리 17개)

`tests/` — 테스트 스위트

`public/` — 정적 자산

`config/` — 정적 구성 + 품질 게이트 상태

`.github/` — GitHub 통합

`.husky/` — Git 훅

`.claude/` — Claude Code 슬래시 명령어

`.agents/` — 범용 에이전트 워크플로(Codex / Cursor / 기타)

`_ideia/`, `_mono_repo/`, `_references/`, `_tasks/` — 트리 외부 콘텐츠