Concepts

Architecture

ima2-gen is a combined image-generation CLI and web UI. Both call /api/* endpoints on a local Express server that delegates to route modules, a local OAuth proxy, SQLite, and your generated-image directory.

Runtime flow

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)

The runtime path is intentionally direct. CLI commands and the browser call the same endpoints; the server sends image requests through the OAuth proxy, the API-key Responses path, or bundled progrok for Grok/xAI Images API, saves files under the configured generated directory, and persists graph sessions in SQLite.

Module map

Area	Owns
`server.ts`	Express bootstrap; registers routes. Paired runtime artifact `server.js`.
`routes/*`	API surfaces: capabilities, generate, edit, multimode, nodes, sessions, history, imageImport, health, storage, metadata, annotations, canvasVersions, comfy, prompts, promptImport, the always-on agent (Agent Mode) and promptBuilder routes, and dev-gated cardNews.
`lib/*`	Storage, OAuth proxy, logging, sessions, inflight state, image metadata embed/restore, prompt-library SQLite, reference compression, canvas-version store, soft-delete trash.
`bin/*`	CLI dispatcher and client commands — near-complete parity with the server API. Agent Mode is the intentional web-UI-only exception; prompt builder uses `ima2 prompt build`.
`ui/src/*`	React UI, React Flow node mode, Canvas Mode, the Agent Mode workspace (`components/agent/*`), mobile shell, prompt-library panel.

Source of truth. Route, lib, server, and bin source files are *.ts. The paired *.js files are committed build artifacts — edit them only through the build, never by hand.

Where data lives

~/.ima2/config.json — file-layer config (see Configuration).
~/.ima2/generated — generated images and metadata sidecars.
~/.ima2/server.json — runtime discovery (the actual bound port).
SQLite — sessions and node-graph snapshots.

The full internal architecture set lives under structure/. For request and response contracts, see the Server API.

Quickstart Generation Modes