Onboarding flow, solo-to-business transition, and activity feed

### Type Feature ### Lineage Child of #107 (Auth + Roles + Audit Trail). Expands the user model beyond the original three-role system. ### Repo `ldraney/landscaping-assistant` ### User Story As a new user, I want to download the app, create an account, and immediately start managing properties so the app is useful from day one -- and later I can request to join an existing business if I work for one. ### Context **The onboarding flow:** 1. User downloads app → sees login screen 2. Login accepts username, email, or phone number (single password works for all identifiers) 3. "Create account" and "Reset password" buttons on login screen 4. New account = solo user with full lead capabilities (create properties, build lists, take photos). App is immediately useful -- this is the hook. 5. Optional: user can request to join a registered business (e.g., "D&T Lawn Rangers") via a simple form 6. Request triggers a Telegram alert to the business admin 7. Admin approves or denies from the Crew tab 8. On approval: user becomes crew under that business. They lose property write access (the business controls its property database). They keep their Today list. **Solo vs business affiliation -- two dimensions:** - **Role** (crew/lead/admin) -- what you can do - **Affiliation** (solo/business member) -- whose data you see A solo user is effectively their own admin. When they join a business, they subordinate to that business's admin and their role determines access. **Property transition on business join:** - Properties created while solo need a clear resolution: archive as personal data, offer to transfer to the business, or keep them invisible while affiliated. TBD -- but the user should not lose data they created. **Activity feed / "Recently Updated" for admin:** - Admin gets a feed showing all property updates from crew, leads, and customers - Shows: who changed what, when, with a link to the property - This is the admin's awareness layer -- any time property data changes, admin knows **Crew members CAN contribute to properties (revised from read-only):** - Crew can post questions about a task on a property (e.g., "Is this tree supposed to be trimmed?") - Crew can upload photos of concerning things (damage, issues, things admin should see) - Admin can respond to questions - Crew still cannot edit core property data (name, address, services, notes) -- that stays lead/admin only - This makes crew more than passive viewers without giving them full write access **Tab layout updated:** - Crew: Today - Lead: Today, Properties - Admin: Today, Week, Properties, Crew (+ activity feed -- could be a section on the Crew tab or a separate view) ### File Targets TBD -- this is a large feature that will be broken into sub-tickets during implementation planning. Key areas: - `app/controllers/registrations_controller.rb` (new) -- self-registration - `app/controllers/business_requests_controller.rb` (new) -- join request flow - `app/models/business.rb` (new) -- tenant/business entity - `app/models/property.rb` -- add business_id (multi-tenancy) - `app/models/user_business.rb` (new) -- join table: user ↔ business with role - `app/views/sessions/new.html.erb` -- add create account + reset password buttons - `app/controllers/activity_feed_controller.rb` (new) -- recent updates for admin - `app/models/property_comment.rb` (new) -- crew questions + admin responses per property - Telegram notification integration for join requests ### Acceptance Criteria - [ ] Login screen accepts username, email, or phone number - [ ] "Create account" flow creates a solo user with lead capabilities - [ ] Solo user can create properties and build their own database immediately - [ ] User can request to join a registered business via simple form - [ ] Business admin receives Telegram alert on join request - [ ] Admin can approve/deny join requests from Crew tab - [ ] Approved user becomes crew under the business (loses property write, keeps Today list) - [ ] Properties created while solo are preserved (exact handling TBD) - [ ] Admin has activity feed showing all property updates (who, what, when) - [ ] Crew can post questions and photos on properties - [ ] Admin can respond to crew questions - [ ] Crew cannot edit core property data (name, address, services) ### Test Expectations - Request specs: registration flow, login with email/phone/username, business join request, approval/denial - Model specs: Business, UserBusiness associations, property scoping by business - Run: `bundle exec rspec` ### Constraints - Keycloak handles auth -- self-registration may use Keycloak's registration endpoint or a custom flow that creates users via Keycloak admin API (basketball-api's `keycloak.py` has the pattern) - Multi-tenancy via business_id on properties -- not database-level isolation, just row-level scoping - Telegram integration for alerts (platform already has Telegram routing for landscaping-assistant alerts via pal-e-platform PR #410) - This ticket is a planning/umbrella ticket -- break into sub-tickets before implementation ### Checklist - [ ] Sub-tickets created for each deliverable - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - #107 -- parent auth issue - #115 -- Phase 1 login - #117 -- Crew tab - `docs/user-stories-auth.md` -- extends the original role model

