# TheRoad-I1 전체 레포 감사 보고서

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

작성일: 2026-05-02  
작성 방식: 원본 코드/프롬프트/기존 문서 수정 없이 read-only 조사 후 새 문서만 작성  
대상 루트: `/Users/manta/Documents/Projects/TheRoad-I1`

## 목적

이번 문서는 특정 이미지 생성 결함만 보지 않고, 전체 레포의 활성 구조와 문제점을 한 번에 파악하기 위한 감사 기록이다.

검토 범위는 다음을 포함한다.

| 영역 | 포함 내용 |
|---|---|
| 레포 구조 | 활성 코드, 런타임 데이터, 백업, 실험, legacy/orphan 후보 |
| backend | FastAPI, 서비스 계층, StepRunner, checkpoint, image pipeline, auth, config |
| DB | PostgreSQL 실제 테이블, SQLAlchemy 모델, Alembic, startup raw migration, 파일 경로 invariant |
| pipeline | `STEP_MANIFEST`, `STEP_CATALOG`, runner binding, 실행/재개/동기화 경로 |
| prompts/LLM | 파일 프롬프트, DB `prompt_template`, prompt loader, model routing, image provider |
| frontend | Vite/React 라우트, API client, 이미지/step 실행 진입점, 테스트 범위 |
| tests/devops | pytest/vitest, Docker Compose, requirements, script/orphan risk |
| 문제 목록 | 별도 `problems.md`에 severity별 정리 |

## 문서 목록

| 문서 | 내용 |
|---|---|
| `01_repository_map.md` | 레포 전체 지도, 활성/legacy/orphan 분류, 주요 디렉터리 책임 |
| `02_backend_architecture.md` | FastAPI, 서비스, StepRunner, background job, image 실행 경로 |
| `03_database_persistence.md` | PostgreSQL/ORM/마이그레이션/체크포인트/파일 경로 저장 구조 |
| `04_pipeline_steps.md` | 59개 step 구조, active/deprecated/removed, 조건부 배경 생성 흐름 |
| `05_prompts_llm.md` | 프롬프트 로딩, DB prompt, LLM model routing, image provider, stale prompt |
| `06_frontend_api.md` | 프론트 라우트, API 호출 경로, 이미지/step UI 진입점, 테스트 공백 |
| `07_tests_devops_legacy.md` | 테스트/운영/스크립트/레거시 코드와 안전장치 |
| `problems.md` | 전체 문제점 별도 목록, 우선순위와 개선 방향 |

## 전체 구조 요약

```mermaid
flowchart TB
    User[User / Browser] --> FE[frontend: Vite React]
    FE --> API[backend FastAPI routers]
    API --> Services[services]
    Services --> Runner[StepRunner]
    Runner --> CP[filesystem checkpoints]
    Runner --> StepRun[(PostgreSQL step_run)]
    Runner --> LLM[LLM clients]
    Runner --> Img[image providers]
    CP --> Sync[checkpoint_sync orchestrator]
    Sync --> DB[(PostgreSQL projection tables)]
    API --> LegacyImage[legacy/direct image endpoints]
    LegacyImage --> DB
    LegacyImage --> Assets[projects/* assets]
    Img --> Assets
    Assets --> API
    API --> FE
```

핵심 아키텍처는 다음과 같다.

| 축 | 현재 의도 | 실제 확인 |
|---|---|---|
| 실행 | `/steps` API + `StepRunner` 중심 | 일부 이미지 API가 legacy/direct service와 raw thread를 병행 |
| 상태 | checkpoint + `step_run` + DB projection | `Episode.status`, `PipelineProgress`, legacy image status가 함께 존재 |
| DB 스키마 | PostgreSQL + Alembic | `create_all()` + startup raw SQL + Alembic + raw SQL 파일이 혼재 |
| 프롬프트 | `prompts/_base` + DB override | stem별 fallback, DB lexical version, 일부 direct file read가 혼재 |
| 모델 설정 | step manifest 기반 single source | `STEP_MANIFEST`, `llm_client.PIPELINE_STEPS`, README, image hard-code가 중복 |
| 파일 경로 | `ImageAsset.file_path` 상대 경로 invariant | checkpoint JSON, source_path, manifest path는 별도 규칙 없음 |

## 최상위 결론

1. 레포의 중심 구조는 존재한다. FastAPI router -> service -> StepRunner -> checkpoint -> DB sync의 방향은 명확하다.
2. 그러나 실제 운영 경로는 하나가 아니다. 특히 이미지 생성은 StepRunner 경로와 legacy/direct endpoint 경로가 동시에 살아 있다.
3. DB 스키마 관리가 가장 위험하다. PostgreSQL 자체는 사용 중이지만 Alembic이 전체 schema source of truth가 아니고, startup migration이 실패를 삼킨다.
4. 프롬프트와 모델 설정은 source of truth가 분산되어 있다. 파일 prompt, DB prompt, hard-coded prompt, `PIPELINE_STEPS`, manifest가 서로 다른 답을 낼 수 있다.
5. 테스트는 안전장치가 강화되어 있지만, 프론트/운영/실제 Postgres/파일경로 결함을 충분히 막지 못한다.
6. `Old/`, `_backup_*`, `prototype*`, `screenplay`, `backend/scripts`, `tests/model_comparison` 등 orphan/legacy 후보가 많아 코드 검색과 실험 재현을 방해한다.

## 조사 방식

사용한 조사 방식은 다음과 같다.

| 방식 | 내용 |
|---|---|
| 파일 전수 스캔 | `rg --files`, `find`, 주요 코드 `nl -ba`, `rg` 검색 |
| DB read-only 조회 | 현재 PostgreSQL 테이블 목록, row count, prompt module count 확인 |
| manifest 계수 | `STEP_CATALOG` 로딩 후 lifecycle/category/applicability/step_type 집계 |
| 하위 병렬 분석 | backend architecture, DB persistence, prompts/LLM, frontend/devops 영역 분리 검토 |
| 생성물 제한 | 새 `docs/full_repo_audit_20260502/` 문서만 추가 |

## 확인된 수치

| 항목 | 값 |
|---|---:|
| repo tracked/visible files by `rg --files` | 1500 |
| `STEP_CATALOG` entries | 59 |
| active steps | 48 |
| deprecated steps | 10 |
| removed steps | 1 |
| PostgreSQL public tables | 26 |
| current `image_asset` rows | 851 |
| current `step_run` rows | 3655 |
| current DB `prompt_template` rows | 114 |
| `prompts/_base` modules | 57 |
| versioned prompt/schema/user files under `_base` | 236 |
| backend test files | 129 |
| frontend test files | 5 |
| backend top-level scripts | 58 |

## 우선 읽을 순서

문제를 빨리 파악하려면 다음 순서가 낫다.

1. `problems.md`
2. `02_backend_architecture.md`
3. `03_database_persistence.md`
4. `05_prompts_llm.md`
5. `04_pipeline_steps.md`
6. `06_frontend_api.md`
7. `07_tests_devops_legacy.md`
8. `01_repository_map.md`

## 제한 사항

이 문서는 read-only 감사다.

테스트 실행, DB write, migration 실행, 코드 수정, 프롬프트 수정, 기존 문서 수정은 하지 않았다. 실제 DB 조회는 read-only SELECT 수준으로만 수행했다.