pal-e-docs

Review: Spike: Keycloak integration and role-based schema design

review-1378-2026-06-07 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Spike
  • [x] Lineage -- Standalone, adequate context
  • [x] Repo -- Multiple (palinks, pal-e-platform, pal-e-services, pal-e-deployments)
  • [x] Question -- Well-structured with sub-questions covering Keycloak setup, Rails schema, role model, platform provisioning, OIDC flow
  • [x] Deliverables -- docs/auth.md + follow-up tickets
  • [x] Time-box -- 3 hours
  • [x] Related -- Lists all affected repos and Spike #15
All required spike template sections are present and well-formed.

Traceability

  • [x] story:auth-roles label -- present on board item
  • [ ] story note MISSING -- project-palinks note does not exist in pal-e-docs. Cannot verify user story entry. However, docs/user-stories.md in the repo does define US-4 (Role-Based Link Visibility) and US-8 (Authentication) which map to this spike. [SCOPE] Create project-palinks note with user-stories section in pal-e-docs.
  • [x] arch:palinks label -- present on board item
  • [ ] arch note MISSING -- No arch-palinks note found in pal-e-docs. The repo does contain docs/architecture.md with substantial Keycloak integration design. [SCOPE] Create architecture note arch-palinks in pal-e-docs (can reference or mirror the repo docs).
  • [x] Forgejo issue -- ldraney/palinks#16, state: open

File Targets

  • [x] docs/auth.md -- does NOT exist yet (correct for a spike deliverable that will be created)
  • [x] docs/architecture.md -- EXISTS and already contains Keycloak auth model, data model with users/clicks/feature_flags tables, role definitions, OIDC flow diagrams
  • [x] docs/visibility.md -- EXISTS and already contains 3-tier visibility model (superadmin, member, public) with schema impact and access scopes
  • [x] docs/user-stories.md -- EXISTS with US-4 (Role-Based Visibility) and US-8 (Authentication) directly relevant to this spike
  • [ ] Role model inconsistency -- ISSUE: The Forgejo issue describes 2 roles (superadmin, member). docs/architecture.md defines 4 roles (admin, collaborator, lead, public). docs/visibility.md defines 3 tiers (superadmin, member, public). The spike should reconcile these conflicting models.

Repo Placement

Correctly identifies multiple repos (palinks, pal-e-platform, pal-e-services, pal-e-deployments). The Forgejo issue is filed on palinks which is the primary service. Cross-repo questions are framed as investigation items, not file changes. Appropriate for a spike.

Dependencies

  • Spike #15 (Route palinks.app domain to production) -- open, directly related. OIDC redirect URIs depend on the production domain being settled. The issue correctly notes this relationship.
  • Board item #1379 (Spike: Define link visibility tiers and assign current links) -- also in backlog with story:auth-roles label. This spike should run after #1378 since it needs the schema design to assign visibility tiers. Not documented as a dependency in #1378.
  • Board item #1381 (Write dev seed data for representative local environment) -- story:auth-roles, depends on schema decisions from this spike. Not documented.
  • No existing Keycloak/OIDC code in the codebase (confirmed by grep). Current schema has only a links table with no users, no visibility column, no feature flags.

Acceptance Criteria

Deliverables are appropriate for a spike:
  • docs/auth.md creation -- verifiable by file existence and content review
  • Follow-up tickets created -- verifiable by checking Forgejo issues
However, given that docs/architecture.md and docs/visibility.md already contain substantial Keycloak design, the deliverable should clarify whether docs/auth.md is a new standalone doc or a consolidation/refinement of existing design spread across multiple docs.

Blast Radius

  • No existing auth code to disrupt -- the codebase has zero Keycloak/OIDC references in Ruby files
  • Schema is minimal (single links table) so adding users/clicks/feature_flags tables is additive, not disruptive
  • Cross-repo blast radius is contained to investigation only (spike produces docs, not code changes)
  • The role model inconsistency across existing docs could propagate confusion into follow-up tickets if not reconciled during this spike

Decomposition Assessment

This is a spike (investigation, not implementation). Single deliverable is docs/auth.md + follow-up tickets. Touches 1 file target in 1 repo for the actual output. Cross-repo investigation is reading, not writing. Well within the 5-minute rule for an agent pass. No decomposition needed.

Recommendations

  • [SCOPE] Create project-palinks note in pal-e-docs with a user-stories section (can reference the repo's docs/user-stories.md).
  • [SCOPE] Create architecture note arch-palinks in pal-e-docs (can reference the repo's docs/architecture.md).
  • [BODY] Add note to spike question: reconcile the role model inconsistency across docs/architecture.md (4 roles: admin, collaborator, lead, public), docs/visibility.md (3 tiers: superadmin, member, public), and the issue body (2 roles: superadmin, member). The spike deliverable should settle the canonical role model.
  • [BODY] Clarify deliverable: specify whether docs/auth.md consolidates/replaces the auth sections in docs/architecture.md and docs/visibility.md, or supplements them. Existing docs already contain substantial Keycloak design.
  • [BODY] Document downstream dependencies: Board items #1379 (visibility tier assignment) and #1381 (dev seed data) depend on schema decisions from this spike.