# Compton Platform

Monorepo-lite project that follows the `docs/TZ.md` specification for the Compton platform.

## Stack

- **Frontend:** React 19, TypeScript, Vite, React Router, TanStack Query, Zustand, RHF + Zod, Ant Design (admin panel)
- **Backend:** FastAPI, SQLAlchemy 2, Alembic, Pydantic v2
- **Data/Infra:** PostgreSQL, Redis, MinIO (S3-compatible), Docker Compose
- **Quality:** Vitest, Testing Library, Playwright, pytest, coverage gates in CI

## Repository Layout

- `apps/web` — frontend SPA
- `apps/api` — backend API (`app/core/crypto.py` — unified crypto; `app/core/install_secrets.py` — bootstrap/lock)
- `apps/api/data/secrets/` — per-install secrets (`install.env`, gitignored)
- `apps/api/data/compton_settings.json` — runtime panel settings (superuser-editable via API)
- `packages/shared-types` — generated API types contract target
- `packages/eslint-config` — shared eslint config package
- `infra` — docker/nginx/ci helper files
- `docker-compose.dev-ports.yml` — optional override to expose DB/Redis/MinIO on host

## Quick Start

**Full stack in Docker** (API + DB + frontend — no local `pnpm install` required):

```bash
# 1. Bootstrap install secrets — REQUIRED before the first docker compose up
python apps/api/scripts/bootstrap_install.py

# 2. Build and start everything
docker compose --profile docker-web up -d --build

# 3. Verify (Windows PowerShell: use curl.exe, not curl — it is an alias for Invoke-WebRequest)
curl.exe http://localhost:8000/api/v1/health
```

