Table of Contents
- Open Questions
- 1. How to use this document
- 2. Status overview
- 3. Open questions (detail)
- Q01 — Concrete org table abstraction
- Q02 — Microsoft Entra ID in v0.1?
- Q03 — Flyway migration strategy
- Q04 — Email magic-link provider in v0.1?
- Q05 — npm package name
- Q06 — SemVer policy and peer-version lockstep
- Q07 — Gitea publishing pipeline
- Q08 — Spring Boot version pin
- Q09 — Frontend bundler
- Q10 — License
- Q11 — First-class i18n in @platesoft/auth/react?
- Q12 — Audit emit channel
- 4. Decided (history)
- 5. How to add a new question
- 6. Cross-references
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, Roadmap.md, or 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?) | ✅ Decided (2026-06-24) | n/a |
| 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) |
✅ Decided (2026-06-24) | n/a |
| 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 | ✅ Decided (2026-06-24) | n/a |
| 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: ✅ Decided 2026-06-24 — Option A: polymorphic FK (org_type, org_id) validated by OrgValidator SPI. plate-auth does NOT ship a concrete organizations table in 0.1.
Context. InspectFlow's Membership 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 |
Decision: Option A. Matches Architecture.md § 4 SPI seams and was already designed into Sprint 14.2 (SPRINT-14.2-MEMBERSHIP-PLAN.md). The runtime-validation gap is closed by the mandatory OrgValidator SPI (default PermissiveOrgValidator with per-call WARN — see Architecture.md § 3.4).
Owner: Patrick. Locked 2026-06-24.
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 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. Sparkboard starts fresh → no problem. InspectFlow gets baseline rows for V1..V5 added in the migration doc (see 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: ✅ Decided 2026-06-24 — npm: @platesoft/auth · Maven: de.platesoft:plate-auth-starter.
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 considered:
| 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 |
Decision: @platesoft/auth (npm) paired with de.platesoft:plate-auth-starter (Maven). Matches the Gitea org slug platesoft. Maven group is de.platesoft (reverse-DNS) → npm scope is @platesoft (shortened). Both artifacts ship in lockstep from the same v0.x.y git tag.
Owner: Patrick. Locked 2026-06-24.
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 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 and 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: ✅ Decided 2026-06-24 — Apache-2.0 placeholder for v0.1.0.
Options considered: MIT, Apache-2.0 (with explicit patent grant — recommended for libs), or internal proprietary.
Decision. plate-auth ships LICENSE.md set to Apache-2.0 as a placeholder for v0.1.0. The repo lives in private Gitea, so the license is dormant — it only activates if/when we choose to open-source. Apache-2.0 was picked over MIT for the explicit patent grant (standard for libraries that consumers will depend on). Patrick may flip to proprietary or another OSI license before any public release.
Owner: Patrick. Locked 2026-06-24.
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 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.
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 |
| Q01 | Polymorphic FK (org_type, org_id) validated by OrgValidator SPI; no concrete organizations table in 0.1 |
2026-06-24 | Architecture.md § 3.4, this doc |
| Q05 | npm: @platesoft/auth · Maven: de.platesoft:plate-auth-starter (lockstep versions) |
2026-06-24 | Architecture.md § 9, this doc |
| Q10 | Apache-2.0 placeholder for v0.1.0 (dormant until open-sourced) | 2026-06-24 | Home.md § Distribution, this doc |
| F1 | PermissiveOrgValidator ships as default OrgValidator, logs WARN on every call |
2026-06-24 | Architecture.md § 3.4, Sprint-0-Plan.md § 4.5, Sprint-0-Testplan.md T-UT15, Integration-Guide.md § 3.3 |
| F2 | plate-auth ships 6 Flyway migrations (V1..V6) in db/migration/auth/; V5__add_microsoft_tenant_id_index.sql is a standalone index migration |
2026-06-24 | Architecture.md § 8.1, Sprint-0-Plan.md § 7.2, Sprint-0-Testplan.md T-IT01 |
5. How to add a new question
- Pick the next
Qxxnumber. - Add a row in § 2 with status 🟠 Open.
- Add a detailed § 3 entry with options + leaning.
- When decided, move row to § 4 and update referenced docs.
- Commit + push.
6. Cross-references
- Home.md
- Vision.md
- Architecture.md
- Roadmap.md
- Sprint-0-Assessment.md
- Sprint-0-Plan.md
- Sprint-0-Testplan.md
- Integration-Guide.md
- Migration-InspectFlow.md
End of Open-Questions.md (v1).