Project SDE Meeting Toolkit

A shared, multi-user web app with two meeting tools:

Field Problem Workshop — capture field problems, cluster them into root problems, dot-vote, build "breadcrumb" trails to measurable outcomes, and assign actions. Includes an optional AI draft feature.
Scope Lock Meeting Suite — Scope Boundary Board, MVP Priority Ranker, Decision Registry, and Micron Pilot Readiness.

Unlike the original single-file HTML versions (kept in legacy/ for reference), everyone who opens the same link works from the same data, stored on a shared server. Edits autosave; a version check prevents two people from silently overwriting each other.

Tech stack

Piece	Choice	Why
Framework	SvelteKit (Svelte 5) + TypeScript	Frontend and server API in one project
Server	Node (`adapter-node`)	Runs as a plain server, easy to containerize
Database	PostgreSQL	Shared storage for all users
Packaging	Docker + docker-compose	One command to run the whole thing internally

Project layout

src/
  app.css                     shared design tokens + base styles
  lib/
    types.ts                  data shapes for both tools
    workspace.svelte.ts       client sync: load / autosave / poll / conflict handling
    toast.svelte.ts           shared toast controller
    components/               Toast, SyncBadge
    defaults/                 seeded baseline state for each tool
    server/
      db/                     Postgres pool + workspace repository
      ai.ts                   Anthropic proxy (holds the API key server-side)
  routes/
    +page.svelte              home / tool picker
    workshop/                 Field Problem Workshop
    scope-lock/               Scope Lock Meeting Suite
    api/
      workspaces/[tool]/[name]/         GET (load) + PUT (save)
      workspaces/[tool]/[name]/reset/   POST (reset to baseline)
      ai/draft/                         POST (AI breadcrumb draft)
db/init.sql                   database schema (runs once on first DB startup)
Dockerfile, docker-compose.yml
legacy/                       the original single-file HTML tools

Run it with Docker (recommended)

Requires Docker Desktop / Docker Engine.

# optional: enable the AI feature by putting a key in your shell/.env first
#   ANTHROPIC_API_KEY=sk-ant-...

docker compose up -d --build

Then open http://localhost:3000. To share on your network, others use http://<your-machine-ip>:3000.

docker compose down          # stop
docker compose down -v       # stop AND erase all saved data (reset the database)
docker compose logs -f app   # watch app logs

The database persists in a Docker volume (db_data), so your data survives restarts.

Run it for development (without Docker)

You need Node 20+ and a PostgreSQL you can connect to.

cp .env.example .env         # then edit DATABASE_URL (and ANTHROPIC_API_KEY if wanted)
npm install
# create the schema in your database:
psql "$DATABASE_URL" -f db/init.sql
npm run dev                  # http://localhost:5173

Other scripts: npm run build (production build), npm run preview (serve the build), npm run check (type-check).

Configuration

All config is via environment variables (see .env.example):

Variable	Purpose
`DATABASE_URL`	Postgres connection string. Set automatically by docker-compose.
`ANTHROPIC_API_KEY`	Enables the "AI draft" button. Leave blank to disable it (the button then fails politely).
`ANTHROPIC_MODEL`	Model for AI drafting (default `claude-sonnet-5`).
`PORT`	Server port (default 3000).
`ORIGIN`	Public URL of the app, e.g. `http://server:3000`. Needed by the Node server for form/security handling.

How the shared-workspace model works

Each tool has a named workspace (default: default) stored as one JSON document with a version number.
When you edit, the browser autosaves after a short pause, sending your changes plus the version you started from.
If a teammate saved first, the server rejects your save (HTTP 409) and hands back their current copy, which your page loads — so nobody's work is silently overwritten. The status badge in the header shows this.
Open pages poll every few seconds, so a teammate's saved changes show up without a manual refresh.

This fits turn-taking meeting use. It is not live character-by-character co-editing (like Google Docs). If that's needed later, the version/polling foundation here can be upgraded to websockets.

Notes / possible next steps

Authentication: there is none yet — anyone with the link can view and edit. The data model already has an updated_by column ready for it.
Multiple named workspaces: the API supports any name (/api/workspaces/workshop/<name>); the UI currently uses default. Adding a workspace picker is straightforward.
The .skill file in legacy/ is a separate Claude skill, unrelated to running the website.

4.9 KiB Raw Blame History