api, bot, and worker — sharing one PostgreSQL
database and one Valkey instance, plus one Next.js application that serves both the customer account
and the operator workspace. The split is about failure isolation, not scale: a batch of four hundred
subscription changes must not be tied to the lifetime of the HTTP request that started it, and
automatic renewals — the only place money moves with nobody watching — run where no request can
cancel them.
Who each surface is for
The three
/v1 prefixes are kept apart deliberately. /v1/panel is a browser surface and therefore
carries cookie, CSRF, and permission checks; /v1/admin is a machine surface with one long-lived
token and no cookies; /v1/account belongs to a customer and can never reach an operator route. Two
more routes are public by necessity: GET /v1/catalog/plans, and
POST /v1/payments/webhooks/{provider}, whose authenticity comes from the provider’s signature
rather than from a credential on the route.
A customer does not choose between the chat and the browser. It is one product with two surfaces: a
cart started in a chat is the cart the browser shows, and a support reply read on the web stops
being unread in Telegram.
Start here
Quickstart
Bring the Compose stack up, redeem the one-time setup token, create the first owner, and prove
the installation is healthy.
Your first sale
From an empty installation to a paid subscription: a plan, a priced version, a payment provider,
the bot, and a test purchase.
Configuration reference
Every environment variable, its default, which process reads it, and what it changes.
How it compares
Where Omniflow differs from Bedolaga and RemnaCore.
What a customer can do
Telegram bot
Every command, screen, and flow: plans, checkout, orders, wallet, shop, gifts, support, and
settings, in Russian and English.
Web panel
Sign-in, dashboard, checkout, shop, support, referrals, and a customer’s own data at
/account.Connecting a device
Per-platform instructions, client deep links, the QR code, the device list, and link rotation.
Notifications and consent
Notification classes, marketing consent, quiet hours, frequency caps, and the news inbox.
Privacy
What a customer can export, how deletion is requested, and what Omniflow never shows or stores.
Selling and money
Catalogue and promotions
Plans, immutable priced versions, localisation, publishing, trials, promo codes, and personal
offers.
Add-ons and the configurator
Extra traffic, device slots, and squads — at checkout and mid-period.
Subscriptions
Entitlements, concurrency, upgrade and downgrade arithmetic, grace, expiry, and recovery.
Orders and payments
The order state machine, provider handoff, webhook idempotency, classifications, and refunds.
Wallet and ledger
The double-entry model, account types, expiring credit, and operator adjustments.
Top-up and saved carts
Customer-initiated top-up, its limits and rolling window, and a cart that re-prices before it
buys.
Automatic renewal
Saved payment methods, the consent record, the dunning schedule, and failed charges.
Fulfillment
Provisioning into Remnawave: operations, idempotency keys, retries, drift, and reconciliation.
Gifts and digital goods
Buying for somebody else, and selling Telegram Premium and Stars beside VPN access.
Campaigns
Audience segments whose definition is rendered beside their live count, and sends that report
suppression honestly.
Referrals and loyalty
Attribution, qualification, rewards granted exactly once, and tier evaluation.
Referral communication
What a referrer is told, what an invitee is told, and what neither is shown about the other.
Customers and imports
The Remnawave import pipeline — preview, apply, resume — and the CSV export.
Financial invariants
The constraints the schema enforces so money cannot be created, lost, or double-counted.
Integrations
Remnawave
The adapter, the pinned API version, every call Omniflow makes, health, and drift.
Payment providers
Telegram Stars, CryptoBot, YooKassa, and manual approval — what each settles and what each
cannot do.
Telegram
BotFather, long polling versus webhook, the Mini App domain, and the operator group.
OIDC
Single sign-on for operators, and sign-in providers for customers.
The admin API
Integrating with
/v1/admin: the token, idempotency keys, cursors, problem documents, request
IDs, and rate limits.Extension policy
Which surfaces are public and stable, what can be extended by configuration alone, and what
deliberately cannot be extended at all.
Running it
Deployment
Compose topology, volumes, image tags, migrations, upgrades, and rollback.
Compatibility and upgrades
The supported version matrix, signed images, the upgrade window, and the deprecation policy.
Reverse proxy
Caddy and Traefik examples, TLS, body limits, and keeping operational endpoints off the public
host.
Admin panel
The operator workspace screen by screen, the permission catalogue, and the six built-in roles.
Admin operations
The day-to-day runbooks an operator performs from the panel.
Installation settings
What the settings screens store, and which of it actually takes effect at runtime.
Support desk
Queues, assignment, priority, tags, internal notes, canned responses, merge, and the workload
report.
Required channels
Requiring Telegram channel membership before a purchase completes.
Risk controls
Blocklist sources stored as salted digests, anomaly rules, and decisions a person always makes.
Observability
The probes, the metrics that are actually written, structured logs, and secret redaction.
Maintenance mode
Blocking new purchases and holding provisioning without disturbing money already taken.
Jobs and queues
The durable queue, the job kinds, dead letters, retries, periodic passes, and retention sweeps.
Operator notifications
The Telegram group, one forum topic per event kind, and why every notice is content-free.
Backup and restore
Encrypted
pg_dump output, verification on every backup, restore, and the standalone decrypt
filter.Security
Credentials, sessions, secrets, transport, rate limits, and the privacy boundaries.
Troubleshooting
Symptoms, what to look at first, and what each classification means.
Anonymous telemetry
The exact payload that is sent, how to inspect it, and how to switch it off.
Privacy
What Omniflow holds, why, for how long, and where a documented retention window isn’t enforced yet.
Reliability and operations
SLIs, importable dashboards and alerts, what’s bounded and reconciled, graceful degradation, and capacity guidance.
AI privacy
What the redaction gateway strips, and the data-use preview shown before anything is enabled.
AI providers
The three adapters, pointing one at a model on your own hardware, per-feature routing, and
what each state on the screen means.
AI governance
Providers, per-feature enablement, budgets at four scopes, and the decision export.
MCP
The server registry, allowlisted tools, and the rules both directions are held to.
Architecture and contributing
Architecture overview
The three processes, the request paths, and why a modular monolith.
Data ownership
The Remnawave boundary: what lives where, and what happens when the two disagree.
Technology
The stack, and the reason each piece is in it.
Threat model
What’s at risk on each surface, the mitigation that actually exists, and the residual risk where one remains.
Development
Workspace setup, the generators, running the stack, and the checks CI will run anyway.
Database
The schema, Atlas migrations, sqlc, and the rules a migration must follow.
Testing
Unit, integration, and browser coverage, and what each layer is responsible for proving.
Documentation
Authoring, validating, and keeping the Russian tree in step with the English one.
Architecture decisions
The records that constrain how Omniflow is built, what each costs, and when to reopen one.
Release process
How a merged commit becomes a version, and what the release workflow gates and publishes.
What Omniflow deliberately does not do
- It does not manage Xray, and it does not read Remnawave’s database. Every VPN-side change is an authenticated call to the Remnawave API, made by the fulfillment pipeline so that it carries an idempotency key, a retry policy, and a history. See Data ownership.
- It does not show an operator a subscription link, a hardware identifier, or a raw provider payload. A device is named by an opaque handle the server resolves back; a fulfillment history returns a status, a classification, and a correlation ID and nothing else.
- It does not delete financial, audit, consent, identity, or entitlement history. Retention sweeps remove disposable operational data only, and a wallet correction is a compensating entry rather than an edit. See Financial invariants.
- It does not reconfigure itself from the panel. Runtime configuration is environment variables, read once at startup by each process; the panel’s installation-settings sections store what an operator types, and no process reads those documents back while running. See Installation settings and Configuration.
- It performs a model call only when an operator presses “test connection”. That button is the whole of the AI runtime in this build: it opens the stored credential, asks the provider for one word, and records whether it answered. Everything else the AI and MCP surfaces do — registering providers, enabling features one at a time, setting budgets, allowlisting tools — is stored and not yet consumed: no feature makes a call, and no process constructs an MCP client. See AI providers and AI governance.
- It does not run more than one bot. Telegram delivers updates to one consumer, so the
botruns as exactly one instance. Theapiand theworkertake any number of replicas: the periodic passes — order and payment maintenance, sweeps, renewals, campaigns, retention, backups — are River jobs that run once per interval across the installation. See Deployment.