pplate/plate-auth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plan(s0): chunk 1 of Sprint-0-Plan (scope + workstream overview)

Patrick Plate
2026-06-24 14:16:26 +02:00
parent 8c94f29dcf
commit c6ed37e6e0
1 changed files with 161 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Sprint-0-Plan.md
+161
@@ -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/<workstream>` branches → PR → squash-merge to `main`.
---
## 2. Workstream overview
```mermaid
flowchart LR
W1[W1: Repo scaffolding<br/>+ CI skeleton] --> W2[W2: Backend extraction<br/>code rename + repackage]
W1 --> W3[W3: Frontend extraction<br/>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 +<br/>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.*