plan(s0): chunk 1 of Sprint-0-Plan (scope + workstream overview)
Patrick Plate
+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.*
|
||||
Reference in New Issue
Block a user