Update docs for four-role multi-user model and tab layout #120

Merged

ldraney merged 4 commits from docs/user-roles-and-tabs into main 2026-06-06 20:50:30 +00:00

Conversation 2 Commits 4 Files changed 6 +497 -232

ldraney commented 2026-06-06 13:05:32 +00:00

Owner

Copy link

Summary

• Rewrites user stories, roadmap, architecture, and README to reflect the four-role model (Client, Crew Member, Crew Lead, Admin) with centered person icon navigation and solo-to-business onboarding flow
• Supersedes the original three-role doc from PR #114

Changes

• docs/user-stories-auth.md: Full rewrite -- four roles, tab layout, onboarding flow, multi-tenancy data model, crew communication, delivery phases, open questions
• docs/ROADMAP.md: Updated from stale tickets 1-3 to reflect completed work (tickets 1-5) and active auth phases 1-4
• docs/app-architecture.md: Added Keycloak auth flow, Business model, per-user queues, role-based navigation, PropertyComment, PaperTrail
• README.md: Updated description, added roles table, fixed doc links, added testing-strategy link
• docs/user-story.md: Marked as historical with pointer to user-stories-auth.md

Test Plan

• All mermaid diagrams render correctly
• Role/tab matrix is consistent across all docs
• Data model in architecture matches user-stories-auth
• ROADMAP ticket references match real Forgejo issue numbers
• No stale references to old tab layout (New, Photos as standalone tabs)

Review Checklist

• Passed automated review-fix loop
• No secrets committed
• No unnecessary file changes
• Commit messages are descriptive

Related Notes

• ldraney/landscaping-assistant #107 -- parent auth issue
• Closes #119

## Summary - Rewrites user stories, roadmap, architecture, and README to reflect the four-role model (Client, Crew Member, Crew Lead, Admin) with centered person icon navigation and solo-to-business onboarding flow - Supersedes the original three-role doc from PR #114 ## Changes - `docs/user-stories-auth.md`: Full rewrite -- four roles, tab layout, onboarding flow, multi-tenancy data model, crew communication, delivery phases, open questions - `docs/ROADMAP.md`: Updated from stale tickets 1-3 to reflect completed work (tickets 1-5) and active auth phases 1-4 - `docs/app-architecture.md`: Added Keycloak auth flow, Business model, per-user queues, role-based navigation, PropertyComment, PaperTrail - `README.md`: Updated description, added roles table, fixed doc links, added testing-strategy link - `docs/user-story.md`: Marked as historical with pointer to user-stories-auth.md ## Test Plan - [ ] All mermaid diagrams render correctly - [ ] Role/tab matrix is consistent across all docs - [ ] Data model in architecture matches user-stories-auth - [ ] ROADMAP ticket references match real Forgejo issue numbers - [ ] No stale references to old tab layout (New, Photos as standalone tabs) ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive ## Related Notes - `ldraney/landscaping-assistant #107` -- parent auth issue - Closes #119

ldraney added 1 commit 2026-06-06 13:05:32 +00:00

Update docs for four-role multi-user model and tab layout ... 93df52605c

- user-stories-auth.md: rewrite with Client/Crew Member/Crew Lead/Admin
  roles, centered person icon nav, solo-to-business onboarding flow,
  multi-tenancy data model, and delivery phases
- ROADMAP.md: reflect completed tickets 1-5, active auth phases 1-4,
  updated dependency graph
- app-architecture.md: add Keycloak auth, Business model, per-user
  queues, role-based navigation, crew communication
- README.md: update description, add roles table, fix doc links
- user-story.md: mark as historical, point to user-stories-auth.md

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

ldraney commented 2026-06-06 13:08:12 +00:00

Author

Owner

Copy link

PR #120 Review

DOMAIN REVIEW

Domain: Documentation (Markdown, Mermaid diagrams, ERD data models, architecture docs)

This is a documentation-only PR updating 5 files (599 additions, 193 deletions) to align the project docs with a new four-role model (Client, Crew Member, Crew Lead, Admin). No code changes, no test impact, no security surface change.

Cross-document consistency check:

1. Data model inconsistency between user-stories-auth.md and app-architecture.md -- The favorited field lives in different places:

   • user-stories-auth.md ERD: favorited is on the USER table
   • app-architecture.md ERD: favorited is on the USER_BUSINESS join table

   The USER_BUSINESS placement (app-architecture.md) is architecturally correct -- favoriting is a per-business action, not a global user attribute. The user-stories-auth.md ERD should match.

2. role field duplication in user-stories-auth.md -- The USER table has role AND the USER_BUSINESS join table also has role. If role is per-business (which the multi-tenancy model implies), it should only be on USER_BUSINESS. Having it on both tables invites divergence when code is written.

3. Role/tab matrix -- Consistent across README, ROADMAP, app-architecture.md, and user-stories-auth.md. All four docs agree on the same role-to-tab mapping. The nav slot layout (Person centered at slot 3) is also consistent.

4. Mermaid diagrams -- Gantt chart, sequence diagrams, flowcharts, and ERDs all use valid Mermaid syntax. The dependency graph correctly shows P1 -> P2 -> P3 -> P4 chain with side dependencies for iOS and Apple enrollment.

