shren207 프로젝트 이해
Anki 카드를 원자적 단위로 분할하는 웹 앱. 정보 밀도 높은 카드를 AI(Gemini/OpenAI)로 학습 효율 좋은 작은 카드로 분리.
모노레포 구조
awesome-anki/
├── packages/
│ ├── core/ # 핵심 로직 — 파서, 분할, 검증, 임베딩, 프롬프트
│ ├── server/ # Hono REST API (localhost:3000)
│ └── web/ # React 19 + Vite 프론트엔드 (localhost:5173)
├── data/ # split-history.db (SQLite, SoT는 MiniPC)
└── output/ # backups/, embeddings/, prompts/
기술 스택
| 영역 | 기술 |
|---|---|
| 런타임 | Bun (npm 아님) |
| 언어 | TypeScript |
| LLM | 멀티 프로바이더 (Gemini + OpenAI), factory 패턴 |
| 백엔드 | Hono (REST API) |
| 프론트엔드 | React 19 + Vite |
| 스타일링 | Tailwind CSS v4 (@tailwindcss/postcss 플러그인) |
| 상태 관리 | TanStack Query |
| 렌더링 | markdown-it + KaTeX + highlight.js |
패키지별 핵심 모듈 (packages/core/src/)
| 모듈 | 역할 |
|---|---|
anki/ |
AnkiConnect API 래퍼 + 학습난이도 탐지(difficulty.ts) — working-with-anki 스킬 참조 |
llm/ |
멀티 LLM 추상화 (factory, adapter, pricing) |
gemini/ |
Gemini 전용 API (분할 프롬프트, cloze-enhancer, zod 응답 검증) |
parser/ |
텍스트 파싱 (container, nid, cloze) — splitting-cards 스킬 참조 |
splitter/ |
Split 로직 — splitting-cards 스킬 참조 |
validator/ |
카드 검증 4종 — validating-cards 스킬 참조 |
embedding/ |
OpenAI 임베딩 (text-embedding-3-large, 3072차원) — managing-embeddings 스킬 참조 |
prompt-version/ |
프롬프트 버전 관리 — managing-prompts 스킬 참조 |
utils/ |
HTML 스타일 보존, diff-viewer, 원자적 파일 쓰기 |
export 규칙
packages/core/src/index.ts에서 명시적 named export 사용. export *는 이름 충돌 발생 (SplitCard, validateStylePreservation 등).
충돌 방지를 위해 prompt-version 함수는 접두사 사용:
listVersions→listPromptVersionsgetVersion→getPromptVersion
실행 방법
bun run dev # 서버 + 클라이언트 동시 실행
bun run dev:server # 서버만 (localhost:3000)
bun run dev:web # 클라이언트만 (localhost:5173)
자주 발생하는 문제
bun install사용:npm install금지- export 충돌: 새 모듈 추가 시
index.ts에서 개별 항목 나열 - Tailwind v4:
tailwindcss init대신@tailwindcss/postcss플러그인 사용 - 포트 충돌:
lsof -ti:3000 | xargs kill -9로 정리 후 재시작
상세 참조
references/architecture.md— 모노레포 상세 구조, 패키지 역할references/tech-stack.md— Bun, Hono, React 19, Tailwind v4 상세references/conventions.md— export 규칙, 실행 방법, 모노레포 설정references/troubleshooting.md— 구조/실행 관련 자주 발생하는 문제 해결