# Understanding Project

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

- Skill: `shren207/understanding-project` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add shren207/understanding-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shren207/understanding-project/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shren207 (https://skillmd.com/u/shren207)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/shren207/understanding-project

---


# 프로젝트 이해

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