converted to proper npm sveltekit project
This commit is contained in:
C-West8
111
README.md
111
README.md
@@ -1,23 +1,106 @@
|
||||
# Project SDE Meeting Toolkit
|
||||
|
||||
## Contents
|
||||
A shared, multi-user web app with two meeting tools:
|
||||
|
||||
| File | Purpose |
|
||||
- **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 |
|
||||
|---|---|
|
||||
| SDE_Field_Problem_Workshop_v5.html | Field problem workshop: Problem Map (capture, clusters, dot voting) → Breadcrumbs (with AI draft) → Actions. Pre-loaded with the July 21 session baseline. |
|
||||
| SDE_Scope_Lock_Meeting_Suite.html | Scope lock meeting suite: Scope Boundary Board, MVP Priority Ranker, Decision Registry, Micron Pilot Readiness. |
|
||||
| construction-breadcrumbs.skill | Claude skill encoding the breadcrumb methodology (EVM, CII AWP, Last Planner, first-time quality). Install via Save skill in Claude to use it in any chat. |
|
||||
| `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. |
|
||||
|
||||
## Running the workshop tool
|
||||
## How the shared-workspace model works
|
||||
|
||||
- **With AI features:** open the HTML file as an artifact inside Claude (upload it to a chat and ask Claude to render it, or keep it in a Project). The AI draft fields button on Breadcrumbs requires the Claude environment and network connectivity.
|
||||
- **Without AI:** open the file directly in any browser. Everything works except the AI button, which fails politely.
|
||||
- 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.
|
||||
|
||||
## Persistence
|
||||
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.
|
||||
|
||||
- The workshop tool holds state in the session only. **Save JSON before closing** and Load JSON to resume. The exported JSON is the working record; the Export summary markdown is the meeting artifact.
|
||||
- The Scope Lock suite autosaves to the browser (localStorage) on the machine where it is opened; its Export button produces the durable record.
|
||||
## Notes / possible next steps
|
||||
|
||||
## Reset behavior
|
||||
|
||||
The workshop tool's Reset returns to the clustered July 21 baseline (43 problems in 7 root clusters, 6 breadcrumbs, 5 actions). The Scope Lock suite's Reset returns to its pre-seeded starting state.
|
||||
- **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.
|
||||
|
||||
Reference in New Issue
Block a user