Assetflow

1. Overview

Assetflow는 여러 AI 데모를 모아 둔 프로젝트가 아니라, 비개발 직군도 게임 에셋 생성과 편집을 요청하고 결과를 관리할 수 있도록 제품 UI, 에이전트 판단, GPU 추론, 모델 저장소 운영을 분리한 내부 AI 플랫폼입니다.

현재 작업공간에서 확인되는 제품 중심축은 다음과 같습니다.

플랫폼은 Next.js 기반 제품 앱을 중심으로 Python 에이전트 서비스, Diffusion 및 vLLM RunPod Serverless 워커, Hugging Face 모델을 network volume으로 전달하는 운영 도구를 독립 배포 단위로 구성합니다.

2. Key Impact

• 자연어 요청을 이미지 생성 도구와 단일·다단계 실행 계획으로 변환하는 Ask AI 흐름을 제품 UI에 연결했습니다.
• 인증, 크레딧, 결제, 생성 이력, 웹훅 처리를 제품 앱에 남기고 AI 분석과 GPU 추론을 별도 서비스로 분리했습니다.
• 이미지, 영상, 업스케일, 배경 제거, 스프라이트 시트 등 18개 도구 디렉터리를 manifest/handler 레지스트리로 관리합니다.
• ComfyUI와 Diffusers 실행 경로를 하나의 Diffusion worker 계약 아래 수용하고, vLLM 채팅 추론은 별도 worker로 격리했습니다.
• LoRA와 대형 체크포인트를 이미지에 포함하지 않고 RunPod network volume에서 공급할 수 있는 Gradio 운영 도구를 마련했습니다.
• 웹 제품을 Capacitor 기반 Android/iOS 셸과 연결하고, 6개 언어 UI 리소스 및 감사 스크립트를 운영합니다.

정량 성과는 현재 저장소만으로 검증할 수 없어 포함하지 않았습니다.

3. Platform Map

4. Common Architecture

4.1. Product and execution boundaries

Assetflow-AI-Site는 시스템 오브 레코드입니다. 브라우저 계약, 사용자 인증, 크레딧 검증과 차감, Prisma 데이터, 생성 요청, 웹훅 완료 처리를 소유합니다. Assetflow-AI-Agent는 자연어 분석과 실행 계획을 담당하고 제품 DB에 직접 접근하지 않습니다. 이 경계는 공개 API를 유지하면서 분석기를 독립 배포하고 장애 시 로컬 분석기로 폴백할 수 있도록 설계되었습니다.

4.2. Long-running Job

GPU 생성은 HTTP 요청 안에서 완료될 때까지 기다리지 않습니다. 제품 앱이 생성 요청과 job ID를 저장하고 RunPod에 제출한 뒤, 상태 조회 또는 웹훅으로 완료 결과를 반영합니다. UI는 queued, running, processing, completed, failed와 같은 상태를 사용자에게 보여 줍니다.

4.3. Provider abstraction

• LLM: OpenAI, Gemini, Claude 어댑터와 우선순위 기반 폴백
• Image and video: RunPod endpoint 설정과 ComfyUI workflow registry
• Chat inference: OpenAI 호환 vLLM server
• Storage: Vercel Blob과 RunPod network volume의 역할 분리

4.4. Contract and registry

도구 ID, 파라미터, 필수 필드, 이미지 정책, 비용 정책, UI 정책은 Site의 tool manifest가 단일 진실입니다. Agent의 도구 스키마와 RAG corpus는 동기화 스크립트로 생성하며 직접 편집하지 않습니다. 브라우저의 message, tool_call, multi_step, clarification 응답 형태는 JSON Schema와 계약 문서로 고정합니다.

5. AI Image Generation Platform

5.1. Problem

게임 아트 제작에는 생성 모델별 프롬프트, 입력 이미지 규격, ComfyUI graph, GPU endpoint와 후처리 방법을 알아야 했습니다. 이 복잡성을 작업자에게 그대로 노출하면 반복 작업과 실패 대응 비용이 커집니다.

5.2. Goal

사용자가 원하는 에셋과 편집 의도를 선택하거나 자연어로 설명하면, 플랫폼이 입력 검증부터 프롬프트 최적화, workflow 선택, 비동기 실행, 결과 저장까지 일관된 흐름으로 처리하게 만드는 것이 목표입니다.

