Casino Niagara Poker

Architecture Report

Now that the site is no longer constrained by GitHub Pages, the strongest path is to keep the public website static and move operations, runtime state, APIs, and admin tooling into a small VPS-backed layer.

Published 2026-05-19 Static-first VPS architecture Discussion report

Keep Static public pages, JSON-driven frontend, simple Python pipeline, and atomic VPS releases.

Improve Runtime data ownership, Caddy/systemd config, API boundaries, cache headers, and operational visibility.

Avoid A full framework migration unless the product direction becomes a richer logged-in/admin application.

Clarifying Questions

No answers are required before using this as a planning baseline, but these questions should be answered before implementation:

Should this remain mostly static and public, or move toward logged-in/admin features?
Is the VPS the long-term production home, or just a better current host than GitHub Pages?
Are we optimizing more for handoff/sale value, or for Kevin-operated convenience?

Current Shape

templates/ is the source of truth for HTML pages.
website/ is generated deploy output served by the VPS.
Python scripts scrape and transform data into public JSON payloads.
The frontend fetches data from /data/*.json.
Deploys use timestamped releases and an atomic current symlink.
A lightweight Python service handles Android test signup behind Caddy.

Best Improvements

1. Add A Real Internal API Layer

Keep static pages, but stop treating every changing thing as a public JSON file written into the webroot. Good candidates are /api/live-games, /api/bad-beat, /api/tournaments/upcoming, /api/health, and private admin status endpoints.

Benefits: cleaner caching rules, better error responses, less public operational/debug data, easier app integration, and a clear path to private/admin features.

2. Move Runtime State Out Of Release Directories

Scripts currently write into the live web release tree. That works, but runtime state living inside deploy artifacts is fragile. Store runtime/generated data under /var/lib/cnp/data, then serve selected public JSON through Caddy aliases or API routes. Keep release directories immutable after deploy.

3. Track Caddy Config In The Repo

The repo should own a Caddyfile template or runbook for cache rules, security headers, reverse proxy routes, and health checks. This improves reliability and handoff value.

4. Introduce One Small CNP Service

Do not build a giant app. Build one small Python service/package for endpoints, health checks, shared config, shared logging, background job status, and optional SQLite storage. The existing signup service proves the pattern.

5. Use SQLite For Operational State

JSON files are fine for public payloads. SQLite is better for Android signups, scraper run history, latest scrape status, alert dedupe, admin notes, manual overrides, and cached upstream scrape results.

6. Build An Operator/Admin Surface

Add a private page/API protected by basic auth or a token. It should show last live-games run, last bad-beat run, stale/failing jobs, safe manual run hooks, Android signup list/export, current deployed release, and rollback notes.

7. Improve Deployment Separation

The release/symlink deploy is solid. Tighten it with immutable website releases, runtime data outside releases, tracked Caddy/systemd templates, one install/bootstrap script, one rollback command, and a health check that verifies HTML, JSON/API, and signup endpoint behavior.

8. Retire GitHub Pages Assumptions

Legacy names like GITHUB_DIR and fallback GitHub publishing paths make the architecture mentally muddy. Rename them over time to SITE_DIR or PUBLIC_DIR, and remove or clearly fence rollback-only code.

9. Improve Asset Caching And Versioning

Replace manual CSS query strings with content-hashed asset filenames or build-generated version tokens. It prevents stale CSS/JS behavior without hand-editing version strings.

10. Keep The Frontend Simple

The current frontend is already suitable for a small data-driven public site. Do not jump to React, Next, or Vite unless the product direction becomes a richer admin application.

Recommended Priority

Phase 1

Move runtime JSON/state out of release directories.
Track Caddy and systemd deployment config.
Add health endpoints/checks.
Add sane Caddy cache and security headers.

Phase 2

Create one small CNP backend service with SQLite.
Move signup and future APIs into it.
Add a private admin/status page.

Phase 3

Clean legacy GitHub naming and publish paths.
Add hashed asset/versioning.
Add a one-command handoff/bootstrap package.

Final Take

The winning architecture is not "make it dynamic". It is "keep the public site static, make operations dynamic."

Static frontend for speed and resilience; small backend for live state, admin, APIs, health, and storage. That gets the upside of leaving GitHub Pages without dragging in framework complexity for no reason.