- JavaScript 56.5%
- TypeScript 41.4%
- CSS 2%
|
|
||
|---|---|---|
| docs | ||
| server | ||
| shared | ||
| web | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| CLAUDE.md | ||
| docker-compose.dev.yml | ||
| docker-compose.yml | ||
| Dockerfile | ||
| LICENSE | ||
| NOTICE | ||
| README.md | ||
| STATUS.md | ||
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.
| Signing in | The client's summary |
|---|---|
![]() |
![]() |
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 |
|---|---|
![]() |
![]() |
| People | Activity builder |
|---|---|
![]() |
![]() |
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 testcd web && npm testcd web && npx playwright testfor browser testscd web && SCREENSHOTS=1 npx playwright test e2e/screenshots.spec.tsregenerates the images indocs/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 |
| 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.