5.3. Workflow

Tool form or Ask AI request
→ input and funding validation
→ multilingual prompt optimization
→ generation record creation
→ ComfyUI workflow or Diffusers backend selection
→ RunPod Serverless submission
→ polling / webhook completion
→ Vercel Blob result and generation history

5.4. Core Features

• 일러스트, 아이콘, 이펙트, 타일맵, 심리스 패턴 생성
• 캐릭터 정규화와 스타일 변환
• 단순 이미지 편집과 image-to-icon 변환
• 배경 제거와 업스케일
• 스프라이트 시트, 9프레임 애니메이션, 전체 모션 생성
• 이미지·텍스트 기반 영상 및 루프 배경 생성
• 다국어 프롬프트 최적화와 이미지 캡션 처리
• 생성 이력, 에셋 업로드, 사용자 크레딧과 결제 흐름

5.5. Technical Decisions

• 모든 도구에 manifest.ts와 handler.ts를 두고, 연쇄 실행 지침이 필요한 도구에는 tool.md를 추가해 제품 정책, 실행 로직, LLM 사용 지침을 분리했습니다.
• ComfyUI API-format workflow의 선택과 입력 binding은 Site registry에 모아 고수준 서비스가 node ID에 의존하지 않게 했습니다.
• Diffusion worker는 catalog에서 모델을 해석한 뒤 ComfyUI, text-to-image, text-to-audio, image edit, video backend로 라우팅합니다.
• 원본 이미지 편집은 요청 대상만 바꾸고 원본의 스타일과 구도를 보존하는 프롬프트 정책을 적용합니다.
• 모델과 LoRA는 network volume 경로를 우선 사용해 컨테이너 이미지와 대형 가중치의 배포 주기를 분리합니다.

5.6. Result

제품 UI와 GPU 실행 세부사항 사이에 도구 레지스트리, workflow adapter, job 상태 계층이 생겼습니다. 새 생성 기능을 추가할 때 route나 UI에 도구 ID 분기를 복제하는 대신 플러그인 디렉터리와 레지스트리를 확장할 수 있습니다.

5.7. My Contribution

저장소에서 확인 가능한 기여 영역은 다음과 같습니다. 실제 개인·팀 분담 비율은 별도 이력 확인이 필요합니다.

• 게임 에셋 생성·편집 도구의 제품 흐름과 manifest 기반 확장 구조
• ComfyUI workflow registry와 RunPod payload mapping
• 모델 catalog 및 backend 기반 다중 모델 Diffusion worker
• 이미지 캡션과 다국어 prompt optimization service
• 생성 상태, webhook, 결과 저장, 오류 전달을 포함한 장시간 작업 흐름
• LoRA 및 checkpoint를 network volume으로 공급하는 운영 도구

6. Agent Chatbot / RAG Platform

6.1. Problem

사용자는 내부 도구의 정확한 이름과 파라미터를 모르며, 여러 이미지 도구를 순서대로 연결할 때 중간 결과와 비용 선택까지 직접 관리하기 어렵습니다.

6.2. Goal

자연어와 선택적 이미지를 분석해 적절한 도구를 선택하고, 필요한 경우 사용자에게 질문한 뒤, 실행 전에 확인 가능한 단일 또는 다단계 계획으로 변환합니다.

6.3. Workflow

User message + optional image
→ Site rule normalization
→ signed Agent analyze request
→ tool schema and tool-document RAG context
→ message / tool_call / multi_step / clarification
→ user confirmation or option selection
→ Site-owned execution and credit validation
→ conversational step progress and result

6.4. Core Features

• 자연어 기반 도구 선택
• 이미지 필요 여부와 funding 조건 검증
• 단일 도구 확인 및 파라미터 편집
• dependsOn과 previousStepResult를 사용하는 multi-step plan
• 사용자 선택이 필요한 clarification UI
• 단계별 사용자 가시 메시지와 진행 상태
• HMAC, timestamp, nonce, idempotency를 사용한 내부 호출
• 도구 문서를 대상으로 한 경량 keyword RAG
• 영어, 한국어, 일본어, 중국어, 독일어, 프랑스어 시스템 프롬프트

6.5. Technical Decisions

