Skip to main content

프론트엔드 개요

이 문서는 frontend-autopromaker-ai 프로젝트의 전반적인 아키텍처, 폴더 구조, 그리고 주요 기술 전략에 대한 개요를 제공합니다.

핵심 아키텍처 원칙​

  • 기능 중심 구조 (Feature-based Structure): 프로젝트를 기능 단위로 명확하게 분리하여 응집도를 높이고 결합도를 낮춥니다. 각 기능은 src/features 폴더 내에 독립적으로 존재하여 코드의 재사용성과 유지보수성을 극대화합니다.
  • 선언적 상태 관리: 서버 상태와 클라이언트 상태를 명확히 분리하여 관리합니다.
    • 서버 상태: TanStack Query(React-Query)를 사용하여 API 데이터 페칭, 캐싱, 동기화 등 복잡한 서버 상태를 효율적으로 관리합니다.
    • 클라이언트 상태: React Context API를 사용하여 사용자의 인증 정보, 지갑 상태 등 전역적으로 필요한 클라이언트 상태를 관리합니다.
  • 중앙화된 데이터 페칭: axios 인스턴스를 중앙에서 관리하는 apiClient를 구현합니다. 이를 통해 API 요청 로직을 표준화하고, JWT 토큰 자동 주입과 같은 공통 로직을 인터셉터로 쉽게 처리합니다.

Next.js 이미지 로더 설정 (next/image)​

next/image 컴포넌트를 사용하여 S3 버킷에 저장된 이미지를 로드하려면, next.config.ts 파일에 해당 S3 버킷의 호스트 이름을 images.remotePatterns에 명시적으로 추가해야 합니다. 이는 Next.js의 보안 정책과 이미지 최적화 기능의 올바른 작동을 위한 필수 설정입니다.

다음은 local 및 dev 환경의 임시 및 영구 S3 버킷에 대한 remotePatterns 설정 예시입니다.

// frontend-autopromaker-ai/next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  output: 'standalone',
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'vivid-ai-permanent-files-local.s3.ap-northeast-1.amazonaws.com',
        port: '',
        pathname: '/creations/**',
      },
      {
        protocol: 'https',
        hostname: 'vivid-ai-permanent-files-dev.s3.ap-northeast-1.amazonaws.com',
        port: '',
        pathname: '/creations/**',
      },
      {
        protocol: 'https',
        hostname: 'vivid-ai-temp-files-local.s3.ap-northeast-1.amazonaws.com',
        port: '',
        pathname: '/raw/**',
      },
      {
        protocol: 'https',
        hostname: 'vivid-ai-temp-files-dev.s3.ap-northeast-1.amazonaws.com',
        port: '',
        pathname: '/raw/**',
      },
    ],
  },
};

export default nextConfig;

주요 기능​

이미지 생성 (/generate)​

  • 고급 설정: 사용자가 생성 과정을 더 세밀하게 제어할 수 있도록 '고급 설정' 기능을 제공합니다.
    • Negative Prompt: 원치 않는 결과물을 배제할 수 있는 Negative Prompt 입력 필드를 지원합니다.
    • Seed 값 제어: 이미지 생성의 일관성을 유지하거나 무작위성을 부여할 수 있도록 Seed 입력 필드와 '랜덤' 체크박스를 제공합니다.
  • UX 개선: 현재 적용된 워크플로우 템플릿이 Negative Prompt를 지원하지 않는 경우, 해당 입력 필드를 비활성화하고 사용자에게 안내 메시지를 표시하여 혼란을 방지합니다.

실시간 이미지 업데이트 (Optimistic UI)​

  • 하이브리드 데이터 동기화: Creations 페이지 진입 시 REST API를 통해 초기 데이터를 불러오지만, 생성 중인 작업의 결과물은 WebSocket을 통해 실시간으로 수신합니다.
  • 캐시 직접 주입 (Cache Injection): 백엔드로부터 IMAGE_ADDED 이벤트를 수신하면, useGlobalGeneratorLogic 훅 내부에서 React Query의 캐시 데이터(['creations'])를 직접 수정합니다.
    • 이를 통해 API 상으로는 아직 PENDING 상태이거나 이미지가 없는([]) 상태라도, 사용자는 새로고침이나 추가적인 API 호출 없이 즉시 생성된 이미지를 화면에서 확인할 수 있습니다.
    • 관련 훅: useComfyWebSocket, useGlobalGeneratorLogic

