# 01. 레포 전체 지도

> 원본 코드/프롬프트/기존 문서를 수정하지 않고 생성한 read-only 감사 문서입니다.

## 최상위 디렉터리 분류

현재 루트의 최상위 디렉터리는 다음처럼 분류된다.

| 경로 | 분류 | 판단 |
|---|---|---|
| `backend/` | 활성 backend | FastAPI app, services, core pipeline, DB, tests, scripts |
| `frontend/` | 활성 frontend | Vite/React UI |
| `prompts/` | 활성 prompt store | backend prompt loader의 기본 root는 `prompts/_base` |
| `docs/` | 문서 | 현재 감사 문서도 여기에 추가 |
| `projects/` | 런타임 데이터 | 업로드 PDF, checkpoint, generated assets, export 등 |
| `data/` | legacy/runtime 데이터 | `service_legacy.sqlite` 등 historical data 존재 |
| `backend/scripts/` | 실험/운영 스크립트 혼재 | 실험 코드, migration helper, generated output 섞임 |
| `scripts/` | 루트 helper script | phase compare, regen 계열 포함 |
| `tests/` | 별도 실험/비교 테스트 | backend pytest와 분리된 model comparison 등 |
| `Old/` | legacy/backup | active app에서 직접 import되는 핵심 경로 아님 |
| `_backup_20260321_0825/` | backup | active code와 구분 필요 |
| `prototype/` | prototype | active FastAPI app과 분리 |
| `prototype_ui/` | 별도 prototype app | tracked FastAPI/SQLite prototype, active app에 mount 안 됨 |
| `screenplay/` | standalone scripts | 별도 prompt system 사용 |
| `pdfs/`, `org/`, `backups/`, `scripts_output/` | runtime/output/archive | active source와 구분 필요 |

## 활성 코드와 런타임 데이터 경계

```mermaid
flowchart LR
    Source[active source] --> Backend[backend/app]
    Source --> Frontend[frontend/src]
    Source --> Prompts[prompts/_base]
    Backend --> Runtime[projects/*]
    Backend --> DB[(PostgreSQL)]
    Scripts[backend/scripts and scripts] --> Runtime
    Scripts --> DB
    Legacy[Old / prototype / screenplay / backups] -. confusion risk .-> Search[code search results]
```

활성 앱 경로와 runtime/output 경로가 같은 레포 안에 같이 있다. 이 구조는 빠른 개발에는 편하지만, 원인 분석 시 다음 문제가 생긴다.

| 문제 | 설명 |
|---|---|
| code search 오염 | 실험/legacy 코드가 active 코드처럼 검색됨 |
| prompt 혼동 | backend prompt와 screenplay prompt가 별도 체계인데 같은 레포에 공존 |
| DB/asset 혼동 | `projects/`, `data/`, `backups/`가 현재 상태와 과거 상태를 동시에 포함 |
| 스크립트 위험 | 일부 script는 dry-run 없이 DB/file mutation 가능 |
| 재현성 저하 | generated PNG/manifest/result가 source와 섞여 commit/worktree 상태 판단을 어렵게 함 |

## 실제 파일 수와 주요 표면

| 항목 | 값 |
|---|---:|
| 전체 파일 수 by `rg --files` | 1500 |
| backend test files | 129 |
| frontend test files | 5 |
| backend top-level scripts | 58 |
| `prompts/_base` modules | 57 |
| prompt/schema/user files under `_base` | 236 |

## backend 활성 구조

| 경로 | 책임 |
|---|---|
| `backend/app/main.py` | FastAPI app 생성, startup, router mount, health |
| `backend/app/api/v1/` | REST API routers |
| `backend/app/api/deps.py` | DB session, auth, project authorization, endpoint wrapper |
| `backend/app/core/` | config, DB, StepRunner, manifest/catalog, job/task registry, path helper |
| `backend/app/core/steps/` | step runner class implementations and registry |
| `backend/app/services/` | project/episode/auth/dispatch/image/checkpoint sync services |
| `backend/app/modules/` | LLM clients, prompt loader, pipeline modules, image modules |
| `backend/app/models/` | SQLAlchemy ORM models |
| `backend/app/schemas/` | Pydantic schemas |
| `backend/alembic/` | Alembic migrations, incomplete baseline |
| `backend/migrations/` | standalone raw SQL migrations |
| `backend/tests/` | backend pytest suite |
| `backend/scripts/` | operational and experimental scripts |

## frontend 활성 구조

| 경로 | 책임 |
|---|---|
| `frontend/src/App.tsx` | route registration and auth wrappers |
| `frontend/src/api/client.ts` | API helper with cookie credentials and timeout |
| `frontend/src/pages/` | dashboard/project/episode/entities/images/prompts/export/admin pages |
| `frontend/src/components/` | shared layout, episode controls, pipeline panel, image review UI |
| `frontend/src/hooks/api/` | React Query hooks and mutations |
| `frontend/src/types/` | shared frontend types |
| `frontend/vite.config.ts` | dev server/proxy |
| `frontend/vitest.config.ts` | test lane config |

## prompt store 구조

`prompts/_base/<module>/<version>/...` 형태가 주 구조다.

예시는 다음과 같다.

| module | 용도 |
|---|---|
| `scene_detail` | scene/shot 상세 prompt |
| `shot_extract` | beat -> shot 추출 |
| `shot_validator` | shot validation |
| `entity_extract_v4` | entity extraction split |
| `background_classify` | Phase 7 배경 그룹 분류 |
| `background_master_plan` | 배경 master plan |
| `floor_plan_prompt` | 도면 prompt 생성 |
| `background_prompt` | 배경 prompt 생성 |
| `ref_image_prompts` | reference image prompt |
| `lvm_prompts` | image validation / LVM |
| `scene_image` | scene image translation prompt |

주의할 점은 prompt loader의 root는 `prompts/_base`이고, `screenplay/prompts`는 별도 standalone script용이다.

## legacy/orphan 후보

아래는 삭제 대상이라는 뜻이 아니라, active runtime과 분리해서 다뤄야 하는 후보군이다.

| 후보 | 근거 |
|---|---|
| `Old/` | 과거 코드/데이터 보관 영역 |
| `_backup_20260321_0825/` | 명시적 백업 |
| `prototype_ui/app.py` | 별도 FastAPI/SQLite prototype, active app에 mount 안 됨 |
| `prototype/` | prototype assets/code |
| `screenplay/` | backend와 다른 prompt/runtime 체계 |
| `tests/model_comparison/` | active manifest와 다른 stale step 이름 포함 |
| `backend/scripts/experiment_*` | 실험 산출물/실험 코드, active API path 아님 |
| `data/service_legacy.sqlite*` | PostgreSQL 이전 legacy DB 흔적 |

## 레포 운영상 권장 경계

| 경계 | 권장 |
|---|---|
| active app | `backend/app`, `frontend/src`, `prompts/_base` 중심으로 정의 |
| runtime data | `projects`, `data`, `pdfs`, `backups`, `scripts_output`를 source와 분리 |
| experiments | `backend/scripts/experiment_*`는 active pipeline과 별도 registry 필요 |
| legacy | `Old`, `_backup_*`, `prototype*`, `screenplay`는 import/search 제외 목록 문서화 필요 |
| scripts | mutation script는 dry-run default, explicit `--apply` 원칙 필요 |