🤝 Vivid-AI 협업 및 온보딩 가이드

Vivid-AI 프로젝트에 합류하신 것을 환영합니다! 🎉 이 문서는 새로운 팀원이 개발 환경을 빠르게 구축하고, 기존 팀원들과 효율적으로 협업하기 위한 필수 가이드라인을 제공합니다.

---

1. 프로젝트 구조 및 개요

vivid-ai는 전체 프로젝트를 아우르는 상위 레포지토리(Parent Repository)이며, 각 서비스는 Git Submodule 형태로 구성되어 있습니다.

모듈명	역할 및 설명	실행 필요
backend-vivid-ai	Nest.js 기반 API 서버. 비즈니스 로직, 인증, DB/Redis 관리를 담당합니다.	✅
frontend-vivid-ai	Next.js 기반 웹 애플리케이션. 사용자 UI/UX를 제공합니다.	✅
post-processing-worker	Python 기반 후처리 워커. S3 raw/ 결과물의 썸네일/preview를 만들고 creations/에 최종 결과 세트를 저장합니다.	✅
ai-server	ComfyUI와 ai-node-agent로 구성된 생성 실행부. local에서는 Docker Compose로 실행하며, API 노드 기반 workflow를 테스트합니다.	✅
docs-vivid-ai	Docusaurus 기반 문서 저장소. 프로젝트의 모든 기술 문서를 관리합니다.	❌

---

2. 필수 준비 사항 (Prerequisites)

작업을 시작하기 전에 다음 도구들을 설치하고 설정해야 합니다.

🛠 설치 도구

1. Node.js: v22.20.0 버전을 권장합니다. (nvm 사용 권장)
2. Docker Desktop: 로컬 데이터베이스(PostgreSQL) 및 각종 컨테이너 실행을 위해 필수입니다.
3. Git: 버전 관리 시스템.
4. PgAdmin4 (선택): 데이터베이스 관리를 위한 GUI 도구.

🔑 보안 및 환경 변수 요청

보안상 Git에 포함되지 않는 민감한 정보들은 기존 팀원(관리자)에게 직접 요청하여 받아야 합니다.

1. .env 파일들:
   • backend-vivid-ai/.env (DB 접속 정보, AWS 키 등)
   • frontend-vivid-ai/.env.local (API URL, 인증/결제 관련 공개 설정 등)
   • ai-server/.env
   • post-processing-worker/.env
2. AWS local 리소스 접근 권한:
   • local 개발도 실제 AWS SQS/S3를 사용합니다.
   • vivid-ai-computation-queue-local, vivid-ai-post-processing-worker-queue-local, local media bucket에 접근 가능한 credential을 요청하세요.
   • local media bucket은 서울 리전(ap-northeast-2)에 생성되어 있으며, raw/, creations/, generation/source/, generation/work-input/, temp/ 등 prefix로 역할을 분리합니다. 세부 기준은 S3 media bucket 설정을 확인하세요.
   • local credential은 prod queue/bucket에 접근하지 못하도록 제한되어야 합니다.

---

3. 개발 환경 설정 및 실행 (Step-by-Step)

Step 1. 저장소 클론 및 서브모듈 초기화

# 1. 메인 저장소 클론 (Organization 주소 확인)
git clone https://github.com/vivid-ai-org/vivid-ai.git

# 2. 프로젝트 폴더 이동
cd vivid-ai

# 3. 서브모듈 초기화 및 업데이트 (필수)
git submodule update --init --recursive

Step 2. Local infrastructure 실행

로컬 개발은 Docker Compose로 Postgres, Redis, ComfyUI, ai-node-agent, post-processing-worker를 실행하고, SQS/S3만 AWS cloud resource를 사용합니다. 전체 기준은 현재 권장 인프라 플랜을 확인합니다.

Step 3. 모듈별 실행

🖥️ Backend (Nest.js)

cd backend-vivid-ai

# 1. 로컬 데이터베이스(PostgreSQL) 실행
docker-compose up -d

# 2. 의존성 설치
npm install

# 3. 서버 실행
npm run start

• 서버 주소: http://localhost:3000
• API 문서: http://localhost:3000/api-docs

🎨 Frontend (Next.js)

cd frontend-vivid-ai

# 1. 의존성 설치
npm install

# 2. 개발 서버 실행
npm run start

• 웹 주소: http://localhost:4000

⚙️ Post-Processing Worker (Python)

cd post-processing-worker

# Docker 컨테이너로 실행
docker-compose up -d

🧠 AI Server (ComfyUI + ai-node-agent)

cd ai-server

# ComfyUI와 ai-node-agent 실행
docker compose up -d --build

---

4. Git 브랜치 전략 및 협업 플로우

안정적인 배포를 위해 엄격한 브랜치 전략을 따릅니다.

🌳 브랜치 종류

