Update docs for multi-user portfolio vision #20

Merged

ldraney merged 2 commits from docs/vision-and-architecture into main 2026-06-07 15:49:42 +00:00

Conversation 2 Commits 2 Files changed 5 +353 -87

ldraney commented 2026-06-07 15:31:53 +00:00

Owner

Copy link

Summary

• Rewrite README and docs to reflect palinks evolving from personal bookmarks to multi-user portfolio hub
• Add Keycloak auth model, role-based visibility tiers, click tracking, and feature flags to architecture
• New docs/visibility.md defining public/member/superadmin access hierarchy

Changes

• README.md: Rewritten as intro + TOC, updated tech stack with Keycloak, added visibility.md to TOC
• docs/architecture.md: Added Keycloak auth flow, user roles (superadmin/member/anonymous), new ER diagram (users, clicks, feature_flags tables), feature flags design
• docs/infrastructure.md: Added auth infrastructure section, OIDC flow, Keycloak secrets, custom domain placeholder
• docs/user-stories.md: Added US-2 click tracking, US-3 feature flags dashboard, US-4 role-based visibility, US-8 authentication, US-9 contact channel
• docs/visibility.md: New file defining three access tiers with mermaid diagrams and schema approach

Test Plan

• Docs-only PR — no code changes, no tests needed
• Mermaid diagrams render correctly on Forgejo
• Role taxonomy consistent across all files (superadmin/member/public)

Review Checklist

• Passed automated review-fix loop
• No secrets committed
• No unnecessary file changes
• Commit messages are descriptive
• Feature flag needed? No — docs-only change

Related Notes

• Related to #15, #16, #17, #18 — spikes informed by these docs
• project-palinks — project page
• arch-palinks — architecture note

## Summary - Rewrite README and docs to reflect palinks evolving from personal bookmarks to multi-user portfolio hub - Add Keycloak auth model, role-based visibility tiers, click tracking, and feature flags to architecture - New docs/visibility.md defining public/member/superadmin access hierarchy ## Changes - `README.md`: Rewritten as intro + TOC, updated tech stack with Keycloak, added visibility.md to TOC - `docs/architecture.md`: Added Keycloak auth flow, user roles (superadmin/member/anonymous), new ER diagram (users, clicks, feature_flags tables), feature flags design - `docs/infrastructure.md`: Added auth infrastructure section, OIDC flow, Keycloak secrets, custom domain placeholder - `docs/user-stories.md`: Added US-2 click tracking, US-3 feature flags dashboard, US-4 role-based visibility, US-8 authentication, US-9 contact channel - `docs/visibility.md`: New file defining three access tiers with mermaid diagrams and schema approach ## Test Plan - [ ] Docs-only PR — no code changes, no tests needed - [ ] Mermaid diagrams render correctly on Forgejo - [ ] Role taxonomy consistent across all files (superadmin/member/public) ## Review Checklist - [x] Passed automated review-fix loop - [x] No secrets committed - [x] No unnecessary file changes - [x] Commit messages are descriptive - [ ] Feature flag needed? No — docs-only change ## Related Notes - Related to #15, #16, #17, #18 — spikes informed by these docs - `project-palinks` — project page - `arch-palinks` — architecture note

ldraney added 1 commit 2026-06-07 15:31:53 +00:00

Update docs for multi-user portfolio vision ... fe704c1439

Rewrite README as intro + TOC for the new direction. Update
architecture (Keycloak auth, roles, clicks, feature flags),
infrastructure (auth infra, custom domain placeholder), and
user stories (click tracking, visibility, feature flags, auth).
Add visibility.md defining public/member/superadmin tiers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldraney commented 2026-06-07 15:33:47 +00:00

Author

Owner

Copy link

PR #20 Review

DOMAIN REVIEW

Tech stack: Documentation only (Markdown, Mermaid diagrams). No code changes. Reviewed for internal consistency, Mermaid syntax correctness, information accuracy, and cross-file coherence.

Critical inconsistency -- role taxonomy diverges across files.

The PR introduces two incompatible role/visibility models that directly contradict each other:

