forked from syntaxbullet/AuroraBot-discord
60 lines
3.2 KiB
Markdown
60 lines
3.2 KiB
Markdown
# 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`.
|