# 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.