> ## Documentation Index
> Fetch the complete documentation index at: https://omniflow-vpn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Omniflow

> What Omniflow is, who each of its four surfaces serves, and where every feature is documented

Omniflow is an open-source commerce, support, and marketing platform for a VPN service that already
runs on [Remnawave](https://omniflow-vpn.mintlify.site/integrations/remnawave.md). Remnawave stays authoritative for VPN users, traffic,
devices, access links, nodes, squads, and Xray state. Omniflow owns everything a business needs
around that: customer identity, a versioned catalogue, orders, payments, a double-entry wallet,
entitlements, durable provisioning, support, campaigns, referrals, loyalty, operator access control,
and an append-only audit trail. It never connects to Remnawave's database and never manages an Xray
process.

It is one Go module with three entrypoints — `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

| Surface | Who uses it | Where it lives | How a caller is authenticated |
| - | - | - | - |
| Telegram bot | A customer | A private chat with your bot | The Telegram account behind the update |
| Customer web panel | A customer | `/account`, backed by `/v1/account` | Session cookie plus CSRF token |
| Operator panel | An operator | `/admin`, backed by `/v1/panel` | Session cookie, CSRF, TOTP or a passkey, and 27 RBAC permissions |
| Bearer-token API | Your own code, and the bot's `/ops` tooling | `/v1/admin` | `Authorization: Bearer <APP_OPERATOR_TOKEN>` |

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](https://omniflow-vpn.mintlify.site/getting-started/quickstart.md)**
>
> Bring the Compose stack up, redeem the one-time setup token, create the first owner, and prove
> the installation is healthy.

> **[Your first sale](https://omniflow-vpn.mintlify.site/getting-started/first-sale.md)**
>
> From an empty installation to a paid subscription: a plan, a priced version, a payment provider,
> the bot, and a test purchase.

> **[Configuration reference](https://omniflow-vpn.mintlify.site/getting-started/configuration.md)**
>
> Every environment variable, its default, which process reads it, and what it changes.

> **[How it compares](https://omniflow-vpn.mintlify.site/comparison.md)**
>
> Where Omniflow differs from Bedolaga and RemnaCore.

## What a customer can do

> **[Telegram bot](https://omniflow-vpn.mintlify.site/customer/telegram-bot.md)**
>
> Every command, screen, and flow: plans, checkout, orders, wallet, shop, gifts, support, and
> settings, in Russian and English.

> **[Web panel](https://omniflow-vpn.mintlify.site/customer/web-panel.md)**
>
> Sign-in, dashboard, checkout, shop, support, referrals, and a customer's own data at `/account`.

> **[Connecting a device](https://omniflow-vpn.mintlify.site/customer/connection.md)**
>
> Per-platform instructions, client deep links, the QR code, the device list, and link rotation.

> **[Notifications and consent](https://omniflow-vpn.mintlify.site/customer/notifications.md)**
>
> Notification classes, marketing consent, quiet hours, frequency caps, and the news inbox.

> **[Privacy](https://omniflow-vpn.mintlify.site/customer/privacy.md)**
>
> What a customer can export, how deletion is requested, and what Omniflow never shows or stores.

## Selling and money

> **[Catalogue and promotions](https://omniflow-vpn.mintlify.site/commerce/catalog-promotions.md)**
>
> Plans, immutable priced versions, localisation, publishing, trials, promo codes, and personal
> offers.

> **[Add-ons and the configurator](https://omniflow-vpn.mintlify.site/commerce/addons-configurator.md)**
>
> Extra traffic, device slots, and squads — at checkout and mid-period.

> **[Subscriptions](https://omniflow-vpn.mintlify.site/commerce/subscriptions.md)**
>
> Entitlements, concurrency, upgrade and downgrade arithmetic, grace, expiry, and recovery.

> **[Orders and payments](https://omniflow-vpn.mintlify.site/commerce/orders-payments.md)**
>
> The order state machine, provider handoff, webhook idempotency, classifications, and refunds.

> **[Wallet and ledger](https://omniflow-vpn.mintlify.site/commerce/wallet-ledger.md)**
>
> The double-entry model, account types, expiring credit, and operator adjustments.

> **[Top-up and saved carts](https://omniflow-vpn.mintlify.site/commerce/wallet-topup-cart.md)**
>
> Customer-initiated top-up, its limits and rolling window, and a cart that re-prices before it
> buys.

> **[Automatic renewal](https://omniflow-vpn.mintlify.site/commerce/recurring-payments.md)**
>
> Saved payment methods, the consent record, the dunning schedule, and failed charges.

> **[Fulfillment](https://omniflow-vpn.mintlify.site/commerce/fulfillment.md)**
>
> Provisioning into Remnawave: operations, idempotency keys, retries, drift, and reconciliation.

> **[Gifts and digital goods](https://omniflow-vpn.mintlify.site/commerce/gifts-and-goods.md)**
>
> Buying for somebody else, and selling Telegram Premium and Stars beside VPN access.

> **[Campaigns](https://omniflow-vpn.mintlify.site/commerce/campaigns.md)**
>
> Audience segments whose definition is rendered beside their live count, and sends that report
> suppression honestly.

> **[Referrals and loyalty](https://omniflow-vpn.mintlify.site/commerce/referrals-loyalty.md)**
>
> Attribution, qualification, rewards granted exactly once, and tier evaluation.

> **[Referral communication](https://omniflow-vpn.mintlify.site/commerce/referrals-communication.md)**
>
> What a referrer is told, what an invitee is told, and what neither is shown about the other.

> **[Customers and imports](https://omniflow-vpn.mintlify.site/commerce/customers-imports.md)**
>
> The Remnawave import pipeline — preview, apply, resume — and the CSV export.

> **[Financial invariants](https://omniflow-vpn.mintlify.site/commerce/financial-invariants.md)**
>
> The constraints the schema enforces so money cannot be created, lost, or double-counted.

## Integrations

> **[Remnawave](https://omniflow-vpn.mintlify.site/integrations/remnawave.md)**
>
> The adapter, the pinned API version, every call Omniflow makes, health, and drift.

> **[Payment providers](https://omniflow-vpn.mintlify.site/integrations/payments.md)**
>
> Telegram Stars, CryptoBot, YooKassa, and manual approval — what each settles and what each
> cannot do.

> **[Telegram](https://omniflow-vpn.mintlify.site/integrations/telegram.md)**
>
> BotFather, long polling versus webhook, the Mini App domain, and the operator group.

> **[OIDC](https://omniflow-vpn.mintlify.site/integrations/oidc.md)**
>
> Single sign-on for operators, and sign-in providers for customers.

> **[The admin API](https://omniflow-vpn.mintlify.site/integrations/api.md)**
>
> Integrating with `/v1/admin`: the token, idempotency keys, cursors, problem documents, request
> IDs, and rate limits.

> **[Extension policy](https://omniflow-vpn.mintlify.site/integrations/extending.md)**
>
> Which surfaces are public and stable, what can be extended by configuration alone, and what
> deliberately cannot be extended at all.

## Running it

> **[Deployment](https://omniflow-vpn.mintlify.site/operations/deployment.md)**
>
> Compose topology, volumes, image tags, migrations, upgrades, and rollback.

> **[Compatibility and upgrades](https://omniflow-vpn.mintlify.site/operations/compatibility.md)**
>
> The supported version matrix, signed images, the upgrade window, and the deprecation policy.

> **[Reverse proxy](https://omniflow-vpn.mintlify.site/operations/reverse-proxy.md)**
>
> Caddy and Traefik examples, TLS, body limits, and keeping operational endpoints off the public
> host.

> **[Admin panel](https://omniflow-vpn.mintlify.site/operations/admin-panel.md)**
>
> The operator workspace screen by screen, the permission catalogue, and the six built-in roles.

> **[Admin operations](https://omniflow-vpn.mintlify.site/operations/admin-operations.md)**
>
> The day-to-day runbooks an operator performs from the panel.

> **[Installation settings](https://omniflow-vpn.mintlify.site/operations/installation-settings.md)**
>
> What the settings screens store, and which of it actually takes effect at runtime.

> **[Support desk](https://omniflow-vpn.mintlify.site/operations/support-desk.md)**
>
> Queues, assignment, priority, tags, internal notes, canned responses, merge, and the workload
> report.

> **[Required channels](https://omniflow-vpn.mintlify.site/operations/required-channels.md)**
>
> Requiring Telegram channel membership before a purchase completes.

> **[Risk controls](https://omniflow-vpn.mintlify.site/operations/risk-controls.md)**
>
> Blocklist sources stored as salted digests, anomaly rules, and decisions a person always makes.

> **[Observability](https://omniflow-vpn.mintlify.site/operations/observability.md)**
>
> The probes, the metrics that are actually written, structured logs, and secret redaction.

> **[Maintenance mode](https://omniflow-vpn.mintlify.site/operations/maintenance-mode.md)**
>
> Blocking new purchases and holding provisioning without disturbing money already taken.

> **[Jobs and queues](https://omniflow-vpn.mintlify.site/operations/jobs-and-queues.md)**
>
> The durable queue, the job kinds, dead letters, retries, periodic passes, and retention sweeps.

> **[Operator notifications](https://omniflow-vpn.mintlify.site/operations/operator-notifications.md)**
>
> The Telegram group, one forum topic per event kind, and why every notice is content-free.

> **[Backup and restore](https://omniflow-vpn.mintlify.site/operations/backup-restore.md)**
>
> Encrypted `pg_dump` output, verification on every backup, restore, and the standalone decrypt
> filter.

> **[Security](https://omniflow-vpn.mintlify.site/operations/security.md)**
>
> Credentials, sessions, secrets, transport, rate limits, and the privacy boundaries.

> **[Troubleshooting](https://omniflow-vpn.mintlify.site/operations/troubleshooting.md)**
>
> Symptoms, what to look at first, and what each classification means.

> **[Anonymous telemetry](https://omniflow-vpn.mintlify.site/operations/telemetry.md)**
>
> The exact payload that is sent, how to inspect it, and how to switch it off.

> **[Privacy](https://omniflow-vpn.mintlify.site/operations/privacy.md)**
>
> What Omniflow holds, why, for how long, and where a documented retention window isn't enforced yet.

> **[Reliability and operations](https://omniflow-vpn.mintlify.site/operations/reliability.md)**
>
> SLIs, importable dashboards and alerts, what's bounded and reconciled, graceful degradation, and capacity guidance.

> **[AI privacy](https://omniflow-vpn.mintlify.site/operations/ai-privacy.md)**
>
> What the redaction gateway strips, and the data-use preview shown before anything is enabled.

> **[AI providers](https://omniflow-vpn.mintlify.site/operations/ai-providers.md)**
>
> 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](https://omniflow-vpn.mintlify.site/operations/ai-governance.md)**
>
> Providers, per-feature enablement, budgets at four scopes, and the decision export.

> **[MCP](https://omniflow-vpn.mintlify.site/operations/mcp.md)**
>
> The server registry, allowlisted tools, and the rules both directions are held to.

## Architecture and contributing

> **[Architecture overview](https://omniflow-vpn.mintlify.site/architecture/overview.md)**
>
> The three processes, the request paths, and why a modular monolith.

> **[Data ownership](https://omniflow-vpn.mintlify.site/architecture/data-ownership.md)**
>
> The Remnawave boundary: what lives where, and what happens when the two disagree.

> **[Technology](https://omniflow-vpn.mintlify.site/architecture/technology.md)**
>
> The stack, and the reason each piece is in it.

> **[Threat model](https://omniflow-vpn.mintlify.site/architecture/threat-model.md)**
>
> What's at risk on each surface, the mitigation that actually exists, and the residual risk where one remains.

> **[Development](https://omniflow-vpn.mintlify.site/contributing/development.md)**
>
> Workspace setup, the generators, running the stack, and the checks CI will run anyway.

> **[Database](https://omniflow-vpn.mintlify.site/contributing/database.md)**
>
> The schema, Atlas migrations, sqlc, and the rules a migration must follow.

> **[Testing](https://omniflow-vpn.mintlify.site/contributing/testing.md)**
>
> Unit, integration, and browser coverage, and what each layer is responsible for proving.

> **[Documentation](https://omniflow-vpn.mintlify.site/contributing/documentation.md)**
>
> Authoring, validating, and keeping the Russian tree in step with the English one.

> **[Architecture decisions](https://omniflow-vpn.mintlify.site/architecture/decisions.md)**
>
> The records that constrain how Omniflow is built, what each costs, and when to reopen one.

> **[Release process](https://omniflow-vpn.mintlify.site/contributing/releases.md)**
>
> 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](https://omniflow-vpn.mintlify.site/architecture/data-ownership.md).
* **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](https://omniflow-vpn.mintlify.site/commerce/financial-invariants.md).
* **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](https://omniflow-vpn.mintlify.site/operations/installation-settings.md) and
  [Configuration](https://omniflow-vpn.mintlify.site/getting-started/configuration.md).
* **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](https://omniflow-vpn.mintlify.site/operations/ai-providers.md) and [AI governance](https://omniflow-vpn.mintlify.site/operations/ai-governance.md).
* **It does not run more than one bot.** Telegram delivers updates to one consumer, so the `bot`
  runs as exactly one instance. The `api` and the `worker` take 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](https://omniflow-vpn.mintlify.site/operations/deployment.md#supported-topology).

> [!WARNING]
>
> Omniflow is under active development. Pin a tagged release rather than a floating image tag, read
> the release notes before upgrading, and take a backup first — there are no down-migrations, so a
> schema rollback is a restore.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.