Initial commit — encrypted chat server + Python clients (v0.8.5)

E2E encrypted chat (X3DH + Double Ratchet, Signal Protocol). Server: asyncio TCP + TLS, MySQL. Clients: PyQt6 GUI + CLI. Secrets (.env, TLS keys, Cloudflare token), runtime data and mobile clients (separate repos) are gitignored. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 18:22:39 -04:00
commit 2e7b72307d
24 changed files with 21821 additions and 0 deletions
--- a/KEC-18_operational_cost_analysis.md
+++ b/KEC-18_operational_cost_analysis.md
@@ -0,0 +1,289 @@
+# KEC-18 Operational Cost Analysis
+
+Date: 2026-03-27
+
+## Executive Summary
+
+- The absolute cheapest workable production setup for roughly 100 concurrent users is one Contabo `Cloud VPS 10` at `EUR4.50/mo`, plus a domain, free Let's Encrypt TLS, free-tier SMTP, and low-cost object backup. That lands around `EUR5.8-6.5/mo` (`USD6.7-7.5/mo`) if email volume stays inside a free tier.
+- The more realistic "do not hate yourself later" floor is about `EUR11-16/mo` (`USD12.7-18.5/mo`) once you include a paid SMTP plan or more backup headroom.
+- For 500 to 1,000 total users, Contabo remains extremely cheap. The main constraint is not raw VPS price; it is operational headroom, backup discipline, and the app's current default connection cap.
+- For 5,000 total users, I would stop using a single-node layout. Split app and MySQL onto separate VPSes and keep uploads/backups external or on a storage-optimized node.
+
+## What I Sized From The Codebase
+
+Relevant defaults in the current code:
+
+- `protocol.py` defaults to `MAX_MESSAGE_BYTES=1 MiB`, `MAX_IMAGE_BYTES=5 MiB`, `MAX_FILE_BYTES=50 MiB`.
+- `server.py` defaults to `MAX_CONNECTIONS_GLOBAL=200`, `MAX_CONNECTIONS_PER_IP=10`, `MAX_UPLOADS_GLOBAL=200`, `MAX_UPLOADS_PER_USER=5`.
+- `db.py` defaults to `DB_POOL_SIZE=10`.
+- `server.py` defaults to `THREAD_POOL_SIZE=40`.
+- `README.md` and `scaling.md` indicate the server is an asyncio TCP relay with synchronous MySQL calls pushed behind `asyncio.to_thread()`, which is lightweight for small deployments but still means DB latency and connection pooling matter.
+
+Implication:
+
+- `100 concurrent users` is feasible on a very small VPS.
+- `More than 200 simultaneously connected devices` is not feasible with the current default connection limit unless configuration is raised and load-tested.
+- File storage, not CPU, becomes the first recurring cost question if usage shifts from chat-heavy to attachment-heavy.
+
+## Assumptions
+
+To make the tiers comparable, I used these planning assumptions:
+
+- The `500`, `1,000`, and `5,000` tiers are treated as total users, not fully concurrent users.
+- Peak concurrent devices:
+  - 100-user tier: about 100
+  - 500-user tier: about 75 to 125
+  - 1,000-user tier: about 125 to 175
+  - 5,000-user tier: about 300 to 500
+- Average retained encrypted upload footprint:
+  - 100 users: 100 GB
+  - 500 users: 250 GB
+  - 1,000 users: 500 GB
+  - 5,000 users: 1 TB
+- SMTP use is limited to registration codes and lightweight transactional mail, not marketing mail.
+- EUR to USD conversion uses the ECB reference `1 EUR = 1.1539 USD` visible on 2026-03-27 in the ECB currency converter.
+
+## Current Vendor Pricing Used
+
+### Contabo
+
+Official Contabo pricing page shows:
+
+- `Cloud VPS 10`: `3 vCPU`, `8 GB RAM`, `75 GB NVMe`, `32 TB traffic`, `EUR4.50/mo`
+- `Cloud VPS 20`: `6 vCPU`, `12 GB RAM`, `100 GB NVMe`, `32 TB traffic`, `EUR7.00/mo`
+- `Cloud VPS 30`: `8 vCPU`, `24 GB RAM`, `200 GB NVMe`, `32 TB traffic`, `EUR14.00/mo`
+- `Cloud VPS 40`: `12 vCPU`, `48 GB RAM`, `250 GB NVMe`, `32 TB traffic`, `EUR25.00/mo`
+- `Storage VPS 10`: `2 vCPU`, `4 GB RAM`, `300 GB SSD`, `EUR4.50/mo`
+- `Storage VPS 20`: `3 vCPU`, `8 GB RAM`, `400 GB SSD`, `EUR7.00/mo`
+
+Note: Contabo also publishes separate location-fee pricing. For example, the location-fee page shows `Cloud VPS 10` in `United States (Central)` at `EUR0.95/mo` extra, for `EUR5.45/mo` total. Base prices above are the standard pricing page numbers.
+
+### Domain, TLS, SMTP, Backup, Monitoring, Agent Costs
+
+- Domain: Porkbun shows `.com` at `USD11.08/yr`, which is about `EUR9.60/yr` or `EUR0.80/mo`.
+- TLS: Let's Encrypt certificates are free.
+- SMTP:
+  - MailerSend free plan: `500 emails/month`
+  - MailerSend Hobby: `EUR5.15/mo` for `5,000 emails/month`
+  - MailerSend Starter: pricing page shows `EUR25/mo` and `50,000 emails/month`
+- Backup/object storage:
+  - Backblaze B2 pricing page shows `USD6/TB/mo` pay-as-you-go.
+  - First `10 GB` is free.
+- Monitoring:
+  - Self-hosted Uptime Kuma can be run on your own server at zero direct license cost.
+  - Managed alternative: UptimeRobot free plan exists; paid plans start at about `USD8/mo`.
+- OpenAI / Codex API:
+  - OpenAI pricing page currently shows `gpt-5.4` standard at `USD2.50 / 1M input tokens` and `USD15.00 / 1M output tokens`.
+  - `gpt-5.4-mini` standard is `USD0.75 / 1M input` and `USD4.50 / 1M output`.
+
+## Recommended Infrastructure By Tier
+
+### Tier A: Minimum Viable, about 100 concurrent users
+
+Recommended stack:
+
+- 1 x `Cloud VPS 10`
+- Let's Encrypt
+- 1 `.com` domain
+- Backblaze B2 for backups
+- MailerSend free or Hobby depending email volume
+
+Why this is enough:
+
+- 8 GB RAM is adequate for Python app + MySQL on one box at this size.
+- 75 GB NVMe is enough if uploads are modest and older media is backed up externally.
+- 32 TB traffic is far above what this workload should consume.
+
+Estimated monthly cost:
+
+- VPS: `EUR4.50` / `USD5.19`
+- Domain amortized monthly: `EUR0.80` / `USD0.92`
+- Backup at about 100 GB retained: about `EUR0.47` / `USD0.54`
+- TLS: `EUR0`
+- SMTP:
+  - Free-tier case: `EUR0`
+  - Safer paid case: `EUR5.15` / `USD5.94`
+
+Total:
+
+- Absolute floor: about `EUR5.77/mo` / `USD6.65/mo`
+- Safer operating floor: about `EUR10.92/mo` / `USD12.60/mo`
+
+### Tier B: About 500 total users
+
+Recommended stack:
+
+- 1 x `Cloud VPS 20`
+- Backblaze B2 backups
+- MailerSend Hobby
+
+Why:
+
+- More CPU and RAM headroom for MySQL buffering, background cleanup, and multi-device behavior.
+- 100 GB NVMe is enough for DB + hot uploads if colder data is backed up externally.
+
+Estimated monthly cost:
+
+- VPS: `EUR7.00` / `USD8.08`
+- Domain: `EUR0.80` / `USD0.92`
+- Backup at about 250 GB retained: about `EUR1.25` / `USD1.44`
+- TLS: `EUR0`
+- SMTP Hobby: `EUR5.15` / `USD5.94`
+
+Total:
+
+- About `EUR14.20/mo` / `USD16.38/mo`
+
+### Tier C: About 1,000 total users
+
+Recommended stack:
+
+- 1 x `Cloud VPS 30`
+- Backblaze B2 backups
+- MailerSend Hobby or Starter
+
+Why:
+
+- `24 GB RAM` gives useful cache headroom for MySQL and smoother bursts.
+- This is the point where a single node is still cheap, but monitoring and restore discipline matter more than raw VPS price.
+
+Estimated monthly cost:
+
+- VPS: `EUR14.00` / `USD16.15`
+- Domain: `EUR0.80` / `USD0.92`
+- Backup at about 500 GB retained: about `EUR2.55` / `USD2.94`
+- TLS: `EUR0`
+- SMTP Hobby: `EUR5.15` / `USD5.94`
+
+Total:
+
+- Lean setup: about `EUR22.50/mo` / `USD25.95/mo`
+
+If you want higher mail headroom:
+
+- Swap SMTP to Starter at `EUR25/mo`
+- New total: about `EUR42.35/mo` / `USD48.87/mo`
+
+### Tier D: About 5,000 total users
+
+Recommended stack:
+
+- 1 x `Cloud VPS 20` for app server
+- 1 x `Cloud VPS 20` for MySQL
+- Backblaze B2 backups for media + DB dumps
+- MailerSend Starter
+
+Why I would split here:
+
+- The current codebase is still operationally simple. A two-node layout buys more reliability than buying one oversized single VPS.
+- Separate failure domains help during DB spikes, backup jobs, and incident response.
+- This tier likely exceeds the current default `MAX_CONNECTIONS_GLOBAL=200` if user concurrency climbs, so configuration and load testing become mandatory.
+
+Estimated monthly cost:
+
+- App VPS: `EUR7.00` / `USD8.08`
+- DB VPS: `EUR7.00` / `USD8.08`
+- Domain: `EUR0.80` / `USD0.92`
+- Backup at about 1 TB retained: about `EUR5.15` / `USD5.94`
+- TLS: `EUR0`
+- SMTP Starter: `EUR25.00` / `USD28.85`
+
+Total:
+
+- About `EUR44.95/mo` / `USD51.87/mo`
+
+Alternative:
+
+- If you strongly prefer a single-node layout, `Cloud VPS 40` plus backups is still cheap, but I would consider it worse operationally than two smaller nodes.
+
+## Minimum Viable Budget Answer
+
+If the question is "what is the absolute minimum monthly spend to run this for about 100 concurrent users," the answer is:
+
+- Roughly `EUR5.8-6.5/mo` (`USD6.7-7.5/mo`) with:
+  - `Cloud VPS 10`
+  - one cheap domain
+  - free TLS
+  - free SMTP tier
+  - minimal external backup
+
+If the question is "what is the minimum I would actually recommend for production without pretending backups and mail do not exist," the answer is:
+
+- Roughly `EUR11-16/mo` (`USD12.7-18.5/mo`)
+
+## Additional Infrastructure Recommendations
+
+### TLS certificates
+
+- Use Let's Encrypt.
+- Direct recurring certificate cost: `EUR0`.
+
+### Domain
+
+- Budget about `EUR10/yr` to `EUR15/yr`.
+- Using current Porkbun `.com` pricing, a normal `.com` is about `EUR9.60/yr`.
+
+### Backups
+
+- Do not rely only on local VPS storage.
+- Cheapest clean option: nightly MySQL dumps + uploaded file backup to Backblaze B2.
+- Ballpark backup cost at current B2 pricing:
+  - 100 GB: about `EUR0.47/mo`
+  - 250 GB: about `EUR1.25/mo`
+  - 500 GB: about `EUR2.55/mo`
+  - 1 TB: about `EUR5.15/mo`
+
+### SMTP relay
+
+- Free tier is enough for early registration-code traffic.
+- Move to Hobby quickly once real users arrive; it is still cheap and removes needless friction.
+
+### Monitoring
+
+- Cheapest option: self-host Uptime Kuma.
+- Managed option: UptimeRobot free or paid.
+- I would treat managed monitoring as optional until there is paying traffic.
+
+## Agent Operational Cost Estimate
+
+These costs depend entirely on token volume, not server size.
+
+Using current OpenAI standard pricing:
+
+- `gpt-5.4`: `USD2.50 / 1M input`, `USD15.00 / 1M output`
+- `gpt-5.4-mini`: `USD0.75 / 1M input`, `USD4.50 / 1M output`
+
+Illustrative monthly spend per active engineering agent:
+
+- Light usage, `gpt-5.4-mini`:
+  - 10M input + 2M output
+  - about `USD16.50/mo` / `EUR14.30/mo`
+- Moderate usage, `gpt-5.4`:
+  - 10M input + 2M output
+  - about `USD55.00/mo` / `EUR47.66/mo`
+- Heavy usage, `gpt-5.4`:
+  - 40M input + 8M output
+  - about `USD220.00/mo` / `EUR190.66/mo`
+
+For a small team of 3 active agents, a realistic monthly AI tooling band is:
+
+- Lean: about `EUR43-50/mo`
+- Moderate: about `EUR143/mo`
+- Heavy: about `EUR570+/mo`
+
+## Risks And Constraints
+
+- The code currently defaults to `MAX_CONNECTIONS_GLOBAL=200`. If "500 users" or "1,000 users" means concurrent devices, current defaults are not enough.
+- The cheapest single-node layout mixes app, MySQL, and hot uploads on one VPS. That is acceptable early, but it increases recovery risk during disk or instance failure.
+- Attachment-heavy usage can outgrow cheap NVMe faster than message traffic will outgrow CPU.
+- SMTP, domain, and monitoring are trivial costs compared with the cost of not having backups.
+
+## Final Recommendation
+
+If I had to choose one path now:
+
+- Launch on `Cloud VPS 10` if the immediate target is only about `100 concurrent users` and budget is extremely tight.
+- Launch on `Cloud VPS 20` if you want a safer early-production baseline without materially changing cost.
+- Move to a split app/DB layout by the time you are targeting `5,000 total users` or any scenario above `200 concurrently connected devices`.
+
+In short: Contabo pricing is not the bottleneck here. Operational discipline, connection-limit tuning, and backup/storage policy are the real budget drivers once the app starts seeing real usage.