Proto-Vortex Update Jan 14
# Dev Log #2 — Repo Split (Web / Server / Docs)
Date: 2026-01-14
TL;DR
This update turns the simulator from a “single repo that contains everything” into three focused repos:
- humanode-network/vortex-simulator-web — UI only
- humanode-network/vortex-simulator-server — backend only (API + DB + tests)
- humanode-network/vortex-simulator-docs — docs only (this repo)
The goal is to make development, CI, and deployment predictable: frontend changes don’t drag backend history, backend changes don’t ship docs, and docs can evolve without breaking builds.
What changed since Dev Log #1 (as features)
1) The simulator is now split into three repos
We separated responsibilities cleanly:
- Web repo contains only the React/Rsbuild UI, static assets, and client-side types.
- Server repo contains the simulation backend: API routes, Postgres schema/migrations, seed scripts, and the Node test suite.
- Docs repo contains the paper reference, the simulation specs, the ops runbook, and dev logs.
This reduces merge conflicts and avoids “accidental coupling” (e.g., docs changes triggering backend CI).
2) Cloudflare/Wrangler assumptions were removed
The simulator backend is no longer documented as “Cloudflare Workers/Pages Functions first”.
Docs now describe the backend as a Node API service (deployable on a VM behind a reverse proxy like Caddy), with:
- explicit scheduler calls for era ticks/rollups (POST /api/clock/tick, rollup endpoints)
- a Postgres-backed persistence mode (DATABASE_URL)
- an in-memory fallback mode (for quick demos)
3) Local dev workflow is now “web + server”
The recommended local workflow is now explicit:
- Run the API server from vortex-simulator-server (default http://127.0.0.1:8788)
- Run the UI from vortex-simulator-web (dev proxy routes /api/* to the API server)
All local-dev docs were updated to match the split.
4) CI expectations are repo-specific
Each repo now has its own “what does yarn test mean?”:
- Web: yarn test should validate the frontend buildability (typecheck + build).
- Server: yarn test runs the Node test suite that exercises API behavior and scenarios.
- Docs: no runtime tests; it’s documentation-only.
5) Docs are re-aligned to the split (this repo)
The simulation docs were updated to stop referring to a monolithic codebase layout (e.g., “api/, db/, src/ live in the same repo”).
Docs now consistently reference:
- server code as vortex-simulator-server/...
- web code as vortex-simulator-web/...
- runtime config as SIM_CONFIG_JSON / /sim-config.json (local dev file: vortex-simulator-server/public/sim-config.json)
Why this split matters
- Reviewability: PRs are smaller and scoped (UI vs backend vs docs).
- Deployability: server can be deployed independently; web can be hosted statically.
- Stability: fewer accidental breaking changes (especially around env/config/CI).
- Velocity: teams can work in parallel without constantly rebasing unrelated directories.
What’s next
Immediate follow-ups after the split:
- Lock a single source of truth for the API contract and keep vortex-simulator-web/src/types/api.ts in sync with it.
- Confirm deployment runbook for the Node server (VM + Caddy + Postgres), then remove any remaining “old platform” setup steps from contributor workflows.
- Re-run an end-to-end smoke test with a real validator wallet:
create proposal → pool vote → chamber vote → visible in UI (and, for system proposals, verify the system side-effects are reflected).