tandpfun/wardrobe 딥다이브
— 옷 사진 한 장을 gpt-image로
카탈로그 컷아웃으로 바꾸는 로컬 옷장

1프로젝트 한 줄 요약

wardrobe는 사진 속 옷을 AI로 오려내(extract) 투명 배경 상품 이미지로 만들고, 그것들을 갤러리처럼 정리해 주는 1인용 로컬 앱이다. 핵심 흐름은 세 문장으로 끝난다. 사진을 끌어다 놓는다 → 사진 속 각 옷이 깔끔한 카탈로그 컷아웃으로 바뀐다 → 원하면 "내가 그 옷을 입은" 사진까지 만들어 준다. 이 모든 결과물(원본·작업파일·완성 PNG·JSON DB)은 클라우드로 나가지 않고 data/ 폴더 안에만 쌓인다. 제작자는 tandpfun(Discord 봇 생태계로 유명한 개발자)이고, 원 게시물은 X(@cdngdev)에 올라온 데모다.

2왜 지금 주목받는가

wardrobe가 TrendShift Daily 상위에 오른 이유는 셋으로 요약된다. 첫째, 결과물이 눈에 확 들어온다 — "내 옷 사진 → 쇼핑몰 상품컷 + 내가 입은 화보"라는 변환은 데모 영상 한 편으로 설득이 끝난다. 둘째, 로컬 퍼스트라는 안심 포인트 — 개인 사진을 다루는 앱인데 클라우드로 안 나간다. 셋째, 코드를 열어 보면 "AI에 의존하지 않고 직접 푼" 영리한 트릭들이 촘촘하다. 특히 "투명 배경을 모델에 맡기지 않고 내가 크로마키로 파낸다"는 결정이 백미다.

3기술 스택 전체 지도

wardrobe의 의존성 목록은 "AI 이미지 앱치고 이렇게 얇다고?" 싶을 만큼 단출하다. 런타임 의존성이 9개뿐이고 devDependencies는 아예 없다. TypeScript도, Tailwind도, ORM도, 상태관리 라이브러리도 없다. 무거운 일(이미지 픽셀 연산)은 sharp 하나가 다 하고, 지능(옷 인식·생성)은 OpenAI API가 다 한다. 나머지는 순수 React + 손으로 쓴 CSS다.

프론트엔드 (src/ — React SPA)

백엔드 (scripts/ — Vite 미들웨어)

AI · 인프라

4아키텍처 심화 분석

4-1. 전체 그림 — 브라우저 ↔ Vite 미들웨어 ↔ OpenAI