• Agent는 분석을, Site는 인증·비용·실행·영속화를 소유하도록 경계를 고정했습니다.
• public manifest와 server handler registry를 분리해 클라이언트에 안전한 정보만 노출합니다.
• 다단계 실행은 route의 도구별 분기 대신 선언적 step dependency와 이전 결과 전달로 표현합니다.
• Python Agent가 소비하는 tool schema와 RAG corpus를 Site manifest 및 tool.md에서 생성해 TS/Python 불일치를 줄입니다.

6.6. Result

사용자는 개별 AI 기능 페이지를 모두 탐색하지 않고 대화형 진입점에서 실행 가능한 계획을 받을 수 있습니다. 동시에 실제 실행과 크레딧 정책은 제품 앱에 유지되어 분석 서비스 교체가 결제 및 데이터 정합성에 직접 영향을 주지 않습니다.

6.7. Current Scope and Limitations

• 현재 RAG는 업로드 문서용 범용 vector RAG가 아니라 도구 문서에 대한 keyword overlap 방식입니다.
• multi-step 단계별 파라미터 편집은 구현되지 않았습니다.
• 비동기 1단계 job 완료 후 2단계를 자동 재개하는 완전한 장시간 chain은 추가 설계가 필요합니다.
• Document Agent, TRPG Simulation Agent, CLI Coding Assistant의 실행 구현은 현재 작업공간에서 확인되지 않았으므로 확장 목표로만 분류합니다.

6.8. My Contribution

• 브라우저와 Agent 사이의 분석 계약 및 안정적인 응답 타입 설계
• manifest/handler/tool document 기반 도구 플러그인 구조
• clarification, single-tool confirmation, multi-step progress UI
• HMAC 서명과 요청 상관관계를 포함한 서비스 분리
• 도구 스키마 및 RAG corpus 동기화 자동화

7. Game Localization Pipeline

7.1. Status

Assetflow-Portfolio/AGENTS.md는 Excel batch translation, Term Base, placeholder validation, Translation QA를 세 번째 플랫폼 도메인으로 정의합니다. 그러나 현재 작업공간의 프로젝트 디렉터리에서는 이 파이프라인의 실행 코드, API, 테스트, 샘플 workbook을 확인하지 못했습니다. 따라서 아래 내용은 완료 구현이 아닌 목표 설계입니다.

7.2. Problem

게임 번역은 일반 문장 번역과 달리 프로젝트 용어, 변수, 숫자, rich text tag, 줄바꿈을 보존해야 하며 대량 workbook에서 행 단위 오류를 추적해야 합니다.

7.3. Goal

Excel 업로드부터 언어와 열 선택, Term Base 적용, batch translation, placeholder 및 용어 QA, 원본 구조를 보존한 다운로드까지 하나의 장시간 작업으로 제공하는 것입니다.

7.4. Target Workflow

Excel upload
→ source / target column and language selection
→ Term Base matching
→ batch translation
→ placeholder and format validation
→ terminology and language QA
→ row-level warning report
→ workbook export

7.5. Required Technical Decisions

• {0}, %s, \n, <br> 및 rich text tag를 번역 대상과 분리해 보존
• 번역 단계와 QA 단계를 분리하고 행 단위 부분 실패를 기록
• provider adapter를 통해 모델 교체 가능성을 유지
• 원본 sheet, cell style, formula, column 구조를 가능한 한 보존
• 대용량 workbook은 job ID와 진행률을 사용하는 비동기 처리

7.6. Portfolio Use

실제 구현 저장소와 검증 결과가 추가되기 전에는 이 모듈을 “구현 완료” 또는 개인 성과로 제시하지 않습니다.

8. Cross-domain Technical Decisions

8.1. Separation of concerns

제품 정책, AI 판단, GPU 추론, 모델 배포를 각각 Site, Agent, worker, Storage tool로 나눴습니다. 이 구조는 각 계층의 실패 원인과 배포 주기를 분리합니다.

8.2. Async by default

이미지·영상 생성과 향후 문서 인덱싱·번역 같은 장시간 작업은 즉시 job ID를 반환하고 상태를 추적하는 패턴을 기본으로 합니다.

8.3. Single source of truth

