POS Integrations

Every service is the same process: a FastAPI app whose lifespan starts, by role, a Kafka consumer and a scheduler. A service declares its routers, Kafka handlers and jobs; an environment variable decides which of them a container runs. Health probes, typed API errors, single-flight jobs and telemetry come from the runtime, so a new service is operable and instrumented by construction. Каждый сервис — один и тот же процесс: приложение FastAPI, в lifespan которого по ролям запускаются Kafka-консьюмер и планировщик. Сервис объявляет свои роутеры, обработчики Kafka и задачи, а переменная окружения решает, что из этого поднимет контейнер. Health-пробы, типизированные ошибки API, защиту задач от параллельного запуска и телеметрию даёт рантайм, поэтому новый сервис с первого дня эксплуатируется и наблюдается так же, как остальные.

The package layout is fixed too (entry points → services → infrastructure, dependencies pointing one way), so adding a service is a scaffold and a checklist. Структура пакета тоже зафиксирована (входные точки → сервисы → инфраструктура, зависимости в одну сторону), поэтому новый сервис — это шаблон и чек-лист.

app = ServiceApp(
    service_name=settings.SERVICE_NAME,
    lifespan=lifespan,                  # yields the deps every entry point shares
    routers=[v1_internal_router],
    kafka=KafkaConfig(
        topic_configs={
            TOPIC: HandlerConfig(handler=handle_event, retry_policy=[0.1, 0.5]),
        },
        group_id=settings.KAFKA_GROUP_ID,
    ),
    jobs=[Job('purge_old_rows', every=timedelta(hours=6), run=purge_old_rows)],
    readiness_checks=[check_postgres],
    job_lock=lambda deps: PostgresAdvisoryLock(deps.engine),
).build()

Why. aiokafka is a client, not an application: ordering, retries, dead letters, rebalances, shutdown and health checks are left to whoever writes the consumer. I wrote that part once, as a framework. A bot declares a handler and a retry policy per topic; the rest is the framework’s job. Зачем. aiokafka — это клиент, а не приложение: порядок, повторы, dead-letter-очередь, ребалансы, остановка и health-проверки остаются на том, кто пишет консьюмер. Я написал эту часть один раз, как фреймворк. Бот объявляет обработчик и политику повторов для топика, а остальное делает фреймворк.

How. One worker per partition gives strict order inside a partition and full concurrency across them. A failing handler retries on its policy, then the record goes to a dead-letter topic owned by that consumer group. The DLQ send is awaited before the offset commit, so a record is either in the DLQ or still unconsumed, never lost in between. Как. Один воркер на партицию даёт строгий порядок внутри партиции и полную конкурентность между ними. Упавший обработчик повторяется по своей политике, после чего запись уходит в dead-letter-топик, принадлежащий этой группе потребителей. Отправка в DLQ дожидается подтверждения брокера до коммита оффсета, поэтому запись либо уже в DLQ, либо ещё не вычитана — потеряться между этими состояниями она не может.

• A full partition queue pauses only that partition; the poll loop never blocks. Переполненная очередь партиции ставит на паузу только её; цикл опроса не блокируется никогда.
• A rebalance lets the record in flight finish, then commits only what was completed. При ребалансе обработка текущей записи доводится до конца, после чего коммитится только завершённое.
• Records too old to matter (a tap from an hour ago) are discarded, and every discard shows in logs and metrics. Записи, потерявшие смысл от времени (нажатие часовой давности), отбрасываются, и каждый такой случай виден в логах и метриках.
• A dead poll loop or a stuck rebalance fails the liveness probe, and the process restarts. Умерший цикл опроса или зависший ребаланс роняют liveness-пробу, и процесс перезапускается.

Why. Plain aiogram leaves every flow to decide when to send, edit or delete a message and how to match a pressed reply button. aiogram-dialog answers that with its own widget layer and implicit wiring: more than the bots needed, and harder to debug. aiogram_windows keeps aiogram’s own keyboards, media and middlewares and adds only the missing rule. Зачем. Чистый aiogram оставляет каждому сценарию самому решать, когда отправить, отредактировать или удалить сообщение и как сопоставить нажатую reply-кнопку. aiogram-dialog отвечает на это собственным слоем виджетов и неявным связыванием: ботам столько было не нужно, а отлаживать это труднее. aiogram_windows оставляет родные клавиатуры, медиа и middleware aiogram и добавляет только недостающее правило.

