pastilhas
4bff81ab2a
PLUGIN.md is the record: what moved, what changed on the way (authenticated image serving, the secret-store OpenAI key fallback, provider_settings left behind), what stays running untouched (the standalone service the mobile app still talks to), why there is no db/ directory, and what verification did and deliberately did not cover. README.md is the marketplace shop window — what it does, what it needs (its own Postgres database, an OpenAI key), and an honest limitations section: two Ateliers can exist side by side right now, and there is no per-user data model yet.
74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# Atelier
|
|
|
|
Image generation for an Officer server: a provider-shaped API over OpenAI's image endpoints, storing
|
|
what it makes so every image has a durable reference — a gallery you can browse, collections you can
|
|
organise, and a job an agent can poll rather than block on.
|
|
|
|
Atelier was a standalone service before this plugin existed
|
|
(`~/officer-dev/dockers/officer-atelier`, still running as `officer-atelier`, still what the mobile app
|
|
talks to). This plugin is a fresh extraction into Officer, not a replacement for it yet — see
|
|
`PLUGIN.md` before assuming the two are interchangeable.
|
|
|
|
## What you get
|
|
|
|
- **Generate** — a prompt, a model, size/quality/background, and a job you watch settle. `n` images
|
|
become `n` independently-tracked rows, so one failure out of four does not discard the three that
|
|
worked.
|
|
- **Gallery** — everything generated, newest first, with a lightbox: pan, zoom about the cursor,
|
|
checkerboard/dark/light backdrops for telling a transparent background from an opaque one that only
|
|
looks it.
|
|
- **Collections** — named sets of images. A generation request can name one by name and it is created on
|
|
first use; the gallery and the lightbox can file an image into one after the fact.
|
|
- **A provider-shaped backend.** "OpenAI" is code, written once; a *provider* is a row — which model,
|
|
whose key, on or off — and several can share one adapter. Today OpenAI is the only adapter; the point
|
|
of the shape is that a second one is a new file, not a redesign.
|
|
- **An OpenAI-compatible job API**, for agents. `POST /api/atelier/images/generations` accepts OpenAI's
|
|
request body verbatim and answers `202` with a job id rather than blocking for the length of the
|
|
generation — the caller polls `GET /api/atelier/images/generations/:id`, optionally with `?wait=` to
|
|
long-poll instead of retrying in a loop.
|
|
|
|
## Requirements
|
|
|
|
- An Officer server, version 1.0.0 or later.
|
|
- A **separate Postgres database**, and its own environment variable: `ATELIER_POSTGRES_URL`. Atelier's
|
|
tables (`generations`, `collections`, `collection_items`, `providers`) do not live in `officer_db` —
|
|
see `PLUGIN.md` for why, and set this before installing. There is no default.
|
|
- An OpenAI API key, set with `bun run secret:set atelier-openai-key`, or configured per-provider in
|
|
Settings → Integrations → Atelier, or (for an install that predates the secret store) as
|
|
`OPENAI_API_KEY` in `.env`.
|
|
|
|
## Install
|
|
|
|
From the Officer marketplace: find Atelier, install. That mounts `/api/atelier` and `/atelier`, starts
|
|
the `officer-atelier` sidecar under PM2, and connects it to whatever `ATELIER_POSTGRES_URL` points at —
|
|
which has to already have the schema (the standalone repo's own `bun db:push` creates it; this plugin
|
|
does not run migrations against a database it does not own the schema of).
|
|
|
|
Uninstalling stops the sidecar and unmounts the route. **It never touches your database** — Atelier's
|
|
tables and rows are not this plugin's to drop, since it does not own the schema push for them either.
|
|
|
|
## Permissions
|
|
|
|
One permission, `atelier`, grantable per role at read or write.
|
|
|
|
- **Read** lets an account use Generate, browse the Gallery and Collections, and see which providers are
|
|
configured (never a key, in any form — not even masked).
|
|
- **Write** additionally lets an account add, edit or delete providers, including their API keys. A
|
|
provider's key authorises real spend on someone's OpenAI account, so treat write here the way you
|
|
would treat write on any billing-adjacent surface.
|
|
|
|
Providers is not a panel — it is a platform Settings screen (Settings → Integrations → Atelier), because
|
|
it is owner-level configuration rather than a working view. See `PLUGIN.md` for why.
|
|
|
|
## Limitations, honestly
|
|
|
|
- **Two Ateliers can exist at once.** This plugin and the standalone service are independent — installing
|
|
this one does not migrate the standalone one's data, stop it, or repoint the mobile app. See
|
|
`PLUGIN.md`.
|
|
- **No per-user data.** Every account with `read` sees the same gallery and the same collections — there
|
|
is no ownership model yet, the same simple shape offscale shipped with first.
|
|
- **The database is separate from `officer_db`**, which means Atelier's tables are not covered by
|
|
`bun db:push`, are not part of the platform's usual backup story unless you back up the second
|
|
database too, and need their own connection string. Migrating them in is real, tracked follow-up work
|
|
— see `PLUGIN.md`.
|