From 108a690f66fb8851cddb44f378903d95d1656167 Mon Sep 17 00:00:00 2001
From: "n.siegfried" <n.siegfried@prime-controls.com>
Date: Mon, 15 Jun 2026 11:00:25 -0700
Subject: [PATCH] Add ONBOARDING.md project handoff/history
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Curated summary of architecture, decisions and rationale, commit timeline,
repo map, deploy pointers, and the pending Phase 2 work — so a teammate or a
fresh Claude Code session can pick up where we left off.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ONBOARDING.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 ONBOARDING.md

diff --git a/ONBOARDING.md b/ONBOARDING.md
new file mode 100644
index 0000000..af097e2
--- /dev/null
+++ b/ONBOARDING.md
@@ -0,0 +1,105 @@
+# Project Handoff & History
+
+A curated record of where this project is, the decisions behind it, and what's
+left — so a teammate (or a fresh Claude Code session) can pick up cleanly. This
+is a summary of the working sessions, not a verbatim chat transcript.
+
+_Last updated: 2026-06-15._
+
+## TL;DR — current status
+
+The **Work Package Suite** is an internal tool for Prime Controls construction
+projects: configure a project **SOP**, then author **Work Packages** against it.
+
+- **Front end:** static HTML/CSS/JS, no build step. Two tools surfaced from the
+  home page — *SOP Configuration* and *Work Package Creator* — both living in one
+  app ([work-package-suite.html](work-package-suite.html)) as two tabs. The
+  Creator is embedded via `<iframe>` ([wp-creation-index.html](wp-creation-index.html)).
+- **Back end (NEW, Phase 1 done):** a Python/FastAPI API + PostgreSQL under
+  [`server/`](server/) for shared storage of SOPs, Work Packages, and comments.
+- **Hosting target:** internal, behind the company firewall. **NGINX** serves the
+  static site and proxies `/api/` to the Python API. No outbound internet calls.
+- **Next up (Phase 2, NOT started):** rewire the front end to read/write the API
+  instead of browser `localStorage`.
+
+## Architecture
+
+```
+browser → NGINX ──serves──> static site (index.html, work-package-suite.html, …)
+                └─proxy /api/─> Python API (FastAPI, uvicorn/gunicorn :8000) → PostgreSQL
+```
+
+Today the front end still stores data in `localStorage`; Phase 2 moves it to the
+API. The API is already built and testable on its own.
+
+## Key decisions (and why)
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Tool structure | One app, two tabs (SOP + WP Creator) | Shared state; SOP flows straight into the Creator. Standalone SOP tool was deleted as a duplicate. |
+| WP Creator integration | Embedded as an `<iframe>` | The real Creator is a separate, complex app; iframing avoids JS global collisions and reuses it as-is. |
+| Discipline on WP types | Removed everywhere | Per request — WP types now carry Enabled / Special Rules / WO Complete Approval only. Also removed the derived Discipline field + trade-code in the Creator. |
+| Hosting | Internal **NGINX**, behind firewall | Company requirement. Considered IIS (dropped) and SharePoint (can't host a multi-file app). |
+| Database | **PostgreSQL** | Site admin is provisioning it; good JSON support for SOP/WP documents. Code uses SQLAlchemy, so it's portable. |
+| Identity | **Name field only** | Trust the internal network; users type their name. No login. |
+| Client data model | **Server-backed** (Phase 2 goal) | SOPs/WPs/comments shared across users; `localStorage` becomes a draft cache. |
+| Comments transport | API → Postgres | Replaces an earlier Power Automate plan; comments now persist to SQL directly. |
+
+## Timeline (by commit)
+
+| Commit | What it delivered |
+|--------|-------------------|
+| `c583daa` | Initial import of the WP Suite files. |
+| `2af4b58` | Consolidated to two tools (one app, two tabs); restored Rev 0 features — white header, single title, Step Comments in header, usage logs, sample data, APM in Team + Sign-offs, drag-and-drop sequencing, pre-loaded deletable sources, two-card home page, embedded WP Creator. |
+| `d2dc6ff` | Removed discipline from WP types and the Creator; removed external Google-Fonts call (firewall hardening); added Export/Import + a central-feedback hook + `DEPLOYMENT.md`. |
+| `7186d46` | First pass wiring feedback through an IIS reverse proxy to Power Automate. |
+| `3d4402c` | Switched that reverse proxy from IIS to **NGINX**. |
+| `a33b777` | **Phase 1 backend**: FastAPI + SQLAlchemy + PostgreSQL (`server/`); NGINX now proxies `/api/` to it; comments persist to SQL; docs rewritten. |
+
+## Repo map
+
+- [index.html](index.html) — home page (two tool cards; SOP card turns green/"Review" when complete).
+- [work-package-suite.html](work-package-suite.html) / [work-package-suite-app.js](work-package-suite-app.js) / [work-package-suite-styles.css](work-package-suite-styles.css) — the SOP Configuration tool + WP tab host.
+- [wp-creation-index.html](wp-creation-index.html) / [wp-creation-app.js](wp-creation-app.js) / [wp-creation-styles.css](wp-creation-styles.css) — the embedded Work Package Creator.
+- [feedback-config.js](feedback-config.js) — `FEEDBACK_ENDPOINT` (`/api/feedback`) + `postFeedback()` helper.
+- [`server/`](server/) — FastAPI API (`app.py`), ORM models (`models.py`), DB setup (`db.py`), `requirements.txt`, `.env.example`, and [server/README.md](server/README.md).
+- [nginx-wp-suite.conf](nginx-wp-suite.conf) — NGINX site config (static + `/api/` proxy).
+- [DEPLOYMENT.md](DEPLOYMENT.md) — end-to-end deploy guide.
+
+## How to run / deploy
+
+- **API + database:** see [server/README.md](server/README.md) (Postgres setup, dev `uvicorn`, prod `gunicorn` + systemd). API docs at `/api/docs`.
+- **Front end + proxy:** see [DEPLOYMENT.md](DEPLOYMENT.md) and [nginx-wp-suite.conf](nginx-wp-suite.conf).
+- Locally the API runs against a SQLite file with zero config, so it can be tried without Postgres.
+
+## What's done vs. pending
+
+**Done**
+- Two-tool consolidation, all Rev 0 feature restorations, discipline removal.
+- Firewall hardening (no external calls).
+- Export/Import feedback on every surface.
+- Phase 1 backend (API + schema) + NGINX proxy + deploy docs.
+
+**Pending — Phase 2: wire the front end to the API**
+- SOP: on *SOP Complete*, `POST /api/sops`; on load, `GET /api/sops/latest` to hydrate the Creator (currently uses `localStorage` key `wp_suite_sop`).
+- WP Creator: save packages via `POST /api/wps`; list/load via `GET /api/wps`
+  (currently `localStorage`). It reads the active SOP from `GET /api/sops/latest`.
+- Comments already post to `/api/feedback` → the API; the *list* views could be
+  switched from `localStorage` to `GET /api/comments`.
+- Keep `localStorage` as an offline draft cache / fallback.
+
+## Open questions for whoever continues
+
+1. **Projects:** the DB supports many SOPs, but the UI assumes one active SOP
+   ("latest"). Do we need a project picker?
+2. **Migrations:** tables are auto-created on startup. Before real data, decide
+   on Alembic for future schema changes.
+3. **Power App view:** if still wanted, point it at the Postgres `comments` /
+   `work_packages` tables via the on-prem data gateway (no app change needed).
+4. **Backups / retention** for the Postgres database (ask the site admin).
+
+## Continuing with Claude Code
+
+Open this repo in Claude Code and start with: *"Read ONBOARDING.md and DEPLOYMENT.md,
+then help me with Phase 2 — wiring the front end to the API."* The commit messages
+above are a reliable trail of what changed and why.