How. An FSM state is a window: a getter renders the screen, a handler reacts to the next update, and the engine then renders whatever state the handler left. There is one live screen per chat: inline screens are edited in place, reply-keyboard screens are sent anew, stale ones are cleaned up. Как. Состояние FSM — это окно: getter рисует экран, handler обрабатывает следующий апдейт, после чего движок рисует то состояние, в котором handler оставил диалог. В чате один живой экран: inline-экраны редактируются на месте, экраны с reply-клавиатурой отправляются заново, устаревшие убираются.

• Registration is explicit: Window(state, getter, handler), no decorators and no hidden wiring. Регистрация только явная: Window(state, getter, handler), без декораторов и скрытого связывания.
• A failed turn persists nothing, and a press that arrives in an expired state is replayed, not lost. Неудачный ход ничего не сохраняет, а нажатие, пришедшее в истёкшем состоянии, воспроизводится, а не теряется.
• It ships its own test kit: a recording bot and update factories. В комплекте свой тестовый набор: записывающий бот и фабрики апдейтов.

async def language_getter(manager: WindowManager) -> View:
    return View(text='Choose your language', reply_markup=language_keyboard())


async def language_handler(manager: WindowManager, button_id: str | None) -> None:
    if button_id is not None:                 # a language button was pressed
        manager.data['language'] = button_id
        manager.goto(Onboarding.ask_phone)


onboarding = WindowGroup(
    Window(Onboarding.ask_language, language_getter, language_handler),
    Window(Onboarding.ask_phone, phone_getter, phone_handler),
    name='onboarding',
)

The order event is written to an outbox table in the transaction that changes the order: a rollback leaves no event, and a commit always gets its event out. Events carry a full snapshot, are keyed by order id and are checked against a Schema Registry in BACKWARD mode. Consumers are written to see the same event twice. Событие заказа пишется в outbox-таблицу в той же транзакции, что меняет заказ: откат не оставляет события, а после коммита оно обязательно уйдёт. Событие несёт полный снимок заказа, ключом служит id заказа, а схема проверяется в Schema Registry в режиме BACKWARD. Потребители рассчитаны на то, что одно и то же событие придёт дважды.

No service imports another. OpenAPI schemas are committed next to the code, and every call between services goes through a typed client generated from them. The admin gateway is a transparent proxy: it signs the person in, resolves the tenant and forwards to the service that owns the data. It merges the services’ admin schemas into one document, from which the React panel generates its types, so a new admin endpoint never touches the gateway. Ни один сервис не импортирует другой. OpenAPI-схемы хранятся в репозитории рядом с кодом, и любой вызов между сервисами идёт через сгенерированный по ним типизированный клиент. Админ-шлюз — прозрачный прокси: он аутентифицирует человека, определяет тенанта и пересылает запрос сервису, которому принадлежат данные. Админ-схемы сервисов он склеивает в один документ, из которого React-панель генерирует свои типы, поэтому новый админ-эндпоинт не требует ни строчки в шлюзе.

Over 2,100 automated tests: about half of the Python code is tests. Service suites run against real Postgres, Kafka and Redis in testcontainers, with shared pytest plugins for faking neighbour services, asserting on Kafka and freezing time. Above them sits a full-flow suite: ten services in one pytest process, driven only through the Telegram webhook, the staff group and the Payme callback. Scenarios assert by translation key, so rewording a message breaks nothing and renaming a key fails loudly. Больше 2100 автотестов: примерно половина кода на Python — тесты. Тесты сервисов работают с настоящими Postgres, Kafka и Redis в testcontainers; общие pytest-плагины подменяют соседние сервисы, проверяют сообщения Kafka и замораживают время. Над ними — сквозной набор: десять сервисов в одном процессе pytest, а управлять ими можно только через вебхук Telegram, группу персонала и колбэк Payme. Сценарии проверяют сообщения по ключу перевода: переформулировка текста ничего не ломает, а переименование ключа сразу роняет тест.

user = make_user(language=Language.RU)
await flows.register_through_bot(user)        # /start, language, phone, the menu
await flows.start_order(user)
await flows.share_new_location(
    user, flows.NEAR_SPOT, resolved_address=fake_geocoding.expected_address,
)
await flows.choose_delivery(user, menu)
await flows.add_configured_item(user, menu.burger, choices=[('Sauce', ['Ketchup'])])
cart, order_id = await flows.checkout(user, operator, payment_method=PaymentMethod.CASH)
await flows.staff_accepts(staff_group, order_id, payment_pending=False)
await user.expect(
    'order_status_notification/order_{id}.awaiting_preparation', id=order_id,
)

