Add landing page with auto-generated screenshots

.env.example

@@ -1,23 +1,19 @@
-# Database Configuration
-POSTGRESQL_CONNECTION_STRING=postgresql://user:password@localhost:5432/ws_scoring
-POSTGRES_USER=user
-POSTGRES_PASSWORD=password
-POSTGRES_DB=ws_scoring
-
-# Server Configuration
-PORT=3000
+# API Server
+API_PORT=3000
+API_CORS_ALLOWED_ORIGIN=http://localhost:5173
+API_CORS_DEV_ORIGIN=http://localhost:5173
 NODE_ENV=development
 
-# CORS Configuration
-CORS_ALLOWED_ORIGIN=http://localhost:5173
-
-# Vite Proxy Configuration (for docker-compose.dev.yml)
-API_TARGET=http://localhost:3000
+# Database (shared between postgres container and API)
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=ws_scoring
 
-# Vite Dev Server Port (used by vite.config.ts)
+# Vite/Frontend
 VITE_DEV_PORT=5173
-
-# API port exposed to frontend for WebSocket direct connections
+VITE_API_TARGET=http://localhost:3000
 VITE_API_PORT=3000
 
 # MCP DBHub port (for docker-compose.dev.yml)

.github/workflows/pages.yml

@@ -0,0 +1,41 @@
+name: Deploy Landing Page to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'landing_page/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: landing_page
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/screenshots.yml

@@ -0,0 +1,112 @@
+name: Generate Landing Page Screenshots
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Prevent screenshot commit from re-triggering
+concurrency:
+  group: screenshots
+  cancel-in-progress: false
+
+jobs:
+  screenshots:
+    name: Generate Screenshots
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:18-alpine
+        env:
+          POSTGRES_USER: user
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: ws_scoring
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      POSTGRES_HOST: localhost
+      POSTGRES_PORT: 5432
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: ws_scoring
+      PORT: 3000
+      CORS_ALLOWED_ORIGIN: http://localhost:5173
+      API_TARGET: http://localhost:3000
+      NODE_ENV: development
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install app dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run database migrations
+        run: bun run db:migrate
+
+      - name: Seed database
+        run: bun run db:seed
+
+      - name: Seed test users
+        run: bun run db:seed:users
+
+      - name: Build frontend
+        run: bun run build:app
+
+      - name: Start API server
+        run: |
+          bun run dev:api &
+          echo "Waiting for API server..."
+          for i in $(seq 1 30); do
+            curl -s http://localhost:3000/rpc > /dev/null && break
+            sleep 1
+          done
+          echo "API server ready"
+
+      - name: Start frontend dev server
+        run: |
+          bun run dev:app &
+          echo "Waiting for Vite dev server..."
+          for i in $(seq 1 30); do
+            curl -s http://localhost:5173 > /dev/null && break
+            sleep 1
+          done
+          echo "Vite dev server ready"
+
+      - name: Install Playwright
+        working-directory: e2e
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+
+      - name: Create screenshots directory
+        run: mkdir -p landing_page/screenshots
+
+      - name: Run screenshot tests
+        working-directory: e2e
+        env:
+          BASE_URL: http://localhost:5173
+          API_URL: http://localhost:3000
+        run: npx playwright test
+
+      - name: Commit and push screenshots
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add landing_page/screenshots/
+          git diff --staged --quiet || git commit -m "chore: update landing page screenshots [skip ci]"
+          git push

.gitignore

@@ -53,3 +53,10 @@ postgres-data/
 
 # Reviews ran locally
 reviews/
+
+# E2E tests
+e2e/node_modules/
+e2e/bun.lock
+e2e/package-lock.json
+e2e/test-results/
+e2e/playwright-report/

AGENTS.md

@@ -93,11 +93,14 @@ bun run db:seed              # Seed test data
 - **Private helpers**: camelCase with descriptive names
 
 ### Error Handling
-- **Custom error classes** extending `Error` (e.g., `HeatDoesNotExistError`)
-- **Type guards** for domain errors: `isDomainError(error)`
-- **Error middleware** wrapper: `withErrorHandling(async () => { ... })`
-- **Domain errors** map to HTTP status codes (400/404/500)
-- **Always log errors** with context
+- **`neverthrow` Result types**: Domain services return `Promise<Result<T, E>>` instead of throwing
+- **Custom error classes** extending `Error` (e.g., `HeatDoesNotExistError`) — used as the `E` in `Result<T, E>`
+- **`unwrapOrThrow(result)`**: API boundary utility that converts `err(domainError)` → `throw ORPCError`
+- **`domainErrorMapper` middleware**: Safety net for unexpected infrastructure errors → 500
+- **`getDomainErrorStatusCode(error)`**: Maps domain errors to HTTP status codes for legacy REST routes
+- **Error union types**: `HeatServiceError`, `BracketServiceError` for type-safe error handling
+- **Pattern**: Domain services validate and return `err(...)`, API handlers call `unwrapOrThrow()` or check `result.isErr()`
+- **Transactions**: Call `unwrapOrThrow(result)` inside `db.transaction()` so domain errors trigger rollback
 
 ### Domain-Driven Design Patterns
 - **Repository pattern**: Interfaces in `domain/`, implementations in `infrastructure/`

CLAUDE.md

