Fantasy Politics

product-fpol is a private, noncommercial fantasy-style game for friends around the 2026 US midterm elections. The eventual game will have a candidate draft, trades, and final standings based on real-world candidate performance.

This repository currently contains only the foundation: a basic webpage, a C++ HTTP server, and development tooling. There are no accounts, candidate records, league rules, drafts, trades, scores, or election data yet.

Prerequisites

Linux with Docker available to your user and Python 3 for the backend tooling.
Node.js 22.12 or newer and npm for the frontend; CI uses Node 24.
Network access on the first setup to fetch npm packages, the build image, and public Conan dependencies.

Modulus supplies the shared C++23/GCC 12 build environment, Conan/CMake integration, formatting, and editor configuration. Ligo supplies HTTP networking and routing. Both are consumed from the public khodo Conan registry; sibling source checkouts are not required. Package reads do not need registry credentials.

Development

From the repository root, configure and build the backend:

python3 modulus.py configure
python3 modulus.py build
python3 modulus.py run

In another terminal, start the frontend:

cd frontend
npm ci
npm run dev

Open http://127.0.0.1:5173. Vite reloads frontend edits and proxies /api to http://127.0.0.1:8080. Rebuild and restart the backend after C++ changes. Both configured ports fail explicitly when occupied.

Check the backend directly or through Vite:

curl http://127.0.0.1:8080/api/health
curl http://127.0.0.1:5173/api/health

The only application API is GET /api/health, which returns HTTP 200 using Ligo's existing envelope:

{"ok":true,"payload":{"status":"ok"}}

Unknown routes return HTTP 404 with Ligo's error envelope. Health is a process liveness check; there is no database or external data source to check yet.

Built frontend

Build the frontend, then serve it with the C++ backend:

npm --prefix frontend run build
python3 modulus.py run -- --web-root frontend/dist

Open http://127.0.0.1:8080. Node is only needed to build the assets; the C++ server serves the resulting HTML, JavaScript, and CSS. Assets are loaded at startup, so restart the server after rebuilding. npm --prefix frontend run preview is also available on port 4173, with the same API proxy, for local frontend previews.

The server accepts --host ADDRESS, --port PORT, --web-root DIRECTORY, and --help. It defaults to 127.0.0.1:8080 and API-only mode. An explicit web root must contain index.html. Only exact registered asset paths are served; there is no SPA fallback or query-string normalization in this scaffold. Hidden files and symlinks are excluded, and /api is reserved. Use only the Vite build output as the web root.

The Modulus runner binds the server to 0.0.0.0 inside its container, publishing port 8080 only on the host's loopback interface. An installed executable defaults to loopback. Port 0 selects an available port and is useful for tests. SIGINT and SIGTERM stop the server cleanly.

Checks and editor support

python3 modulus.py test
python3 modulus.py format --check
npm --prefix frontend run build

The frontend build includes strict TypeScript checking. npm --prefix frontend run typecheck runs that check alone. The backend CTest smoke suite starts real server processes to check health, routing, binary/static assets, startup errors, port conflicts, and shutdown.

Check both native configurations:

python3 modulus.py configure --all
python3 modulus.py build --all
python3 modulus.py test --all

Configure generates ignored editor files. Customize modulus.json, not those generated files; refresh compile databases with python3 modulus.py lsp. C++ and Python use the shared Modulus formatting policy and full names rather than aliases. Run python3 modulus.py format before committing.

The checked-in modulus.py is copied unchanged from Modulus's canonical modulus/bootstrap.py. configure --update refreshes shared tooling and packages. --no-remote on configure uses only the project-local Conan cache, which must already contain dependencies. Keep build outputs and downloaded tooling untracked.

The Gitea workflow checks the frontend build plus backend formatting, debug/release builds, and tests. It has no publishing or deployment job. Its direct build mode provisions the shared compiler and tools on the CI runner, following the sibling repositories' convention. CMake installation installs the backend executable; distribute built frontend assets separately when deployment is added.

Future product work

Define league rules, eligible races and candidates, drafting, trades, and scoring together before introducing domain models.
Add persistence when needed; Noto is the existing SQLite library to evaluate then.
Choose an election data source later. Live feeds, scraping, update schedules, and correction handling remain undecided; this scaffold makes no external election requests.
Add accounts, invitations, deployment, and operational requirements when the game needs them.

Keep reusable networking and infrastructure in the shared libraries and product rules in this repository. Luma and Sonus are native UI/audio libraries and are not dependencies of this web application.

5.3 KiB Raw Blame History