107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# 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/`](./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.
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|