# 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. [x] `docker-compose up` exposes port 3000.
2. [x] `http://localhost:3000` loads a styled HTML page (verifying static asset serving + SSR).
3. [x] `http://localhost:3000/health` returns JSON.
4. [x] Folder structure established as defined above.

## 5. Implementation Plan
- [x] **Infrastructure**: Create `src/web/` directory structure.
- [x] **Core Logic**: Implement `WebServer` class in `src/web/server.ts` with routing and static file serving logic.
- [x] **Integration**: Bind `WebServer.start()` to `src/index.ts`.
- [x] **Docker**: Update `docker-compose.yml` to map port `3000:3000`.
- [x] **Views**: Create a basic `BaseLayout` function in `src/web/views/layout.ts`.
- [x] **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`.