File	Roles/Tiers Defined
docs/architecture.md (User Roles table)	admin, collaborator, lead, public
docs/architecture.md (ER diagram: users.role)	admin, collaborator, lead, public
docs/architecture.md (ER diagram: links.visibility)	public, lead, collaborator, admin
docs/visibility.md (Access Tiers)	superadmin, member, public
docs/visibility.md (Schema + Ruby scope)	superadmin, member, public
docs/user-stories.md (US-4 acceptance criteria)	public, lead, collaborator, admin

These are fundamentally different designs. Architecture.md describes a 4-tier model (public < lead < collaborator < admin). Visibility.md describes a 3-tier model (public < member < superadmin). The ER diagram enum values don't match the visibility.md schema. The Ruby visible_to scope in visibility.md uses superadmin/member but architecture.md's data model says the column holds public, lead, collaborator, admin.

A developer implementing from these docs would get contradictory instructions depending on which file they read first.

Mermaid diagrams: Syntax is valid across all files. The flowcharts, sequence diagrams, ER diagram, journey map, and state diagrams all use correct Mermaid syntax and should render on Forgejo.

No sensitive information leaked: No secrets, credentials, or internal IPs exposed. Keycloak secret names are listed as environment variable names only (appropriate for docs). The Tailscale domain is already public via funnel.

BLOCKERS

1. Role taxonomy inconsistency across files (BLOCKER)

As detailed above, architecture.md and user-stories.md define 4 roles (admin, collaborator, lead, public) while visibility.md defines 3 tiers (superadmin, member, public). The ER diagram, Ruby scope, and acceptance criteria all conflict. This must be reconciled before merge -- whichever model is correct, all files must agree.

2. "Closes #15" is incorrect (BLOCKER)

The PR body says Closes #15 -- domain spike referenced in infrastructure docs. Issue #15 is "Spike: Route palinks.app domain to production" and is still open. This PR does NOT resolve that spike -- docs/infrastructure.md line 169 explicitly says the routing approach is "under investigation" and links to Spike #15 as future work. Merging this PR would auto-close an unresolved spike. Change to References #15 or Related to #15.

3. docs/visibility.md missing from README TOC (BLOCKER)

The PR adds a new file docs/visibility.md but does not add it to the Docs section in README.md. The README lists architecture, infrastructure, pipeline, user-stories, and rails-notes -- but not visibility. A new doc file that is not discoverable from the README is an oversight that should be fixed in this PR.

NITS

1. Architecture.md Auth Model text says "two tiers of users" but the section immediately below defines four roles. The introductory sentence should match whichever role count is decided.

2. User story renumbering gap: US-1 through US-10 are defined, but the old US-3 (Annotate and Organize) lost its Mermaid flowchart in the renumbering to US-6. The old diagram was removed but no replacement was added. This is minor but worth noting -- the other user stories retained their diagrams.

3. Architecture.md Auth Model flowchart shows "click tracking" in the anonymous path (Anonymous experience / click tracking, public links only) but click tracking is described as a feature flag elsewhere. If click tracking is behind a feature flag, anonymous users might not get it by default. The diagram implies it is always-on for anonymous users.