서버 모니터링 및 작업 진행 상황 (/admin/monitor)​

  • ServerMonitor.tsx 컴포넌트를 통해 생성 실행부의 CPU, RAM, 디스크 등 시스템 메트릭을 실시간으로 시각화합니다.
  • 현재 진행 중인 사용자 작업의 상태(대기 중, 실행 중, 진행률 등)를 실시간으로 표시하여 운영 투명성을 확보하고, 관리자가 시스템 상태를 한눈에 파악할 수 있도록 돕습니다.

상세 문서​

UI/UX 및 기능 개선 (2025-11-21)​

테마 시스템 (Dark/Light Mode)​

  • MUI 기반 테마 적용: Tailwind CSS 클래스 기반의 스타일링을 MUI (Material UI) 컴포넌트 및 시스템(sx prop)으로 전면 리팩토링하여 다크 모드와 라이트 모드를 완벽하게 지원합니다.
  • 대상 컴포넌트: CreationCard, CreationDetailModal, GeneratorForm, Navbar 등 주요 UI 요소.

네비게이션 및 라우팅​

  • "Generate" 페이지 통합: 별도의 "생성" 페이지(/generate)를 제거하고, 루트 경로(/) 접속 시 "My Creations"(/creations) 갤러리로 리다이렉트하도록 변경했습니다.
  • Global Generator: 생성 폼(GeneratorForm)은 상단 바에 고정되어 어디서든 접근 가능하므로, 별도 페이지가 불필요해졌습니다.

상태 표시 개선​

  • 작업 상태 시각화:
    • Waiting (Queued): 노란색 모래시계 아이콘. 작업이 SQS 큐에 대기 중인 상태.
    • Preparing (Processing): 파란색 로딩 아이콘. Worker가 작업을 수신하고 ComfyUI에 전송한 상태.
    • Generating (In Progress): 녹색 로딩 아이콘 및 실시간 퍼센트 바. 생성 provider 또는 ComfyUI workflow가 실행 중인 상태.
  • NaN% 버그 수정: 대기 중인 작업에 대해 잘못된 진행률이 표시되던 문제를 해결했습니다.

Admin Monitor​

  • 탭 기반 뷰: 서버 모니터링 페이지를 '전체', '대기 중', '실행 중', '완료/실패' 탭으로 분리하여 많은 작업을 효율적으로 관리할 수 있도록 개선했습니다.

비디오 생성 지원 및 미리보기 (2025-11-24)​

비디오 자동 재생 (Autoplay Preview)​

  • CreationCard 개선: 갤러리 목록의 카드(CreationCard)가 이미지뿐만 아니라 비디오 파일도 지원하도록 업데이트되었습니다.
    • 자동 감지: thumbnailPath의 확장자를 확인하여 비디오 파일(.mp4, .webm 등)인 경우 자동으로 <video> 태그를 렌더링합니다.
    • 미리보기 최적화: autoPlay, muted, loop, playsInline 속성을 적용하여 사용자가 별도의 클릭 없이도 갤러리에서 바로 움직이는 결과물을 확인할 수 있습니다.
  • 상세 보기 플레이어: 결과물을 클릭하여 열리는 상세 모달(CreationDetailModal)에서는 원본 고화질 비디오를 재생할 수 있는 컨트롤이 포함된 비디오 플레이어를 제공합니다.

상태 처리 로직 강화​

  • 실시간 실패 감지: WebSocket을 통해 failed 상태의 이벤트가 수신되면, 데이터베이스의 상태가 아직 PROCESSING이라 하더라도 즉시 UI에 '실패(Failed)' 상태를 반영하도록 로직을 강화했습니다. 이를 통해 사용자는 불필요하게 "처리 중..." 상태를 기다리지 않고 즉각적인 피드백을 받을 수 있습니다.