Open [http://localhost:5173](http://localhost:5173) — static landing (`index.html`). SPA routes (`/login`, `/admin`, `/profile`, …) are served via `app.html` fallback in Vite dev/preview.

The `web` container runs Vite with hot-reload; dependencies are installed inside the container automatically.

Log in as `admin@compton.example` (password `Admin1234` by default) and open `/admin`. See [Seed data](#seed-data) for all demo accounts.

**Optional** — copy env files if you also run API or frontend locally (hybrid mode):

```bash
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
```

> **Important:** Run bootstrap **before** the first `docker compose up`. If Postgres was started without `install.env`, the API will fail with `password authentication failed for user "compton_app"`. Fix: `docker compose --profile docker-web down -v`, then bootstrap + up again. See [Troubleshooting](#troubleshooting).

**Hybrid setup** (Docker API + local frontend):

```bash
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
pnpm install
python apps/api/scripts/bootstrap_install.py
docker compose up -d
pnpm --filter web dev
```

## Local Setup

### Prerequisites

- **Docker + Docker Compose** — enough for the full-stack Docker workflow
- **Node.js 22+ and pnpm 9+** — only if you run the frontend locally (`pnpm --filter web dev`)
- **Python 3.12** — bootstrap script, local API, or tests outside Docker

### Start services

| Mode | Command | What runs |
| ---- | ------- | --------- |
| **Full Docker (recommended)** | `docker compose --profile docker-web up -d --build` | API, Postgres, Redis, MinIO, Vite on `:5173` |
| **API + infra only** | `docker compose up -d` | API, Postgres, Redis, MinIO — frontend locally |
| **Local API + local frontend** | see [Run applications](#run-applications) | everything on host |

| Service   | URL / Port                                     | Notes |
| --------- | ---------------------------------------------- | ----- |
| API       | [http://localhost:8000](http://localhost:8000) | migrations + seed on startup |
| Web (dev) | [http://localhost:5173](http://localhost:5173) | Docker `--profile docker-web` or `pnpm --filter web dev` |
| Postgres  | internal docker network                        | host access via `docker-compose.dev-ports.yml` |
| Redis     | internal docker network                        | host access via `docker-compose.dev-ports.yml` |
| MinIO     | internal docker network                        | host access via `docker-compose.dev-ports.yml` |

> Do not run Docker `web` and `pnpm --filter web dev` at the same time — both bind port **5173**.

The Docker `web` container bind-mounts source for live-reload on Windows/macOS (`CHOKIDAR_USEPOLLING=true`); `node_modules` stay isolated inside the container.

### Install secrets

Each project copy gets unique runtime secrets generated once and locked forever (prevents accidental rotation and DB credential mismatch).

| File | Purpose |
| ---- | ------- |
| `apps/api/data/secrets/install.env` | PostgreSQL, JWT, S3/MinIO credentials (gitignored) |
| `apps/api/data/secrets/install.meta.json` | Install ID and lock timestamp (gitignored) |

**Bootstrap (required before first `docker compose up`):**

```bash
python apps/api/scripts/bootstrap_install.py
```

Generated keys: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `DATABASE_URL`, `JWT_ACCESS_SECRET`, `JWT_REFRESH_PEPPER`, `S3_SECRET_KEY`, `MINIO_ROOT_PASSWORD`.

Docker Compose passes `install.env` directly into the `api`, `postgres`, and `minio` services — no root `.env` or `--env-file` flag needed.

- Re-run is safe: existing locked secrets are never overwritten.
- API entrypoint also calls `ensure_install_secrets()` on startup (adopts env vars when migrating from an older setup).
- **Do not rotate** `POSTGRES_PASSWORD` / JWT secrets after first bootstrap without a coordinated DB migration — see [docs/secrets-recovery.md](docs/secrets-recovery.md).

**Host access to DB/Redis/MinIO** (DBeaver, pgAdmin, MinIO console):

```bash
docker compose -f docker-compose.yml -f docker-compose.dev-ports.yml up -d
```

| Exposed port | Service |
| ------------ | ------- |
| 5432         | PostgreSQL |
| 6379         | Redis |
| 9000 / 9001  | MinIO API / console |

**Reveal credentials:** Admin → Security → Install Secrets (superuser only, audited). Supports `database_password`, `jwt_access_secret`, `jwt_refresh_pepper`, `s3_secret_key`.

### Configure environment

For hybrid or fully local dev, copy example env files:

```bash
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
```

Key variables:

| Variable                                  | App | Purpose                                              |
| ----------------------------------------- | --- | ---------------------------------------------------- |
| `DATABASE_URL`                            | api | PostgreSQL connection string                         |
| `APP_ENV`                                 | api | `development` / `production` startup guards          |
| `JWT_ACCESS_SECRET`, `JWT_REFRESH_PEPPER` | api | Token signing (32+ bytes)                            |
| `VITE_API_URL`                            | web | Local dev: `http://localhost:8000`. Docker `web`: `http://api:8000` |
| `VITE_USE_API_PROXY`                      | web | `true` — proxy `/api` through Vite (default in dev)  |
| `EMAIL_DELIVERY_MODE`                     | api | `memory` (Docker dev) or `smtp` (real mail)          |
| `STORAGE_MODE`                            | api | `s3` (MinIO) or `memory` (tests)                     |
| `S3_*`                                    | api | MinIO/S3 credentials and bucket                      |
| `CORS_ORIGINS`                            | api | Must include `http://localhost:5173`                 |
| `ENABLE_TEST_ROUTES`                      | api | `true` only for E2E (email token helper)             |
| `TRUSTED_PROXY_IPS`                       | api | Which proxy IPs may set `X-Forwarded-For`            |
| `ADMIN_INITIAL_PASSWORD`                  | api | Seed password for superuser admin                      |
| `DEMO_USER_PASSWORD`                      | api | Seed password for regular demo user                    |
| `DEMO_OPS_PASSWORD`                       | api | Seed password for ops admin (no superuser)           |
| `ENABLE_RATE_LIMIT`                       | api | Rate limiting (required `true` in production)        |
| `COOKIE_SECURE`                           | api | HttpOnly refresh cookie `Secure` flag                |
| `COMPTON_SETTINGS_PATH`                   | api | Path to runtime settings JSON (default `data/compton_settings.json`) |

In dev the frontend proxies API requests through Vite (`/api` → backend). Locally the target is `localhost:8000`; in Docker Compose it is the `api` service.

### Runtime settings (`compton_settings.json`)

Non-secret runtime toggles live in `apps/api/data/compton_settings.json` and are applied on API startup. Superusers can read/update them via `GET/PATCH /admin/settings`.

Env vars with the same keys (e.g. `ENABLE_RATE_LIMIT`, `CORS_ORIGINS`) act as **locks** — when set, the corresponding JSON field cannot be changed from the admin panel.

Typical fields: rate limit, API docs, secure cookie, JWT TTL, CORS origins, SMTP host/port, avatar limits, audit retention.

### Install dependencies (hybrid / local dev only)

Skip if you use `docker compose --profile docker-web` — dependencies are installed inside the `web` container.

```bash
pnpm install
pip install -r apps/api/requirements-dev.txt
```

### Run applications

**Option A — Full Docker stack:**

```bash
python apps/api/scripts/bootstrap_install.py   # first run only
docker compose --profile docker-web up -d --build
```

**Option B — Docker API + local frontend:**

```bash
python apps/api/scripts/bootstrap_install.py   # first run only
docker compose up -d
pnpm --filter web dev
```

**Option C — Local API + local frontend:**

```bash
cd apps/api
alembic upgrade head
uvicorn app.main:app --reload --app-dir .
```

In another terminal:

```bash
pnpm --filter web dev
```

Open [http://localhost:5173](http://localhost:5173).

### Seed data

After migrations the database is seeded on every API startup with demo users and CMS pages. Passwords come from env vars (defaults in `.env.example`):

| Email | Env variable | Default (dev) | Role | Superuser | Access |
| ----- | ------------ | --------------- | ---- | --------- | ------ |
| `admin@compton.example` | `ADMIN_INITIAL_PASSWORD` | `Admin1234` | `admin` | yes | Full admin + Security/Diagnostics/Install Secrets |
| `ops@compton.example` | `DEMO_OPS_PASSWORD` | `OpsAdmin1234` | `admin` | no | Users, Content, Activity (no Security/Diagnostics) |
| `user@compton.example` | `DEMO_USER_PASSWORD` | `User1234` | `user` | no | Profile only |

**Content pages:** `about`, `privacy`, `terms` (published).

> Change demo passwords via env before first seed in production. Admin-created users must pass the shared password policy (length, complexity, denylist).

## Frontend Routes

The project uses a **dual-entry** frontend:

| Entry | Served at | Purpose |
| ----- | --------- | ------- |
| `index.html` | `/` | Public marketing landing (static HTML/CSS/JS in `main/`) |
| `app.html` | `/login`, `/register`, `/profile`, `/admin`, `/pages/:slug`, … | React SPA (auth, profile, admin, CMS pages) |

Vite middleware rewrites SPA paths to `app.html` on dev/preview (`vite.main-static.ts`).

| Path               | Page                  | Access                  |
| ------------------ | --------------------- | ----------------------- |
| `/`                | Landing (`index.html`)| public                  |
| `/login`           | Login                 | guest                   |
| `/register`        | Registration          | guest                   |
| `/verify`          | Email verification    | public                  |
| `/forgot-password` | Password reset request| guest                   |
| `/reset-password`  | Set new password      | public (with token)     |
| `/pages/:slug`     | CMS page              | public (published only) |
| `/profile`         | Profile CRUD + avatar | authenticated           |
| `/admin`           | Admin panel           | role `admin`            |

**Auth model:** one login flow for everyone. The `is_superuser` flag on admin accounts controls access to critical panel sections (Security, Diagnostics, Install Secrets reveal, runtime settings). Regular admins see Users, Content, and Activity only.

- **Access JWT** — in memory only (Zustand), not in `localStorage` / `sessionStorage`.
- **Refresh token** — HttpOnly cookie (`Path=/api/v1/auth`, `SameSite=Lax`), rotated on each refresh.
- **Session restore on reload** — `AuthBootstrap` calls a deduplicated `bootstrapSessionRefresh()` when a session hint exists in `sessionStorage` **or** the current path is protected (`/admin`, `/profile`). Guards wait for `bootstrapped` before redirecting.
- **After login** — admins go to `/admin`, regular users to `/profile`.

Admin users can return to the public landing via the **«На сайт»** topbar link (full navigation to `/`, not client-side React routing).

## API Overview

Base URL: `http://localhost:8000/api/v1`

| Area        | Endpoints                                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Health**  | `GET /health`                                                                                                                 |
| **Auth**    | `POST /auth/register`, `/login`, `/logout`, `/refresh`, `/verify-email`, `/forgot-password`, `/reset-password`                |
| **Profile** | `GET/PATCH /users/me`, `POST /users/me/password`, `POST /users/me/avatar`                                                     |
| **Content** | `GET /content/pages`, `GET /content/pages/{slug}`, admin: `POST/PATCH/DELETE /content/pages`, `GET /content/pages/manage/all` |
| **Admin**   | `GET/PATCH /admin/users`, `POST /admin/users`, `PATCH /admin/users/{id}/password`, `GET /admin/stats`, `GET/PATCH /admin/settings`, `GET /admin/diagnostics/report`, `GET /admin/activity-feed`, `POST /admin/ui-activity`, `GET /admin/server-log`, `GET /admin/secrets`, `POST /admin/secrets/reveal` |
| **Media**   | `GET /media/files/{path}`                                                                                                     |

OpenAPI docs (when `ENABLE_DOCS=true`): [http://localhost:8000/api/v1/docs](http://localhost:8000/api/v1/docs)

## Database Migrations

```bash
cd apps/api
alembic upgrade head    # apply schema
alembic downgrade -1    # rollback one revision
```

Tables: `users`, `user_profiles`, `refresh_tokens`, `password_reset_tokens`, `email_verification_tokens`, `content_pages`.

**Security constraints** (PostgreSQL, migration `20260714_0004`):

- `CHECK` on `users.role`, `users.status`, `content_pages.status`
- Superuser rule: `is_superuser=true` only when `role=admin`
- Indexes on `expires_at` for token tables

Expired tokens are cleaned up on API startup (`cleanup_expired_tokens`, 30-day retention).

## Auth Email (SMTP)

- Verify/reset use one-time opaque tokens (SHA-256 hash + pepper in DB, TTL 1 hour); raw token omitted from production email bodies
- Env: `SMTP_HOST`, `SMTP_PORT`, `SMTP_FROM`, `FRONTEND_URL`, `EMAIL_DELIVERY_MODE`
- Docker dev: `EMAIL_DELIVERY_MODE=memory` (no real SMTP required)
- Local SMTP: Mailpit/Mailhog on `localhost:1025` (`SMTP_HOST=localhost`, `SMTP_PORT=1025`)
- Tests: `EMAIL_DELIVERY_MODE=memory` (in-memory outbox)

## Profile & Avatar (MinIO)

- `GET/PATCH /api/v1/users/me`, `POST /api/v1/users/me/password`, `POST /api/v1/users/me/avatar`
- Avatar: jpeg/png/webp, max 2 MB, re-encoded via Pillow (SVG rejected)
- Storage env: `STORAGE_MODE` (`s3` or `memory`), `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_BUCKET`
- Local dev: MinIO on `localhost:9000` (console `9001`), bucket `compton` (created on API startup)
- Tests: `STORAGE_MODE=memory` (in-memory file store, no MinIO)

## Admin Panel

- Route: `/admin` (`AdminGuard`, role `admin`)
- UI: WESP-style **Ant Design** shell with fixed left sidebar, content topbar, and a dedicated admin theme system
- Topbar actions:
  - **Light/Dark** — toggles isolated admin theme (preference persisted in `localStorage`)
  - **«На сайт»** — opens the static landing at `/` (`index.html`) via full navigation
  - **Logout** — revokes refresh cookie and redirects to `/login`
- Reload UX: no blocking «Loading…» screens; admin routes preload the current admin background (`#f6f6f4` in Light, `#1f2229` in Dark) to avoid flash
- Sections:
  - **Users** — list/create/patch role, status, password
  - **Content** — CMS CRUD
  - **Security** *(superuser only)* — runtime toggles + Install Secrets reveal
  - **Diagnostics** *(superuser only)* — security health checks (JWT, CORS, DB credentials, SSL mode, token table size, install secrets lock)
  - **Activity** — admin audit feed + server log tail
- Business rules: last admin protected, no self-demotion, no self-block; critical endpoints require `is_superuser`

### Auth UI (zootech)

Auth pages (`/login`, `/register`, `/forgot-password`, `/reset-password`, `/verify`) use a WESP-inspired zootech card layout with organic theme tokens (`#48816d`, centered card, icon inputs). `AppHeader` is hidden on auth routes and in `/admin`.

## Tests

```bash
# Frontend unit/component (coverage ≥ 85%)
pnpm --filter web test:ci

# Same, inside Docker web container (when pnpm is not installed on host)
docker compose --profile docker-web exec web sh -c "cd apps/web && pnpm test:ci"

# Backend unit/integration (coverage ≥ 90%)
cd apps/api && python -m pytest --cov=app --cov-fail-under=90

# E2E regression (Playwright §15.7, 16 critical scenarios)
pnpm --filter web e2e
```

### E2E (Playwright)

- `pnpm --filter web e2e` starts a dedicated API (`:8001`) and Vite (`:5175`) — does not conflict with dev on `:5173` or Docker API on `:8000`
- Uses SQLite + `EMAIL_DELIVERY_MODE=memory` + `ENABLE_TEST_ROUTES=true`
- Test email tokens: `GET /api/v1/test/emails/latest-token` (only when test routes enabled)
- Reuse running API: `E2E_START_API=false E2E_API_URL=http://localhost:8000 pnpm --filter web e2e`
- Install browsers once: `pnpm --filter web exec playwright install chromium`

## Troubleshooting

| Problem | Solution |
| ------- | -------- |
| **`docker compose up` fails: install.env missing** | Run `python apps/api/scripts/bootstrap_install.py` before first start |
| **API exits: `password authentication failed for user "compton_app"`** | Postgres volume was initialized before bootstrap. Reset local dev data: `docker compose --profile docker-web down -v`, bootstrap again, then `docker compose --profile docker-web up -d --build`. See [docs/secrets-recovery.md](docs/secrets-recovery.md) |
| **Login failed** with correct credentials | Check API: `curl http://localhost:8000/api/v1/health`. Ensure `apps/web/.env` exists for local frontend. Restart: `docker compose restart web` or `pnpm --filter web dev` |
| **401 on `/auth/refresh` in browser console (guest)** | Expected for logged-out users on public pages — refresh is skipped unless a session hint or protected path (`/admin`, `/profile`) triggers bootstrap |
| **Logged out after F5 on `/admin`** | Usually a failed refresh (expired cookie) or stale Docker web build. Rebuild: `docker compose --profile docker-web up -d --build web`. Log in again if the refresh cookie expired |
| **«На сайт» in admin does nothing / goes to login** | Must use full navigation to `/` (static landing), not React Router. Ensure topbar action is `href="/"`, then rebuild web container if behavior persists |
| **White flash on admin reload** | `app.html` preloads admin background before React mount. Verify `localStorage.wespAdminTheme` and rebuild web if stale assets are served |
| **Sidebar should stay visible while scrolling** | Admin sidebar is fixed on desktop (`position: fixed`, `height: 100vh`) and switches back to normal flow on mobile (`<=768px`) |
| **Port 5173 already in use** | Stop Docker web: `docker compose --profile docker-web stop web`. Or stop local Vite |
| **Frontend in Docker: missing modules / esbuild errors** | Rebuild: `docker compose --profile docker-web up -d --build web`. Do not run `pnpm install` on the host for the Docker workflow |
| **Hot-reload not working in Docker (Windows/macOS)** | Enabled via `CHOKIDAR_USEPOLLING=true`. Restart: `docker compose --profile docker-web restart web` |
| **Admin panel missing Security/Diagnostics tabs** | Log in as `admin@compton.example` (superuser), not `ops@compton.example` |
| **Need DB password for DBeaver** | Admin → Security → Install Secrets → Reveal DB password (superuser), then `docker-compose.dev-ports.yml` |
| **Lost `install.env` / DB auth failed** | See [docs/secrets-recovery.md](docs/secrets-recovery.md). Do not regenerate secrets if Postgres volume already exists |
| **CORS errors in browser console** | Keep `VITE_USE_API_PROXY=true` (default in dev). Do not call `localhost:8000` directly from the browser |

## Security Highlights

All cryptographic primitives live in a single module (`apps/api/app/core/crypto.py`); `security.py` and `media_signing.py` re-export from it.

| Layer | Mechanism |
| ----- | --------- |
| **Passwords** | bcrypt cost 12 with per-user salt (embedded in hash); shared denylist |
| **Access JWT** | HS256, short TTL, in-memory on frontend only |
| **Refresh tokens** | HttpOnly cookie (`Path=/api/v1/auth`), rotation + family reuse detection; SHA-256 hash with server-side **pepper** |
| **Email/reset tokens** | Opaque tokens, SHA-256 + pepper in DB; raw token never stored |
| **Media URLs** | HMAC-SHA256 signed paths with TTL |
| **Install secrets** | `secrets.token_*` generation; generate-once + lock; superuser reveal (audited) |

**Auth & API**

- Refresh token rotation and reuse-detection (family revoke)
- Rate limiting and brute-force lockout (`ENABLE_RATE_LIMIT=true` in Docker compose)
- Pending/blocked users rejected on refresh; frontend clears session on `403` (`ACCOUNT_BLOCKED`, `EMAIL_NOT_VERIFIED`)
- Origin/Referer validation on cookie-based auth endpoints
- `TRUSTED_PROXY_IPS` — only listed proxies may influence client IP via `X-Forwarded-For`
- Email bodies omit raw tokens in production (`EMAIL_DELIVERY_MODE=memory` or `ENABLE_TEST_ROUTES=true` only)

**Data & infra**

- PostgreSQL/Redis/MinIO on internal Docker network by default (no host ports)
- DB CHECK constraints, connection pool tuning, startup token cleanup
- CMS HTML sanitization (bleach) with allowed URL protocols: `http`, `https`, `mailto`
- Signed avatar URLs; RBAC + superuser guards on admin routes
- Admin password policy on user create/reset

**Production guards** (`APP_ENV=production` — API refuses to start if):

- `ENABLE_TEST_ROUTES=true`
- `ENABLE_DOCS=true`
- `ENABLE_RATE_LIMIT=false`
- `COOKIE_SECURE=false`
- Default DB credentials (`user:pass`) or placeholder JWT secrets
- `DATABASE_URL` without `sslmode=require`

## Related Documentation

- [docs/secrets-recovery.md](docs/secrets-recovery.md) — recover from lost install secrets
- [docs/security-checklist.md](docs/security-checklist.md) — pre-production security checklist
- [docs/TZ.md](docs/TZ.md) — full technical specification

## MVP Status (Phase 1)

| #   | Feature                       | Status |
| --- | ----------------------------- | ------ |
| 1.1 | PostgreSQL + Alembic + seed   | done   |
| 1.2 | Auth + SMTP (verify/reset)    | done   |
| 1.3 | Profile CRUD + avatar (MinIO) | done   |
| 1.4 | Content pages                 | done   |
| 1.5 | Admin panel (Ant Design + zootech auth UI) | done   |
| 1.6 | E2E regression §15.7          | done   |