5. Issue references -- All referenced Forgejo issue numbers (#107, #108, #109, #115, #116, #117, #118) exist and have matching titles.

6. Superseded PR -- PR body states this supersedes PR #114. PR #114 and its parent issue #113 are both still open. They should be closed if this PR fully replaces that work.

BLOCKERS

None. This is a documentation-only PR. No code, no secrets, no security surface. The BLOCKER criteria (test coverage for new functionality, unvalidated input, secrets, DRY auth violations) do not apply.

NITS

1. Data model inconsistency (favorited/role placement) -- See domain review items 1 and 2 above. These are doc-level inconsistencies that will cause confusion when the implementation starts. Recommend resolving before merge so the implementation tickets have a single source of truth for the schema.

2. Multi-Database doc dropped from README -- The README doc table removes Multi-Database (docs/multi-database.md) but that file still exists on disk. If the doc is still relevant, keep the link. If it is obsolete, either delete the file or mark it historical (like user-story.md was handled). Silently dropping the link while keeping the file creates a discoverability gap.

3. Trailing whitespace removal -- The diff removes a trailing blank line at the end of README.md (line 44 in the old file). Fine, just noting it is unrelated to the stated scope.

4. PR #114 / Issue #113 cleanup -- If this PR fully supersedes #114, both #114 and #113 should be closed (or #114 marked as superseded) to avoid stale open items in the tracker.

SOP COMPLIANCE

• Branch named after issue -- Branch is docs/user-roles-and-tabs. Convention requires {issue-number}-{kebab-case-purpose} (e.g., 119-update-docs-four-role-model). This branch does not include the issue number.
• PR body follows template -- Has Summary, Changes, Test Plan, Review Checklist, Related Notes sections. Well-structured.
• Related references plan slug -- No plan slug referenced. The task states no plan slug exists, so this is expected. Noting for completeness.
• No secrets committed -- Confirmed. No credentials, API keys, or .env files in the diff.
• No unnecessary file changes -- All 5 files are documentation files directly related to the stated scope. No scope creep.
• Commit messages are descriptive -- Recent commits (d745727, 058c9f2, 4bfe6b7) have clear purpose-driven messages.

PROCESS OBSERVATIONS

• Change failure risk: Low. Documentation-only changes carry no deployment risk.
• Deployment frequency: No impact. No code to deploy.
• Documentation gap: The two data model ERDs (user-stories-auth.md vs app-architecture.md) disagree on favorited placement and role duplication. When Phase 2 implementation starts, the developer will need to decide which doc is canonical. Resolving this now saves a round-trip later.
• Stale PR: PR #114 should be closed to keep the backlog clean.

VERDICT: APPROVED

The data model inconsistency and branch naming are real issues but non-blocking for a documentation PR. The role/tab matrix is internally consistent across all four docs, the Mermaid diagrams are syntactically valid, issue references all resolve, and no secrets or code changes are present. Recommend fixing the favorited/role placement inconsistency and closing PR #114 before starting Phase 2 implementation work.

## PR #120 Review ### DOMAIN REVIEW **Domain**: Documentation (Markdown, Mermaid diagrams, ERD data models, architecture docs) This is a documentation-only PR updating 5 files (599 additions, 193 deletions) to align the project docs with a new four-role model (Client, Crew Member, Crew Lead, Admin). No code changes, no test impact, no security surface change. **Cross-document consistency check:** 1. **Data model inconsistency between user-stories-auth.md and app-architecture.md** -- The `favorited` field lives in different places: - `user-stories-auth.md` ERD: `favorited` is on the `USER` table - `app-architecture.md` ERD: `favorited` is on the `USER_BUSINESS` join table The `USER_BUSINESS` placement (app-architecture.md) is architecturally correct -- favoriting is a per-business action, not a global user attribute. The user-stories-auth.md ERD should match. 2. **`role` field duplication in user-stories-auth.md** -- The `USER` table has `role` AND the `USER_BUSINESS` join table also has `role`. If role is per-business (which the multi-tenancy model implies), it should only be on `USER_BUSINESS`. Having it on both tables invites divergence when code is written. 3. **Role/tab matrix** -- Consistent across README, ROADMAP, app-architecture.md, and user-stories-auth.md. All four docs agree on the same role-to-tab mapping. The nav slot layout (Person centered at slot 3) is also consistent. 4. **Mermaid diagrams** -- Gantt chart, sequence diagrams, flowcharts, and ERDs all use valid Mermaid syntax. The dependency graph correctly shows P1 -> P2 -> P3 -> P4 chain with side dependencies for iOS and Apple enrollment. 5. **Issue references** -- All referenced Forgejo issue numbers (#107, #108, #109, #115, #116, #117, #118) exist and have matching titles. 6. **Superseded PR** -- PR body states this supersedes PR #114. PR #114 and its parent issue #113 are both still open. They should be closed if this PR fully replaces that work. ### BLOCKERS None. This is a documentation-only PR. No code, no secrets, no security surface. The BLOCKER criteria (test coverage for new functionality, unvalidated input, secrets, DRY auth violations) do not apply. ### NITS 1. **Data model inconsistency (favorited/role placement)** -- See domain review items 1 and 2 above. These are doc-level inconsistencies that will cause confusion when the implementation starts. Recommend resolving before merge so the implementation tickets have a single source of truth for the schema. 2. **Multi-Database doc dropped from README** -- The README doc table removes `Multi-Database` (`docs/multi-database.md`) but that file still exists on disk. If the doc is still relevant, keep the link. If it is obsolete, either delete the file or mark it historical (like user-story.md was handled). Silently dropping the link while keeping the file creates a discoverability gap. 3. **Trailing whitespace removal** -- The diff removes a trailing blank line at the end of `README.md` (line 44 in the old file). Fine, just noting it is unrelated to the stated scope. 4. **PR #114 / Issue #113 cleanup** -- If this PR fully supersedes #114, both #114 and #113 should be closed (or #114 marked as superseded) to avoid stale open items in the tracker. ### SOP COMPLIANCE - [ ] **Branch named after issue** -- Branch is `docs/user-roles-and-tabs`. Convention requires `{issue-number}-{kebab-case-purpose}` (e.g., `119-update-docs-four-role-model`). This branch does not include the issue number. - [x] **PR body follows template** -- Has Summary, Changes, Test Plan, Review Checklist, Related Notes sections. Well-structured. - [ ] **Related references plan slug** -- No plan slug referenced. The task states no plan slug exists, so this is expected. Noting for completeness. - [x] **No secrets committed** -- Confirmed. No credentials, API keys, or .env files in the diff. - [x] **No unnecessary file changes** -- All 5 files are documentation files directly related to the stated scope. No scope creep. - [x] **Commit messages are descriptive** -- Recent commits (`d745727`, `058c9f2`, `4bfe6b7`) have clear purpose-driven messages. ### PROCESS OBSERVATIONS - **Change failure risk**: Low. Documentation-only changes carry no deployment risk. - **Deployment frequency**: No impact. No code to deploy. - **Documentation gap**: The two data model ERDs (user-stories-auth.md vs app-architecture.md) disagree on `favorited` placement and `role` duplication. When Phase 2 implementation starts, the developer will need to decide which doc is canonical. Resolving this now saves a round-trip later. - **Stale PR**: PR #114 should be closed to keep the backlog clean. ### VERDICT: APPROVED The data model inconsistency and branch naming are real issues but non-blocking for a documentation PR. The role/tab matrix is internally consistent across all four docs, the Mermaid diagrams are syntactically valid, issue references all resolve, and no secrets or code changes are present. Recommend fixing the `favorited`/`role` placement inconsistency and closing PR #114 before starting Phase 2 implementation work.

ldraney added 1 commit 2026-06-06 13:08:55 +00:00

Fix review nits: reconcile data model, restore multi-database doc link ... 9cb3473e11

- Remove role/favorited from USER entity (belongs on USER_BUSINESS)
- Add multi-database.md back to README doc table

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

ldraney commented 2026-06-06 13:09:03 +00:00

Author

Owner

Copy link

Fixed review nits in 9cb3473:

• Removed role and favorited from USER entity in user-stories-auth.md -- they belong on USER_BUSINESS (role is relative to a business, not global). Now consistent with app-architecture.md.
• Restored multi-database.md link in README doc table.

Remaining nits (not fixing):

• Branch naming convention -- cosmetic, not worth rebasing
• PR #114 / issue #113 -- will close after this PR merges (superseded)

Fixed review nits in 9cb3473: - Removed `role` and `favorited` from `USER` entity in user-stories-auth.md -- they belong on `USER_BUSINESS` (role is relative to a business, not global). Now consistent with app-architecture.md. - Restored `multi-database.md` link in README doc table. Remaining nits (not fixing): - Branch naming convention -- cosmetic, not worth rebasing - PR #114 / issue #113 -- will close after this PR merges (superseded)

ldraney added 1 commit 2026-06-06 13:12:05 +00:00

Add missing docs to README, update hotwire with auto_dismiss controller ... 222b675e5b

- README: add pipeline.md, alerting.md, observability-roadmap.md,
  user-stories/ subdirectory -- all docs now linked
- hotwire.md: add auto_dismiss_controller.js (was missing from file
  tree and controller descriptions)

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

ldraney added 1 commit 2026-06-06 17:12:18 +00:00

Remove ROADMAP.md — project management lives in pal-e-docs ... 291203ef07

Roadmap, milestones, and dependency tracking belong on the project
board and project page, not as a markdown file in the repo. The repo
holds implementation and architecture docs.

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

ldraney referenced this pull request 2026-06-06 19:26:15 +00:00

Phase 1: Keycloak login with Authorization Code + PKCE (five test accounts) #115

ldraney merged commit e1c34270f0 into main 2026-06-06 20:50:30 +00:00

ldraney deleted branch docs/user-roles-and-tabs 2026-06-06 20:50:30 +00:00

ldraney referenced this pull request from a commit 2026-06-06 20:50:30 +00:00

Update docs for four-role multi-user model and tab layout (#120)

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/landscaping-assistant!120

No description provided.