elchess.org

ElChess

ElChess is the Bun workspace monorepo for the first serious build of elchess.org: an Astro-owned chess web surface, an Elysia API, PostgreSQL as the durable store, and Caddy for local edge-style routing.

BUILD.md is the execution authority for the repo. docs/architecture.md records current repo truth and points back to the build plan.

Current scope

This repository currently implements:

• Phase 0 bootstrap for the monorepo, shared configs, docs, and local ops wiring.
• Phase 1 product shell work for the Astro web app, initial design tokens, UI primitives, responsive app routes, and Playwright smoke coverage.
• Phase 2 auth foundation work for SQL migrations, durable users / profiles / sessions tables, secure cookie-backed sessions, and protected API routes.
• Placeholder chess gameplay, matchmaking, ratings, review logic, and realtime orchestration are still intentionally unfinished.

Local setup

1. Install Bun 1.3+ and Docker Desktop.
2. Run bun install.
3. Run bun run dev.
4. Open http://localhost:8080 for the Caddy-routed web surface.
5. Open http://localhost:8080/api/health for the API health endpoint.
6. Open http://localhost:8080/auth/sign-up to exercise the current auth shell.

bun run dev starts the Astro and Elysia dev servers, attempts to bring up PostgreSQL and Caddy through Docker Compose, and runs the checked-in SQL migrations against the configured database. If port 8080 is already occupied, export CADDY_PORT=<open-port> before running the command. If Docker is unavailable, the web and API apps still start directly on ports 4321 and 3001, but the PostgreSQL-backed auth flows will need a reachable database.

Scripts

• bun run dev starts the local stack, applies migrations, and launches the app dev servers.
• bun run db:migrate applies forward SQL migrations.
• bun run db:reset rebuilds the schema from the checked-in migrations.
• bun run build builds the shared packages, API, and Astro web app.
• bun run lint runs Biome across the repo.
• bun run typecheck runs package tsc checks and astro check.
• bun run test runs Bun tests for the implemented packages and API.
• bun run test:auth runs the API auth integration suite.
• bun run test:e2e runs Playwright smoke coverage.
• bun run check:proxy verifies Caddy routing to the web app and API.
• bun run verify runs the baseline quality bar.

Repo shape

apps/
  api/           Elysia HTTP API with cookie-backed auth flows
  web/           Astro pages, layouts, and Vue islands
packages/
  contracts/     Shared Zod contracts
  chess-core/    Placeholder board shell helpers
  ui/            Design tokens, primitives, and first Vue island
db/
  migrations/    Forward SQL migrations
  seeds/         Local seed assets (not implemented yet)
docs/
  architecture.md
ops/
  scripts/       Local dev and verification helpers

Frontend boundary

Astro owns routes, layouts, document composition, and the authenticated shell. Vue is introduced only for the live board-adjacent island in the game room shell, which is still the first place BUILD.md says richer client state is justified. The current boundary is documented in docs/architecture.md.