@@ -252,3 +252,21 @@ describe("MyComponent", () => {
 - Simple presentational components (just display props)
 - Components that are better tested via integration/E2E tests
 - Styling/layout (use visual regression testing instead)
+
+## Landing Page
+
+The project has a public landing page at `landing_page/index.html` hosted on GitHub Pages.
+
+### Landing Page Maintenance
+
+When adding or changing user-facing features:
+- Update `landing_page/index.html` feature descriptions to reflect the change
+- If new screens/pages are added, consider adding Playwright screenshots in `e2e/screenshots.spec.ts` and updating the landing page layout
+- Screenshots are auto-regenerated on push to main via `.github/workflows/screenshots.yml`
+
+### E2E Screenshot Tests
+
+- E2E tests live in `e2e/` with their own `package.json` (Playwright, isolated from main app)
+- Run locally: `cd e2e && npm test` (requires app + seeded DB running)
+- Screenshots saved to `landing_page/screenshots/`
+- Test users created by `bun run db:seed:users` (judge1, judge2, headjudge)

README.md

@@ -15,6 +15,10 @@ a real project.
 Currently, I also intentionally don't focus on clean/component-based/reusable/testable frontend code (it is messy what
 the genie generated so far). This is fine ;) as I'll eventually throw it away and rebuild once I got user feedback.
 
+## See It In Action
+
+Check out the [WS Scoring Landing Page](https://danbim.github.io/ws-scoring/) to see the app in action with screenshots for judges, head judges, and spectators.
+
 ## Features
 
 - **PostgreSQL Database**: Relational database with Drizzle ORM for type-safe queries
@@ -50,13 +54,17 @@ Make sure you have a PostgreSQL instance running, e.g. by starting a correspondi
 docker run -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password -e POSTGRES_DB=ws_scoring -p 5432:5432 postgres:18-alpine
 ```
 
-Set the `POSTGRESQL_CONNECTION_STRING` environment variable with your database connection details:
+Configure the database connection using environment variables (or copy `.env.example` to `.env`):
 
 ```bash
-export POSTGRESQL_CONNECTION_STRING="postgresql://user:password@host:port/database"
+export POSTGRES_HOST=localhost
+export POSTGRES_PORT=5432
+export POSTGRES_USER=user
+export POSTGRES_PASSWORD=password
+export POSTGRES_DB=ws_scoring
 ```
 
-If not provided, it defaults to `postgresql://localhost:5432/postgres`.
+`POSTGRES_HOST` defaults to `localhost` and `POSTGRES_PORT` defaults to `5432` if not provided.
 
 #### Drizzle Database Migrations
 
@@ -234,10 +242,11 @@ The application will be available on the configured `PORT` (default: 3000).
 
 Create a `.env` file based on `.env.example`:
 
+- `POSTGRES_HOST` - PostgreSQL hostname (default: localhost)
+- `POSTGRES_PORT` - PostgreSQL port (default: 5432)
 - `POSTGRES_USER` - PostgreSQL username (required for production, no default)
 - `POSTGRES_PASSWORD` - PostgreSQL password (required for production, no default)
 - `POSTGRES_DB` - Database name (default: ws_scoring)
-- `POSTGRESQL_CONNECTION_STRING` - Full connection string (optional, overrides above)
 - `PORT` - API server port (default: 3000)
 - `CORS_ALLOWED_ORIGIN` - CORS allowed origin (default: http://localhost:5173 for dev, http://localhost:3000 for production)
 - `API_TARGET` - Target URL for Vite proxy (default: http://localhost:3000, or http://app:3000 in Docker)

__tests__/api/heat-routes.test.ts

@@ -379,7 +379,7 @@ describe("Heat API Routes", () => {
       expect(data.error).toContain("Validation error");
     });
 
-    it("should return 400 if heat does not exist", async () => {
+    it("should return 404 if heat does not exist", async () => {
       const heatId = getUniqueHeatId("nonexistent");
       const request = createWaveScoreRequest(heatId, {
         scoreUUID: "wave-1",
@@ -388,7 +388,7 @@ describe("Heat API Routes", () => {
       });
 
       const response = await handleAddWaveScore(request);
-      expect(response.status).toBe(400);
+      expect(response.status).toBe(404);
 
       const data = (await response.json()) as { error: string };
       expect(data.error).toContain("does not exist");

__tests__/api/middleware/error-handling.test.ts

@@ -19,6 +19,7 @@ import {
   RiderAlreadyInHeatError,
   RiderNotInHeatError,
   ScoreMustBeInValidRangeError,
+  ScoreNotFoundError,
   ScoreUUIDAlreadyExistsError,
 } from "../../../src/domain/heat/errors.js";
 
@@ -78,9 +79,18 @@ describe("error-handling middleware", () => {
       expect(getDomainErrorStatusCode(error)).toBe(404);
     });
 
+    it("should return 404 for HeatDoesNotExistError", () => {
+      const error = new HeatDoesNotExistError("test-heat");
+      expect(getDomainErrorStatusCode(error)).toBe(404);
+    });
+
+    it("should return 404 for ScoreNotFoundError", () => {
+      const error = new ScoreNotFoundError("test-score");
+      expect(getDomainErrorStatusCode(error)).toBe(404);
+    });
+
     it("should return 400 for heat domain errors", () => {
       expect(getDomainErrorStatusCode(new HeatAlreadyExistsError("test"))).toBe(400);
-      expect(getDomainErrorStatusCode(new HeatDoesNotExistError("test"))).toBe(400);
       expect(getDomainErrorStatusCode(new NonUniqueRiderIdsError())).toBe(400);
       expect(getDomainErrorStatusCode(new RiderNotInHeatError("test", "test"))).toBe(400);
       expect(getDomainErrorStatusCode(new ScoreMustBeInValidRangeError(15))).toBe(400);