Values card-sort app (career & life values) — career.tealmaker.com/cards
  • JavaScript 56.5%
  • TypeScript 41.4%
  • CSS 2%
Find a file
Ben Reed ae7039532b Record the deploy, privacy approval and license in the status
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 09:43:38 -06:00
docs Record the deploy, privacy approval and license in the status 2026-10-16 09:43:38 -06:00
server License the code under AGPL-3.0-or-later, carving out the deck text 2026-10-16 09:43:38 -06:00
shared Add values card-sort app (career.tealmaker.com/cards) 2026-10-13 10:52:59 -06:00
web License the code under AGPL-3.0-or-later, carving out the deck text 2026-10-16 09:43:38 -06:00
.dockerignore Add values card-sort app (career.tealmaker.com/cards) 2026-10-13 10:52:59 -06:00
.env.example Add audit retention, legal holds and hard client deletion (#8, #13) 2026-10-15 21:33:04 -06:00
.gitignore Rewrite docs for IT administrators and add README screenshots 2026-10-14 14:42:04 -06:00
CLAUDE.md Add audit retention, legal holds and hard client deletion (#8, #13) 2026-10-15 21:33:04 -06:00
docker-compose.dev.yml Add SMTP mail outbox, worker and Mailpit dev compose (#3) 2026-10-13 17:35:35 -06:00
docker-compose.yml Add audit retention, legal holds and hard client deletion (#8, #13) 2026-10-15 21:33:04 -06:00
Dockerfile Add values card-sort app (career.tealmaker.com/cards) 2026-10-13 10:52:59 -06:00
LICENSE License the code under AGPL-3.0-or-later, carving out the deck text 2026-10-16 09:43:38 -06:00
NOTICE License the code under AGPL-3.0-or-later, carving out the deck text 2026-10-16 09:43:38 -06:00
README.md License the code under AGPL-3.0-or-later, carving out the deck text 2026-10-16 09:43:38 -06:00
STATUS.md Record the deploy, privacy approval and license in the status 2026-10-16 09:43:38 -06:00

Values Card Sort

A web app for the values card-sort exercise used in career counselling. Clients sort value cards (Career Values, Life Values) into Very Important, Somewhat Important and Not Important. They note what each value means to them, flag cards to discuss, and share a printable summary with their counsellor.

It's built for a counselling practice to run on its own server. Clients and counsellors sign in with an emailed link or a password, and each person sees only what their role allows.

Sorting a card: the drawn card in the centre, with buttons for each column

Signing in The client's summary
Sign-in page with email link and password options Summary page listing sorted cards, flags and notes, ready to copy or print

What it does

  • Two starter activities: Career Values (44 cards) and Life Values (48 cards).
  • Activity builder: staff create custom activities with 2–7 columns, import cards from CSV or plain paste, preview as a client, and assign selected activities. Owners can edit assigned definitions; removed cards retain existing responses.
  • Navigation bar: every screen shows the pages your role can use (Sessions, Client dashboard, Activity builder, and for the owner People and Outbox), who is signed in, and Log out.
  • Client dashboard: counsellors follow linked clients and per-activity progress, invite and assign in one step, start new sessions, resend or revoke invitations, and open read-only boards and summaries. Owners see all clients.
  • People and Outbox (owner): create users of any role, link counsellors to clients, change roles or disable accounts, place a client on legal hold, permanently delete a client, and check or retry emails.
  • Data retention: expired sign-in records and old emails are purged automatically. Most audit rows are purged after 24 months (progress and completion records stay with their session), and audit IP addresses are blanked after 90 days. Both periods are configurable, and a legal hold exempts that client's records.
  • Built-in help: ? buttons open short help on signing in, sorting, summaries, the dashboard, access history, the builder, roles and client deletion.
  • Access history: records staff reads and live-sync admissions; IP addresses are visible only to owners.
  • Email notices: assignment emails and notices on each session/activity's first completion, with configurable counsellor and owner completion recipients.
  • Sort on any device: draw a card, then tap a column or drag the card onto it. Keyboard shortcuts (⌥/Alt + V, S or N to place, D to draw, F to flag) work for faster sorting.
  • Notes and flags: a note on each card ("what this means to me"), a reflection per activity, and 🚩 flags for cards to discuss.
  • Summary / Share: copy the results as text, or print / save as PDF.
  • Live sync: a session open on two devices stays in step.
  • Theme: choose Light (default), Dark, or Auto (system) at the top of any screen. The choice is saved on this device; printing always uses a light theme.

Who sees what

Role Who it's for Can do
Owner The practice lead or IT contact Everything: add staff and clients, link counsellors to clients, archive sessions, place legal holds, delete clients, see the email outbox. Other people's sessions are read-only
Counsellor (stored role admin) A counsellor See their linked clients and those clients' sessions (read-only), add clients, create sessions for them
Client A person doing the exercise Their own sessions only
Sessions Client dashboard
The owner's Sessions page under the navigation bar, with Summary / Share and archive actions for each session Client dashboard: client cards with each assignment's status, progress bar and cards placed, beside the invite and new-session forms
People Activity builder
People page: every account with its role and status, invitation and account actions, and the Create user and Counsellor links forms Activity builder: the activity list beside the editor for a new activity with custom columns

Sign-in is by one-time email link (valid 15 minutes) or by password once a user sets one. Every page and API call is checked on the server, and anything not explicitly allowed is refused.

Running it

  • To host it for a practice, start with the self-hosting guide. It covers installing with Docker, email setup, creating the first owner, backups, upgrades, privacy and troubleshooting.
  • For reverse proxy, release and rollback details, see the deployment guide.
  • For clients, the client guide is a plain-language page the practice can link to or print: signing in, sorting cards, notes and flags, and saving the summary.
  • For developers: the API is in docs/api.md, and the local setup is below.

Try it locally (Docker)

This needs Docker. It starts the app with Mailpit, a test mailbox that catches every email the app sends:

docker network create npm_default   # once; the compose file expects a proxy network
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build -d
docker exec career-app node server/cli.js bootstrap-owner --email you@example.com --name "Your name"

Open http://localhost:3000/cards/, enter your email and choose Email a sign-in link. The link arrives in Mailpit at http://localhost:8025.

Developing without Docker

Use Node 22 (the better-sqlite3 database driver compiles against it).

cd web && npm ci && npm run build && cd ..
cd server && npm ci
export DB_PATH=./dev.db PUBLIC_BASE_URL=http://localhost:3000/cards/ \
  PRACTICE_NAME="Dev practice" SMTP_FROM=dev@example.test MAIL_MODE=log
node cli.js bootstrap-owner --email you@example.test --name "You"
node index.js &                                  # http://localhost:3000/cards/
node cli.js login-link --email you@example.test  # prints a sign-in link

Tests:

  • cd server && npm test
  • cd web && npm test
  • cd web && npx playwright test for browser tests
  • cd web && SCREENSHOTS=1 npx playwright test e2e/screenshots.spec.ts regenerates the images in docs/images/.

How it's built

Part Tech Location
Web app Vite + plain TypeScript (no framework) web/
Server Node 22, Fastify, SQLite (better-sqlite3) server/
Sign-in and permissions Hashed cookie sessions, argon2id passwords, CSRF checks, rate limits server/auth.js, server/policy.js
Email SMTP outbox with retries server/mail.js
Live sync Server-Sent Events server/streams.js, web/src/sync.ts
Card data SQLite, seeded from server/migrations/002-seed.json server/db.js
Packaging One Docker image and Docker Compose Dockerfile, docker-compose.yml

One container serves the app and its API under /cards/ on port 3000, and keeps all data in one SQLite file on a Docker volume.

Roadmap

The issues are tracked in this repo:

# Feature State
1 Sign-in with roles (RBAC) Released
2 Decks as separate activities Done
3 Email (SMTP) for sign-in links, invites and notices Done
4 Admin dashboard (client progress, invitations) Released
5 Activity Builder (custom decks and columns) Released
6 Jane App integration Researched; waits on Jane partner access (report)
7 Light / dark / auto theme Done
8 Data retention (purges, legal hold, client deletion) Expired sign-in rows are purged (released). Audit retention, legal holds and client deletion are done on main; not yet released
9 Navigation bar, page layout and built-in help Released
10 Read-only staff review; ADMIN_CAN_EDIT removed Done on main; not yet released

Project status: STATUS.md.

License

The code is licensed under the GNU Affero General Public License v3.0 or later. If you host a modified version for other people, you must offer them its source. The starter deck text (card titles and descriptions) is not under the AGPL: it's included with the owning practice's permission, for use with this app. See NOTICE before you redistribute or host a fork.