• prod: 운영(Production) 배포용 브랜치. 가장 안정적인 상태입니다.
• dev: 개발(Development) 통합 및 테스트용 브랜치.
• feature/*: 새로운 기능 개발용 (예: feature/login-ui).
• fix/*: 버그 수정용.

🔄 작업 순서 (Workflow) 상세

1. 브랜치 생성 (Start) 새로운 기능(Feature)이나 버그 수정(Fix)을 시작할 때는 무조건 최신 prod에서 브랜치를 생성합니다.

# 1. prod 브랜치로 이동 및 최신화
git checkout prod
git pull origin prod

# 2. 작업 브랜치 생성 (명명규칙: feature/기능명, fix/버그명)
git checkout -b feature/new-dashboard-ui

2. 작업 및 커밋 (Work) 로컬에서 작업을 진행합니다. 커밋 메시지는 Conventional Commits 규칙을 권장합니다.

• 예: feat: 새로운 대시보드 레이아웃 적용, fix: 로그인 버튼 클릭 불가 문제 수정

3. 개발 서버 배포 및 테스트 (Test on Dev) 작업한 내용을 개발 서버(Dev)에 반영하여 테스트합니다.

# 1. dev 브랜치로 이동 및 최신화
git checkout dev
git pull origin dev

# 2. 작업 브랜치를 dev에 병합 (반드시 --no-ff 사용)
git merge --no-ff feature/new-dashboard-ui
# (충돌 발생 시 해결 후 commit)

# 3. dev 원격 저장소로 푸시 (CI/CD 자동 배포 트리거)
git push origin dev

🚨 주의: 이때 feature/new-dashboard-ui 브랜치는 삭제하지 않습니다. Prod 배포를 위해 필요합니다.

4. 운영 서버 배포 (Release to Prod) Dev 환경에서 검증이 완료된 브랜치만 Prod에 병합합니다.

# 1. prod 브랜치로 이동 및 최신화
git checkout prod
git pull origin prod

# 2. 검증된 작업 브랜치를 prod에 병합
git merge --no-ff feature/new-dashboard-ui

# 3. prod 원격 저장소로 푸시
git push origin prod

# 4. (선택) 작업 브랜치 삭제
git branch -d feature/new-dashboard-ui

---

5. 프로젝트 컨벤션 (Conventions)

📚 코드 스타일 및 포맷팅

• 스타일링: **MUI (Material UI)**와 sx props를 사용하여 스타일링합니다.
• 린팅 및 포맷팅: ESLint와 Prettier 설정이 되어 있습니다.
  • VS Code 확장 프로그램: 일관된 코드 스타일 유지를 위해 다음 확장 프로그램 설치를 강력히 권장합니다.
    • ESLint: 코드에서 발견된 문제(버그, 스타일 문제 등)를 즉시 시각적으로 피드백해 줍니다.
    • Prettier - Code formatter: 파일을 저장할 때 자동으로 코드 포맷팅을 해줍니다.
  • settings.json에 editor.formatOnSave: true 설정을 추가하면 편리합니다.

📁 폴더 구조

• src/features 폴더 하위에 기능별로(예: auth, gallery, generation) 코드를 모아두는 Feature-based 구조를 지향합니다.

---

6. 기능 구현 및 백엔드 연동 가이드 (Core Features)

UI/UX 구현은 자유롭게 진행하시되, 백엔드와 데이터를 주고받는 핵심 로직은 아래 가이드를 참고하여 기존 아키텍처와 일관성을 유지해 주세요.

🏗 1. 동적 폼(Dynamic Form) 생성 및 제출

우리 서비스는 고정된 입력 폼이 아닌, ComfyUI 워크플로우 템플릿에 따라 입력 필드가 동적으로 변하는 구조입니다.

1. 템플릿 조회: GET /api/v1/workflows/:id API를 통해 템플릿 정보를 가져옵니다.
2. 스키마 파싱: 응답 데이터 중 userInputs 필드(JSON Schema)를 분석하여 UI를 렌더링해야 합니다.
   • widget: text (Input), number (Slider/Input), combo (Select) 등
   • min, max: 숫자 입력의 유효성 검사 범위
3. 생성 요청: 사용자가 입력한 값들을 모아 modifications 객체로 구성하여 전송합니다.
   • API: POST /api/v1/generation/from-template
   • Body 예시:

     {
       "workflowId": "...",
       "modifications": {
         "seed": 12345,
         "prompt": "A futuristic city",
         "cfg": 7.5
       }
     }

🖼️ 2. AI 친화적 해상도 규칙 (Image Size)

AI 모델은 8의 배수(권장 64의 배수) 픽셀에서 최적의 성능을 냅니다. UI의 SD/HD/FHD 버튼은 아래 테이블에 맞춰 변환되어 전송되어야 합니다.

• SD (Standard): 기본 생성/저비용 옵션
• HD (High): 일반 고화질 옵션
• FHD (Full High): HD보다 높은 고해상도 옵션

비율 (W:H)	SD	HD	FHD	비고
1:2	512 x 1024	704 x 1408	960 x 1920
9:16	512 x 912	768 x 1344	1080 x 1920	📱 Shorts/Reels 최적화
2:3	512 x 768	832 x 1216	1280 x 1920
3:4	512 x 680	896 x 1152	1248 x 1664
1:1	512 x 512	1024 x 1024	1440 x 1440	🟧 인스타그램
4:3	680 x 512	1152 x 896	1664 x 1248
3:2	768 x 512	1216 x 832	1920 x 1280
16:9	912 x 512	1344 x 768	1920 x 1080	📺 유튜브/썸네일 최적화
2:1	1024 x 512	1408 x 704	1920 x 960

7. 배포 (Deployment)

• Dev 배포: dev 브랜치에 코드가 푸시되면 자동으로 개발 서버에 배포됩니다.
• Prod 배포: prod 브랜치에 코드가 병합되고 릴리스 태그가 생성되면 운영 서버에 배포됩니다.
• Docs 배포: 문서 변경 사항은 Vercel을 통해 자동으로 배포됩니다.

---

💡 문제 해결 (Troubleshooting)

• Q: 로컬 백엔드가 켜지지 않고 Redis 에러가 나요.
  • A: SSH 터널링이 켜져 있는지 확인하세요. Bastion Host IP 등록 여부도 확인해야 합니다.
• Q: DB 접속이 안 돼요.
  • A: 로컬 DB라면 docker ps로 컨테이너 상태를 확인하세요. Dev/Prod DB라면 PgAdmin에서 SSH 터널링 설정을 확인하세요.

추가적인 질문이나 문제는 팀 커뮤니케이션 채널을 통해 언제든 문의해 주세요! 🚀