Repository navigation
Architecture
This page is for developers. It shows how the parts fit together. The split follows security, failure and scale boundaries, not features.
Telegram ⇄ bot ⇄ core ⇄ provisioner ⇄ 3x-ui / Marzban panels
│ ⇅
│ payments ⇄ gateways, the TRON watcher
Mini App / dashboard (served by core) · backup · Caddy ⇄ tls-agent
BOBRES is a Go monorepo. The dashboard and the Mini App are Vue 3 apps embedded into the core binary. Everything runs with Docker Compose on one server.
| Service | Job | Networks |
|---|---|---|
caddy |
HTTPS gateway. The only service reachable from the internet | public, edge |
postgres |
One database, one schema and one role per service | backend |
redis |
The bot's conversation state and rate limits. Disposable | backend |
core |
Users, plans, orders, wallet and ledger, tickets, resellers, the delivery worker, the dashboard and Mini App API, the watchdog | edge, backend |
bot |
Telegram: customers, staff, alerts, backup delivery. Also the proxy for anything core needs from the internet | edge, backend, egress |
payments |
Gateway secrets, payment intents, Zarinpal, IDPay, NextPay, Aqayepardakht, Stars, the TRON and TON watchers, manual receipts | edge, backend, egress |
provisioner |
The only holder of panel tokens. Creates, renews and deletes clients | backend, egress |
tls-agent |
Applies HTTPS changes to Caddy. Core's image, with no network | none |
backup |
Daily encrypted pg_dump. Reaches the internet only when S3 copies are on |
backend, offline |
backend, edge and offline are internal Docker networks. Only egress has a route out. Core has no internet access, so a compromised dashboard cannot phone home. backup and tls-agent run behind compose profiles that bobres install sets. The BOBRES services run read-only as user 65532, with all capabilities dropped.
- One PostgreSQL. Schemas
core,paymentsandprovisioner. No cross-schema joins or foreign keys: services refer to each other by ID only (UUID v7). - Migrations are forward-only (goose) and additive. Each service runs its own schema's migrations at start.
bobres rollbackrestores the database from the restore point taken before the update. - Amounts are
bigintin minor units plus a currency code, never floats. The ledger is append-only. A wallet balance is a cached sum of it. Every money-moving call carries an idempotency key with a unique index.
-
Synchronous: gRPC on the internal network. Contracts are in
proto/(managed with buf, generated code ingen/). -
Asynchronous: each service writes events to a transactional outbox. Consumers pull them over gRPC (
events.v1.EventFeedService) with one cursor per consumer, and de-duplicate with an inbox. Events are past-tense, versioned facts likeorder.paid.v1, and handlers are idempotent. Failures retry with back-off, then go to a dead-letter table and raise an alert. - Auth: one token per service. A server accepts only its legitimate callers, and core presents a different token to each service it calls. mTLS is not built.
The purchase flow: the bot calls core.CreateOrder. Core emits order.created. Payments creates an intent and the customer pays. Payments emits payment.succeeded. Core marks the order paid, writes the ledger and emits order.paid. The provisioner creates the client and emits subscription.provisioned. The bot sends the link. A wallet payment skips the payments step. If the panel is down, the order stays paid and is retried.
-
web/dashboardis the staff dashboard at/admin.web/miniappis the customer store at/app/. Both are built into folders that core embeds.make dashboardandmake miniappbuild them. - The Mini App signs a customer in with Telegram's
initData. Only the bot holds the bot token, so core sends the data to the bot's/internal/miniapp/verify. - Public pages served by core:
/sub/<token>,/terms,/privacy,/healthz,/readyzand/webhooks/<provider>.
Core has no Docker socket. Anything that needs the host goes through a file in a shared folder and a root systemd unit:
| Helper | Mechanism |
|---|---|
| Update and restore from the dashboard | Core writes run/update/request.json. bobres-updater.path starts bobres update --from-request, which runs the same code as the command line and writes status.json
|
| Host monitoring |
bobres-monitor.timer writes run/monitor/snapshot.json every 30 seconds. Core reads it read-only |
| Start at boot |
bobres.service runs bobres start at every boot, so a container Docker left stopped comes back. bobres stop leaves run/stopped, which keeps it from starting a store stopped on purpose |
| HTTPS | Core writes a request file. The tls-agent re-checks it and talks to Caddy through its admin socket |
| Path | Contents |
|---|---|
cmd/ |
One main per program: core, bot, payments, provisioner, backup, bobres (the CLI), licensesrv (the vendor's license server, never part of an install) |
internal/core/{domain,store,server,web} |
Business rules, SQL, gRPC and HTTP handlers |
internal/bot/ |
The Telegram handlers, texts (i18n, Persian and English), notifier |
internal/payments/, internal/provisioner/
|
The gateways, and the service that drives panels |
internal/xui, internal/marzban
|
Panel clients and adapters. Each has a fake (xuifake, marzbanfake) for tests |
internal/license, internal/release
|
License tokens, tiers and release verification |
proto/, gen/
|
Protobuf contracts and generated code |
deploy/ |
The compose file, Caddy templates, systemd units |
install/ |
install.sh and the embedded public keys |
tools/, tests/, site/
|
Tools, end-to-end tests, the public site |
Two offline root keys sign keys.txt, a list of release keys with expiry, sequence number and revocations. A release key signs checksums.txt (version, channel, expiry), and the CLI must match its signed checksum. Release images are signed with keyless cosign. The release workflow checks that signature and builds each image digest into the CLI. See Security.
The longer design notes are in docs/PLAN.md, docs/01-database.md and docs/02-events-and-apis.md.
BOBRES, made by TECSO-DEV. Source-available, all rights reserved (see LICENSE). Site: bobresai.cv.
Start
Run the store
- Dashboard Guide
- Bot Guide
- Mini App
- Plans and Pricing
- Payments
- Panels
- Resellers
- Digital Accounts
- Subscription Page
- Terms and Privacy Pages
- Reports
Operate
Develop
فارسی