Portfolio Project

LangGraph 에이전트 워크플로우를 시각화하고 제어하는 콘솔

FlowPilot은 ComfyUI 스타일의 독립 노드를 조합해 콘텐츠 제작 파이프라인을 구성하고, 실행 과정을 SSE로 실시간 모니터링하는 풀스택 데모입니다. 프론트엔드는 Cloudflare Pages에 정적 배포되고, 백엔드는 Google Cloud Run에서 FastAPI와 LangGraph로 동작합니다.

Architecture

Cloudflare Pages

Next.js Static Export · React Flow · Zustand

REST + SSE (fetch / ReadableStream)

Google Cloud Run

FastAPI · LangGraph StateGraph · Node Registry

OpenRouter

LLM (Gemini Flash)

fal.ai

FLUX 이미지

Tavily

웹 검색

Supabase PostgreSQL

Checkpointer · projects/runs

Cloudflare R2

생성 이미지 저장 · 공개 URL

Frontend · ai-agent-fe

Next.js 정적 사이트. 서버 없이 CDN에서 서빙되며 모든 상호작용은 브라우저에서 처리합니다.

UI Runtime

  • Next.js14 App Router

    정적 내보내기(output: export)로 서버 없이 CDN 배포

  • React18

    클라이언트 컴포넌트 기반 실시간 상태 반영

  • TypeScript5

    React Flow Node/Edge 제네릭 확장, SSE 이벤트 타입 정의

  • Tailwind CSS3

    CSS 변수 기반 다크 Slate/Zinc 디자인 토큰, 상태별 Glow·스트라이프 애니메이션

  • lucide-react

    노드·상태·액션 아이콘. 색상만으로 구분하지 않도록 텍스트와 병기

Workflow & State

  • @xyflow/react12

    커스텀 노드 카드·커스텀 에지, 드래그 앤 드롭 추가, 재작성 루프 에지 애니메이션

  • Zustand5

    그래프·실행·로그·결과·승인 대기·채팅을 단일 스토어로 관리해 Chat/Node 탭 간 세션 공유

  • fetch + ReadableStream

    SSE 파서를 직접 구현해 event/data 블록을 StreamEvent로 변환

  • Mock Stream Runner

    백엔드와 동일한 이벤트 계약으로 재작성 분기·승인 대기·실패를 시뮬레이션

Delivery

  • Cloudflare Pages

    글로벌 CDN 정적 호스팅, _headers로 보안·캐시 헤더 적용

  • Wrangler4

    CLI 직접 배포(pages deploy) 및 로컬 미리보기

  • GitHub Actions

    main 푸시 시 빌드 후 wrangler-action으로 자동 배포

  • Playwright + Chrome

    헤드리스 브라우저로 실행 흐름·승인 모달·모바일 레이아웃 검증

Backend · ai-agent-be

FastAPI + LangGraph 비동기 API. 노드 레지스트리, 동적 그래프 빌더, 체크포인터, SSE 스트리밍을 제공합니다.

API Server

  • Python3.11

    typing.Required 기반 AgentState TypedDict

  • FastAPI0.141

    비동기 REST + StreamingResponse SSE, lifespan으로 체크포인터·스토어 관리

  • Uvicorn

    Cloud Run이 주입하는 $PORT로 단일 워커 실행, 스케일은 인스턴스 단위

  • Pydantic2

    프로젝트 JSON·그래프 스키마 검증, pydantic-settings로 환경변수 로딩

  • httpx

    OpenRouter·fal.ai·Tavily를 SDK 없이 직접 호출하는 비동기 HTTP 클라이언트

Agent Orchestration

  • LangGraph

    프로젝트 JSON → StateGraph 동적 컴파일, 조건부 에지, Fan-out/Fan-in

  • Self-Correction Loop

    Reviewer 점수 미달 시 review_feedback을 담아 Copywriting으로 회귀, retry_count 상한

  • Human-in-the-Loop

    interrupt_before로 중단 → 체크포인트 병합 → POST /api/graph/resume 재개

  • ComfyUI 스타일 노드

    BaseNode 서브클래스를 패키지 스캔으로 자동 등록, INPUT_TYPES 스키마를 프론트 팔레트로 노출

  • SSE Emitter

    thread 단위 단조 증가 seq, 15초 하트비트로 프록시 유휴 타임아웃 방지

Models & Tools

  • OpenRouter

    OpenAI 호환 엔드포인트로 LLM 호출. 라우팅·텍스트·비전 모델을 config 한 곳에서 선택

  • Gemini Flash

    라우터·카피라이팅·리뷰어·비전 리뷰 기본 모델 (비용 최적화)

  • FLUX (fal.ai / OpenRouter)

    이미지 생성 제공사 어댑터. 함수 하나 = 제공사 하나로 교체 가능

  • Tavily

    Web Search 노드. 같은 topic으로 병렬 배선해 Fan-out 시연

Persistence & Infra

  • Supabase PostgreSQL

    AsyncPostgresSaver 체크포인트 + projects/runs 테이블 (psycopg3 풀)

  • Cloudflare R2

    boto3 S3 호환 API로 생성 이미지 업로드, State에는 URL만 저장

  • Docker + Google Cloud Run

    python:3.11-slim 컨테이너, asia-northeast3, min 0 / max 3 인스턴스

  • Secret Manager

    API 키·DB URL을 시크릿으로 마운트, CORS 허용 목록은 환경변수

  • pytest + pytest-asyncio

    LLM 모킹으로 네트워크 없이 그래프 빌더·노드·실행 API 테스트