Init

core.md

@@ -0,0 +1,59 @@
+# Core
+
+REST API server — the control plane of Nexuma. Manages users, tariffs, subscriptions, nodes, traffic accounting, and generates subscription configs for VPN clients.
+
+## Configuration
+
+Edit the environment variables in [`docker-compose.base.yml`](./docker-compose.base.yml):
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DB_HOST` | Yes | PostgreSQL host |
+| `DB_PORT` | Yes | PostgreSQL port |
+| `DB_USER` | Yes | Database user |
+| `DB_PASSWORD` | Yes | Database password |
+| `DB_NAME` | Yes | Database name |
+| `REDIS_HOST` | Yes | Redis host |
+| `REDIS_PORT` | Yes | Redis port |
+| `JWT_SECRET` | Yes | Access token secret |
+| `JWT_REFRESH_SECRET` | Yes | Refresh token secret |
+| `JWT_EXPIRES_IN` | No | Access token TTL (default: `15m`) |
+| `JWT_REFRESH_EXPIRES_IN` | No | Refresh token TTL (default: `7d`) |
+| `TELEGRAM_BOT_TOKEN` | No | Enables Telegram bot and OAuth login |
+| `CORS_ORIGINS` | No | Allowed CORS origins (default: `*`) |
+
+## API Overview
+
+### Public
+
+- `POST /auth/register` — create account
+- `POST /auth/login` — login, get JWT tokens
+- `POST /auth/refresh` — refresh access token
+- `GET /sub/:uuid` — subscription config for VPN clients (base64 URI list)
+- `GET /sub/:uuid/info` — subscription info (JSON)
+- `GET /health`, `GET /metrics`
+
+### User
+
+- `GET /me` — profile and balance
+- `GET /me/subscriptions` — subscriptions and links
+- `GET /me/balance/transactions` — transaction history
+
+### Admin
+
+- **Users** — CRUD, status approval (pending / active / rejected), balance management
+- **Tariffs** — CRUD
+- **Nodes** — CRUD, protocol management, xray/MTProto version install, GeoIP update, outbounds
+- **Subscriptions** — create, manage, auto-renewal toggle
+- **Routing rule sets** — xray-native rules and balancers
+- **External subscriptions** — aggregate external VPN share URLs
+- **Audit logs**
+
+## Tariff types
+
+| Type | Expiry | Auto-renews |
+|------|--------|-------------|
+| Timed paid | By date | If balance ≥ 0 |
+| Timed free | By date | Always |
+| Indefinite paid | When traffic exhausted | If balance ≥ 0 |
+| Indefinite free | When traffic exhausted | Always |