Doc: Add Auth Management Paths and Key Decisions to arch-auth-westside-basketball

forgejo_admin commented

2026-03-21 21:40:07 +00:00

Owner

Type

Feature

Lineage

plan-wkq → Phase 11

Repo

forgejo_admin/basketball-api (docs only — pal-e-docs note update)

User Story

As a platform operator
I want the auth management paths and key decisions documented in the architecture note
So that future sessions don't rebuild what Keycloak already provides

Board label note for Betty Sue: This ticket was originally tagged WS-S1 (deploy). The correct story is WS-S3 (Keycloak) or WS-S12 (user account mgmt). Please update the board item label accordingly.

Context

We spent hours building a custom password reset flow before realizing Keycloak's admin console and account console already handle most auth management. The auth architecture needs to be documented so this doesn't happen again.

File Targets

pal-e-docs note arch-auth-westside-basketball — add Auth Management Paths and Key Decisions subsections via update_block or create_block

Files NOT to touch:

No code files — this is documentation only
Do NOT modify project-westside-basketball — content belongs in the arch note

Acceptance Criteria

Auth Management Paths subsection added to arch-auth-westside-basketball
Key Decisions subsection added to arch-auth-westside-basketball
Three auth paths documented (self-service reset, account console, admin console)
Key URLs and roles documented
Key decision recorded: all email = Gmail OAuth, custom forgot-password bypasses Keycloak SMTP

Test Expectations

Subsections visible via get_section(slug="arch-auth-westside-basketball", anchor_id="auth-management-paths") and get_section(slug="arch-auth-westside-basketball", anchor_id="key-decisions")
Run command: N/A — pal-e-docs note update

Constraints

Update pal-e-docs arch note, not a code file and not the project page
Use Dottie agent or main session

Checklist

Arch note updated with both subsections
No unrelated changes

basketball-api #132 — custom password reset flow
basketball-api #144 — Marcus admin access + account console links

Review History

review-268-2026-03-27: Fixed file target (project page → arch note), story label (WS-S1 → WS-S3/WS-S12), test expectation (project page section → arch note subsections)

### Type Feature ### Lineage `plan-wkq` → Phase 11 ### Repo `forgejo_admin/basketball-api` (docs only — pal-e-docs note update) ### User Story As a platform operator I want the auth management paths and key decisions documented in the architecture note So that future sessions don't rebuild what Keycloak already provides > **Board label note for Betty Sue:** This ticket was originally tagged WS-S1 (deploy). The correct story is WS-S3 (Keycloak) or WS-S12 (user account mgmt). Please update the board item label accordingly. ### Context We spent hours building a custom password reset flow before realizing Keycloak's admin console and account console already handle most auth management. The auth architecture needs to be documented so this doesn't happen again. ### File Targets - pal-e-docs note `arch-auth-westside-basketball` — add **Auth Management Paths** and **Key Decisions** subsections via `update_block` or `create_block` Files NOT to touch: - No code files — this is documentation only - Do NOT modify `project-westside-basketball` — content belongs in the arch note ### Acceptance Criteria - [ ] Auth Management Paths subsection added to arch-auth-westside-basketball - [ ] Key Decisions subsection added to arch-auth-westside-basketball - [ ] Three auth paths documented (self-service reset, account console, admin console) - [ ] Key URLs and roles documented - [ ] Key decision recorded: all email = Gmail OAuth, custom forgot-password bypasses Keycloak SMTP ### Test Expectations - [ ] Subsections visible via `get_section(slug="arch-auth-westside-basketball", anchor_id="auth-management-paths")` and `get_section(slug="arch-auth-westside-basketball", anchor_id="key-decisions")` - Run command: N/A — pal-e-docs note update ### Constraints - Update pal-e-docs arch note, not a code file and not the project page - Use Dottie agent or main session ### Checklist - [ ] Arch note updated with both subsections - [ ] No unrelated changes ### Related - basketball-api #132 — custom password reset flow - basketball-api #144 — Marcus admin access + account console links ### Review History - review-268-2026-03-27: Fixed file target (project page → arch note), story label (WS-S1 → WS-S3/WS-S12), test expectation (project page section → arch note subsections)

forgejo_admin commented

2026-03-27 21:09:07 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-268-2026-03-27

The ticket's core intent is valid -- auth management paths and the Gmail OAuth decision are genuinely missing from docs. However, the file target points to the wrong note.

Issues found:

Wrong target: Ticket says "add Auth Architecture section to project-westside-basketball" but the project page already links to a dedicated arch-auth-westside-basketball note (8 subsections). The new content belongs there, not inline on the project page.
Story label mismatch: story:WS-S1 is about IaC deployment, not auth. Should be WS-S3 (Keycloak realms) or WS-S12 (user account management).
Missing arch label: Board item needs arch:auth label.
Test expectation will fail: get_section(slug="project-westside-basketball", anchor_id="auth-architecture") targets the wrong note. Should target arch-auth-westside-basketball.

