pal-e-docs

Review: ConfigMap + volume mount for paldocs Keycloak theme

review-1718-2026-07-03 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Board item #1718 on board-paldocs. Forgejo issue: ldraney/pal-e-platform#492. First review of a well-structured feature ticket that follows an established pattern (landscaping/westside themes). One traceability gap prevents READY.

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- dependency of paldocs #82
  • [x] Repo -- ldraney/pal-e-platform
  • [x] User Story -- present, well-formed
  • [x] Context -- thorough, documents 3-repo pattern with prior art
  • [x] File Targets -- create and modify targets with "do not touch" section
  • [x] Feature Flag -- "none" (infra work, appropriate)
  • [x] Acceptance Criteria -- 7 items, all verifiable
  • [x] Test Expectations -- 3 items + run command
  • [x] Constraints -- 4 items referencing specific lines
  • [x] Checklist -- present
  • [x] Related -- 5 entries with cross-references

Traceability

  • [x] story:auth label -- role-based access control via Keycloak
  • [x] story note verified -- found in project-paldocs user-stories section as story-paldocs-auth
  • [x] arch:keycloak label -- Keycloak infrastructure component
  • [ ] arch note MISSING -- [SCOPE] Create architecture note arch-keycloak for Keycloak component. Search for "arch-keycloak" returned no results in pal-e-docs.
  • [x] Forgejo issue -- ldraney/pal-e-platform#492, open

File Targets

  • [x] keycloak/themes/paldocs/login/theme.properties -- to CREATE. Parent directory does not exist yet (expected for new theme). Reference implementation at keycloak/themes/landscaping/login/theme.properties confirmed with content: parent=keycloak, import=common/keycloak, styles=css/login.css
  • [x] keycloak/themes/paldocs/login/resources/css/login.css -- to CREATE. Reference at keycloak/themes/landscaping/login/resources/css/login.css confirmed with CSS design tokens.
  • [x] terraform/modules/keycloak/main.tf -- to MODIFY. File exists (292 lines). Line references verified:
  • [x] terraform/modules/keycloak/variables.tf -- correctly listed as "do not touch", file exists

Repo Placement

Correct. Issue filed on ldraney/pal-e-platform, all file targets are in pal-e-platform. The 3-repo pattern is properly scoped: paldocs #82 (CSS design in paldocs repo), this issue (ConfigMap/volume in pal-e-platform), pal-e-services #162 (realm config in pal-e-services). Each repo has its own issue.

Dependencies

  • paldocs #82 (board item #1705, backlog) -- CSS source files. Issue states "must be completed first." This is a hard upstream dependency. The agent cannot create login.css with actual paldocs design tokens until paldocs #82 defines them.
  • pal-e-services #162 (board item #1719, backlog) -- downstream. Sets login_theme = "paldocs" on the realm. Depends on this issue completing first.
  • paldocs #26 (board item #1387, backlog) -- Keycloak OIDC client. Same story:auth chain but not a direct dependency of this issue.
  • Dependency chain documented in issue body. Ordering is clear: #82 -> #492 -> #162.

Acceptance Criteria

7 acceptance criteria. All are agent-verifiable:
  • AC 1-2: File existence checks (trivial)
  • AC 3-5: Code pattern checks in main.tf (grep/read)
  • AC 6: tofu plan verification (run command provided)
  • AC 7: Pod health check (kubectl)
Test expectations include the exact run command: cd ~/pal-e-platform/terraform && tofu plan -var-file=k3s.tfvars. Solid.

Blast Radius

Low. This is an additive change following an established pattern with two working examples. No existing resources are modified. The Keycloak pod will restart when the new volume mount is applied, causing brief downtime for all Keycloak-served auth flows (westside, landscaping, pal-e-docs). This is expected and acceptable for a dev environment.

Decomposition Assessment

7 acceptance criteria exceeds the >5 threshold, but no decomposition needed. Rationale:
  • 3 file targets in 1 repo -- under the >3 files / >2 repos threshold
  • AC 1-5 are aspects of a single code change (add theme to TF module)
  • AC 6-7 are verification steps, not separate work items
  • Established pattern with two reference implementations -- agent work estimated at 2-3 minutes
  • Decomposition would create overhead without value

Recommendations

  • [SCOPE] Create architecture note arch-keycloak for the Keycloak component. Multiple board items reference arch:keycloak (#1387, #1389, #1705, #1718, #1719) but no backing note documents the component's architecture, integration points, or theme system.