understanding-project

name	understanding-project
description	프로젝트 구조, 아키텍처, 기술 스택, 패키지 역할 등 전반적인 이해가 필요할 때 사용. 코드가 어디에 있는지, 패키지 간 의존성이 어떤지, 왜 이 구조인지 궁금하면 이 스킬. Triggers: "모노레포 구조가 어떻게 돼", "기술 스택", "export 충돌", "패키지 간 의존성", "프로젝트 구조", "어떤 패키지에 있어", "파일 어디에 있어", "아키텍처", "디렉터리 구조", "코드 위치", "모듈 역할", "어떤 기술 쓰고 있어", "스택", "의존성". Covers the monorepo architecture, package roles, tech stack, and coding conventions.

프로젝트 이해

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

실행 방법

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