OpenDocuments: Instructions file for Codex

AGENTS.md

Project Overview

OpenDocuments는 자체 호스팅 RAG(Retrieval-Augmented Generation) 플랫폼이다. GitHub, Notion, Google Drive 등 다양한 소스의 문서를 인덱싱하고, 자연어로 질문하면 출처와 함께 답변을 제공한다.

• Repository: https://github.com/joungminsung/OpenDocuments
• License: MIT
• Node.js: >= 20.0.0
• Package Manager: [email protected]
• Build Orchestrator: Turborepo v2.3.0
• Language: TypeScript 5.5+ (strict mode, ESM)

---

Monorepo Structure

packages/          # 핵심 패키지 (5개)
  core/            # 비즈니스 로직 전체 (RAG, ingest, storage, auth, plugin system)
  server/          # HTTP API (Hono), MCP server, auth middleware, widget
  cli/             # CLI 17개 명령어 (Commander.js) - npm 글로벌 패키지 'opendocuments'
  web/             # React SPA (Vite + Tailwind) - private, npm 배포 안 함
  client/          # TypeScript SDK (@opendocuments/client)

plugins/           # 플러그인 (21개)
  model-*/         # 5개: ollama, openai, anthropic, google, grok
  parser-*/        # 9개: pdf, docx, xlsx, html, jupyter, email, code, pptx
  connector-*/     # 8개: github, notion, gdrive, s3, confluence, swagger, web-crawler, web-search

docs-site/         # VitePress 문서 사이트 (GitHub Pages 자동 배포)

---

Common Commands

npm run setup          # install + build (처음 클론 시)
npm run build          # turbo build (전체)
npm run test           # turbo test (51 tasks, ~648 tests)
npm run dev            # watch mode (전체)
npm run typecheck      # turbo typecheck

# 특정 패키지만
npx turbo build --filter=opendocuments-core
npx turbo test --filter=opendocuments-core

---

Code Conventions

TypeScript

• strict mode 필수 (tsconfig.base.json)
• ESM: 모든 import에 .js 확장자 필수

  import { sha256 } from './utils/hash.js'    // O
  import { sha256 } from './utils/hash'        // X
  

• any 사용 금지 (web UI 제외). unknown 또는 명시적 타입 사용
• 공개 API에는 JSDoc 작성

Naming

대상	규칙	예시
파일	kebab-case	document-store.ts
클래스	PascalCase	DocumentStore
함수/변수	camelCase	getDocumentBySourcePath
상수	UPPER_SNAKE_CASE	MAX_ALERTS
DB 컬럼	snake_case	workspace_id
환경변수	UPPER_SNAKE_CASE	OPENDOCUMENTS_DATA_DIR
CLI 명령어	kebab-case	auth create-key