4. visibility.md references palinks.app as the public URL, but the README and other docs still reference palinks.tail5b443a.ts.net as the live URL. The custom domain is noted as "Planned" in infrastructure.md. Using palinks.app in visibility.md prose is premature until the domain spike (#15) is resolved.

5. Open Questions section in visibility.md is good practice for a docs PR but the first question ("Should public visitors see anything before logging in") seems already answered by the architecture docs and US-1 which describe anonymous users seeing public links. Consider reconciling or removing.

SOP COMPLIANCE

• Branch named after issue: Branch is docs/vision-and-architecture. Does not follow {issue-number}-{kebab-case-purpose} convention. If this PR is meant to close an issue, the branch should be named accordingly (e.g., 15-docs-multi-user-vision). However, since "Closes #15" is incorrect anyway, this may just be an unlinked docs PR -- in which case, what issue does it belong to?
• PR body follows template: Has Summary, Changes, Test Plan, Review Checklist, Related Notes sections. Well-structured.
• Related Notes references plan slug: No plan slug referenced. The user indicated there is no plan slug, so this is noted but not blocking.
• No secrets committed: Confirmed. Only environment variable names listed, no actual values.
• No unnecessary file changes: All 5 files are docs files relevant to the stated scope.
• Commit messages: Not visible in the diff but PR title is descriptive.

PROCESS OBSERVATIONS

• This docs PR establishes the architectural vision for a significant evolution of palinks. The inconsistency between the 3-tier and 4-tier models should be resolved as a design decision before these docs become the implementation reference for spikes #16, #17, and #18.
• The PR references spikes #16, #17, #18 as "informed by these docs" which is the correct relationship -- these docs are upstream design inputs to those spikes.
• The incorrect "Closes #15" is a change failure risk -- merging would auto-close an unresolved spike, making it invisible in the backlog.

VERDICT: NOT APPROVED

Three blockers must be resolved:

1. Reconcile the role taxonomy across all files (4-role vs 3-tier)
2. Change "Closes #15" to "References #15" or "Related to #15"
3. Add docs/visibility.md to the README Docs TOC

## PR #20 Review ### DOMAIN REVIEW **Tech stack**: Documentation only (Markdown, Mermaid diagrams). No code changes. Reviewed for internal consistency, Mermaid syntax correctness, information accuracy, and cross-file coherence. **Critical inconsistency -- role taxonomy diverges across files.** The PR introduces two incompatible role/visibility models that directly contradict each other: | File | Roles/Tiers Defined | |------|---------------------| | `docs/architecture.md` (User Roles table) | admin, collaborator, lead, public | | `docs/architecture.md` (ER diagram: `users.role`) | admin, collaborator, lead, public | | `docs/architecture.md` (ER diagram: `links.visibility`) | public, lead, collaborator, admin | | `docs/visibility.md` (Access Tiers) | superadmin, member, public | | `docs/visibility.md` (Schema + Ruby scope) | superadmin, member, public | | `docs/user-stories.md` (US-4 acceptance criteria) | public, lead, collaborator, admin | These are fundamentally different designs. Architecture.md describes a 4-tier model (public < lead < collaborator < admin). Visibility.md describes a 3-tier model (public < member < superadmin). The ER diagram enum values don't match the visibility.md schema. The Ruby `visible_to` scope in visibility.md uses `superadmin`/`member` but architecture.md's data model says the column holds `public, lead, collaborator, admin`. A developer implementing from these docs would get contradictory instructions depending on which file they read first. **Mermaid diagrams**: Syntax is valid across all files. The flowcharts, sequence diagrams, ER diagram, journey map, and state diagrams all use correct Mermaid syntax and should render on Forgejo. **No sensitive information leaked**: No secrets, credentials, or internal IPs exposed. Keycloak secret names are listed as environment variable names only (appropriate for docs). The Tailscale domain is already public via funnel. ### BLOCKERS **1. Role taxonomy inconsistency across files (BLOCKER)** As detailed above, `architecture.md` and `user-stories.md` define 4 roles (admin, collaborator, lead, public) while `visibility.md` defines 3 tiers (superadmin, member, public). The ER diagram, Ruby scope, and acceptance criteria all conflict. This must be reconciled before merge -- whichever model is correct, all files must agree. **2. "Closes #15" is incorrect (BLOCKER)** The PR body says `Closes #15 -- domain spike referenced in infrastructure docs`. Issue #15 is "Spike: Route palinks.app domain to production" and is still open. This PR does NOT resolve that spike -- `docs/infrastructure.md` line 169 explicitly says the routing approach is "under investigation" and links to Spike #15 as future work. Merging this PR would auto-close an unresolved spike. Change to `References #15` or `Related to #15`. **3. `docs/visibility.md` missing from README TOC (BLOCKER)** The PR adds a new file `docs/visibility.md` but does not add it to the Docs section in `README.md`. The README lists architecture, infrastructure, pipeline, user-stories, and rails-notes -- but not visibility. A new doc file that is not discoverable from the README is an oversight that should be fixed in this PR. ### NITS 1. **Architecture.md Auth Model text says "two tiers of users"** but the section immediately below defines four roles. The introductory sentence should match whichever role count is decided. 2. **User story renumbering gap**: US-1 through US-10 are defined, but the old US-3 (Annotate and Organize) lost its Mermaid flowchart in the renumbering to US-6. The old diagram was removed but no replacement was added. This is minor but worth noting -- the other user stories retained their diagrams. 3. **Architecture.md Auth Model flowchart** shows "click tracking" in the anonymous path (`Anonymous experience / click tracking, public links only`) but click tracking is described as a feature flag elsewhere. If click tracking is behind a feature flag, anonymous users might not get it by default. The diagram implies it is always-on for anonymous users. 4. **visibility.md references `palinks.app`** as the public URL, but the README and other docs still reference `palinks.tail5b443a.ts.net` as the live URL. The custom domain is noted as "Planned" in infrastructure.md. Using `palinks.app` in visibility.md prose is premature until the domain spike (#15) is resolved. 5. **Open Questions section in visibility.md** is good practice for a docs PR but the first question ("Should public visitors see anything before logging in") seems already answered by the architecture docs and US-1 which describe anonymous users seeing public links. Consider reconciling or removing. ### SOP COMPLIANCE - [ ] **Branch named after issue**: Branch is `docs/vision-and-architecture`. Does not follow `{issue-number}-{kebab-case-purpose}` convention. If this PR is meant to close an issue, the branch should be named accordingly (e.g., `15-docs-multi-user-vision`). However, since "Closes #15" is incorrect anyway, this may just be an unlinked docs PR -- in which case, what issue does it belong to? - [x] **PR body follows template**: Has Summary, Changes, Test Plan, Review Checklist, Related Notes sections. Well-structured. - [ ] **Related Notes references plan slug**: No plan slug referenced. The user indicated there is no plan slug, so this is noted but not blocking. - [x] **No secrets committed**: Confirmed. Only environment variable names listed, no actual values. - [x] **No unnecessary file changes**: All 5 files are docs files relevant to the stated scope. - [x] **Commit messages**: Not visible in the diff but PR title is descriptive. ### PROCESS OBSERVATIONS - This docs PR establishes the architectural vision for a significant evolution of palinks. The inconsistency between the 3-tier and 4-tier models should be resolved as a design decision before these docs become the implementation reference for spikes #16, #17, and #18. - The PR references spikes #16, #17, #18 as "informed by these docs" which is the correct relationship -- these docs are upstream design inputs to those spikes. - The incorrect "Closes #15" is a change failure risk -- merging would auto-close an unresolved spike, making it invisible in the backlog. ### VERDICT: NOT APPROVED Three blockers must be resolved: 1. Reconcile the role taxonomy across all files (4-role vs 3-tier) 2. Change "Closes #15" to "References #15" or "Related to #15" 3. Add `docs/visibility.md` to the README Docs TOC

ldraney added 1 commit 2026-06-07 15:34:27 +00:00

Fix role taxonomy to superadmin/member/public across all docs ... 4b5f744a05

Align architecture.md and user-stories.md with visibility.md's
three-tier model (superadmin, member, anonymous). Add visibility.md
to README TOC.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldraney commented 2026-06-07 15:46:29 +00:00

Author

Owner

Copy link

PR #20 Re-Review

PREVIOUS BLOCKER RESOLUTION

All three blockers from the prior review have been addressed:

1. Role taxonomy inconsistency -- RESOLVED. The Keycloak role names are now consistent across all five files: superadmin and member as Keycloak roles, public/anonymous as the unauthenticated tier. architecture.md line 76 explicitly clarifies: "Public is the absence of auth, not a Keycloak role. Superadmin and member are the two Keycloak roles." visibility.md mirrors this framing. The ER diagram, the visibility scope, and the role table all align.

2. "Closes #15" would auto-close an unresolved spike -- RESOLVED. The PR body now reads "Related to #15, #16, #17, #18 -- spikes informed by these docs" which correctly references without triggering auto-close. Issue #15 remains open as expected.

3. visibility.md missing from README TOC -- RESOLVED. README.md line 15 now includes - [Visibility](docs/visibility.md) -- access tiers and role-based link filtering, placed logically between Infrastructure and User Stories.

DOMAIN REVIEW

This is a docs-only PR (Markdown and Mermaid diagrams). No code changes. Domain checks applied: documentation quality, internal consistency, cross-reference accuracy.

Role terminology -- minor residual inconsistency (nit, not blocker):

• user-stories.md US-1 line 36: "leads see lead links" -- "lead" is not a defined role. Per the architecture, leads would be member tier users. This is an acceptance criterion phrasing, not a role definition, so it reads more as an audience description than a taxonomy violation.
• user-stories.md US-9 line 170: "Contact option visible to lead and collaborator roles" -- references "lead and collaborator roles" which are audience segments, not Keycloak roles. Per the architecture there are only two Keycloak roles (superadmin, member).
• user-stories.md US-3 flowchart line 89: "Admin?" decision node -- uses "Admin" rather than "superadmin". This is a diagram display label and reads naturally in context.

These are all in user-stories.md where audience-oriented language is appropriate. The authoritative role definitions in architecture.md and visibility.md are precise and consistent. Not a blocker.

Cross-references verified:

• visibility.md references Spike #17 for the link audit deliverable -- #17 is open, correct
• infrastructure.md references Spike #15 for domain routing -- #15 is open, correct
• PR body references #15, #16, #17, #18 -- all exist and are open
• All five changed files cross-reference each other accurately

Mermaid diagrams: 14 diagrams across 4 files. Syntax is correct. Entity relationships in the ER diagram match the visibility scope logic in visibility.md. Auth flow diagrams in architecture.md and infrastructure.md are consistent (OIDC redirect flow, token exchange, role assignment).

BLOCKERS

None.

NITS

1. US-1 acceptance criteria (user-stories.md line 36): "leads see lead links" could say "members see member + public links" to match the defined taxonomy. Low priority -- the intent is clear.

2. US-9 acceptance criteria (user-stories.md line 170): "visible to lead and collaborator roles" could say "visible to authenticated users (member role)" for precision. The current wording implies more Keycloak roles than exist.

3. US-3 flowchart (user-stories.md line 89): "Admin?" decision node could say "Superadmin?" to match the role name used everywhere else. Cosmetic only.

4. Auth Model section (architecture.md line 48): "The auth flow supports two tiers of users" -- technically three tiers (superadmin, member, anonymous). The sentence seems to mean "two tiers of authenticated users" but could be clearer.

SOP COMPLIANCE

• Branch named descriptively (docs/vision-and-architecture -- docs-only, no parent issue number expected)
• PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related Notes all present)
• Related Notes references plan slug (project-palinks, arch-palinks)
• No secrets committed (Keycloak secrets are documented as env var names only, values stored in SOPS)
• No unnecessary file changes (5 files, all docs, all on-topic)
• Commit messages are descriptive
• No "Closes" keyword for unresolved spikes