ldraney commented

2026-06-06 11:26:46 +00:00

Owner

Type

Feature

Lineage

Child of #107 (Auth + Roles + Audit Trail). Expands the user model beyond the original three-role system.

Repo

ldraney/landscaping-assistant

User Story

As a new user, I want to download the app, create an account, and immediately start managing properties so the app is useful from day one -- and later I can request to join an existing business if I work for one.

Context

The onboarding flow:

User downloads app → sees login screen
Login accepts username, email, or phone number (single password works for all identifiers)
"Create account" and "Reset password" buttons on login screen
New account = solo user with full lead capabilities (create properties, build lists, take photos). App is immediately useful -- this is the hook.
Optional: user can request to join a registered business (e.g., "D&T Lawn Rangers") via a simple form
Request triggers a Telegram alert to the business admin
Admin approves or denies from the Crew tab
On approval: user becomes crew under that business. They lose property write access (the business controls its property database). They keep their Today list.

Solo vs business affiliation -- two dimensions:

Role (crew/lead/admin) -- what you can do
Affiliation (solo/business member) -- whose data you see

A solo user is effectively their own admin. When they join a business, they subordinate to that business's admin and their role determines access.

Property transition on business join:

Properties created while solo need a clear resolution: archive as personal data, offer to transfer to the business, or keep them invisible while affiliated. TBD -- but the user should not lose data they created.

Activity feed / "Recently Updated" for admin:

Admin gets a feed showing all property updates from crew, leads, and customers
Shows: who changed what, when, with a link to the property
This is the admin's awareness layer -- any time property data changes, admin knows

Crew members CAN contribute to properties (revised from read-only):

Crew can post questions about a task on a property (e.g., "Is this tree supposed to be trimmed?")
Crew can upload photos of concerning things (damage, issues, things admin should see)
Admin can respond to questions
Crew still cannot edit core property data (name, address, services, notes) -- that stays lead/admin only
This makes crew more than passive viewers without giving them full write access

Tab layout updated:

Crew: Today
Lead: Today, Properties
Admin: Today, Week, Properties, Crew (+ activity feed -- could be a section on the Crew tab or a separate view)

File Targets

TBD -- this is a large feature that will be broken into sub-tickets during implementation planning. Key areas:

app/controllers/registrations_controller.rb (new) -- self-registration
app/controllers/business_requests_controller.rb (new) -- join request flow
app/models/business.rb (new) -- tenant/business entity
app/models/property.rb -- add business_id (multi-tenancy)
app/models/user_business.rb (new) -- join table: user ↔ business with role
app/views/sessions/new.html.erb -- add create account + reset password buttons
app/controllers/activity_feed_controller.rb (new) -- recent updates for admin
app/models/property_comment.rb (new) -- crew questions + admin responses per property
Telegram notification integration for join requests

Acceptance Criteria

Login screen accepts username, email, or phone number
"Create account" flow creates a solo user with lead capabilities
Solo user can create properties and build their own database immediately
User can request to join a registered business via simple form
Business admin receives Telegram alert on join request
Admin can approve/deny join requests from Crew tab
Approved user becomes crew under the business (loses property write, keeps Today list)
Properties created while solo are preserved (exact handling TBD)
Admin has activity feed showing all property updates (who, what, when)
Crew can post questions and photos on properties
Admin can respond to crew questions
Crew cannot edit core property data (name, address, services)

Test Expectations

Request specs: registration flow, login with email/phone/username, business join request, approval/denial
Model specs: Business, UserBusiness associations, property scoping by business
Run: bundle exec rspec

Constraints

Keycloak handles auth -- self-registration may use Keycloak's registration endpoint or a custom flow that creates users via Keycloak admin API (basketball-api's keycloak.py has the pattern)
Multi-tenancy via business_id on properties -- not database-level isolation, just row-level scoping
Telegram integration for alerts (platform already has Telegram routing for landscaping-assistant alerts via pal-e-platform PR #410)
This ticket is a planning/umbrella ticket -- break into sub-tickets before implementation