# Project Guidelines

## Overview

VPN-Proxy is a self-hosted VPN/proxy management system using **sing-box** as the core proxy engine (VLESS + REALITY TLS). It consists of a NestJS (TypeScript) backend, a vanilla HTML/JS frontend, PowerShell scripts for Windows management, and Docker for deployment. Documentation and UI are in **Russian**.

## Architecture

```
Browser → NestJS web server (PORT, default 3456)
           ├─ Serves index.html with SSI-like includes (<!-- include "components/X.html" -->)
           └─ API endpoints in web/api/src/proxy/proxy.controller.ts
                 ↓ writes config
              data/client.json → sing-box binary (PROXY_PORT, default 8080)
                                    ↓ reload via HTTP to RELOAD_PORT (9090, internal)
                                    ↓
                              VPN traffic out
```

### Key layers

| Layer | Location | Notes |
|-------|----------|-------|
| Frontend | `web/index.html`, `web/components/`, `web/static/` | Tailwind via CDN, no build step |
| Backend | `web/api/` | NestJS + TypeScript, minimal deps |
| Proxy core | `docker/entrypoint.sh` + sing-box binary | Config in `data/client.json` |
| Windows client | `manage.ps1`, `scripts/` | PowerShell 7+ required, runs as Admin |
| Docker | `docker-compose.yml` (dev), `docker-compose.server.yml` (prod, host network) |

### State files (`data/`)

All JSON. Do not change their structure without updating both backend and JS consumers:
- `client.json` — active sing-box config
- `subscription.json` — subscription URL + selected server
- `fallback.json` — fallback proxy settings
- `proxy_enabled.json` — on/off toggle
- `start_time.json` — uptime timestamp
- `hwid` — immutable device ID (16-char hex), generated once

## Build and Run

```powershell
# Docker (dev, bridged network)
docker compose up -d              # starts on localhost:3456 + 8080
docker compose up -d --build      # rebuild after changes

# Docker (Linux VPS, host network for UDP)
docker compose -f docker-compose.server.yml up -d

# Logs
docker logs -f sing-proxy

# Windows native (PowerShell 7, Admin)
.\manage.ps1

# Backend dev (local)
cd web/api
npm install
npm run start:dev
```

Environment variables: `PORT` (3456), `PROXY_PORT` (8080), `RELOAD_PORT` (9090), `PROXY_BIND_IP` (0.0.0.0).

## Conventions

### Code style
- **TypeScript**: NestJS conventions — modules, controllers, services. `camelCase` for methods, `PascalCase` for classes
- **PowerShell**: `PascalCase` functions (e.g., `Write-Success`, `Manage-ScheduledTask`)
- **JSON keys**: `camelCase` (e.g., `serverPort`, `selectedServer`)
- **HTML element IDs**: `camelCase` (e.g., `subUrlInput`, `fallbackToggle`)

### Adding features
- New API endpoint → controller in `web/api/src/proxy/proxy.controller.ts` + JS call in `web/static/js/app.js`
- Business logic → `web/api/src/proxy/proxy.service.ts`
- VLESS config changes → `web/api/src/vless/vless.service.ts`
- Persistent state → `web/api/src/storage/storage.service.ts` (JSON file I/O)
- Network utilities → `web/api/src/network/network.service.ts`
- Windows scripts → `scripts/setup-*.ps1`, shared helpers in `scripts/lib/`

### Backend module structure
```
web/api/src/
  main.ts              — Bootstrap & static assets
  app.module.ts        — Root module
  config/config.ts     — Environment configuration
  storage/             — JSON file persistence + HWID
  vless/               — VLESS URL parsing + sing-box config generation
  network/             — TCP latency + proxy performance measurement
  proxy/               — API controller + business logic service
```

### VLESS handling
- Parsing is strict: requires `vless://uuid@host:port?pbk=...&sid=...` format (REALITY params mandatory)
- Subscription URLs must be `http://` or `https://` only

## Pitfalls

- **Windows Docker cannot use `network_mode: host`** — UDP (Discord voice, games) won't work in Docker on Windows. Use native sing-box via `manage.ps1` instead.
- **Port 9090 is internal only** — used for reload triggers via netcat, never expose externally.
- **`hwid` is immutable** — after first generation, changing it requires manual file deletion.
- **DOS line endings** — the Dockerfile runs `dos2unix` on shell scripts. Keep this in place.
- **sing-box needs a config before starting** — apply config via the web UI first; it won't bootstrap empty.
- **No test suite exists** — validate changes manually via Docker.
- **NestJS build required** — the Dockerfile runs `npm ci && npm run build` during image build. For local dev use `npm run start:dev`.