Glossary
Who is this for
Section titled “Who is this for”Anyone who meets an unfamiliar word on this site, in the logs or in the code.
- Kiosk → session → job → pack is the guest chain; lead → outbox → card is the sales chain.
- Sheet, anchor, likeness and consistency are generation terms; you need them only for the generation pipeline.
- Terms are listed alphabetically inside each group.
Guest flow
Section titled “Guest flow”| Term | Meaning |
|---|---|
| Station | The physical point at the venue: a tablet on a stand, power, internet. One station was used in the pilot. |
| Kiosk | The web page the tablet shows in the browser’s kiosk mode (/kiosk/ on the API domain). Plain HTML and JavaScript, no build step. |
| Session | One guest’s pass through the kiosk, identified by a random token carried in the QR code. Statuses: idle → linked → consented → template_chosen → photo_taken, or expired. See State machines. |
| Deep link | The t.me/<bot_username>?start=<token> link encoded in the QR code. Opening it starts the bot with the session token. |
| Consent | The guest’s tap on Agree in the bot. It moves the session to consented; nothing involving the camera is possible before it. |
| Outfit | What the character wears on the stickers. The guest picks one of six cards on the tablet. In code an outfit is a catalogue entry with a text description that goes into the prompt. |
| Template | The historical name of a catalogue entry (template_id). In the older composite mode a template is a pre-drawn body image the AI-drawn head is placed on. Today “template” and “outfit” refer to the same catalogue row. |
| Burst | The series of frames the tablet shoots; it uploads the best one. |
| Pack limit | The rule “one pack per Telegram account” (also called anti-duplicate). An admin can raise the limit for one account by one. |
| Notice | The reason a session was closed by the pack limit (pack_ready or pack_in_progress); the kiosk shows a friendly screen instead of an error. |
| Closed reason | Why the tablet abandoned a session: idle_timeout, qr_timeout, cancel, staff_reset, camera_error, kiosk_reset. |
| Staff reset | Holding the top-left corner of the kiosk for three seconds returns it to the idle screen. |
Generation
Section titled “Generation”| Term | Meaning |
|---|---|
| Job | One generation task for one photo. Statuses: queued → processing → delivering → done or failed. |
| Worker | The loop inside the bot process that takes jobs from the queue. WORKER_SLOTS jobs run in parallel. |
| Queue | Jobs with status queued in the SQLite jobs table. There is no separate message broker. |
| Render mode | How stickers are produced. figure: the AI draws the whole bust figure. composite: the AI draws heads only and code places them on a body template; kept as a fallback. |
| Sheet | One AI-generated image containing several figures on a green background. The default layout 3x4 means three sheets of four figures. |
| Layout guide | An empty grid image sent with the prompt so the model keeps figures inside cells. |
| Chroma key | Removing the flat green background (#00FF00) in code to get a transparent figure. |
| Cell | One slot of the sheet grid. Cutting is done cell by cell. |
| Appearance passport | A strict JSON description of the guest (hair, skin, facial hair, age band, face box) produced by a cheap vision model from the selfie. It feeds the prompt locks and the quality check. It is cleared when the job ends. |
| Locks | Blocks of prompt text that pin an attribute across all stickers: IDENTITY LOCK, HAIR LOCK, FACE LOCK, AGE LOCK, SKIN LOCK, OUTFIT LOCK, COLOR LOCK, HARD LOCKS. |
| Anchor | A single stylised portrait of the guest generated first in consistency mode. All sheets use it as the main reference, so the 12 stickers show the same character. |
| Consistency | CONSISTENCY_MODE: anchor portrait, parallel sheets, skin-tone normalisation, a pack-level quality check, targeted regeneration of outliers. Goal: identical appearance across the 12 stickers. |
| Likeness | LIKENESS_MODE: how strongly the face follows the selfie. classic uses the selfie and a face crop as the only face source, with no anchor. hybrid is classic plus colour consistency enforced by code. Empty means consistency mode decides. |
| QC / QA | Automatic checks: sheet validity (figure count, grid, edge contact), identity check by a vision model, pack-level outlier check. |
| Outlier | A sticker the pack-level check marks as different from the rest (hair, skin, face shape, facial hair). |
| Regeneration | Redrawing one figure as a single image when it is an outlier, touches the sheet edge, is missing or has a flat side cut. Limited by CONSISTENCY_MAX_REGEN. |
| Edge defect / flat cut | A figure cut by the sheet border, or an arm cut by a straight vertical line. Both trigger regeneration. |
| ΔE | Colour distance in LAB space, used to compare skin and hair tones. |
| Despill | Removing the green fringe left by the chroma key along the figure’s edge. |
| Die-cut outline | The white sticker border drawn by code around each figure. |
| Provider | An AI vendor. PRIMARY_AI_PROVIDER is tried first, FALLBACK_AI_PROVIDER second. |
| Fallback provider | The second AI vendor used when the first fails. Configured but currently without a key — see Known gaps. Not the same as the fallback channel of the leads module; sales never mentions this one to clients. |
| Stage | A named step of a job in the cost and timing accounting: passport, anchor, anchor_verify, sheet, regen, qa_pack, qa_regen and others. |
| RPD | Requests per day — the provider’s daily image quota. The day is counted in Pacific time. |
Delivery
Section titled “Delivery”| Term | Meaning |
|---|---|
| Pack | A Telegram sticker set of 12 stickers created by the bot for one guest. |
| Pack name | The technical name pack<N>_<telegram_user_id>_by_<bot_username>; the link is t.me/addstickers/<pack name>. Names are never deleted or reused. |
| Delivering | The job status between “pack created” and “link sent”. The link goes out only after two independent checks pass. |
| Sweeper | A loop that enforces delivery deadlines every 20 seconds: a delay notice after 5 minutes, failure after 15. |
| Delay notice | The single “still polishing” message a guest gets if the link is not ready after 5 minutes. |
| Term | Meaning |
|---|---|
| Lead | A request from the landing page form, stored in the leads table. Shown in the group as #stickers_<id>. |
| Leads server | The POST /leads endpoint of the product API. |
| Request id | A UUID the form creates when it opens. A retry with the same id never creates a second lead. |
| Outbox | The pattern “store first, publish later”: a lead with an empty published_at is waiting to be posted; a loop in the bot retries until it succeeds. |
| Card | The Telegram message in the sales group that shows a lead, with status buttons. |
| Status | new, in_work, contacted, deal, refused, spam. The five working statuses can follow each other in any order; nothing returns a lead to new. Every press is recorded. |
| Lead admin | A Telegram user listed in LEADS_ADMIN_IDS. Only lead admins can press buttons and call /stickers_* commands. |
| Repeat | A second request from the same Telegram username or phone within 24 hours. It updates the existing card instead of creating a new lead. |
| Fallback channel | The landing page’s direct sendMessage to the group when the leads server does not answer. Marked with a warning line; not stored in the database. Unrelated to the fallback provider of the generation pipeline. |
| Reminder | One ping on a card that stayed new for two hours, sent on weekdays 09:00–21:00 Tashkent time. |
| Digest | The daily 10:00 Tashkent summary in the group. |
| Anonymisation / erasure | Replacing a lead’s personal fields with empty values, on schedule or on request (/stickers_forget). Statistics stay. |
| Prefix | stickers_ — every command, callback and hashtag of this product in the shared group starts with it, because bots of other products live in the same group. |
Operations
Section titled “Operations”| Term | Meaning |
|---|---|
sticker-api |
The systemd service running the FastAPI application (kiosk API, admin panel, leads endpoint). |
sticker-bot |
The systemd service running the bot process: polling, worker, sweeper, cleanup, leads loop. Exactly one instance. |
| Droplet | The DigitalOcean virtual server. It is shared with a second, unrelated project. |
| Caddy | The web server in front of the API: TLS certificates and reverse proxy. |
| Maintenance mode | A pause for guests: the bot answers “maintenance”, the kiosk starts no sessions, the worker takes no jobs. Sources: env, admin (/pause), auto (provider out of money). |
| Auto-pause | Maintenance mode switched on automatically when the AI provider answers 402 “no credits”. |
| Event mode | EVENT_MODE=1: paid developer tools refuse to run on the production AI key. |
| Admin panel | The password-protected page /admin on the API domain: spend, queue, guests, retry and reset actions. |
| TTL | Time to live of guest files: PHOTO_TTL_HOURS, at most 72. |
| Instance lock | A lock file that stops a second bot process from starting with the same data directory. |
| Snapshot | A DigitalOcean image of the whole droplet, taken manually before an event. |
Landing page
Section titled “Landing page”| Term | Meaning |
|---|---|
| Hero scene | The animated tablet-and-phone demonstration at the top of the landing page. All of it is mock-ups drawn in code. |
| Showcase | The section where a visitor switches between six demo people and sees their 12 stickers. |
| Demo people | Six fictional, generated faces used for landing assets. No real third party’s face is ever used. |
| Dictionary | A per-language file with every visible string of the landing page. |
| Audit / shots / film | The landing page’s own verification scripts: structural checks, screenshots, scroll recording. |
Where to go next
Section titled “Where to go next”- Paths by role — pick your reading order.
- State machines — every status and transition.
- Generation pipeline — the generation terms in context.
Last verified: 2026-11-13 against ai-sticker-pack@b715418 and ai-stickers-landing@e350ff5.