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 from problem to measurable outcome, 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.

Everyone who opens the same link works from the same data, stored on a shared server. Edits autosave, and a version check stops two people from silently overwriting each other. The original single-file HTML versions are kept in legacy/ for reference.

Tech stack

SvelteKit (Svelte 5) + TypeScript — frontend and server API in one project
Node (@sveltejs/adapter-node) — runs as a plain server, easy to containerize
PostgreSQL — shared storage for all users (accessed with pg, no ORM)
Docker + docker-compose — one command to run the whole thing internally

Quick start (Docker)

Requires Docker Desktop / Docker Engine.

docker compose up -d --build

Open http://localhost:3000. To let others on your network in, they use http://<your-machine-ip>:3000.

docker compose down          # stop
docker compose down -v       # stop AND erase all saved data
docker compose logs -f app   # watch app logs

Data persists in a Docker volume (db_data), so it survives restarts.

To enable the AI draft feature, provide an Anthropic API key before starting — either export ANTHROPIC_API_KEY in your shell or put it in a .env file next to docker-compose.yml. Without a key the AI button simply fails politely; everything else works.

Local development (without Docker)

Needs Node 20+ and a PostgreSQL you can reach.

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

Scripts: npm run build (production build) · npm run preview (serve the build) · npm run start (run the built server) · 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. Blank = feature disabled.
`ANTHROPIC_MODEL`	Model for AI drafting (default `claude-sonnet-5`).
`PORT`	Server port (default 3000).
`ORIGIN`	Public URL the app is served from; used to validate POST origins.

Project layout

src/
  app.css                     shared design tokens + base styles
  app.html                    page shell
  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.svelte, SyncBadge.svelte
    defaults/                 seeded baseline state for each tool (index, workshop, scope-lock)
    server/
      db/index.ts             Postgres connection pool (lazy)
      db/workspaces.ts        load / save / reset with optimistic concurrency
      ai.ts                   Anthropic proxy (holds the API key server-side)
  routes/
    +layout.svelte            imports global CSS
    +page.svelte              home / tool picker
    workshop/+page.svelte     Field Problem Workshop
    scope-lock/+page.svelte   Scope Lock Meeting Suite
    api/
      workspaces/[tool]/[name]/+server.ts        GET (load) + PUT (save)
      workspaces/[tool]/[name]/reset/+server.ts  POST (reset to baseline)
      ai/draft/+server.ts                        POST (AI breadcrumb draft)
db/init.sql                   database schema (runs once on first DB startup)
static/favicon.svg
Dockerfile, docker-compose.yml
.gitea/workflows/build-image.yml   CI: build + push image on push to main
legacy/                       the original single-file HTML tools + the .skill file

How the shared-workspace model works

Each tool has a named workspace (the UI uses default) stored as one JSON document with a version number.
Editing 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 returns their current copy, which your page loads — so no one's work is silently overwritten. The header status badge reflects this.
Open pages poll every few seconds, so a teammate's saved changes appear without a manual refresh.

This fits turn-taking meeting use. It is not live character-by-character co-editing (like Google Docs); the version/polling foundation could be upgraded to websockets if that's ever needed.

Continuous integration (Gitea Actions)

.gitea/workflows/build-image.yml builds the Docker image and pushes it to Gitea's built-in container registry on every push to main, tagged :latest and :<commit-sha>.

It requires, on your Gitea instance: Actions enabled with a registered act_runner, that runner able to build images (host Docker socket mounted, or docker-in-docker), and the package registry enabled (on by default). The workflow uses the auto-injected token; if that lacks package-write scope, add a Personal Access Token with write:package as a repo secret named REGISTRY_TOKEN. Details are in the workflow file's header comments.

The `.skill` file

legacy/construction-breadcrumbs.skill is a Claude skill (a zip of instructions + a methodology knowledge base). It is not part of the website — it teaches Claude how to draft breadcrumb fields using construction methodology (EVM, CII AWP, Last Planner, first-time quality). The same knowledge is embedded server-side in src/lib/server/ai.ts, which powers the app's AI draft button. Install the skill in Claude (via "Save skill") to use the methodology in any chat.

Possible next steps

Authentication — none yet; anyone with the link can view and edit. The workspaces.updated_by column is already there for when it's added.
Multiple named workspaces — the API accepts any name (/api/workspaces/workshop/<name>); the UI currently hardcodes default. A workspace picker would be a small addition.

6.4 KiB Raw Blame History