# Xcr9 Host (ایکس‌سی‌آر۹ هاستینگ) Documentation for LLMs

> High-Performance European Virtual Private Server (VPS) hosting platform offering automated Hetzner Cloud (Germany & Finland) and OVHcloud (France & Poland) servers tailored for Iranian developers and businesses.

## System Summary & Stack
- **Architecture**: Node.js + Express REST API Backend, SQLite (`better-sqlite3` with WAL mode) DB, Vanilla HTML5/CSS3/JS Frontend.
- **Security**: JWT Bearer token / Cookie authentication, bcrypt password hashing, helmet CSP, CORS, express-rate-limit.
- **Base URL**: `https://xcr9.host` or `http://127.0.0.1:3000`
- **Default Admin**: `admin@xcr9.host` / `Xcr9Admin2025!`

---

## Core Value Proposition & Pricing Engine
- **Dedicated Clean IPs**: Pre-tested IPv4 addresses to guarantee 100% clean ports.
- **Low Latency Routing**: 65ms–80ms ping to Iranian ISPs (Hamrah-e Aval, Irancell, Shatel, TCI).
- **Financial Model**:
  - Base Datacenter Cost (EUR) + **30% Profit Margin** (`MARKUP = 1.30`)
  - Exchange Rate: **1 EUR = 200,000 Toman** (`EUR_TO_TMN = 200000`)
  - Live Hetzner REST API Sync with 1-hour in-memory cache.
  - Payment options: Toman (ZarinPal & Card-to-Card), Euro (€), USDT (TRC20 / TON).

---

## Database Schemas (SQLite)

- **`users`**: `id`, `name`, `email`, `phone`, `password_hash`, `role` ('user'|'admin'), `wallet_tmn`, `is_active`, `created_at`
- **`servers`**: `id`, `user_id`, `name`, `ip`, `cpu`, `ram`, `disk`, `bandwidth`, `os`, `status` ('active'|'stopped'), `root_password`, `provider`, `location`, `plan_name`, `renewal_date`, `price_tmn`, `notes`, `created_at`
- **`orders`**: `id`, `user_id`, `plan_id`, `plan_name`, `provider`, `price_tmn`, `price_eur`, `period_months`, `status` ('pending_payment'|'pending_setup'|'active'|'expired'|'cancelled'), `server_id`, `expires_at`, `payment_method`, `admin_note`, `created_at`, `updated_at`
- **`tickets`**: `id`, `user_id`, `subject`, `department`, `priority`, `status` ('open'|'replied'|'closed'), `created_at`, `updated_at`
- **`ticket_messages`**: `id`, `ticket_id`, `sender_role` ('user'|'support'), `sender_name`, `message`, `created_at`
- **`invoices`**: `id`, `user_id`, `order_id`, `title`, `amount_tmn`, `type` ('charge'|'order'|'renewal'), `status` ('pending'|'paid'|'cancelled'), `payment_method`, `created_at`
- **`notifications`**: `id`, `user_id`, `title`, `message`, `type` ('info'|'success'|'warning'|'error'|'order'), `is_read`, `created_at`

---

## API Routes & Endpoints Reference

### Public & Auth (`/api/auth`)
- `POST /api/auth/register` - `{ name, email, password, phone }` -> `{ token, user }`
- `POST /api/auth/login` - `{ email, password }` -> `{ token, user }`
- `GET /api/auth/me` [Auth] -> `{ user }`
- `POST /api/auth/change-password` [Auth] - `{ current_password, new_password }`

### Orders & Hetzner Live Plans (`/api/orders`)
- `GET /api/orders/plans` - Query params: `category`, `provider`, `refresh=1`. Returns live Hetzner plans + calculated markup price.
- `GET /api/orders` [Auth] - List my placed orders & server IP links.
- `POST /api/orders` [Auth] - `{ plan_id, period_months, payment_method }`. Deducts wallet balance if `payment_method === 'wallet'`.
- `POST /api/orders/:id/renew` [Auth] - `{ period_months }`. Deducts wallet balance and extends `expires_at`.

### Servers (`/api/servers`)
- `GET /api/servers` [Auth] - List user's assigned active/stopped VPS instances.
- `GET /api/servers/:id` [Auth] - Get single server details.
- `POST /api/servers/:id/power` [Auth] - Toggle server power state (`active` <-> `stopped`).
- `POST /api/servers/:id/reboot` [Auth] - Trigger server reboot action.

### Tickets & Support (`/api/tickets`)
- `GET /api/tickets` [Auth] - List user tickets.
- `POST /api/tickets` [Auth] - `{ subject, department, priority, message }`
- `GET /api/tickets/:id` [Auth] - View ticket details & message thread.
- `POST /api/tickets/:id/reply` [Auth] - `{ message }`

### Invoices & Wallet (`/api/invoices`, `/api/wallet`)
- `GET /api/invoices` [Auth] - List user invoice history.
- `POST /api/wallet/charge` [Auth] - `{ amount_tmn, payment_method }` -> creates pending invoice.
- `GET /api/wallet/balance` [Auth] - Returns current wallet balance (`wallet_tmn`).

### Admin API (`/api/admin`) [Admin Auth Guard]
- `GET /api/admin/stats` - System overview metrics.
- `GET /api/admin/users` - Search & filter user accounts.
- `GET /api/admin/users/:id` - Complete profile data of a user.
- `PUT /api/admin/users/:id/toggle` - Activate/Deactivate user.
- `POST /api/admin/users/:id/wallet` - `{ amount_tmn, note }` credit/debit wallet balance.
- `GET/POST /api/admin/servers` - List or create raw server assets.
- `POST /api/admin/servers/:id/assign` - `{ user_id, order_id }` Assign VPS to user & activate order.
- `POST /api/admin/servers/:id/unassign` - Revoke VPS assignment.
- `GET/PUT /api/admin/orders` - Update order setup status.
- `GET/POST/PUT /api/admin/tickets` - Support ticket management & replies.
- `GET/PUT /api/admin/invoices` - Approve invoice & auto-credit user wallet.
- `POST /api/admin/notifications` - Direct or broadcast system notifications.

---

## File Structure & Map
- `backend/server.js`: Express server setup, middleware, rate limiters, static serving.
- `backend/database.js`: SQLite initialization via `better-sqlite3`, table creation & seeding.
- `backend/services/hetzner.js`: Hetzner Cloud API client, caching layer (1h), markup calculator.
- `backend/middleware/auth.js`: JWT token validator.
- `backend/middleware/admin.js`: Guard checking `user.role === 'admin'`.
- `index.html`: Public marketing landing page with interactive pricing & customizer.
- `panel/login.html`: Login & registration page.
- `panel/dashboard.html`: User dashboard connected to API.
- `panel/admin.html`: System admin dashboard.
- `js/data.js`: Client dataset fallback & markup constants.
- `js/app.js`: Landing page UI logic, customizer sliders, currency switchers, and FAQ preservation for dedicated SEO pages.
- `js/panel.js`: Panel UI interactivity helper & state persistence.
- `blog_automator.py`: Python script utilizing Grok (xAI) API and Google Translator as a fallback to fetch, translate, and generate automatic SEO blog posts via cronjob.
- `generator.py`: Python script used to automatically generate highly optimized SEO landing pages.
- `blog/`: Directory containing `index.html` (main blog grid) and `post-template.html` used by the python automator.
- `vps-germany.html`, `crypto-vps.html`, etc.: Automatically generated dedicated SEO landing pages focusing on specific keywords.