클라이언트(React SPA)와 "서버"(Vite 미들웨어)는 같은 프로세스 안에 있다. 브라우저는 /api/import/*로 요청하고, Vite 서버에 얹힌 wardrobeImportApi 핸들러가 받아 sharp로 이미지를 주무르고 OpenAI를 호출한 뒤 파일로 저장한다. 별도 백엔드 서버는 존재하지 않는다.

4-2. 심장부 — 옷 한 벌이 컷아웃이 되는 3단계

모든 옷은 crop → garment → modeled라는 3단계 상태 기계를 거친다. 각 단계는 "생성 → 리뷰(사용자 승인/거절/재생성)"를 반복한다. 순서대로 뜯어보자.

① 인식 — Responses API로 "옷 목록 + 위치" 뽑기

업로드된 사진을 sharp로 정규화한 뒤, OpenAI /responses에 엄격한 json_schema(이름 wardrobe_items, 최대 8개)로 질의한다. 모델은 옷마다 이름·카테고리·주색(hex)·부색·태그와 함께 1000×1000으로 정규화한 정수 바운딩박스를 돌려준다. 카테고리는 딱 5종으로 제한: upperbody(상의) · wholebody_up(원피스류) · lowerbody(하의) · accessories_up(액세서리) · shoes(신발). 앱은 이 박스를 픽셀로 환산하고 max(12px, 8%) 여백을 더해 crop을 떠낸다.

② 컷아웃 — "크로마 배경에 그려라" + 앱이 파낸다

여기가 핵심 트릭이다. 앱은 먼저 옷의 주색과 가장 먼 크로마색을 고른다(chooseChromaKey: 초록 #00ff00·마젠타 #ff00ff·시안 #00ffff 중 RGB 거리 최대). 그 색을 프롬프트에 넣어 gpt-image에 "그 단색 배경 위에 옷만" 그리게 한다. 실제 프롬프트(buildGarmentPrompt)의 배경·금지 조항이 특히 촘촘하다:

# buildGarmentPrompt — 핵심 조항 (요약 발췌)
Primary request: Reconstruct ONLY the complete empty ${name} (${category})
  as a clean, front-facing ecommerce catalog product photograph.
  If a wearer is present, remove them. ...no person, body, mannequin, or hanger.
Background: Perfectly flat, absolutely uniform solid ${chromaKey} chroma-key
  color, edge-to-edge. No shadows, gradient, texture, vignette, reflection...
Critical: Use no ${chromaKey} anywhere in the garment.
  Produce exactly one complete garment with a crisp, separable outer silhouette.

실제 API 호출은 /images/edits에 멀티파트 폼으로 나간다. OpenAI SDK 없이 순수 fetch+FormData다:

// openAIEdit — /images/edits 멀티파트 호출
const form = new FormData();
form.set("model", model);        // gpt-image-2 (또는 OPENAI_GARMENT_MODEL)
form.set("prompt", prompt);
form.set("size", size);          // 옷 컷아웃: "1024x1024"
form.set("quality", quality || "high");
form.set("output_format", "png");
for (const [i, image] of images.entries()) {
  const normalized = await normalizeImage(image.data);
  form.append("image[]", new Blob([normalized], { type: "image/png" }), ...);
}
const response = await fetch(`${baseUrl}/images/edits`, {
  method: "POST", headers: { Authorization: `Bearer ${key}` }, body: form,
});
// result.data[0].b64_json → Buffer 로 디코드

모델이 준 이미지는 투명이 아니라 크로마색 배경이다. 진짜 투명화는 앱이 sharp로 직접 한다(removeChromaBackground) — 이 과정엔 AI가 전혀 없다:

③ 화보 — "나 + 옷" 두 장으로 입은 모습 합성

옷 컷아웃이 승인되면(선택) /images/edits를 한 번 더 부른다. 이번엔 이미지를 순서대로 두 장 넣는다 — data/model-reference.png(나) 먼저, 옷 PNG 나중, 크기 1536x1024(3:2). 프롬프트는 "Image 1의 사람이 Image 2의 옷을 입은 프로페셔널 에디토리얼 사진을 만들되 얼굴·정체성·나이·비율을 보존하고 옷의 색·소재·핏·로고를 그대로 유지"하라고 지시한다. 재생성 시엔 사용자의 지시문(User regeneration direction: ...)이 뒤에 덧붙는다.

4-3. 저장 — DB가 없다, JSON 파일이 곧 DB

ORM도 SQL도 없다. 두 개의 JSON "테이블"과 작업별 상태 파일이 전부다. 완성된 옷은 data/library.json(평면 배열)에, 진행 중 작업은 data/jobs/<uuid>/job.json에 담긴다. 기록은 항상 원자적 쓰기(임시 파일 → rename, 실패 시 복사 폴백)로 안전하게 이뤄지고, 서버 재시작 시 중단된 작업을 스스로 정리·재개한다.

// data/library.json — 옷 한 벌의 레코드 모양
{
  "id": "import-<uuid>",              // Codex 경로에선 바이트 해시로 안정 UUID
  "name": "Navy Fair Isle Cardigan",
  "part": "wholebody_up",           // 5종 카테고리 enum
  "color": "#172033",
  "secondaryColor": "#f2efe6",       // hex 또는 null
  "palette": ["#172033", "#f2efe6"],
  "tags": ["knit", "fair isle", "zip"],
  "image": "/api/import/library/import-<uuid>-garment.png",
  "modeledImage": "/api/import/library/import-<uuid>-modeled.png", // 또는 null
  "importJobId": "<uuid>"
}

사용자의 이름 변경·색 조정·삭제 같은 편집은 서버 레코드 위에 브라우저 localStorage(open-wardrobe-edits-v1·open-wardrobe-deleted-v1)로 얹힌다. 덕분에 모든 필드마다 쓰기 API를 만들지 않고도 UI가 즉각 반응하고 편집이 유지된다("낙관적 UI + 로컬 오버레이" 패턴).

5디렉토리 구조 해부

구조를 읽는 열쇠는 "폴더 이름이 곧 역할"이다. src/는 브라우저에서 도는 클라이언트, scripts/는 Vite 서버 안에 사는 서버 로직, .agents/skills/는 앱 대신 에이전트가 같은 파이프라인을 돌리게 하는 Codex 스킬, public/은 PWA 자산이다. 그리고 실제 데이터가 쌓이는 data/는 런타임에 생성되고 저장소엔 없다(gitignore).

6학습 포인트

기술별로 배울 것

7시스템 · 실행 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식
· GitHub 저장소: github.com/tandpfun/wardrobe (MIT · v1.0.0)
· 원 게시물(데모): x.com/cdngdev/status/2076812846793650485
· TrendShift 카드: trendshift.io/repositories/84145 (Daily #7)

저장소 안에서 먼저 열 곳
· scripts/import-job-api.mjs — 인식·컷아웃·화보·저장의 심장부(§4)
· src/import-flow.jsx — 3단계 리뷰 상태기계 + 폴링/낙관적 UI
· src/App.jsx — 갤러리·팔레트 추출·스포이드·localStorage 오버레이
· vite.config.mjs — "서버 없는 서버"가 배선되는 곳
· .agents/skills/import-clothes/SKILL.md — 같은 파이프라인의 에이전트 버전
· .env.example + README.md — 설정과 요구사항(숨은 변수는 소스로 보완)

곁들여 학습(표준·이웃)
· Vite 플러그인 API · sharp 문서 — 미들웨어·이미지 연산의 표준
· OpenAI Images 가이드 · Responses API — 인식·생성 호출의 원전
· §인덱스의 다른 cat-media(이미지·얼굴) · cat-claude-skills 딥다이브와 비교