pal-e-docs

Review: Keycloak login theme for paldocs

review-1705-2026-07-03 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Related to paldocs #28
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- present, well-formed
  • [x] Context -- thorough, references landscaping-assistant pattern
  • [x] File Targets -- 2 files in paldocs, cross-repo changes noted
  • [x] Feature Flag -- none (correct for CSS-only)
  • [x] Acceptance Criteria -- 4 items
  • [x] Test Expectations -- manual only (correct for CSS-only)
  • [x] Constraints -- present, clear boundaries
  • [x] Checklist -- present
  • [x] Related -- present

Traceability

  • [x] story:auth label -- story-paldocs-auth
  • [x] story note verified -- found in project-paldocs user-stories section: "role-based access control via Keycloak"
  • [x] arch:keycloak label -- present on board item
  • [ ] arch note MISSING -- search for "arch-keycloak" returned no results. Tracked by pal-e-platform #303 ("Create arch-keycloak note (platform traceability gap)") but not yet created. [SCOPE] Create architecture note arch-keycloak for the Keycloak component.
  • [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/paldocs/issues/82, open

File Targets

  • [x] keycloak-theme/paldocs/login/theme.properties -- new file (expected). Pattern matches landscaping-assistant reference at ~/landscaping-assistant/keycloak-theme/landscaping/login/theme.properties (parent=keycloak, import=common/keycloak, styles=css/login.css).
  • [x] keycloak-theme/paldocs/login/resources/css/login.css -- new file (expected). Pattern matches landscaping reference (9.7KB CSS file with PatternFly overrides).
  • [x] app/assets/stylesheets/application.css -- exists (30KB). Design token source for CSS extraction. Agent can grep this for colors, fonts, spacing.
  • [x] Cross-repo: pal-e-platform ConfigMap pattern verified -- existing themes (westside, landscaping) use kubernetes_config_map_v1 resource + volume mount in modules/keycloak/main.tf. Theme files also stored at ~/pal-e-platform/keycloak/themes/{name}/login/ (identical copies for ConfigMap file() references).
  • [x] Cross-repo: pal-e-services realm config verified -- pal-e-docs realm in k3s.tfvars exists but has NO login_theme field yet. Needs login_theme = "paldocs" added.

Repo Placement

OK. Forgejo issue filed on ldraney/paldocs. Primary file targets (CSS theme source) are in paldocs. Cross-repo changes in pal-e-platform and pal-e-services are correctly identified as separate PRs.
Note: The existing pattern stores theme files in BOTH the app repo (source of truth for co-evolution with application.css) AND pal-e-platform (for ConfigMap file() references). The issue correctly scopes paldocs as the primary target.

Dependencies

  • paldocs #26 (board #1387) -- "Add paldocs Keycloak OIDC client via Terraform" -- backlog, sprint:3. Theme cannot be tested without a Keycloak realm/client. Code work is independent but deployment is blocked.
  • paldocs #28 (board #1389) -- "Rails OIDC integration with Keycloak" -- backlog, sprint:3. Lineage reference. Logically independent -- theme is CSS-only, no app code coupling.
  • Cross-repo deployment gap -- No Forgejo issues exist for: (1) pal-e-platform ConfigMap + volume mount for paldocs theme, (2) pal-e-services login_theme = "paldocs" on pal-e-docs realm. These steps are mentioned in the issue body as "separate PRs" but lack trackable tickets.

Acceptance Criteria

  • [x] AC1: "keycloak-theme/paldocs/login/ directory created" -- agent-verifiable via file existence check
  • [x] AC2: "CSS matches paldocs design tokens" -- partially agent-verifiable (grep application.css for tokens, confirm they appear in login.css)
  • [x] AC3: "No Keycloak branding visible" -- manual only, requires deployed theme rendering
  • [x] AC4: "Theme renders correctly on mobile" -- manual only, requires deployed theme rendering
4 acceptance criteria, 2 agent-verifiable, 2 manual-only. Reasonable for CSS-only feature. No automated test command (correct -- CSS theming has no unit test surface).

Blast Radius

Low. CSS-only changes isolated to Keycloak login page. No app code impact. No shared service changes. The only risk is in the cross-repo pal-e-platform ConfigMap/volume mount (separate PR) -- incorrect volume mounts could affect existing westside and landscaping themes. That risk belongs to the pal-e-platform PR, not this ticket.

Decomposition Assessment

No decomposition needed. 2 file targets in 1 repo, 4 acceptance criteria, estimated agent work well under 5 minutes. CSS pattern is well-established from landscaping-assistant reference.

Recommendation

  • [SCOPE] Create architecture note arch-keycloak for the Keycloak component. Already tracked by pal-e-platform #303 but not yet done. Traceability gap -- all arch:keycloak board items reference a non-existent backing note.
  • [SCOPE] Create Forgejo issues for cross-repo deployment steps: (1) pal-e-platform issue for ConfigMap keycloak-paldocs-theme + volume mount + theme file copy, (2) pal-e-services issue for adding login_theme = "paldocs" to pal-e-docs realm in k3s.tfvars. Without these tickets, the deployment path is undocumented and untracked.