Spike #121: Document client request flow (packages, projects, Stripe)

ldraney commented

2026-06-06 20:57:16 +00:00

Owner

Summary

Design spike documenting the client request flow — unified lifecycle for package changes and project requests, ServiceRequest data model, Stripe payment integration, and updated delivery phases.

Changes

Fleshes out client user story in docs/user-stories-auth.md with unified request flow for package changes and projects
Adds ServiceRequest model to ERD (request_type, status lifecycle, stripe_payment_link)
Adds Service.monthly_price to data model
Updates delivery phases to match board (Auth → Roles → Properties → Multi-tenancy → iOS)
Expands permission matrix with package/project/payment actions
Updates open questions (Stripe webhooks, pricing model, photo storage)
Adds five implementation tickets (#122-#126) to Related Tickets section

Test Plan

Verify mermaid diagrams render (client request flowchart, ERD, delivery phases)
Verify permission matrix rows are correct for all four roles
Verify Related Tickets section lists all new issues

Review Checklist

Docs only — no code changes
ERD matches the ServiceRequest model described in ticket #122
Delivery phases match board phase labels
Open questions updated (old #4/#5 resolved, new ones added)

Closes #121

Spike output — five implementation tickets created:

#122 ServiceRequest model + migration (3pts, phase:3)
#123 Client request UI: My Property view (5pts, phase:3)
#124 Admin request management (5pts, phase:3)
#125 Stripe integration: payment links + webhook (8pts, phase:3)
#126 Property detail page refresh: Projects button + CSS (3pts, phase:3)

## Summary Design spike documenting the client request flow — unified lifecycle for package changes and project requests, ServiceRequest data model, Stripe payment integration, and updated delivery phases. ## Changes - Fleshes out client user story in `docs/user-stories-auth.md` with unified request flow for package changes and projects - Adds ServiceRequest model to ERD (request_type, status lifecycle, stripe_payment_link) - Adds Service.monthly_price to data model - Updates delivery phases to match board (Auth → Roles → Properties → Multi-tenancy → iOS) - Expands permission matrix with package/project/payment actions - Updates open questions (Stripe webhooks, pricing model, photo storage) - Adds five implementation tickets (#122-#126) to Related Tickets section ## Test Plan - [ ] Verify mermaid diagrams render (client request flowchart, ERD, delivery phases) - [ ] Verify permission matrix rows are correct for all four roles - [ ] Verify Related Tickets section lists all new issues ## Review Checklist - [x] Docs only — no code changes - [x] ERD matches the ServiceRequest model described in ticket #122 - [x] Delivery phases match board phase labels - [x] Open questions updated (old #4/#5 resolved, new ones added) ## Related Notes Closes #121 Spike output — five implementation tickets created: - #122 ServiceRequest model + migration (3pts, phase:3) - #123 Client request UI: My Property view (5pts, phase:3) - #124 Admin request management (5pts, phase:3) - #125 Stripe integration: payment links + webhook (8pts, phase:3) - #126 Property detail page refresh: Projects button + CSS (3pts, phase:3)

ldraney added 1 commit

2026-06-06 20:57:16 +00:00

Spike #121 : Document client request flow, ServiceRequest model, Stripe

CI / scan_ruby (pull_request) Waiting to run

Details

CI / scan_js (pull_request) Waiting to run

Details

CI / lint (pull_request) Waiting to run

Details

ci/woodpecker/push/woodpecker Pipeline was successful

Details

ci/woodpecker/pr/woodpecker Pipeline was successful

Details

0c48ce49e2

Adds client story to user-stories-auth.md: unified request lifecycle
for package changes and projects (requested → quoted → paid → scheduled
→ completed), ServiceRequest data model, Stripe payment links, updated
delivery phases and permission matrix. Creates tickets #122-#126.

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

ldraney commented

2026-06-06 20:58:55 +00:00

Author

Owner

PR #127 Review

DOMAIN REVIEW

Docs-only PR -- single file changed (docs/user-stories-auth.md). No code, no migrations, no tests needed. Reviewing for internal consistency, data model correctness, and Mermaid syntax.

Mermaid syntax: All four diagrams (role hierarchy, client request flowchart, ERD, delivery phases) use valid Mermaid syntax. Node definitions, arrow labels, and relationship cardinalities are well-formed.

Delivery phases: Match the stated board layout -- Phase 1: Auth Foundation, Phase 2: Roles & Tabs, Phase 3: Property Features, Phase 4: Multi-Tenancy, Phase 5: iOS Distribution. The note that ServiceRequest + Stripe spans phases 3-4 is a useful clarification.

Related tickets: Section lists #107, #115-#118, #121-#126. All referenced issues confirmed to exist in the tracker. Coverage is complete.

Open questions: Old #4 (client-property link) and old #5 (Stripe -- "separate ticket, not scoped here") are properly replaced with more specific questions (#4 pricing model, #5 Stripe webhooks vs polling, #6 photo storage). The old questions are resolved by the design in this doc and the new tickets.

BLOCKERS

None. This is a docs-only change with no code, so the standard BLOCKER criteria (test coverage, input validation, secrets, DRY auth) do not apply.

NITS

ServiceRequest declined status missing from prose lifecycle. The ERD defines six statuses: requested | quoted | paid | scheduled | completed | declined. But the My Property section (line 120) only lists five: requested -> quoted -> paid -> scheduled -> completed. The declined status should appear in the prose lifecycle to match the data model. Similarly, the client request flowchart has no branch for admin declining a request -- it flows linearly from review to quote. Consider adding a declined path from the admin review node.
Client photo upload vs permission matrix ambiguity. The Client role description box says "Pay via Stripe, upload photos" and the My Property section says "Photo upload for issues." However, the permission matrix row "Post questions/photos on properties" has Client = No. This appears intentional (that row covers crew communication, not client issue photos), but the role description box does not distinguish between these two photo upload contexts. Consider clarifying in the role box: "upload photos (via requests)" to avoid confusion with the crew communication photo feature.
"View service package + monthly price" breaks superset hierarchy. The role hierarchy is described as "Four roles, each a superset of the one below it." However, the permission matrix has Admin = Yes for "View service package + monthly price" but Crew Lead = No. If this is intentional (pricing is sensitive business data), the "each a superset" statement in the preamble needs a caveat. If Leads should see packages for properties they manage, the matrix needs updating.
PR body says #122-#126, Related section also includes #121. Minor -- the PR body "Related Notes" section says "five implementation tickets created: #122-#126" but the doc's Related Tickets section correctly also includes #121 (this spike itself). No action needed, just noting the PR body undercounts by one.

SOP COMPLIANCE

Branch naming: Branch is spike/client-request-flow -- does not follow {issue-number}-{kebab-case-purpose} convention. Expected: 121-client-request-flow-spike or similar with issue number prefix.
PR body follows template (Summary, Changes, Test Plan, Related)
Related section does not reference a plan slug -- "Related Notes" references tickets but no pal-e-docs plan slug. Acceptable for a spike if no plan exists.
No secrets committed
No scope creep -- all changes are within the single doc file
Commit messages are descriptive

PROCESS OBSERVATIONS

Clean docs spike. The unified ServiceRequest model is a sound design choice -- one table for both package changes and project requests avoids the complexity of two separate models with nearly identical lifecycles. The five implementation tickets (#122-#126) are well-scoped with clear boundaries.

The declined status omission from the prose and flowchart (nit #1) is the most important item to address before implementation tickets reference this doc as their spec -- developers reading the flowchart would miss that admin can decline requests, which affects UI and state machine design in #122 and #123.

VERDICT: APPROVED

The nits are real inconsistencies worth fixing but none rise to BLOCKER level for a design doc. The data model, permission matrix, delivery phases, and ticket references are solid. Recommend addressing nit #1 (declined status) before #122 implementation begins, as it affects the state machine spec.

## PR #127 Review ### DOMAIN REVIEW Docs-only PR -- single file changed (`docs/user-stories-auth.md`). No code, no migrations, no tests needed. Reviewing for internal consistency, data model correctness, and Mermaid syntax. **Mermaid syntax**: All four diagrams (role hierarchy, client request flowchart, ERD, delivery phases) use valid Mermaid syntax. Node definitions, arrow labels, and relationship cardinalities are well-formed. **Delivery phases**: Match the stated board layout -- Phase 1: Auth Foundation, Phase 2: Roles & Tabs, Phase 3: Property Features, Phase 4: Multi-Tenancy, Phase 5: iOS Distribution. The note that ServiceRequest + Stripe spans phases 3-4 is a useful clarification. **Related tickets**: Section lists #107, #115-#118, #121-#126. All referenced issues confirmed to exist in the tracker. Coverage is complete. **Open questions**: Old #4 (client-property link) and old #5 (Stripe -- "separate ticket, not scoped here") are properly replaced with more specific questions (#4 pricing model, #5 Stripe webhooks vs polling, #6 photo storage). The old questions are resolved by the design in this doc and the new tickets. ### BLOCKERS None. This is a docs-only change with no code, so the standard BLOCKER criteria (test coverage, input validation, secrets, DRY auth) do not apply. ### NITS 1. **ServiceRequest `declined` status missing from prose lifecycle.** The ERD defines six statuses: `requested | quoted | paid | scheduled | completed | declined`. But the My Property section (line 120) only lists five: `requested -> quoted -> paid -> scheduled -> completed`. The `declined` status should appear in the prose lifecycle to match the data model. Similarly, the client request flowchart has no branch for admin declining a request -- it flows linearly from review to quote. Consider adding a `declined` path from the admin review node. 2. **Client photo upload vs permission matrix ambiguity.** The Client role description box says "Pay via Stripe, upload photos" and the My Property section says "Photo upload for issues." However, the permission matrix row "Post questions/photos on properties" has Client = No. This appears intentional (that row covers crew communication, not client issue photos), but the role description box does not distinguish between these two photo upload contexts. Consider clarifying in the role box: "upload photos (via requests)" to avoid confusion with the crew communication photo feature. 3. **"View service package + monthly price" breaks superset hierarchy.** The role hierarchy is described as "Four roles, each a superset of the one below it." However, the permission matrix has Admin = Yes for "View service package + monthly price" but Crew Lead = No. If this is intentional (pricing is sensitive business data), the "each a superset" statement in the preamble needs a caveat. If Leads should see packages for properties they manage, the matrix needs updating. 4. **PR body says #122-#126, Related section also includes #121.** Minor -- the PR body "Related Notes" section says "five implementation tickets created: #122-#126" but the doc's Related Tickets section correctly also includes #121 (this spike itself). No action needed, just noting the PR body undercounts by one. ### SOP COMPLIANCE - [ ] **Branch naming**: Branch is `spike/client-request-flow` -- does not follow `{issue-number}-{kebab-case-purpose}` convention. Expected: `121-client-request-flow-spike` or similar with issue number prefix. - [x] PR body follows template (Summary, Changes, Test Plan, Related) - [ ] **Related section does not reference a plan slug** -- "Related Notes" references tickets but no pal-e-docs plan slug. Acceptable for a spike if no plan exists. - [x] No secrets committed - [x] No scope creep -- all changes are within the single doc file - [x] Commit messages are descriptive ### PROCESS OBSERVATIONS Clean docs spike. The unified ServiceRequest model is a sound design choice -- one table for both package changes and project requests avoids the complexity of two separate models with nearly identical lifecycles. The five implementation tickets (#122-#126) are well-scoped with clear boundaries. The `declined` status omission from the prose and flowchart (nit #1) is the most important item to address before implementation tickets reference this doc as their spec -- developers reading the flowchart would miss that admin can decline requests, which affects UI and state machine design in #122 and #123. ### VERDICT: APPROVED The nits are real inconsistencies worth fixing but none rise to BLOCKER level for a design doc. The data model, permission matrix, delivery phases, and ticket references are solid. Recommend addressing nit #1 (declined status) before #122 implementation begins, as it affects the state machine spec.

ldraney added 1 commit

2026-06-06 20:59:50 +00:00

Fix review nits: decline path, photo distinction, role hierarchy caveat

ci/woodpecker/push/woodpecker Pipeline was successful

Details

ci/woodpecker/pr/woodpecker Pipeline was successful

Details

CI / scan_ruby (pull_request) Has been cancelled

Details

CI / scan_js (pull_request) Has been cancelled

Details

CI / lint (pull_request) Has been cancelled

Details

fc929800d8

- Add decline branch to client request flowchart
- Include declined in status lifecycle list
- Clarify client photo uploads vs crew communication photos
- Fix superset claim — client has exclusive permissions (requests, payments)

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