MatchCut

MatchCut은 GenAI 모델 정합성 검증을 위한 Hybrid Full-Stack 솔루션입니다. Next.js(Client)의 즉각적인 상호작용과 FastAPI(Server)의 처리 능력을 결합하여, On-Device AI(CLIP) 와 Server-Side Processing을 동시에 지원하는 유연한 아키텍처를 구현했습니다.

---

🛠 Features

• Hybrid Architecture: Frontend(Next.js)와 Backend(FastAPI)가 통합된 구조로, 경량 로직은 브라우저에서, 중작업은 파이썬 서버에서 처리
• On-Device AI Verification: transformers.js (CLIP) 모델을 활용한 Client-Side 1차 필터링 (Zero Cost)
• Scalable Backend: Docker로 컨테이너화된 FastAPI 서비스가 심화 분석 및 로그 처리를 담당 (Extensible)
• Automated Curation: Ground Truth와 생성 이미지 간의 유사도를 측정하여 Valid / Noise 데이터를 자동 분류
• Quality Dashboard: 캐릭터별 정합성 유지율(Quality Rate) 및 백엔드 상태(Health) 실시간 모니터링

---

🏗 Architecture

graph TD
    User([Data Manager]) -->|Upload Images| Client[Next.js Client]
    
    subgraph "Frontend Layer (Next.js)"
        Client -->|Load Model| CLIP[🤖 Transformers.js]
        Client -->|Proxy API| Proxy[API Routes]
    end
    
    subgraph "Backend Layer (Python/FastAPI)"
        Proxy -->|HTTP/JSON| Server[⚡ FastAPI Server]
        Server -->|Compute| Analytics[Advanced Logic]
    end
    
    CLIP -->|Feature Extraction| Vector[Image Embeddings]
    Vector --"Pass/Fail"--> Meta[Metadata Tagging]
    
    Meta -->|Persist| DB[(Supabase DB & Storage)]
    Server -.->|Log/Audit| DB

Loading

---

📦 Tech Stack

Category	Technology
Frontend	Next.js, React
Backend	FastAPI, Python
Styling	Tailwind CSS, Shadcn/UI
Infra	Docker
AI / ML	Transformers.js (CLIP Model)
Database	Supabase (Postgres, Storage)

---

🚀 Getting Started

Prerequisites

• Node.js (Latest LTS recommended)
• Python (3.10+ recommended)
• Docker (Optional, for container deployment)
• Supabase Project

Installation

1. Repository Clone

   git clone https://github.com/jeonsavvy/MatchCut.git
   cd MatchCut

2. Backend (Python/FastAPI)

90: cd backend
91: # 가상환경 생성 (권장)
92: python -m venv venv
93: source venv/bin/activate  # Windows: venv\Scripts\activate
94: 
95: # Install Real Dependencies (Pillow, NumPy for Pixel Analysis)
96: pip install -r requirements.txt
97: 
98: # Run Server (Port 8000)
99: python main.py
100: ```

> **Architectural Note: Serverless-First Strategy**
> 본 프로젝트는 **Edge-First (Client-Only) 모드**를 기본으로 하며, 정밀 분석 시에만 리소스를 사용하는 **Scale-to-Zero 패턴**을 지향합니다.
> 
> *   **Production Goal**: Cloud Run/Knative 환경에서 요청 시 자동 기동(Auto-scaling)되는 구조.
> *   **Local Demo**: 로컬 시연 시에는 위 명령어로 서버를 수동 구동하여 **이 'On-Demand 리소스 분리' 구조를 시뮬레이션**합니다.

```bash
cd backend
# 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install Real Dependencies (Pillow, NumPy for Pixel Analysis)
pip install -r requirements.txt

# Run Server (Port 8000)
python main.py

3. Setup Frontend (Terminal 2)

   # Install Node Dependencies
   npm install
   
   # Setup Env
   # (.env.local 파일에 NEXT_PUBLIC_SUPABASE_URL 등 설정 필요)
   
   # Run Next.js Server (Port 3000)
   npm run dev

4. Verification

   • Visit http://localhost:3000
   • Upload images and verifying them via Dashboard.

Docker Build (Optional)

# Build Backend Container
npm run docker:build
# or
docker build -t matchcut-backend ./backend

---

📂 Directory Structure

├── app/                 # Next.js Frontend App
│   ├── ingest/
│   └── verify/
├── backend/             # [New] FastAPI Backend Server
│   ├── main.py
│   └── Dockerfile
├── lib/
│   ├── backend-client.ts # FastAPI Interop Layer
│   └── analyze-client.ts # Transformers.js Layer
├── supabase_setup.sql   # Database Schema
└── README.md