개요

💎 프로젝트 개요: SurfAI 최종 업데이트: 2025년 6월 29일

이 문서는 SurfAI 프로젝트의 비전, 핵심 개념, 주요 기능, 그리고 목표를 상세히 설명합니다.

---

1. 프로젝트 비전 (Vision)

SurfAI의 핵심 비전은 AI 이미지 및 비디오 생성 기술의 복잡성을 제거하고, 누구나 전문가 수준의 결과물을 손쉽게 만들 수 있도록 하는 것입니다.

기존의 AI 생성 도구들은 사용자가 복잡한 노드 구조나 수많은 파라미터 값을 직접 이해하고 설정해야 하는 높은 진입 장벽을 가지고 있습니다. SurfAI는 이러한 문제를 해결하기 위해, 기술 전문가(관리자)가 잘 만들어진 ComfyUI 워크플로우를 "템플릿"으로 등록하면, 일반 사용자는 마치 잘 만들어진 카메라 앱의 필터를 고르듯, 몇 가지 직관적인 파라미터만 조절하여 일관성 있고 고품질의 결과물을 얻을 수 있는 혁신적인 사용자 경험을 제공하고자 합니다.

---

2. 핵심 개념 (Core Concepts)

SurfAI 서비스는 다음 두 가지 핵심 개념을 중심으로 구축됩니다.

가. 워크플로우 템플릿 (Workflow Template)

• 정의: 특정 목적(예: '고품질 인물 사진 생성', '애니메이션 스타일 단편 비디오 제작')을 위해 최적화된 ComfyUI 워크플로우의 "청사진"입니다.
• 구성 요소: 템플릿은 ComfyUI의 원본 definition JSON과, 사용자가 제어할 수 있는 parameter_map으로 구성됩니다.
• 역할: 관리자만이 이 템플릿을 생성하고 관리하며, 서비스의 핵심 생성 능력을 정의하고 확장하는 역할을 합니다.

나. 동적 파라미터 (Dynamic Parameters)

• 정의: 워크플로우 템플릿 내에서 사용자가 직접 수정할 수 있도록 관리자가 지정한 핵심 변수들입니다.
• 예시: positive_prompt, negative_prompt, seed, cfg, steps, 비디오의 length 및 fps 등.
• 역할: 사용자는 복잡한 노드 구조를 전혀 몰라도, 프론트엔드의 친화적인 UI를 통해 이 파라미터 값들만 수정하여 자신만의 독창적인 결과물을 생성할 수 있습니다.

---

3. 주요 기능 (Key Features)

가. 관리자 (Admin) 기능

• 워크플로우 템플릿 관리 (CRUD): 관리자 전용 페이지에서 워크플로우 템플릿을 생성, 조회, 수정, 삭제할 수 있습니다.
• 역할 기반 접근 제어 (RBAC): 특정 이메일 주소를 가진 사용자에게만 관리자 권한을 부여하여 시스템을 안전하게 관리합니다.
• (향후) 사용자 및 서비스 통계 관리: 전체 사용자 목록 조회, 서비스 사용량 통계 등을 확인할 수 있는 대시보드 기능을 확장할 수 있습니다.

나. 일반 사용자 (User) 기능

• 간편한 로그인: 이메일/비밀번호 가입 또는 Google 계정을 통한 간편 로그인을 지원합니다.
• 템플릿 기반 생성: 공개된 워크플로우 템플릿 목록에서 원하는 스타일을 선택하고, 간단한 폼 입력을 통해 이미지/비디오 생성을 요청합니다.
• 실시간 진행 상황 확인: WebSocket을 통해 생성 작업의 진행률, 대기열 상태, 그리고 생성 중인 프리뷰 결과물을 실시간으로 확인할 수 있습니다.
• 개인 갤러리 (히스토리): 자신이 생성한 모든 결과물을 "히스토리" 페이지에서 확인하고 관리할 수 있습니다.
• 결과물 관리: 갤러리에서 각 결과물을 확대하여 상세 생성 정보(사용한 파라미터 등)를 확인하고, 고화질 원본 파일을 다운로드하거나 삭제할 수 있습니다.

---

4. 기술 스택 (Tech Stack)

• Frontend: Next.js, React, TypeScript, Tailwind CSS
• Backend: NestJS, TypeScript, TypeORM, PostgreSQL
• Infrastructure: Docker, Google Cloud Run, Cloudflare R2, Nginx
• Documentation: Docusaurus, Gemini CLI, Mermaid

---

5. 기술적 목표 (Technical Goals)

• 안정성 및 확장성: 모든 서비스를 Docker 컨테이너화하고 Google Cloud Run에 배포하여, 트래픽에 따라 자동으로 확장되는 안정적인 서버리스 아키텍처를 구축합니다.
• 보안: JWT와 HttpOnly 쿠키를 이용한 안전한 인증, CSRF 및 WAF를 통한 웹 공격 방어, 역할 기반 접근 제어 등 다층적인 보안 체계를 적용합니다.
• 자동화된 워크플로우: GitHub Actions를 이용한 CI/CD 파이프라인을 구축하여, 코드 변경 사항을 자동으로 테스트하고 배포하는 프로세스를 확립합니다.
• 유지보수성: 프론트엔드와 백엔드를 명확히 분리하고, 각 내부에서도 모듈과 컴포넌트의 책임을 명확히 나누는 클린 아키텍처를 지향합니다.
• 살아있는 문서: Docusaurus를 통해 모든 문서를 코드와 함께 Git으로 관리합니다. 이를 통해 항상 최신 상태의 정확한 문서를 모든 구성원이 쉽게 열람할 수 있는 환경을 구축합니다.