Exquisite
_{An imkerutils product}

EXQUISITE is a browser-based, generative reimagining of the Surrealist cadavre exquis / exquisite corpse, a 20th century collaborative game in which artists and writers passed a folded page from one contributor to the next, each adding a hidden fragment until an unexpected whole emerged.

In this 21st-century version, the folded sheet becomes a shared digital canvas, the parlor game becomes a hosted web app, and the next fragment is produced through a prompt-driven image-generation step. Users enter a room, take turns extending the image, and each generated move becomes part of a durable state machine.

The product is built around authority: who may act, what canvas state is canonical, which turn is live, whether credits have been debited, whether a step is idempotent, and how the system recovers if generation fails halfway through.

What Exquisite Is

EXQUISITE is intended to run as a hosted browser application backed by an API server, database, blob storage, and image-generation provider. A room owns a shared canvas. Members are ordered. The current player submits a prompt and direction, the system extends the image, and the room advances only after the database commit succeeds.

The current implementation includes:

• native account and session-cookie auth,
• FastAPI routes serving both the browser UI and JSON API behavior,
• Postgres-backed rooms, members, turns, credits, locks, and ledgers,
• deterministic canvas-growth geometry,
• blob-backed canvas storage,
• OpenAI and mock generation clients behind a provider interface,
• a browser UI served by the FastAPI application,
• admin/operator endpoints for beta operations and recovery workflows.

System Shape

The core design is intentionally simple:

browser web app
    -> FastAPI API
        -> Postgres for canonical state
        -> blob storage for canvas bytes
        -> generator provider for new image content

Postgres is the authority for users, rooms, turns, nonces, credits, step records, and lock state. Blob storage owns image bytes. The API coordinates transitions; it should not become a second source of truth.

That distinction matters because a generation step crosses several failure-prone boundaries:

• verify the authenticated user and room membership,
• verify turn ownership and nonce,
• debit credits,
• acquire a room lock,
• load the canonical canvas,
• run the generator,
• enforce deterministic geometry constraints,
• write the new canvas,
• commit or abort the step with auditable state.

Why imkerutils

The repository name is historical and still accurate at the implementation level. EXQUISITE grew out of imkerutils, a set of deterministic image-processing and tiling utilities for extracting, pasting, extending, and checking image regions.

Those utilities became the substrate for EXQUISITE's canvas mechanics. The product layer now lives mostly under imkerutils/exquisite, while the lower-level tiling helpers remain under imkerutils/tiling_utils.

Main Code Areas

imkerutils/exquisite/api_server contains the FastAPI application: auth routes, room routes, step execution endpoints, health checks, admin routes, request logging, and runtime validation.

imkerutils/exquisite/service contains business logic for users, sessions, rooms, credits, locks, step lifecycle control, and commit/abort behavior.

imkerutils/exquisite/geometry and imkerutils/exquisite/pipeline contain the deterministic image-growth logic: tile modes, overlap handling, reference-tile construction, KEEP-region enforcement, and session-oriented extension behavior.

imkerutils/exquisite/storage contains the blob-store abstraction and local filesystem storage backend.

imkerutils/exquisite/assets/ui contains the current browser UI.

imkerutils/tiling_utils contains the older reusable image-region utilities that EXQUISITE builds on.

Engineering Retrospective

For readers investigating how EXQUISITE was actually built, the most useful long-form record is EXQUISITE Engineering Retrospective: From Prototype to Beta Staging.

That report traces the Project Owner's path from proof-of-concept image-extension experiments through local rebuild, hosted beta staging, and the current application architecture. It is especially useful because it records technical problems solved during development, not just final code structure: prompt-only extension drift, mask/frontier/splice contracts, turn/credit/idempotency semantics, DB/blob/API authority boundaries, browser-grounded UI debugging, phase-closure discipline, and the human/LLM engineering workflow used to keep the work tethered to real repo, runtime, and deployment state.

Current Status

EXQUISITE is an active beta-stage product codebase, not a polished public release. The application is meant to be a hosted web app, and the current beta staging target is Render. The end-to-end product path is real and test-backed: users, sessions, rooms, turn order, canvas storage, generation providers, credits, locks, and recovery-oriented step execution are all represented in the codebase.

In other words, EXQUISITE is substantially implemented as an application, but it is not yet complete as a public, production-operated service. The remaining work is mostly scaling, deployment hardening, billing completion, admin model refinement, documentation curation, and confidence-building around live infrastructure.

Current reality:

• The core web-app flow is substantially implemented.
• Render is the current beta staging target.
• Production scaling and operations still need explicit hardening.
• Stripe/payment handling is not production-ready.
• The admin model is still staging-grade: admin/operator surfaces are early-stage, intentionally guarded, and not presented as production-ready access control.
• Some docs are internal continuity records rather than polished public docs.
• Public-release review is tracked under docs/audit.

Local Development

Install the project from a checkout:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Run the default test suite:

uv run pytest

Some API and service tests require a local Postgres database and EXQUISITE runtime environment variables.

Useful starting points:

• imkerutils/exquisite/README.md
• imkerutils/exquisite/docs/eng_cont/2026/summaries/super_reports/program_manager_beta_deployment_report.md
• docs/runbook_smoke.md
• docs/audit/imkerutils_public_release_security_audit_2026-05-27.md