From c6ed37e6e028d28ae96590fb66188543ef23bc88 Mon Sep 17 00:00:00 2001 From: Patrick Plate Date: Wed, 24 Jun 2026 14:16:26 +0200 Subject: [PATCH] plan(s0): chunk 1 of Sprint-0-Plan (scope + workstream overview) --- Sprint-0-Plan.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 Sprint-0-Plan.md diff --git a/Sprint-0-Plan.md b/Sprint-0-Plan.md new file mode 100644 index 0000000..9904de4 --- /dev/null +++ b/Sprint-0-Plan.md @@ -0,0 +1,161 @@ +# Sprint 0 — Implementation Plan + +**Status:** Draft v1 +**Date:** 2026-06-24 +**Owner:** Patrick (plate-software) +**Based on:** [`Sprint-0-Assessment.md`](Sprint-0-Assessment.md), [`Architecture.md`](Architecture.md) +**Target version:** `0.1.0` (both Maven + npm) + +--- + +## Reading guide + +This is the single longest document in the wiki. It is structured as: + +1. **Scope + ground rules** (this section) +2. **Workstream overview** (the 7 parallel-ish workstreams) +3. **Backend extraction — step-by-step** +4. **Frontend extraction — step-by-step** +5. **Flyway migration consolidation** +6. **Build + publishing pipeline** +7. **Security review checklist** (must pass before v0.1.0 tag) +8. **Rollout plan** (InspectFlow + Sparkboard adoption) +9. **Acceptance criteria** +10. **Open items deferred to v0.2+** + +Each step is numbered so the Code-mode worker can check off progress without ambiguity. + +--- + +## 1. Scope + ground rules + +### 1.1 In scope (Sprint 0) + +- New git repo `plate-auth` (already created — `git.plate-software.de/pplate/plate-auth`) +- Backend artifact `de.platesoft:plate-auth-starter:0.1.0` (Maven, Spring Boot 4 starter) +- Frontend artifact `@platesoft/auth@0.1.0` (npm, NextAuth v5 wiring) +- 5 SPIs (`OrgValidator`, `OrgDisplayNameResolver`, `InvitationMailer`, `AccessRequestMailer`, + `OnboardingHook`) +- Flyway migrations under `db/migration/auth/V1..V5` (one less than InspectFlow because V30 stays + in app — see § 5) +- Gitea Actions pipeline that publishes both artifacts on a `v*` git tag +- Internal integration tests covering exchange + JWT + memberships +- All 10 wiki docs reviewed + approved by Plan Reviewer + GO from Patrick + +### 1.2 Out of scope (deferred — see [`Roadmap.md`](Roadmap.md)) + +- WebAuthn / passkeys (v0.2+) +- Multi-replica nonce store (v0.3) +- Refresh-token rotation table (v0.3) +- JWT secret rotation via `kid` (v0.3) +- External audit-log sink (v0.3) +- `LoginEventSink` SPI (v0.3) +- SAML, SCIM, OIDC server, mobile SDKs (post-1.0, demand-driven) + +### 1.3 Ground rules + +- **No new features.** This sprint is an extraction. Anything beyond what InspectFlow already does + in Sprint 14.1–14.6 is automatic v0.2 fodder. +- **Single git repo, two artifacts.** Maven module + npm package live in one repo with a shared + `CHANGELOG.md` and lockstep versions. +- **Tests must pass on day 1.** No "TODO: write tests later" lines in committed code. +- **Plan Reviewer is mandatory before code.** No code starts until the plan is APPROVED. +- **Branch policy:** `feature/sprint-0/` branches → PR → squash-merge to `main`. + +--- + +## 2. Workstream overview + +```mermaid +flowchart LR + W1[W1: Repo scaffolding
+ CI skeleton] --> W2[W2: Backend extraction
code rename + repackage] + W1 --> W3[W3: Frontend extraction
factories + types] + W2 --> W4[W4: SPI design + impl] + W2 --> W5[W5: Flyway consolidation] + W3 --> W6[W6: Build + publish pipeline] + W4 --> W6 + W5 --> W6 + W6 --> W7[W7: Integration tests +
InspectFlow dry-run] +``` + +| # | Workstream | Owner | Depends on | Estimate | +|---|---|---|---|---| +| W1 | Repo scaffolding (Maven + npm structure, CI skeleton, README) | Code mode | — | 0.5d | +| W2 | Backend extraction — class moves, package renames, config namespace | Code mode | W1 | 1.5d | +| W3 | Frontend extraction — `createAuthConfig` factory, proxy factory, types | Code mode | W1 | 1d | +| W4 | SPI design — 5 interfaces + default no-op implementations + `@ConditionalOnMissingBean` wiring | Code mode | W2 | 1d | +| W5 | Flyway migration consolidation + `flyway_schema_history_auth` decision | Code mode | W2 | 0.5d | +| W6 | Gitea Actions publish pipeline — Maven + npm to Gitea Package Registry | Code mode | W2, W3, W4, W5 | 0.5d | +| W7 | Integration tests + InspectFlow dry-run migration | Code mode | All | 1.5d | +| | **Total** | | | **~6.5 code days + plan + review buffer = ~9–10 calendar days** | + +--- + +## 3. Backend extraction — overview + +See § 4 for step-by-step. + +The backend extraction is fundamentally: + +1. **Move** every class in `inspectflow/backend/src/main/java/de/platesoft/inspectflow/{config,filter,service,controller,entity,repository,dto,enums}/...` that is auth-related into `plate-auth/plate-auth-starter/src/main/java/de/platesoft/auth/...` +2. **Rename** every import, `@Value("${jwt....}")` → `@Value("${plate.auth.jwt....}")` etc. +3. **Replace** every direct `companies` repository call inside `MembershipService` etc. with a call through `OrgValidator` / `OrgDisplayNameResolver` SPI. +4. **Add** `PlateAuthAutoConfiguration` + `PlateAuthProperties` + `META-INF/spring/...AutoConfiguration.imports`. +5. **Add** default no-op SPI implementations annotated `@ConditionalOnMissingBean`. + +No new domain logic. No new endpoints. No new entity fields. + +--- + +## 4. Frontend extraction — overview + +See § 6 for step-by-step. + +The frontend extraction is: + +1. **Move** the NextAuth config from `inspectflow/frontend/lib/auth-config.ts` into a `createAuthConfig(opts)` factory in `plate-auth/packages/auth/src/config/index.ts` +2. **Move** the proxy logic from `inspectflow/frontend/app/api/[...path]/route.ts` into a `createProxyHandlers(opts)` factory +3. **Move** the HMAC exchange logic from `inspectflow/frontend/lib/exchange.ts` into `plate-auth/packages/auth/src/exchange/` +4. **Replace** the InspectFlow-specific `localStorage` keys with configurable prefixes +5. **Export** typed hooks (`useAccessToken`, `useMemberships`) and re-export NextAuth's `useSession`, `signIn`, `signOut` + +--- + +## 5. Flyway strategy — overview + +See § 7 for step-by-step. + +**Decision (to be ratified by Patrick — see [`Open-Questions.md`](Open-Questions.md) Q03):** + +- plate-auth ships migrations under `classpath:db/migration/auth/V1..V5` +- Consumers configure Flyway with **multiple locations** + **separate history table** for plate-auth: + ```properties + spring.flyway.locations=classpath:db/migration,classpath:db/migration/auth + # Default app history table stays "flyway_schema_history" + # plate-auth's history is tracked in the SAME table but with V1..V5 from auth/ prefixed via + # an installed_rank shift OR — preferred — a *second* Flyway managed by plate-auth's auto-config. + ``` +- For InspectFlow, V26–V31 already ran. We do **not** re-run them. Migration recipe: + - Insert a "baseline" row into `flyway_schema_history_auth` marking V1..V5 as already applied + - Detailed steps in [`Migration-InspectFlow.md`](Migration-InspectFlow.md) + +Final pattern is locked in § 7. The Plan Reviewer must approve the chosen approach before code starts. + +--- + +## 6. Build + publish pipeline — overview + +See § 8 for step-by-step. + +- Single repo. `mvn -pl plate-auth-starter package` builds the JAR. `npm -w @platesoft/auth build` + builds the npm package. +- A git tag `v0.1.0` triggers a Gitea Actions workflow that: + 1. Builds + tests both artifacts + 2. Publishes the JAR to Gitea Package Registry (Maven) + 3. Publishes the npm tarball to Gitea Package Registry (npm) + 4. Updates the `CHANGELOG.md` with the release date +- Snapshot builds (on every push to `main`) publish to `0.1.0-SNAPSHOT` / `0.1.0-snapshot.N`. + +--- + +*Plan continues in the next section — backend extraction step-by-step.*