# OOTD POC Server - 전체 구조 개요 및 분석 가이드

## 프로젝트가 하는 일

OOTD(Outfit Of The Day) POC Server는 **스마트 옷장 관리 시스템**의 백엔드입니다.

핵심 기능:
1. **얼굴 인식 (FaceID)**: 사진에서 얼굴을 감지하고, 등록된 사용자와 매칭
2. **의류 분석 (Garment Analysis)**: 사진 속 의류를 LLM(Gemini/GPT)으로 분석하여 카테고리, 색상, 스타일 등 태그 추출
3. **고스트 마네킹**: 사진에서 사람을 제거하고 옷만 추출한 이미지 생성
4. **옷장 관리 (Wardrobe)**: 분석된 의류를 사용자별로 저장하고, 필터/페이지네이션으로 조회. 사용자 간 의류 재할당 지원
5. **VTON (가상 피팅)**: 인물 사진 + 옷장의 고스트 의류들을 멀티-이미지 LLM으로 합성하여 결과 이미지 생성

## 기술 스택

| 구분 | 기술 |
|------|------|
| 언어 | Python 3.10 |
| 웹 프레임워크 | FastAPI (비동기) |
| ORM | SQLAlchemy 2.0 (async, Mapped 스타일) |
| DB | PostgreSQL 14 + pgvector (벡터 유사도 검색) |
| 마이그레이션 | Alembic |
| 얼굴 인식 | insightface (buffalo_l 모델, 512차원 임베딩) |
| LLM (의류 분석) | Gemini 2.5 Flash 또는 GPT-5.4 (환경변수로 전환) |
| LLM (고스트 마네킹) | Gemini 2.0 Flash 또는 GPT-5.4 (Responses API image_generation) |
| 이미지 처리 | Pillow, OpenCV |
| 테스트 | pytest (async) + VS Code REST Client (.http 파일) |

## 디렉토리 구조

```
ootd-poc-server/
├── app/                          # FastAPI 애플리케이션
│   ├── main.py                   # 진입점 (FastAPI 앱 생성, 라우터 등록)
│   ├── config.py                 # 환경 설정 (pydantic-settings)
│   ├── dependencies.py           # 의존성 주입 팩토리 (DB 세션, 서비스 인스턴스)
│   ├── middleware.py             # 에러 핸들링 미들웨어
│   ├── models/                   # SQLAlchemy ORM 모델
│   │   ├── base.py               # 공통 Base, UUID PK, 타임스탬프 mixin
│   │   ├── user.py               # User 모델
│   │   ├── face.py               # FaceEmbedding 모델
│   │   └── garment.py            # Garment 모델
│   ├── schemas/                  # Pydantic 요청/응답 스키마
│   │   ├── common.py             # 페이지네이션, GarmentBrief 등 공통
│   │   ├── face.py               # FaceRegister/Identify 응답
│   │   └── garment.py            # GarmentAnalyze, Ghost, List, PATCH 응답
│   ├── routers/                  # API 엔드포인트 (얇은 레이어)
│   │   ├── health.py             # GET /api/v1/health
│   │   ├── user.py               # GET/POST/DELETE /api/v1/users
│   │   ├── face.py               # POST /api/v1/faces/register, identify, DELETE
│   │   ├── garment.py            # POST /api/v1/garments/analyze, {id}/ghost, GET list, PATCH, DELETE
│   │   ├── vton.py               # POST /api/v1/vton/generate (가상 피팅)
│   │   └── admin.py              # DELETE /api/v1/admin/reset, POST cleanup
│   ├── services/                 # 비즈니스 로직 레이어
│   │   ├── face_service.py       # 얼굴 등록/식별 + pgvector 검색
│   │   ├── garment_service.py    # 의류 분석 파이프라인
│   │   ├── vton_service.py       # VTON (인물 + 고스트 의류 합성)
│   │   ├── wardrobe_service.py   # 옷장 조회/필터링
│   │   └── llm/                  # LLM 프로바이더 추상화
│   │       ├── base.py           # 추상 인터페이스 (BaseLLMProvider)
│   │       ├── prompts.py        # 프롬프트 템플릿
│   │       ├── gemini.py         # Gemini API 구현
│   │       └── openai.py         # OpenAI API 구현
│   └── utils/                    # 유틸리티
│       ├── face_analyzer.py      # insightface 래퍼
│       └── image.py              # 이미지 저장/리사이즈/삭제
├── storage/                      # 이미지 파일 저장소
│   ├── faces/                    # 얼굴 이미지 (사용자별 폴더)
│   ├── originals/                # 원본 업로드 이미지
│   ├── ghost_mannequin/          # 고스트 마네킹 결과 이미지
│   └── vton/                     # VTON 합성 결과 이미지 (사용자별 폴더)
├── alembic/                      # DB 마이그레이션
│   ├── env.py                    # 마이그레이션 설정 (async)
│   └── versions/                 # 마이그레이션 파일들
├── frontend/                     # 프론트엔드 (vanilla HTML/CSS/JS 데모 앱, / 에서 서빙)
├── tests/                        # 테스트
│   ├── conftest.py               # 공유 픽스처 (Mock LLM, Mock Face, 테스트 DB)
│   ├── test_health.py            # 헬스체크 테스트
│   ├── test_face.py              # 얼굴 API 테스트
│   ├── test_garment.py           # 의류 분석 API 테스트
│   ├── test_wardrobe.py          # 옷장 API 테스트
│   ├── fixtures/                 # 테스트용 이미지 파일
│   └── http/                     # VS Code REST Client 파일
├── .env                          # 환경 변수 (API 키, DB URL 등)
├── requirements.txt              # Python 의존성
├── alembic.ini                   # Alembic 설정
└── CLAUDE.md                     # 프로젝트 참조 문서
```