## Scope Review: NEEDS_REFINEMENT Review note: `review-268-2026-03-27` The ticket's core intent is valid -- auth management paths and the Gmail OAuth decision are genuinely missing from docs. However, the file target points to the wrong note. **Issues found:** - **Wrong target**: Ticket says "add Auth Architecture section to `project-westside-basketball`" but the project page already links to a dedicated `arch-auth-westside-basketball` note (8 subsections). The new content belongs there, not inline on the project page. - **Story label mismatch**: `story:WS-S1` is about IaC deployment, not auth. Should be `WS-S3` (Keycloak realms) or `WS-S12` (user account management). - **Missing arch label**: Board item needs `arch:auth` label. - **Test expectation will fail**: `get_section(slug="project-westside-basketball", anchor_id="auth-architecture")` targets the wrong note. Should target `arch-auth-westside-basketball`.

forgejo_admin commented

2026-03-28 11:40:59 +00:00

Author

Owner

Scope Review (pass 2): NEEDS_REFINEMENT

Review note: review-268-2026-03-27 (updated)

Issue body unchanged since first review. Three of four original findings remain open (arch:auth label was already present, correcting prior pass).

Issues to fix:

[BODY] Wrong file target: ticket says "add Auth Architecture section to project-westside-basketball" but the project page already links to a dedicated arch-auth-westside-basketball note (8 subsections). New content (auth mgmt paths, Gmail OAuth decision) belongs in that existing arch note.
[LABEL] Story mismatch: story:WS-S1 is IaC deployment, not auth. Should be story:WS-S3 (Keycloak realms) or story:WS-S12 (user account mgmt).
[BODY] Test expectation targets wrong note: get_section(slug="project-westside-basketball", ...) should be get_section(slug="arch-auth-westside-basketball", anchor_id="auth-management-paths").

## Scope Review (pass 2): NEEDS_REFINEMENT Review note: `review-268-2026-03-27` (updated) Issue body unchanged since first review. Three of four original findings remain open (arch:auth label was already present, correcting prior pass). **Issues to fix:** 1. `[BODY]` Wrong file target: ticket says "add Auth Architecture section to `project-westside-basketball`" but the project page already links to a dedicated `arch-auth-westside-basketball` note (8 subsections). New content (auth mgmt paths, Gmail OAuth decision) belongs in that existing arch note. 2. `[LABEL]` Story mismatch: `story:WS-S1` is IaC deployment, not auth. Should be `story:WS-S3` (Keycloak realms) or `story:WS-S12` (user account mgmt). 3. `[BODY]` Test expectation targets wrong note: `get_section(slug="project-westside-basketball", ...)` should be `get_section(slug="arch-auth-westside-basketball", anchor_id="auth-management-paths")`.

forgejo_admin changed title from ~~Doc: Record auth architecture on Westside project page~~ to Doc: Add Auth Management Paths and Key Decisions to arch-auth-westside-basketball

2026-03-28 11:42:17 +00:00

forgejo_admin commented

2026-03-28 11:46:00 +00:00

Author

Owner

Scope Review (pass 3): READY

Review note: review-268-2026-03-27-v2

Issue body refinements address all prior findings. File target now correctly points to arch-auth-westside-basketball. Test expectations target the correct note slug and anchor IDs. Template is complete with all required sections.

One label fix remains (board-level, not issue body):

[LABEL] Board item #268: change story:WS-S1 to story:WS-S3 (or story:WS-S12). Issue body explicitly requests this.

After label fix, ticket is ready to move todo → next_up.

## Scope Review (pass 3): READY Review note: `review-268-2026-03-27-v2` Issue body refinements address all prior findings. File target now correctly points to `arch-auth-westside-basketball`. Test expectations target the correct note slug and anchor IDs. Template is complete with all required sections. **One label fix remains (board-level, not issue body):** - `[LABEL]` Board item #268: change `story:WS-S1` to `story:WS-S3` (or `story:WS-S12`). Issue body explicitly requests this. After label fix, ticket is ready to move todo → next_up.

forgejo_admin referenced this issue from a commit

2026-03-28 11:50:39 +00:00

doc: auth architecture with management paths and key decisions

forgejo_admin referenced this issue from a pull request that will close it,

2026-03-28 11:51:17 +00:00

doc: auth architecture with management paths and key decisions #200

forgejo_admin referenced this issue

2026-03-28 11:54:57 +00:00

doc: auth architecture with management paths and key decisions #200

forgejo_admin

2026-03-28 11:54:58 +00:00