# 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

```sh
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).