How to read this section
Who is this for
Section titled “Who is this for”Anyone who opens the architecture section for the first time: a developer taking over the code, an operator who wants to know what runs where, or a reviewer checking a design decision.
- The section follows the C4 model: context (level 1), containers (level 2), components (level 3). In place of C4’s code-level diagrams, the sidebar’s fourth level (“L4 · Key flows”) holds step-by-step flows, and every component table links straight to the source file.
- Read top-down: System context → Containers → the component page of the container you work on.
- Behaviour over time lives in two places: State machines (what statuses exist and who changes them) and the flow pages (who calls whom, step by step).
- Data model lists every table and column, including which columns hold personal data.
- Every claim on these pages was checked against the code at the commit named in the Last verified line. Where the in-repo notes disagree with the code, the pages follow the code.
The system in one paragraph
Section titled “The system in one paragraph”AI Sticker Pack is an event activation. A guest taps Start on a tablet (the kiosk), scans a QR code that opens a Telegram bot, gives consent in the bot, picks an outfit on the tablet and is photographed by the tablet camera. The tablet is free for the next guest at once. In the background a worker sends the selfie to an image model (Gemini by default, OpenAI as fallback), cuts the result into 12 stickers, creates a personal Telegram sticker set and — only after checking that the set really opens — sends the guest a link in the bot. Everything on the server is two Python processes over one SQLite file, behind Caddy. A separate Next.js landing page on Vercel collects requests from event organisers and hands them to the same server, where the bot posts them into a Telegram group as cards with status buttons.
C4 levels used here
Section titled “C4 levels used here”| Level | Question it answers | Page |
|---|---|---|
| 1 — System context | Who uses the system and which outside systems does it depend on? | System context |
| 2 — Containers | Which separately running things exist, on which ports, and who opens each connection? | Containers |
| 3 — Components | Which modules make up one container, and which file holds each? | The six pages under Components below |
| 4 — Key flows | In what order do the parts talk during one scenario? | The eight flow pages below |
A container in C4 is anything that runs or stores data on its own: a process, a browser page, a database file. It is not a Docker container — this project does not use Docker.
Map of the section
Section titled “Map of the section”Structure
Section titled “Structure”| Page | What you get |
|---|---|
| System context | People, external systems, what the system does and does not do |
| Containers | Every running part: technology, port, protocol, who initiates each connection |
| Component: landing | The Next.js site: locale routing, request form, delivery with fallback |
| Component: sticker-api | FastAPI process: kiosk endpoints, admin panel, POST /leads |
| Component: sticker-bot | The bot process: routers, worker loop, sweeper, cleanup, leads loop, shutdown |
| Component: generation pipeline | From a queued job to 12 sticker files: render modes, sheet layouts, quality checks, limits |
| Component: kiosk | The tablet page: screens, timers, camera, the endpoints it calls |
| Component: storage and infrastructure | SQLite and migrations, file storage with TTL, Caddy, systemd, backups, firewall |
Behaviour and data
Section titled “Behaviour and data”| Page | What you get |
|---|---|
| State machines | Session, job and lead statuses with a transition table: trigger, actor, code location |
| Data model | ER diagram and a per-table column reference with personal-data flags |
| Flow: guest session | Start → QR → consent → outfit → photo |
| Flow: generation | What the worker does with one job |
| Flow: pack delivery | Verifying the sticker set and sending the link exactly once |
| Flow: lead submission | Landing form → POST /leads → card in the group |
| Flow: lead status | Status buttons and group commands |
| Flow: reminders and digest | The once-a-minute housekeeping of the leads module |
| Flow: data erasure | Photo TTL, appearance data, lead anonymisation |
| Flow: deploy and rollback | How code reaches the server |
Cross-cutting concerns and decisions
Section titled “Cross-cutting concerns and decisions”| Page | What you get |
|---|---|
| Security | Trust boundaries, authentication, rate limits |
| Privacy | What personal data exists and how long it lives |
| Reliability | Retries, exactly-once delivery, restart behaviour |
| Observability | Logs, alerts, timing lines |
| Performance | Concurrency limits and where time goes |
| Internationalisation | Languages of the landing, the kiosk and the bot |
| Decisions | Architecture decision records |
Conventions on these pages
Section titled “Conventions on these pages”- Diagrams are Mermaid. Boxes are containers or components; arrows point from the side that opens the connection.
- Source links go to the
mainbranch on GitHub. File paths are relative to the repository root. sticker-apiandsticker-botare the names of the two systemd units and are used as the names of the two server processes everywhere.- Russian strings that the product shows to people are quoted verbatim with an English gloss.
Where to go next
Section titled “Where to go next”- System context — start here if you have never seen the product.
- Containers — start here if you need ports, processes and connection directions.
- Glossary — terms such as kiosk, pack, job, lead, anchor.
Last verified: 2026-11-13 against ai-sticker-pack@b715418 and ai-stickers-landing@e350ff5.