# CLAUDE.md — Booking Proxy Claude

## Project Overview

Production-grade **Playwright-powered browser proxy** that streams live web sessions to authenticated users. Handles ~200 concurrent browser sessions with anti-bot mitigation, real-time DOM streaming, JWT auth, and full Docker/Kubernetes deployment.

**Two frontend clients:**
- `client/` — generic proxy UI
- `client-cahoo/` — CahooTravel-branded UI (active development target)

---

## Architecture

```
Backend (Express + Playwright + WebSocket)  →  port 3008
client/            (Next.js 14)             →  port 3009
client-cahoo/      (Next.js 14)             →  port 3010
Redis                                       →  session/cache store
```

Key source files:
- [src/index.ts](src/index.ts) — Application entry, middleware, graceful shutdown
- [src/config/index.ts](src/config/index.ts) — All env config with validation
- [src/core/BrowserPool.ts](src/core/BrowserPool.ts) — Session pool lifecycle
- [src/core/BrowserSession.ts](src/core/BrowserSession.ts) — Individual browser session wrapper
- [src/routes/proxy.routes.ts](src/routes/proxy.routes.ts) — Main proxy REST API (~3100 lines)
- [src/routes/auth.routes.ts](src/routes/auth.routes.ts) — Auth: register, login, Google/Apple OAuth
- [src/websocket/StreamingServer.ts](src/websocket/StreamingServer.ts) — Real-time DOM streaming over WebSocket
- [src/utils/urlRewriter.ts](src/utils/urlRewriter.ts) — URL rewriting for proxied links/CSS

---

## Development Commands

```bash
# Install all dependencies (backend + both frontends)
make install

# Run everything locally
make dev

# Run individual services
make dev-server        # backend on :3008
make dev-client        # client on :3009
make dev-client-cahoo  # cahoo on :3010

# Build TypeScript
npm run build

# Lint
npm run lint

# Tests
npm test
```

### Docker / Kubernetes

```bash
make build          # Build Docker image
make start          # docker-compose up (includes Redis, Prometheus, Grafana)
make stop
make restart

# Kubernetes
helm install playwright-proxy ./helm/playwright-proxy \
  --namespace playwright-proxy \
  --set config.sessionSecret=... \
  --set config.jwtSecret=...
```

---

## Environment Variables

Copy `.env.example` to `.env`. Required:
```
SESSION_SECRET=<random string>
JWT_SECRET=<random string>
```

Optional:
```
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
APPLE_CLIENT_ID / NEXT_PUBLIC_APPLE_CLIENT_ID / NEXT_PUBLIC_APP_URL
DECODO_API_URL / DECODO_AUTH          # upstream scraping proxy
PORT, HOST, NODE_ENV, LOG_LEVEL
MAX_CONCURRENT_SESSIONS, BROWSER_TIMEOUT_MS, IDLE_TIMEOUT_MS
ALLOWED_ORIGINS                        # CORS
METRICS_ENABLED=true                   # Prometheus endpoint at /metrics
```

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | Node.js 18+, TypeScript 5, Express 4 |
| Browser automation | Playwright 1.40 (Chromium) |
| Real-time | WebSocket (`ws`) |
| Auth | JWT (`jsonwebtoken`), bcryptjs, Google OAuth, Apple Sign-In |
| Cache/sessions | Redis (ioredis) |
| Monitoring | Prometheus (`prom-client`), Grafana |
| Logging | Winston |
| Frontend | Next.js 14, React 18, Tailwind CSS, Zustand |
| Infra | Docker, docker-compose, Kubernetes + Helm |

TypeScript config: ES2022 target, CommonJS modules, strict mode, no unused locals/params.

---

## API Reference

### Auth endpoints
```
POST /api/auth/register
POST /api/auth/login          → returns JWT
POST /api/auth/google
POST /api/auth/apple
```

### Proxy endpoints (require Bearer JWT)
```
POST   /api/proxy/session/create
POST   /api/proxy/session/:id/navigate
GET    /api/proxy/session/:id/html
GET    /api/proxy/session/:id/screenshot
POST   /api/proxy/session/:id/interact
DELETE /api/proxy/session/:id
GET    /api/proxy/pool/stats
```

### System
```
GET /health
GET /metrics   (if METRICS_ENABLED=true)
WS  /ws        (real-time DOM streaming)
```

### Demo credentials
```
Email: demo@example.com
Password: demo123
```

---

## Code Conventions

- TypeScript strict mode — no `any` without justification
- All types defined in [src/types/index.ts](src/types/index.ts)
- Logging via Winston ([src/utils/logger.ts](src/utils/logger.ts)) — never use `console.log` in server code
- Rate limiting in [src/middleware/rateLimit.ts](src/middleware/rateLimit.ts)
- Auth middleware in [src/middleware/auth.ts](src/middleware/auth.ts)
- `client-cahoo/` is the actively maintained branded frontend; `client/` is the generic reference client

---

## Key Notes

- `proxy.routes.ts` is intentionally large (~3100 lines) — the main proxy logic lives there
- Anti-bot mitigations are in [src/utils/user-agents.ts](src/utils/user-agents.ts) and BrowserSession headers
- Upstream proxy (Decodo/Smartproxy) is optional; sessions work without it
- Session pooling handles idle timeout and memory cleanup automatically