## 코드 분석 순서 (추천)

아래 순서대로 읽으면 의존성 흐름을 따라 자연스럽게 이해할 수 있습니다:

### Phase 1: 설정 및 인프라 (기반 이해)
1. **`app/config.py`** - 환경 변수 설정. 어떤 설정값이 있는지 파악
2. **`app/models/base.py`** - ORM 기본 클래스. UUID PK, 타임스탬프 패턴 이해
3. **`app/models/user.py`** → `face.py` → `garment.py` - DB 스키마. 테이블 간 관계 파악
4. **`app/dependencies.py`** - 의존성 주입. 서비스/DB 세션이 어떻게 생성되는지 이해

### Phase 2: 핵심 비즈니스 로직 (서비스 레이어)
5. **`app/utils/face_analyzer.py`** - insightface 래퍼. 얼굴 임베딩 추출 과정
6. **`app/services/face_service.py`** - 얼굴 등록/식별 전체 플로우 + pgvector 검색
7. **`app/services/llm/base.py`** → `prompts.py` - LLM 인터페이스와 프롬프트
8. **`app/services/llm/gemini.py`** 또는 `openai.py` - 실제 LLM API 호출 구현
9. **`app/services/garment_service.py`** - 의류 분석 파이프라인 전체 플로우
10. **`app/services/wardrobe_service.py`** - 옷장 조회/필터링 로직

### Phase 3: API 레이어 (라우터)
11. **`app/routers/health.py`** - 가장 단순한 엔드포인트
12. **`app/routers/face.py`** - 얼굴 API. 서비스 호출 패턴 이해
13. **`app/routers/garment.py`** - 의류 API. 분석, 고스트, 목록조회, 재할당
14. **`app/routers/user.py`** - 사용자 목록 API

### Phase 4: 앱 구성 및 미들웨어
15. **`app/middleware.py`** - 에러 핸들링, 요청 로깅
16. **`app/main.py`** - 앱 조립. lifespan, 라우터 등록, 정적 파일 마운트

### Phase 5: 테스트 구조
17. **`tests/conftest.py`** - Mock 전략. 어떻게 LLM/Face 모델 없이 테스트하는지
18. **`tests/test_*.py`** - 각 엔드포인트 테스트 케이스

## 핵심 데이터 흐름

```
[사용자 사진 업로드]
       │
       ▼
  ┌─────────────────────────────────────┐
  │  Router (garment.py)                │
  │  - 이미지 수신                       │
  │  - (옵션) Face 식별 → user_id 결정   │
  └───────────┬─────────────────────────┘
              │
              ▼
  ┌─────────────────────────────────────┐
  │  GarmentService.analyze_and_save()  │
  │  1. 이미지 리사이즈                   │
  │  2. 원본 이미지 저장                  │
  │  3. LLM으로 의류 분석                 │
  │  4. DB에 Garment 레코드 저장          │
  └───────────┬─────────────────────────┘
              │
              ▼
  ┌─────────────────────────────────────┐
  │  DB: garments 테이블                 │
  │  - category_main, category_sub      │
  │  - description (한국어)              │
  │  - tags (JSONB, 영어 값)            │
  │  - source_image_path                │
  │  - ghost_image_path                 │
  └─────────────────────────────────────┘
              │
              ▼
  ┌─────────────────────────────────────┐
  │  Ghost Mannequin (별도 요청)         │
  │  POST /garments/{id}/ghost          │
  │  - 개별 의류에 대해 고스트 마네킹 생성 │
  └─────────────────────────────────────┘
              │
              ▼
  ┌─────────────────────────────────────┐
  │  Garment API                        │
  │  GET /api/v1/garments               │
  │  - user_id 선택 (전체/사용자별 조회)  │
  │  - 카테고리/태그 필터                 │
  │  - 페이지네이션                      │
  └─────────────────────────────────────┘
```

## 주요 설계 결정

| 결정 | 이유 |
|------|------|
| Global User (UUID 00000000...) | 얼굴 인식 실패/비활성화 시 fallback. 모든 의류가 누군가에게 속하도록 보장 |
| LLM Provider 패턴 | 환경변수 하나로 Gemini ↔ OpenAI 전환. 추상 인터페이스 + 구현체 패턴 |
| JSONB 태그 | 유연한 스키마. GIN 인덱스로 필터링 성능 확보 |
| pgvector 코사인 거리 | 얼굴 임베딩 유사도 검색에 최적. `<=>` 연산자 사용 |
| 비동기 전체 | FastAPI + asyncpg + async SQLAlchemy. I/O 바운드 작업(LLM API, DB) 효율화 |

## 관련 문서

| 문서 | 내용 |
|------|------|
| [01-infrastructure.md](01-infrastructure.md) | 설정, DB, 마이그레이션, 의존성 주입 |
| [02-models-schemas.md](02-models-schemas.md) | ORM 모델, Pydantic 스키마 |
| [03-face-recognition.md](03-face-recognition.md) | 얼굴 인식 시스템 (insightface + pgvector) |
| [04-llm-analysis.md](04-llm-analysis.md) | LLM 의류 분석 + 고스트 마네킹 |
| [05-garment-pipeline.md](05-garment-pipeline.md) | 의류 분석 파이프라인 전체 흐름 |
| [06-wardrobe-api.md](06-wardrobe-api.md) | 옷장 조회/필터링 |
| [07-api-reference.md](07-api-reference.md) | 전체 API 명세 + curl 예제 |
| [08-testing-guide.md](08-testing-guide.md) | 테스트 실행 방법 + HTTP 테스트 사용법 |
| [09-vton-api.md](09-vton-api.md) | VTON (가상 피팅) API — 인물 + 옷장 합성 |