One GitHub Actions run builds, tests, migrates and deploys any selection of services as matrix jobs. A red suite or a failed migration holds back only its own service, which keeps its previous image while the others ship. Migrations run before any restart and are additive by rule, so the previous image always works on the new schema. The deploy refuses to restart a service whose database is not at its image’s Alembic head, and rollback is one more workflow. Один запуск GitHub Actions собирает, тестирует, мигрирует и деплоит любой набор сервисов матричными джобами. Красные тесты или упавшая миграция задерживают только свой сервис: он остаётся на прежнем образе, пока остальные выкатываются. Миграции выполняются до любого рестарта и по правилу только добавляют, поэтому предыдущий образ всегда работает на новой схеме. Деплой откажется перезапускать сервис, чья база не на Alembic-head его образа, а откат — отдельный workflow.

A restaurant’s bot token and its payment credentials are not known at deploy time: the owner enters them in the admin panel while the system is running. The service that owns such a secret writes it to OpenBao and reads it from there. It never lands in a database row, an env file or an event. Токен бота ресторана и его платёжные реквизиты неизвестны в момент деплоя: владелец вводит их в админ-панели, когда система уже работает. Сервис, которому принадлежит такой секрет, пишет его в OpenBao и оттуда же читает. В строку базы, env-файл или событие он не попадает никогда.

• Each service signs in with its own AppRole and can read only its own class of paths. Каждый сервис входит со своим AppRole и читает только свой класс путей.
• Webhook secrets are derived, not stored: an HMAC of the tenant and a generation number under a versioned signing key. One tenant’s webhook can be revoked alone, the whole fleet’s by rotating the key. Секреты вебхуков не хранятся, а выводятся: это HMAC от тенанта и номера поколения на версионируемом ключе подписи. Вебхук одного тенанта можно отозвать отдельно, а всего парка — ротацией ключа.
• Admin passwords are hashed with argon2id; sessions are opaque tokens in Redis and can be revoked at once. Пароли администраторов хешируются argon2id, сессии — непрозрачные токены в Redis, которые отзываются мгновенно.

Production is a single VDS with 4 vCPU and 8 GB of RAM. Everything runs on it under Docker Compose: the eleven services, PostgreSQL, Kafka with its Schema Registry, Redis, MinIO, OpenBao, nginx and the whole telemetry stack. Продакшен — это один VDS с 4 vCPU и 8 ГБ памяти. Под Docker Compose на нём работает всё: одиннадцать сервисов, PostgreSQL, Kafka со Schema Registry, Redis, MinIO, OpenBao, nginx и весь стек телеметрии.

No Kubernetes, no managed database and no managed broker. That is a deliberate choice to cut costs: the load fits one machine, and everything the product needs from an orchestrator at this scale (health checks, restarts, one-service deploys, rollback) is covered by Compose and the pipeline above. The price is a single failure domain, accepted at this scale. Ни Kubernetes, ни управляемой базы, ни управляемого брокера. Это сознательное решение ради экономии: нагрузка помещается на одну машину, а всё, что продукту на таком масштабе нужно от оркестратора (health-проверки, рестарты, выкатка одного сервиса, откат), закрывают Compose и конвейер выше. Цена — единая точка отказа, на таком масштабе она принята осознанно.

• Seven Compose fragments behind one entry point; Postgres, Redis, Kafka, the telemetry stack and the edge each sit on their own network. Семь фрагментов Compose за одной точкой входа; Postgres, Redis, Kafka, стек телеметрии и входной nginx живут каждый в своей сети.
• Only nginx faces the internet. Grafana is reached through an SSH tunnel. В интернет смотрит только nginx. До Grafana можно добраться только через SSH-туннель.
• Images are built in CI, tagged by commit and pulled from the registry. A deploy recreates exactly one container and records every attempt, so a rollback knows where to go back to. Образы собираются в CI, помечаются коммитом и забираются из реестра. Деплой пересоздаёт ровно один контейнер и записывает каждую попытку, поэтому откат знает, куда возвращаться.
• The dev stack mirrors production: the same Compose fragments, and a self-hosted tunnel gives it stable public hostnames for Telegram and Payme webhooks. Dev-стенд повторяет продакшен: те же фрагменты Compose, а собственный туннель даёт ему постоянные публичные адреса для вебхуков Telegram и Payme.
• Ten runbooks cover the rest: provisioning, TLS, the secret store, alerting, webhooks, smoke tests. Остальное описано в десяти ранбуках: подготовка сервера, TLS, хранилище секретов, алертинг, вебхуки, смоук-тесты.
• The door stays open: services take their role from an environment variable and expose startup, liveness and readiness probes, so moving to an orchestrator later changes the deployment, not the code. Дверь остаётся открытой: сервис берёт роль из переменной окружения и отдаёт startup-, liveness- и readiness-пробы, так что переезд на оркестратор изменит развёртывание, а не код.