# Pure Flow Architecture

## Target

Build a paid VPN subscription service on `pureflow.net` where the website markets the service, Telegram handles onboarding and renewals, and 3x-ui manages Xray clients, subscriptions, traffic, and server locations.

## Core Flow

```mermaid
flowchart LR
  User["User"] --> Site["pureflow.net website"]
  User --> Bot["Telegram bot"]
  Site --> Bot
  Bot --> Payment["Payment provider"]
  Payment --> Bot
  Bot --> App["Pure Flow backend"]
  App --> XUI["3x-ui control plane"]
  XUI --> Nodes["VPN nodes / Xray"]
  XUI --> Sub["Subscription links"]
  Sub --> User
  App --> Profile["Web profile API"]
  Profile --> Site
```

## Components

### Website

Responsibilities:

- Product positioning, tariffs, FAQ, instructions.
- Language switching. Current languages: Russian and English.
- CTA links into Telegram using `?start=` payloads.
- Web profile shell for future authenticated subscription state.

Current implementation:

- Static `index.html`, `styles.css`, `app.js`.
- Translations live in `CONTENT` inside `app.js`. Add a new top-level language object to add another locale.

### Telegram Bot

Responsibilities:

- `/start`, language choice, trial, purchase, profile, links, renewal, support.
- Payment handoff.
- Create or extend 3x-ui client after payment confirmation.
- Send subscription and location-specific links.
- Keep support visible.

Current implementation:

- `bot/` contains a Telegraf starter with dry-run behavior.
- Real production wiring needs bot token, payment provider, and validated 3x-ui API settings.

### Pure Flow Backend

Recommended responsibilities:

- Own product database: Telegram user ID, internal user ID, plan, payment status, subscription status, 3x-ui client ID, locale.
- Handle payment webhooks idempotently.
- Call 3x-ui only from an internal network.
- Generate profile session tokens for website login from Telegram.
- Keep an audit log of subscription changes.

Do not make the website call 3x-ui directly.

### 3x-ui

Useful upstream capabilities:

- Multi-protocol Xray management.
- Per-client expiry, traffic accounting, IP limits, links, QR codes, and subscriptions.
- Built-in subscription server and REST API with in-panel Swagger.
- SQLite by default and PostgreSQL option.
- Multi-node support.
- Telegram bot and Fail2ban features.

Important production caveat:

The upstream 3x-ui README currently states that the project is intended for personal use only and should not be used in a production environment. For Pure Flow, this means 3x-ui should be treated as an MVP control plane until hardening, security review, and operational controls are complete.

## Recommended Deployment

### MVP

- Static site on CDN or simple VPS.
- Telegram bot and backend on a private VPS.
- 3x-ui panel on a private admin host or private subnet.
- VPN nodes in 4 launch locations: Germany, London, Netherlands, Finland.
- PostgreSQL for product backend.
- 3x-ui can start with SQLite for a small MVP, but PostgreSQL should be tested before scaling.

### Hardening

- Put 3x-ui behind VPN/admin allowlist, never public.
- Enable TLS everywhere.
- Rotate panel credentials and bot/payment secrets.
- Validate all 3x-ui API calls against in-panel Swagger.
- Add backups for product database and 3x-ui database.
- Add monitoring: node health, Xray status, certificate expiry, traffic anomalies, payment webhook failures.
- Use idempotency keys for payment webhooks.
- Separate admin users from customer users.
- Add abuse policy, terms, refund policy, and acceptable use terms before selling broadly.

## Data Model

Minimal product tables:

- `users`: id, telegram_id, locale, created_at, status.
- `subscriptions`: id, user_id, plan_key, starts_at, expires_at, status, xui_client_id.
- `payments`: id, user_id, provider, amount, currency, status, provider_payment_id, idempotency_key.
- `locations`: id, code, name, country, xui_inbound_id, status.
- `subscription_links`: id, subscription_id, location_id, url_hash, created_at.
- `events`: id, actor, action, payload, created_at.

## Payment Lifecycle

1. Bot creates a pending order.
2. User pays through provider.
3. Provider webhook reaches backend.
4. Backend verifies signature and idempotency.
5. Backend creates or extends client in 3x-ui.
6. Backend stores subscription status.
7. Bot sends profile and links.
8. Web profile reflects same state.

## 3x-ui Integration Notes

Use the in-panel Swagger as the source of truth for endpoints and schemas. The adapter in `bot/src/xuiClient.js` is intentionally configurable because endpoint paths and auth behavior should be validated against the installed 3x-ui version.

Recommended API operations:

- Authenticate bot/backend to panel.
- Read inbounds and locations.
- Create a client for a plan.
- Extend expiry date.
- Reset or read traffic usage.
- Generate subscription and per-location links.
- Disable expired clients.

## Risks

- Upstream production warning for 3x-ui.
- Payment disputes and refunds need clear automation.
- "Unlimited traffic" must be backed by capacity planning.
- VPN services can be abused; terms, rate limits, and support tooling are required.
- Telegram-only account ownership can become fragile if the user loses account access.

## Next Build Step

Create the backend service that sits between Telegram/payment/3x-ui. Keep the current bot as a UI layer and move all state changes into backend endpoints.