Initial commit — Performance West telecom compliance platform

Includes: API (Express/TypeScript), Astro site, Python workers,
document generators, FCC compliance tools, Canada CRTC formation,
Ansible infrastructure, and deployment scripts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docserver/README.md

@@ -0,0 +1,112 @@
+# Performance West — Document Conversion Worker
+
+Converts DOCX files to pixel-perfect PDFs using Microsoft Word on a Windows VM.
+No HTTP server, no open ports, no SSH tunnel needed.
+
+## Architecture
+
+The Windows VM connects **outbound** to MinIO only. No inbound access required.
+
+```
+Linux workers container       MinIO (S3)           Windows VM (any NAT)
+       │                         │                        │
+       ├─ PUT docx ─────────────→│                        │
+       │  to-convert/{id}.docx   │←─ poll every 3s ───────┤
+       │                         │   list to-convert/      │
+       │                         │                        ├─ Word.SaveAs PDF
+       │                         │←─ PUT pdf ─────────────┤
+       │                         │  converted/{id}.pdf     │
+       │                         │←─ DELETE docx ──────────┤
+       │←─ GET pdf ──────────────┤                        │
+       │  converted/{id}.pdf     │                        │
+       └─ DELETE pdf ────────────┤                        │
+```
+
+The `pdf_converter.py` on the Linux side uploads the DOCX and polls until
+the PDF appears (up to `DOCSERVER_TIMEOUT` seconds, default 120).
+
+If the Windows VM is unavailable or slow, conversion falls back automatically
+to LibreOffice headless in the workers container (70-80% fidelity).
+
+## Windows VM Requirements
+
+- Windows 10/11 Pro or Windows Server 2022
+- Microsoft Word (Office 2021+ recommended)
+- Python 3.12+ (from python.org — check "Add to PATH")
+- Outbound internet access to MinIO (HTTPS, no inbound ports needed)
+
+## Setup
+
+Run `install.ps1` as Administrator in PowerShell on the Windows VM:
+
+```powershell
+cd C:\path\to\docserver
+
+.\install.ps1 `
+  -MinioEndpoint  "minio.performancewest.net" `
+  -MinioPort      443 `
+  -MinioSecure    $true `
+  -MinioAccessKey "your_access_key" `
+  -MinioSecretKey "your_secret_key"
+```
+
+This will:
+1. Verify Python and Word are installed
+2. Install `pywin32` and `minio` Python packages
+3. Copy `docserver_worker.py` to `C:\docserver\`
+4. Write `C:\docserver\docserver.env` with your MinIO credentials
+5. Register a Task Scheduler task (`PW-DocserverWorker`) that starts at login
+6. Start the worker immediately
+
+The worker must run as a **logged-in user** — Word COM requires an interactive
+Windows session and will fail under a system service account.
+
+## How to access MinIO externally
+
+The Windows VM needs to reach MinIO. Options:
+
+**A. MinIO exposed externally (simplest)**
+Set `MINIO_ENDPOINT=minio.performancewest.net`, `MINIO_PORT=443`, `MINIO_SECURE=true`.
+Add a MinIO nginx vhost on the Debian server that proxies port 443 → MinIO port 9000.
+
+**B. VPN / WireGuard**
+Connect the Windows VM to the same private network as the Debian server.
+Use the internal IP `192.168.x.x:9000` and `MINIO_SECURE=false`.
+
+**C. Cloudflare Tunnel**
+Run a cloudflared tunnel on the Debian server and connect from Windows.
+
+## Heartbeat monitoring
+
+The worker writes `minio://{bucket}/docserver-heartbeat.json` every 60 seconds:
+
+```json
+{
+  "status": "ok",
+  "word_version": "16.0",
+  "host": "WINVM-01",
+  "ts": "2026-04-05T12:00:00+00:00"
+}
+```
+
+Read this to check if the worker is alive. The `health_check()` function in
+`pdf_converter.py` reads it automatically.
+
+## Manual test
+
+Place a `.docx` file in `minio://{bucket}/to-convert/test.docx` and watch for
+`minio://{bucket}/converted/test.pdf` to appear within a few seconds.
+
+Using the MinIO web console (`http://server:9001`) or `mc` CLI:
+
+```bash
+mc cp mydoc.docx local/performancewest/to-convert/test.docx
+# wait a few seconds...
+mc ls local/performancewest/converted/
+mc cp local/performancewest/converted/test.pdf ./test.pdf
+```
+
+## Logs
+
+Worker logs: `C:\docserver\logs\worker.log`
+Task Scheduler log: Event Viewer → Task Scheduler → `PW-DocserverWorker`