Skip to content

feat(api): rewrite server with Bun, Hono, and versioned game modules - #127

Draft
rohanseshan wants to merge 7 commits into
mainfrom
rohanseshan/lvt-243-ground-up-server-rewrite
Draft

rohanseshan wants to merge 7 commits into
mainfrom
rohanseshan/lvt-243-ground-up-server-rewrite

Conversation

@rohanseshan

@rohanseshan rohanseshan commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

What changed

Lovat needs a server that contributors can extend without spreading each year's game rules through HTTP handlers and database columns. This ground-up implementation adds an independent Bun 1.4.4/Hono API, shared API contracts, and pure versioned game modules. It replaces all 137 inventoried legacy route registrations with domain-owned handlers and native Bun training WebSockets. Registration coverage alone does not establish complete behavioral parity.

Game modules define report schemas, timing/scoring rules, typed metrics, calculation dependencies, aggregation, plausibility and prediction. New games use versioned JSON report storage; explicit adapters retain the 2026-v1 contracts. A fictional second game exercises different fields, clocks, scores, structured metrics and alliance size through real HTTP/PostgreSQL tests. It is not registered in production.

Requests use scoped batched reads, bounded work/payloads, short revision-aware caching, local JWT verification and a controlled database pool. Transactional outbox jobs deliver invalidations/email/Slack outside requests. See qualification evidence and annual-game workflow.

Refs: LVT-243, LVT-370 through LVT-378, LVT-381.

Areas affected

  • Server (replacement API and extracted definitions)
  • Dashboard
  • Collection
  • Website
  • Shared documentation, CI, or deployment

Contracts and data

  • No API, report-schema, authentication, deep-link, season-metric, or database contract changed
  • Every affected producer and consumer was updated together
  • Tenant and source-team visibility was reviewed
  • No credentials, production data, or private scouting notes are included

Shared packages retain independent npm lockfiles; the replacement app uses bun.lock and local package links. Additive migrations introduce revision/outbox storage, event-scoped Slack threads and versioned GameReport data. Legacy adapters intentionally tighten protected writes and unify inconsistent metrics; CSV/default pagination and other compatibility differences are documented. Flutter client adoption, generic report management/worker reassessment and future-game training/schedules remain follow-ups.

Verification

Commands run locally:

  • In apps/api, Bun 1.4.4: bun install --frozen-lockfile, bun run test (35 pass), bun run test:integration (3 pass), bun run lint, bun run format:check, bun run inventory:check (137/137 registrations).
  • In packages/api: npm test (9 pass), npm run generate:check, npm run lint, npm run format:check.
  • In packages/games: npm test (3 pass), npm run lint, npm run format:check.
  • In apps/server, Node 22.20.0: npm test (1,454 pass after merging current main), npm run typecheck, npm run typecheck:test. Earlier rewrite milestone also passed build; lint had 0 errors and 78 existing warnings.
  • Worker after merging current main: bun test on Bun 1.4.4 (80 pass), bun run typecheck; on pinned Bun 1.3.14, mode guards plus outbox integration (7 pass). Railway npm test (7 pass) / npm run typecheck and CI selector/report tests (10 pass). Server npm run test:integration -- test/crossAppContract.integration.test.ts (3 pass). Root structure script passes with a Bash rg function invoking the Windows rg.exe.
  • Earlier worker milestone: all 64 tests pass on local Bun 1.4.0; the pinned Bun 1.3.14 run passes the 5 new outbox tests but hangs in a catalog test/cleanup on local Windows/PostgreSQL 18. Linux CI qualification remains required; this has not been established as a pre-existing failure.

Integration tests use disposable loopback PostgreSQL and run-specific Redis namespaces. Bun/Hono local p95 at 1,000 reports: 128.04 ms cold / 1.64 ms warm; at 5,000: 624.33 / 1.74 ms. These are diagnostic results, not production guarantees or controlled old/new comparisons. The combined fixture/client/server maximum run peaked around 1.07 GiB RSS: the low-memory target is not yet qualified. See the qualification document for workload/sample limits.

Merged current main through 7df804b into this branch in 047295b, preserving finite worker windows and requiring continuous mode for API effect delivery. This updates the branch only; the PR remains unmerged.

Deployment

Draft: existing production traffic remains on apps/server. CI/Docker target Bun/Hono for the replacement; the worker effect consumer is opt-in. Docker is unavailable locally, so the image build was not run. Real Auth0/Slack/email staging, isolated memory profiling, soak/load tests, consumer compatibility and rollback rehearsal are required before cutover. Nothing has been merged or deployed.

Move legacy OpenAPI definitions and Collection report validation into an independent @lovat/api package. Add typed v3 analysis contracts, a client helper, and reproducible OpenAPI artifacts while preserving legacy route behavior.

Refs: LVT-371
Add an isolated v3 API with locally verified JWTs, mandatory source scoping, batched report/event reads, typed metric definitions and deterministic aggregation. Bound requests, datasets, concurrency and database work; add route inventory, fixtures, synthetic benchmarks and CI while retaining the existing server for unmigrated workflows.

Refs: LVT-370, LVT-372, LVT-373
@railway-app

railway-app Bot commented Nov 13, 2026

Copy link
Copy Markdown

This PR was not deployed automatically as @rohanseshan does not have access to the Railway project.

In order to get automatic PR deploys, please add @rohanseshan to your workspace on Railway.

Keep cache revisions and email or Slack delivery durable across API retries and worker failures. Lease each effect and fan out warnings per channel to avoid repeating successful deliveries.

Refs: LVT-375, LVT-376
Implement report lifecycle, scoped management, analysis views, onboarding, training, exports and Slack without delegating to the old server. Bound cold work and cache memory, persist delivery effects, and publish reusable lifecycle contracts.

Keep rollout gated on consumer compatibility and staging. Patch the shared validator against collection memory exhaustion.

Refs: LVT-243, LVT-371, LVT-372, LVT-374, LVT-375, LVT-376
Serve the independent rewrite with Hono and native Bun HTTP and WebSockets. Preserve scoped access, bounded work, payload limits, and graceful shutdown on the new runtime.

Move game rules, schemas, metrics, aggregation, and prediction into a pure package. Persist future game reports with explicit versions and JSON data, while retaining typed 2026 compatibility adapters. Prove the generic path with a fictional second game.

Refs: LVT-243

Refs: LVT-381
@rohanseshan rohanseshan changed the title feat(api): start ground-up rewrite with shared contracts and metric engine feat(api): rewrite server with Bun, Hono, and versioned game modules Nov 20, 2026
Preserve finite worker execution windows and the replacement API outbox consumer. Reject effect delivery in finite modes before database access, and retain shared API dependency selection in CI and Railway build watches.

Refs: LVT-243

Refs: LVT-376
data: {
name,
userId: user(ctx).id,
keyHash: createHash("sha256").update(apiKey).digest("hex"),
Hydrate bounded payload batches and reduce completed match groups instead of retaining whole event datasets. Recheck access inside short database snapshots so avoiding per-event joins preserves tenant and reliability restrictions.

Add isolated server benchmarks, soak checks, real HTTP rollback rehearsal, and cryptographic/provider fixtures. Build and smoke-test the pruned production image in CI under a memory limit. Remove an obsolete legacy forwarder to restore unit coverage.

Refs: LVT-243

Refs: LVT-378

Refs: LVT-381
await db.user.create({
data: {
id,
email: id.replace("|", "-") + "@example.invalid",

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants