핵심 개념

아키텍처

ima2-gen은 이미지 생성 CLI와 웹 UI가 결합된 앱입니다. 둘 다 로컬 Express 서버의 /api/* 엔드포인트를 호출하고, 서버는 라우트 모듈·로컬 OAuth 프록시·SQLite·생성 이미지 디렉터리로 위임합니다.

런타임 흐름

CLI (bin/ima2.ts, bin/commands/*) ──┐
Web UI (ui/dist, served)          ──┼──→ server.ts ──→ routes/*
                                    │                     │
                                    │           lib/*  (storage, sessions, inflight, metadata)
                                    │           openai-oauth  (OpenAI OAuth proxy)
                                    │           progrok  (bundled xAI proxy)
                                    │           ~/.ima2/generated  (images + sidecars)
                                    └────────── better-sqlite3  (sessions + graph)

런타임 경로는 의도적으로 단순합니다. CLI 명령과 브라우저가 같은 엔드포인트를 호출하고, 서버는 OAuth 프록시, API key Responses 경로, 또는 Grok/xAI Images API용 번들 progrok으로 이미지 요청을 보내고, 설정된 생성 디렉터리에 파일을 저장하고, 그래프 세션을 SQLite에 보존합니다.

모듈 맵

영역책임
server.tsExpress 부트스트랩, 라우트 등록. 짝 런타임 산출물 server.js.
routes/*API 표면: capabilities, events (SSE 멀티플렉스), generate, edit, multimode, nodes, sessions, history, imageImport, health, storage, metadata, annotations, canvasVersions, comfy, prompts, promptImport, keys, auth, quota, grok, agy, 항상 등록되는 agent(Agent 모드)·promptBuilder 라우트, video, dev 게이트된 cardNews.
lib/*스토리지, OAuth 프록시, 로깅, 세션, inflight 상태, eventBus (SSE 멀티플렉싱용 pub/sub 링 버퍼), ssePublish (취소-완료 레이스 가드), 이미지 메타데이터 임베드/복원, 프롬프트 라이브러리 SQLite, 레퍼런스 압축, canvas 버전 저장소, soft-delete 휴지통.
bin/*CLI 디스패처와 클라이언트 명령 — 서버 API와 거의 완전한 패리티. Agent Mode는 의도적인 웹 UI 전용 예외이고, prompt builder는 ima2 prompt build를 씁니다.
ui/src/*React UI, React Flow node 모드, Canvas Mode, Agent 모드 워크스페이스(components/agent/*), 모바일 셸, 프롬프트 라이브러리 패널.
원본(Source of truth). 라우트·lib·서버·bin 소스 파일은 *.ts입니다. 짝이 되는 *.js는 커밋된 빌드 산출물 — 손이 아니라 빌드로만 편집하세요.

데이터 위치

  • ~/.ima2/config.json — 파일 레이어 설정 (설정 참고).
  • ~/.ima2/generated — 생성 이미지와 메타데이터 사이드카.
  • ~/.ima2/server.json — 런타임 탐색(실제 바인딩 포트).
  • SQLite — 세션과 node 그래프 스냅샷.

전체 내부 아키텍처 문서는 structure/에 있습니다. 요청/응답 계약은 서버 API를 보세요.