프로젝트 이해

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 → listPromptVersions
getVersion → getPromptVersion

실행 방법

bash

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 — 구조/실행 관련 자주 발생하는 문제 해결

Search AI Tools

understanding-project

Install this agent skill to your Project

SKILL.md