• Agent tool: Site manifest and handler registry
• Diffusion model: diffusion_models.json
• ComfyUI workflow selection: Site ComfyUI registry
• Cross-repo contract: JSON Schema and shared docs
• Model artifact path: RunPod network volume mapping

8.4. Failure visibility

외부 provider 오류를 UI에 그대로 노출하지 않되, 분석, validation, funding, dispatch, worker execution, storage와 같은 실패 단계를 구분할 수 있는 안정적 오류 코드와 상태를 사용합니다.

8.5. Deployment portability

OpenAI-compatible Agent 및 vLLM 경로, provider adapters, config-driven endpoint selection으로 특정 모델 공급자와 제품 기능의 결합을 낮췄습니다.

9. My Contribution

9.1. AI / ML

• 이미지 생성, 편집, 영상, 업스케일을 위한 모델 및 workflow 실행 구조
• VLM 기반 이미지 caption service와 다국어 prompt optimization
• LoRA catalog, checkpoint path, model backend routing
• 자연어 도구 선택과 도구 문서 RAG를 사용하는 Agent 분석 흐름

9.2. Backend

• Next.js API, 서비스, repository, infrastructure adapter의 계층 분리
• 인증·크레딧·생성 상태·webhook을 Site에 유지하는 실행 경계
• HMAC 기반 Site-Agent 내부 계약과 idempotent 실행 구조
• ComfyUI/Diffusers/vLLM RunPod worker 및 공통 job payload 운영

9.3. Frontend and Product

• 생성 도구별 입력 UI와 결과 흐름
• Ask AI의 clarification, confirmation, multi-step progress 경험
• 생성 이력, asset 관리, 오류 복구 상태
• 다국어 웹 UI와 Capacitor 기반 Android/iOS 배포 구조

9.4. Infrastructure and Operations

• CUDA 기반 RunPod Serverless worker 이미지와 smoke test
• Hugging Face 모델을 S3-compatible network volume으로 전달하는 Gradio 도구
• cross-repo 계약, tool parity, model catalog 검증 스크립트
• daily log, topic, runbook을 사용하는 agent harness

이 절은 구현 영역을 요약한 것입니다. 면접·공개 포트폴리오에 사용하기 전 commit history와 업무 기록으로 본인의 직접 기여 문장을 확정해야 합니다.

10. Limitations and Next Step

10.1. Current Limitations

• 범용 문서 업로드·embedding·vector search 기반 Document Agent는 현재 구현 근거가 없습니다.
• TRPG simulation, 안전한 CLI coding assistant, Excel localization은 설계 범위입니다.
• multi-step plan은 표시와 실행을 지원하지만 단계별 편집과 장시간 비동기 자동 재개가 완결되지 않았습니다.
• 저장소만으로 검증할 수 있는 사용자·품질·비용 지표가 없습니다.
• 제품 README와 일부 과거 운영 문서의 기술 버전·worker 설명은 현재 코드와 차이가 있어 코드 및 최신 AGENTS 문서를 우선해야 합니다.

10.2. Next Step

1. 실제 사용자 지표를 수집해 생성 성공률, 평균 처리 시간, 재시도율, 비용을 포트폴리오 성과로 연결합니다.
2. tool execution의 request ID를 Site, Agent, RunPod 전 구간에서 연계해 관측성을 강화합니다.
3. 비동기 multi-step 상태 머신과 단계별 plan edit를 구현합니다.
4. 범용 Document Agent가 필요하면 parsing, chunking, embedding, retrieval 평가를 별도 모듈로 추가합니다.
5. Localization을 진행할 경우 workbook 보존과 placeholder 회귀 테스트를 먼저 계약으로 고정합니다.

11. Tech Stack

Layer	Technology
Product	Next.js, React, TypeScript, Tailwind CSS, Zustand
Mobile	Capacitor, Android, iOS
Auth and Data	NextAuth, Prisma, PostgreSQL-compatible Vercel database
Agent	Python 3.12, Flask, LangChain, OpenAI-compatible API
AI Providers	OpenAI, Google Gemini, Anthropic Claude, vLLM
Generation	ComfyUI, Diffusers, PyTorch, LoRA
GPU Runtime	RunPod Serverless, NVIDIA CUDA
Storage	Vercel Blob, RunPod network volume, S3-compatible API
Validation	Vitest, Python unittest, JSON Schema, smoke tests, parity scripts