PROCESS OBSERVATIONS

This PR establishes the architectural north star for palinks' evolution from personal bookmarks to multi-user portfolio. The four open spikes (#15-#18) are correctly referenced as "Related" rather than closed. The docs provide enough structure to guide implementation without over-specifying -- the TODO placeholders (link inventory audit in visibility.md, contact channel specifics in US-9) are appropriately deferred to their respective spikes.

VERDICT: APPROVED

## PR #20 Re-Review ### PREVIOUS BLOCKER RESOLUTION All three blockers from the prior review have been addressed: 1. **Role taxonomy inconsistency** -- RESOLVED. The Keycloak role names are now consistent across all five files: `superadmin` and `member` as Keycloak roles, `public`/anonymous as the unauthenticated tier. architecture.md line 76 explicitly clarifies: "Public is the absence of auth, not a Keycloak role. Superadmin and member are the two Keycloak roles." visibility.md mirrors this framing. The ER diagram, the visibility scope, and the role table all align. 2. **"Closes #15" would auto-close an unresolved spike** -- RESOLVED. The PR body now reads "Related to #15, #16, #17, #18 -- spikes informed by these docs" which correctly references without triggering auto-close. Issue #15 remains open as expected. 3. **visibility.md missing from README TOC** -- RESOLVED. README.md line 15 now includes `- [Visibility](docs/visibility.md) -- access tiers and role-based link filtering`, placed logically between Infrastructure and User Stories. ### DOMAIN REVIEW This is a docs-only PR (Markdown and Mermaid diagrams). No code changes. Domain checks applied: documentation quality, internal consistency, cross-reference accuracy. **Role terminology -- minor residual inconsistency (nit, not blocker):** - `user-stories.md` US-1 line 36: "leads see lead links" -- "lead" is not a defined role. Per the architecture, leads would be `member` tier users. This is an acceptance criterion phrasing, not a role definition, so it reads more as an audience description than a taxonomy violation. - `user-stories.md` US-9 line 170: "Contact option visible to lead and collaborator roles" -- references "lead and collaborator roles" which are audience segments, not Keycloak roles. Per the architecture there are only two Keycloak roles (superadmin, member). - `user-stories.md` US-3 flowchart line 89: "Admin?" decision node -- uses "Admin" rather than "superadmin". This is a diagram display label and reads naturally in context. These are all in user-stories.md where audience-oriented language is appropriate. The authoritative role definitions in architecture.md and visibility.md are precise and consistent. Not a blocker. **Cross-references verified:** - visibility.md references Spike #17 for the link audit deliverable -- #17 is open, correct - infrastructure.md references Spike #15 for domain routing -- #15 is open, correct - PR body references #15, #16, #17, #18 -- all exist and are open - All five changed files cross-reference each other accurately **Mermaid diagrams:** 14 diagrams across 4 files. Syntax is correct. Entity relationships in the ER diagram match the visibility scope logic in visibility.md. Auth flow diagrams in architecture.md and infrastructure.md are consistent (OIDC redirect flow, token exchange, role assignment). ### BLOCKERS None. ### NITS 1. **US-1 acceptance criteria** (user-stories.md line 36): "leads see lead links" could say "members see member + public links" to match the defined taxonomy. Low priority -- the intent is clear. 2. **US-9 acceptance criteria** (user-stories.md line 170): "visible to lead and collaborator roles" could say "visible to authenticated users (member role)" for precision. The current wording implies more Keycloak roles than exist. 3. **US-3 flowchart** (user-stories.md line 89): "Admin?" decision node could say "Superadmin?" to match the role name used everywhere else. Cosmetic only. 4. **Auth Model section** (architecture.md line 48): "The auth flow supports two tiers of users" -- technically three tiers (superadmin, member, anonymous). The sentence seems to mean "two tiers of *authenticated* users" but could be clearer. ### SOP COMPLIANCE - [x] Branch named descriptively (`docs/vision-and-architecture` -- docs-only, no parent issue number expected) - [x] PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related Notes all present) - [x] Related Notes references plan slug (`project-palinks`, `arch-palinks`) - [x] No secrets committed (Keycloak secrets are documented as env var names only, values stored in SOPS) - [x] No unnecessary file changes (5 files, all docs, all on-topic) - [x] Commit messages are descriptive - [x] No "Closes" keyword for unresolved spikes ### PROCESS OBSERVATIONS This PR establishes the architectural north star for palinks' evolution from personal bookmarks to multi-user portfolio. The four open spikes (#15-#18) are correctly referenced as "Related" rather than closed. The docs provide enough structure to guide implementation without over-specifying -- the TODO placeholders (link inventory audit in visibility.md, contact channel specifics in US-9) are appropriately deferred to their respective spikes. ### VERDICT: APPROVED

ldraney merged commit adbd881c31 into main 2026-06-07 15:49:42 +00:00

ldraney deleted branch docs/vision-and-architecture 2026-06-07 15:49:42 +00:00

ldraney referenced this pull request from a commit 2026-06-07 15:49:42 +00:00

Update docs for multi-user portfolio vision (#20)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

ldraney/palinks!20

No description provided.