핵심 개념

아키텍처

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, generate, edit, multimode, nodes, sessions, history, imageImport, health, storage, metadata, annotations, canvasVersions, comfy, prompts, promptImport, 항상 등록되는 agent(Agent 모드)·promptBuilder 라우트, dev 게이트된 cardNews.
lib/*스토리지, OAuth 프록시, 로깅, 세션, inflight 상태, 이미지 메타데이터 임베드/복원, 프롬프트 라이브러리 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를 보세요.