Bowler Chart

A small, self-hosted web app for a team to collaboratively build and report on a bowler chart (a.k.a. bowling chart) — tracking project and KPI status month by month.

• Everyone can view the whole chart.
• Each user can create/edit/delete only their own projects and KPIs.
• A single administrator manages users and color schemes.
• Material 3 UI (Beer CSS) with admin-defined, per-user-switchable color schemes.

Tech stack

Layer	Choice
Server	Node.js + Express
Database	SQLite (better-sqlite3)
Sessions	express-session + SQLite store
Passwords	bcryptjs
Hardening	helmet + double-submit CSRF tokens
UI	Beer CSS (Material 3) + Alpine.js, no build step
Theming	material-dynamic-colors (seed color → full palette)

Front-end libraries are vendored into public/vendor/ (no remote CDN calls).

Setup

npm install        # installs deps (needs Node 18+; tested on Node 24)
npm run vendor     # copies UI libs from node_modules into public/vendor
cp .env.example .env   # then edit .env (set ADMIN_PASSWORD + SESSION_SECRET)
npm start

Open http://localhost:3000 and sign in with the admin credentials from .env. The admin account and two starter color schemes are created automatically on first run (only when the database is empty).

Native module note: better-sqlite3 must be v12+ on Node 24 — earlier versions have no prebuilt binary for Node 24 and would require a C/Python build toolchain.

Project layout

server.js            Express bootstrap, middleware, route mounting
db/                  schema.sql + connection/seed (db/index.js)
src/
  auth.js            credential check, hashing, CSRF token
  middleware/        requireAuth, requireAdmin, csrf, requireOwnerOrAdmin
  routes/            auth, users, schemes, chart, projects, kpis, entries
public/              login.html, index.html, admin.html, css, js, vendor
scripts/vendor.js    copies UI libs into public/vendor

Data model

users → owns → projects → has → kpis → has 12 monthly → entries (value + manual status: green / amber / red / none). color_schemes define a seed color + light/dark mode; users pick a preferred one (falls back to the default).

Authorization

• View endpoints (GET /api/chart, GET /api/schemes) require only login.
• Mutations re-check ownership server-side: a user may modify a project (and its KPIs/entries) only if they own it; the admin may modify anything.
• All state-changing requests must include the X-CSRF-Token header (issued via GET /api/me and login).