AuroraBot-discord/tickets/2026-01-07-web-server-foundation.md

2026-01-07-web-server-foundation: Web Server Infrastructure Foundation

Status: Done Created: 2026-01-07 Tags: infrastructure, web, core

1. Context & User Story

• As a: Developer
• I want to: Establish a lightweight, integrated web server foundation within the existing codebase.
• So that: We can serve internal tools (Workbench) or public pages (Leaderboard) with minimal friction, avoiding complex separate build pipelines.

2. Technical Requirements

Architecture

• Native Bun Server: Use Bun.serve() for high performance.
• Exposure: The server port must be exposed in docker-compose.yml to be accessible outside the container.
• Rendering Strategy: Server-Side Rendering (SSR) via Template Literals.
  • Why? Zero dependencies. No build step (like Vite/Webpack) required. We can simply write functions that return HTML strings.
  • Client Side: Minimal Vanilla JS or a lightweight drop-in library (like HTMX or Alpine from CDN) can be used if interactivity is needed later.

File Organization (src/web/)

We will separate the web infrastructure from game modules to keep concerns clean.

• src/web/server.ts: Main server class/entry point.
• src/web/router.ts: Simple routing logic.
• src/web/routes/: Individual route handlers (e.g., home.ts, health.ts).
• src/web/views/: Reusable HTML template functions (Header, Footer, Layouts).
• src/web/public/: Static assets (CSS, Images) served directly.

API / Interface

• GET /health: Returns { status: "ok", uptime: <seconds> }.
• GET /: Renders a basic HTML landing page using the View system.

3. Constraints & Validations (CRITICAL)

• Zero Frameworks: No Express/NestJS.
• Zero Build Tools: No Webpack/Vite. The code must be runnable directly by bun run.
• Docker Integration: Port 3000 (or env PORT) must be mapped in Docker Compose.
• Static Files: Must implement a handler to check src/web/public for file requests.

4. Acceptance Criteria

1. docker-compose up exposes port 3000.
2. http://localhost:3000 loads a styled HTML page (verifying static asset serving + SSR).
3. http://localhost:3000/health returns JSON.
4. Folder structure established as defined above.

5. Implementation Plan

• Infrastructure: Create src/web/ directory structure.
• Core Logic: Implement WebServer class in src/web/server.ts with routing and static file serving logic.
• Integration: Bind WebServer.start() to src/index.ts.
• Docker: Update docker-compose.yml to map port 3000:3000.
• Views: Create a basic BaseLayout function in src/web/views/layout.ts.
• Env: Add PORT to config.ts / env.ts.

Implementation Notes

• Created src/web directory with router.ts, server.ts and subdirectories routes, views, public.
• Implemented WebServer class using Bun.serve.
• Added basic CSS and layout system.
• Added PORT to src/lib/env.ts (default 3000).
• Integrated into src/index.ts to start on boot and graceful shutdown.
• Fixed unrelated typing issues in src/commands/admin/note.ts and src/db/indexes.test.ts to pass strict CI checks.
• Verified with bun test and bun x tsc.