plan: add Open-Questions.md (Q01-Q12 with leanings + deadlines)

2026-06-24 14:27:51 +02:00
parent 13e706277f
commit 09a84bf0c8
1 changed files with 295 additions and 0 deletions
@@ -0,0 +1,295 @@
+# Open Questions
+
+**Status:** Draft v1
+**Date:** 2026-06-24
+**Owner:** Patrick
+**Scope:** Decisions that are unresolved before Sprint 0 starts and must be answered (or explicitly deferred) before the v0.1.0 tag
+
+---
+
+## 1. How to use this document
+
+Each question has:
+
+- **ID** (Q01…)
+- **Topic** (one-liner)
+- **Status:** 🟠 Open · 🟡 Leaning · ✅ Decided · ⏭️ Deferred
+- **Context** — why this is a question
+- **Options** considered
+- **Current leaning** with rationale
+- **Decision deadline** (which gate)
+- **Owner** (who decides)
+
+When a question is decided, this doc gets updated; the decision is also reflected in [Architecture.md](Architecture.md), [Roadmap.md](Roadmap.md), or [Sprint-0-Plan.md](Sprint-0-Plan.md) as appropriate, and a stub fact is stored in BigMind.
+
+---
+
+## 2. Status overview
+
+| ID | Topic | Status | Decide by |
+|----|-------|--------|-----------|
+| Q01 | Concrete org table abstraction (Company → generic Organization?) | 🟡 Leaning | Before W4 (SPI design) |
+| Q02 | Microsoft Entra ID in v0.1 or defer to v0.2 | 🟡 Leaning | Before W2 starts |
+| Q03 | Flyway migration strategy (separate schema_history vs baseline reset) | 🟡 Leaning | Before W5 (Flyway work) |
+| Q04 | Email magic-link provider in v0.1 or v0.2 | ⏭️ Deferred | n/a |
+| Q05 | npm package name (`@platesoft/auth` vs alternatives) | 🟡 Leaning | Before W3 starts |
+| Q06 | SemVer policy details — peer-version lockstep enforcement | 🟡 Leaning | Before v0.1.0 release |
+| Q07 | Gitea publishing pipeline (Gitea Actions vs manual deploy) | 🟡 Leaning | Before W6 |
+| Q08 | Spring Boot version pin (4.0.7 vs 4.1.0 vs latest milestone) | ✅ Decided | n/a (4.1.0) |
+| Q09 | Frontend bundler — `tsup` vs `tsc` vs `unbuild` | 🟠 Open | Before W3-A |
+| Q10 | License — MIT, Apache-2.0, or internal proprietary | 🟠 Open | Before v0.1.0 release |
+| Q11 | First-class i18n in `@platesoft/auth`/react? | ⏭️ Deferred | n/a |
+| Q12 | Audit emit channel — DB rows only, or also event stream? | 🟡 Leaning | Before W2 |
+
+---
+
+## 3. Open questions (detail)
+
+### Q01 — Concrete org table abstraction
+
+**Status:** 🟡 Leaning toward: **Keep org as polymorphic FK validated by SPI; do NOT ship a concrete `organizations` table in plate-auth 0.1**
+
+**Context.** InspectFlow's [`Membership`](backend/src/main/java/de/platesoft/inspectflow/entity/Membership.java) entity references `Company` (concrete entity). Sparkboard will have its own org table (probably `Project` or `Studio`). plate-auth must support both without leaking either domain.
+
+**Options considered:**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A) Polymorphic FK `(org_type, org_id)` validated by `OrgValidator` SPI | No domain leak; each consumer keeps its own concrete table | No FK constraint in DB; needs runtime validation |
+| B) Generic `organizations` table in plate-auth, consumers reference it | Real FK; consistent schema | Consumers must mirror their own org table into ours; cross-DB sync nightmare |
+| C) Abstract `@MappedSuperclass` consumers extend | Type-safe at JPA level | Forces JPA inheritance; cross-app reuse breaks |
+
+**Leaning:** Option **A**. Matches [Architecture.md § 4 SPI seams](Architecture.md) and was already designed into Sprint 14.2 ([`SPRINT-14.2-MEMBERSHIP-PLAN.md`](docs/SPRINT-14.2-MEMBERSHIP-PLAN.md:1)).
+
+**Decision deadline:** Before W4 (SPI design) starts.
+
+**Owner:** Patrick.
+
+---
+
+### Q02 — Microsoft Entra ID in v0.1?
+
+**Status:** 🟡 Leaning toward: **Defer to v0.2**
+
+**Context.** InspectFlow Sprint 14.1 ships Google OAuth. Microsoft Entra ID was scoped into the "SSO sprint" but never landed. Sparkboard does not need it day 1.
+
+**Options:**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A) Include MS provider in v0.1 | Single PR, both providers symmetric | Adds scope to Sprint 0, no consumer asks for it yet |
+| B) Defer to v0.2; SPI hooks present, provider impl absent | Smaller Sprint 0; provider added cleanly later | InspectFlow team has to wait for MS |
+| C) Include MS but mark `@Experimental` | Available + visible | Half-tested code in stable release |
+
+**Leaning:** Option **B**. Keeps Sprint 0 tight. Note in [Roadmap.md](Roadmap.md) v0.2 line item.
+
+**Decision deadline:** Before W2 starts (impacts provider package layout).
+
+**Owner:** Patrick.
+
+---
+
+### Q03 — Flyway migration strategy
+
+**Status:** 🟡 Leaning toward: **Separate `flyway_schema_history_auth` table + multi-locations**
+
+**Context.** InspectFlow has migrations V1..V31 in one history table. plate-auth needs V1..V5 (its own auth migrations). If we deploy plate-auth into InspectFlow's existing DB, Flyway sees "your V1 is not my V1" — collision.
+
+**Options:**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A) Separate `flyway_schema_history_auth` table; second Flyway bean | Clean separation; both apps see only their migrations | Two Flyway runs at startup; complexity |
+| B) Baseline-on-migrate + InspectFlow-side stub rows V1..V5 = "applied" | Single history table | Risky — Flyway baseline is one-shot; mistakes are hard to fix |
+| C) Renumber plate-auth migrations to V100+ | Single table, no collision | Forever pollutes plate-auth versioning; ugly |
+| D) Forbid plate-auth from owning migrations; consumer apps copy SQL | No coupling | Defeats the purpose of a starter; each consumer drifts |
+
+**Leaning:** Option **A**. Documented in [Sprint-0-Plan.md § 7.1](Sprint-0-Plan.md). Sparkboard starts fresh → no problem. InspectFlow gets baseline rows for V1..V5 added in the migration doc (see [Migration-InspectFlow.md](Migration-InspectFlow.md)).
+
+**Decision deadline:** Before W5 starts.
+
+**Owner:** Patrick + Plan Reviewer ratification.
+
+---
+
+### Q04 — Email magic-link provider in v0.1?
+
+**Status:** ⏭️ Deferred to v0.2
+
+**Context.** Magic-link sign-in is a common third option (after Google + password). InspectFlow Sprint 14.1 explicitly deferred it.
+
+**Decision:** No v0.1 work. SPI seam `InvitationMailer` is generic enough to repurpose if we add magic-link later. Roadmap v0.2.
+
+**Owner:** Patrick — already decided.
+
+---
+
+### Q05 — npm package name
+
+**Status:** 🟡 Leaning toward: **`@platesoft/auth`**
+
+**Context.** The npm scope must be registered on the Gitea npm registry, which means it must be unique within our setup. We control the registry, so collisions aren't a concern; aesthetics + intent are.
+
+**Options:**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| `@platesoft/auth` | Matches Maven group `de.platesoft`; clear org scope | None |
+| `@plate/auth` | Shorter | Looks like the company is "plate" alone |
+| `plate-auth` (unscoped) | Simpler | No org scope — collides with NPM-public name space if we ever publish there |
+| `@plate-software/auth` | Verbose but explicit | Long imports |
+
+**Leaning:** `@platesoft/auth`. Matches the Gitea org slug `platesoft`. Maven group is `de.platesoft` (reverse-DNS) → npm scope is `@platesoft` (shortened).
+
+**Decision deadline:** Before W3-A starts (first `package.json` written).
+
+**Owner:** Patrick.
+
+---
+
+### Q06 — SemVer policy and peer-version lockstep
+
+**Status:** 🟡 Leaning toward: **Lockstep enforced via npm `peerDependencies` + a startup check in the starter**
+
+**Context.** Backend and frontend ship from the same monorepo at the same version. If a consumer pins backend `0.1.0` and frontend `0.2.0`, the HMAC envelope contract might drift.
+
+**Options:**
+
+| Option | Mechanism | Pros | Cons |
+|--------|-----------|------|------|
+| A) Document only — trust the consumer | Wiki note | No code overhead | Easy to break |
+| B) Peer-version lockstep (npm peer dep `>=0.1.0 <0.2.0` against a matching Maven artifact in the consumer's `pom.xml`) | npm peer + runtime check | Hard to misuse | Cross-language peer dep is unusual |
+| C) Embed a `wire-version` constant in both artifacts; HMAC header includes it; mismatched envelope rejected | Code | Strict; testable | Adds protocol field |
+
+**Leaning:** Option **B + C combined** — npm peer dep + `wire-version=1` constant embedded in HMAC envelope. v0.1 → wire-version 1. Bumping wire-version is the trigger for a 0.x → 0.(x+1) release across both halves.
+
+**Decision deadline:** Before v0.1.0 release.
+
+**Owner:** Patrick + Plan Reviewer.
+
+---
+
+### Q07 — Gitea publishing pipeline
+
+**Status:** 🟡 Leaning toward: **Gitea Actions on tag `v*`**
+
+**Context.** Gitea supports both Maven and npm registries. We need to publish on each tag.
+
+**Options:**
+
+| Option | Pros | Cons |
+|--------|------|------|
+| A) Gitea Actions (`.gitea/workflows/release.yml`) on tag push | Reproducible, auditable; matches InspectFlow's CI style | Need runner availability |
+| B) Manual `mvn deploy` + `npm publish` from a maintainer's laptop | Zero CI setup | Not reproducible; "works on my machine" risk |
+| C) GitHub-mirror with GitHub Actions, push artifacts to Gitea via API | Reuse GH free runners | Two-CI complexity |
+
+**Leaning:** Option **A**. [Sprint-0-Plan.md § 8](Sprint-0-Plan.md) sketches `ci.yml` + `release.yml`.
+
+**Decision deadline:** Before W6.
+
+**Owner:** Patrick.
+
+---
+
+### Q08 — Spring Boot version pin
+
+**Status:** ✅ Decided — **4.1.0**
+
+**Context.** Sparkboard targets 4.1.0 (latest GA). InspectFlow runs 4.0.7 today but is on its own upgrade path.
+
+**Decision.** plate-auth targets Spring Boot **4.1.0** as minimum. The starter compiles against 4.1.0 APIs. InspectFlow's Sprint 14.7 will bump 4.0.7 → 4.1.0 as a prerequisite for swapping to plate-auth. Compatibility window: starter v0.1.x works with Spring Boot 4.1.x. A future v0.2 may broaden to 4.2.x.
+
+**Stored.** Reflected in [Architecture.md § 1 wire contract](Architecture.md) and [Roadmap.md](Roadmap.md).
+
+---
+
+### Q09 — Frontend bundler
+
+**Status:** 🟠 Open
+
+**Context.** `@platesoft/auth` ships ESM with `server` / `edge` / `react` subpath exports. We need a bundler that handles tree-shaking + conditional exports correctly.
+
+**Options:**
+
+| Bundler | Notes |
+|---------|-------|
+| `tsup` | Most common for libs; sensible defaults; good for ESM-only |
+| `tsc` (plain TypeScript compiler) | Zero deps; less ergonomic for multi-entry |
+| `unbuild` | Nuxt-team tool; good DX |
+| `rollup` (raw) | Power user; more config |
+
+**Decision deadline:** Before W3-A.
+
+**Owner:** Patrick.
+
+---
+
+### Q10 — License
+
+**Status:** 🟠 Open
+
+**Options:** MIT, Apache-2.0 (with explicit patent grant — recommended for libs), or internal proprietary.
+
+**Note:** plate-auth lives in a private Gitea repo. License only matters if/when we decide to open-source. For Sprint 0 we ship with `LICENSE.md` set to `Apache-2.0` placeholder; flip to proprietary if Patrick decides later.
+
+**Decision deadline:** Before v0.1.0 tag.
+
+**Owner:** Patrick.
+
+---
+
+### Q11 — First-class i18n in `@platesoft/auth/react`?
+
+**Status:** ⏭️ Deferred
+
+**Decision.** Components in `@platesoft/auth/react` ship with English strings only in v0.1. Consumers wrap with their own i18n (InspectFlow uses next-intl, Sparkboard TBD). v1.0 may revisit.
+
+---
+
+### Q12 — Audit emit channel
+
+**Status:** 🟡 Leaning toward: **DB rows only in v0.1; pluggable `AuditEmitter` SPI in v0.2**
+
+**Context.** [`LoginEvent`](backend/src/main/java/de/platesoft/inspectflow/entity) writes a DB row per login. Some consumers may want to emit to Kafka, NATS, syslog, or an external SIEM.
+
+**Decision:** v0.1 = DB rows only. The `AuditEmitter` SPI added in v0.2 will let consumers tee events out. Refer to [Roadmap.md](Roadmap.md).
+
+**Owner:** Patrick.
+
+---
+
+## 4. Decided (history)
+
+| ID | Decision | Date | Reference |
+|----|----------|------|-----------|
+| Q08 | Spring Boot 4.1.0 minimum | 2026-06-24 | Architecture.md |
+| Q04 | Magic-link → v0.2 | 2026-06-24 | Roadmap.md |
+| Q11 | i18n → consumer-supplied | 2026-06-24 | this doc |
+
+---
+
+## 5. How to add a new question
+
+1. Pick the next `Qxx` number.
+2. Add a row in § 2 with status 🟠 Open.
+3. Add a detailed § 3 entry with options + leaning.
+4. When decided, move row to § 4 and update referenced docs.
+5. Commit + push.
+
+---
+
+## 6. Cross-references
+
+- [Home.md](Home.md)
+- [Vision.md](Vision.md)
+- [Architecture.md](Architecture.md)
+- [Roadmap.md](Roadmap.md)
+- [Sprint-0-Assessment.md](Sprint-0-Assessment.md)
+- [Sprint-0-Plan.md](Sprint-0-Plan.md)
+- [Sprint-0-Testplan.md](Sprint-0-Testplan.md)
+- [Integration-Guide.md](Integration-Guide.md)
+- [Migration-InspectFlow.md](Migration-InspectFlow.md)
+
+---
+
+**End of Open-Questions.md (v1).**