Skip to content

kalee

보드게임 룰북을 통해 룰을 숙지하기에는, 초심 룰 마스터가 아무리 룰북을 자세히 읽더라도, 모호한 부분, 에러 플레이가 나올수밖에 없다.

Code Video Cerebral Valley

Core trick

Chunks uploaded rulebook PDFs into a vector index and requires each answer to carry page and section citations that link to source text.

Tags

productivity

Description

보드게임 룰북을 통해 룰을 숙지하기에는, 초심 룰 마스터가 아무리 룰북을 자세히 읽더라도, 모호한 부분, 에러 플레이가 나올수밖에 없다. 이를 심판해주는 심판관이 있다면 어떨까 하는 생각에 개발하였다. When learning the rules of a board game through the rulebook, even if a beginner rule master reads it very carefully, ambiguous parts and gameplay errors are almost inevitable. I developed this with the idea of having a referee who could judge and resolve those situations.
splkm97/rulebook-arbiter★ 00 forksPythonCreated Feb 28, 2026 · last push Feb 28, 2026

README excerpt

# 룰북 심판관 (Rulebook Arbiter)

보드게임 룰북 PDF를 업로드하면 RAG 기반으로 규칙을 질의응답해주는 웹 앱.

답변에 `[p.3, §게임 준비]` 형태의 인라인 인용이 포함되어, 클릭하면 원문을 바로 확인할 수 있다.

## 주요 기능

- **PDF 업로드** — 드래그앤드롭으로 룰북 업로드, 자동 텍스트 추출 → 청킹 → 임베딩 → 인덱싱
- **RAG Q&A** — 자연어 질문에 대해 룰북 원문 인용이 포함된 답변 생성
- **인용 검증** — 인용 배지 클릭 시 원문 텍스트와 하이라이트 표시
- **3가지 프리셋** — 학습 (초보자 설명) / 셋업 (게임 준비 가이드) / 심판 (분쟁 판정)
- **한국어 · English** — UI 및 AI 답변 양방향 언어 지원

## 기술 스택

| 레이어 | 기술 |
|--------|------|
| Frontend | React 19, TypeScript, Vite, Tailwind CSS 4, Zustand, TanStack Query |
| Backend | FastAPI, Python 3.12+, ChromaDB, Google Gemini API |
| Infra | Docker Compose |

## 시작하기

### 사전 요구사항

- [Google Gemini API 키](https://aistudio.google.com/apikey)
- Docker + Docker Compose (Docker 실행) 또는 Python 3.12+ / Node.js 20+ (로컬 실행)

### Docker (권장)

```bash
cp .env.example .env
# .env 파일에서 RULEBOOK_GEMINI_API_KEY 설정

docker compose up
```

- Frontend: http://localhost:5173
- Backend: http://localhost:8000
- API 문서: http://localhost:8000/docs

### 로컬 실행

**Backend:**

```bash
cd backend
cp ../.env.example ../.env        # API 키 설정
uv sync
uv run uvicorn app.main:app --reload
```

**Frontend:**

```bash
cd frontend
npm install
npm run dev
```

Vite 개발 서버가 `/api` 요청을 `localhost:8000`으로 프록시한다.

## 테스트

```bash
# Backend 단위 테스트
cd backend && uv run pytest

# Frontend E2E 테스트 (Playwright)
cd frontend && npx playwright install  # 최초 1회
npm run test:e2e
```

## 환경 변수

| 변수 | 기본값 | 설명 |
|------|--------|------|
| `RULEBOOK_GEMINI_API_KEY` | — | Google Gem

Team