pal-e-docs

Review: [Ch 7] Services wiring — Keycloak realm and OIDC client

review-1948-2026-08-01 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Feature Flag — "none" (infra provisioning, acceptable)
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

Traceability

  • [x] story:full-stack label — "Register READMEs via CLI, browse on phone via iOS app with Keycloak auth"
  • [x] story note verified — found in project-mdview user-stories section
  • [x] arch:mdview-infra label — infrastructure component
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-mdview-infra. Note returned 404 from pal-e-docs.
  • [x] Forgejo issue — ldraney/mdview#17, state: open

File Targets

  • [ ] pal-e-services/terraform/keycloak.tf — ISSUE: keycloak.tf contains HCL resource definitions that use var.keycloak_realms and var.keycloak_clients. The actual realm/client VALUES are populated in the tfvars file (e.g., pattern in k3s.tfvars.example). The file target should reference the tfvars file where keycloak_realms and keycloak_clients entries are added, not keycloak.tf itself.
  • [ ] pal-e-deployments/overlays/mdview/prod/secrets.enc.yaml — ISSUE: This file does not exist yet. The issue says "add KEYCLOAK_* env vars" implying modification, but the file needs to be created. The SOPS-encrypted pattern exists in other overlays (e.g., overlays/landscaping-assistant/prod/secrets.enc.yaml).
  • [ ] MISSING: pal-e-deployments/overlays/mdview/prod/kustomization.yaml — currently only references ../base. Must be updated to include the new secrets.enc.yaml as a resource.
  • [ ] MISSING: No file target references the keycloak_clients variable entry. AC #2 requires an OIDC client with PKCE, but the file targets only mention the realm (keycloak_realms). The client is a separate variable/resource.

Repo Placement

MISMATCH: Issue filed on ldraney/mdview but all file targets are in ldraney/pal-e-services and ldraney/pal-e-deployments. The mdview repo itself has zero file targets. Existing board pattern filed infra issues on the target repos (item #1243 on pal-e-services/issues/99, item #1244 on pal-e-deployments/issues/174). Consider splitting into separate issues on the target repos or documenting why this cross-repo filing is intentional.

Dependencies

  • Upstream (done): Items #1243 (var.services entry), #1244 (kustomize overlay), #1245 (RAILS_MASTER_KEY), #1246 (ArgoCD sync) — all in "done" column. Infrastructure foundation is in place.
  • Downstream: Item #1951 [Ch 11] "Integration — auth, database, and API token generation" (8 pts, backlog) depends on this ticket. Ch 11 wires the app to use the Keycloak realm created here.
  • Parallel: Item #1947 [Ch 6] "Database provisioning — CNPG for API tokens and sessions" (3 pts, backlog) — independent but both feed into Ch 11.
  • Dependencies are not documented in the issue body.

Acceptance Criteria

4 criteria — all verifiable via tofu plan output and file inspection. However:
  • AC #4 lists KEYCLOAK_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID, KEYCLOAK_CLIENT_SECRET — but the landscaping-assistant pattern also includes KEYCLOAK_ISSUER. If the app needs the issuer URL (common for OIDC validation), it should be added.
  • Missing AC for kustomization.yaml update — the secrets file must be referenced in the kustomize overlay to take effect.
  • No existing auth gems in the mdview Gemfile (confirmed via grep), consistent with the "app-side auth is Ch 11" constraint.

Blast Radius

Low. All Keycloak changes are additive — new realm and client. No existing realms or clients are modified. The secrets are namespaced to mdview. No other services are affected. The pattern is well-established (landscaping-assistant, basketball/westside).

Decomposition Assessment

2 file targets (corrected to ~4 with missing targets) across 2 repos, 4 acceptance criteria, estimated agent work under 5 minutes. The work is pattern-following from existing Keycloak setup. No decomposition needed.

Recommendations

  • [SCOPE] Create architecture note arch-mdview-infra in pal-e-docs. The label exists on multiple board items (Ch 6, Ch 7, Ch 10, Ch 16, Ch 17) but the backing note is missing.
  • [BODY] Fix file target: pal-e-services/terraform/keycloak.tf should reference the tfvars file where keycloak_realms and keycloak_clients values are defined, not the resource definitions in keycloak.tf.
  • [BODY] Fix file target: pal-e-deployments/overlays/mdview/prod/secrets.enc.yaml — change "add" to "create" since the file does not exist.
  • [BODY] Add missing file target: pal-e-deployments/overlays/mdview/prod/kustomization.yaml — needs update to reference secrets.enc.yaml.
  • [BODY] Add missing file target for keycloak_clients entry — AC requires OIDC client but no file target covers it.
  • [BODY] Consider adding KEYCLOAK_ISSUER to AC #4, consistent with the landscaping-assistant secrets pattern.
  • [BODY] Repo placement: issue filed on mdview but work is entirely in pal-e-services and pal-e-deployments. Consider filing on target repos or adding a note justifying the cross-repo filing.
  • [BODY] Document dependencies: Ch 11 (item #1951) depends on this ticket; note in issue body.