67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# 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).
|