# Multi-User Access — Implementation Phases Plan of record for adding multi-user access (workspaces, folder sharing, invitations) to mytodos. Tech: Laravel 13 / PHP 8.4 / MySQL / Livewire 4 SFC pages / Pest / Flux UI (free). **Status:** Phases 1–3 complete and green (303 tests, 714 assertions). Phase 4 pending. --- ## Access model (settled decisions) - Roles: `admin > editor > marker > viewer` (additive). - Effective folder role = max of: - creator → admin, - explicit `folder_user` share, - inherited ancestor shares, - workspace default: owner/admin → admin, member → viewer. - Folder visibility: `private` / `workspace`. Defaults: personal → private, family/org → workspace. - Explicit shares cascade down the subtree. A `private` folder drops out of inherited workspace access (workspace-wide grants flow only through workspace-visibility folders). - No deny semantics. - Todos have no ACL — they inherit their folder's access and `organization_id`. `todos.user_id` stays "created by". - Page scope: folders in the user's active workspace (`users.current_organization_id`) the user can access, plus folders explicitly shared with them from any workspace. Workspace-membership folders in non-active workspaces are NOT shown on pages. - `Folder::scopeVisibleTo(Builder, User|int $user, ?int $workspaceId = null)` and `Todo::scopeVisibleTo(...)`. `null` workspaceId keeps broad behavior (model tests rely on it); pages pass `activeWorkspaceId(): int`. - `organization_id` is NOT NULL on `folders` and `todos`. --- ## Phase 1 — Foundations ✅ - Migrations `2026_10_10_214840`–`214847`: workspaces (`organizations`), `organization_user` pivot (role), `folder_user` pivot (role, invited_by), `invitations`, plus `organization_id` on `folders`/`todos`, `current_organization_id` on `users`. - Models: `Organization`, `Invitation`; relations on `User`, `Folder`, `Todo`. - Enums: `OrganizationRole`, `FolderRole`, `FolderVisibility` (each with `label()`). - Policies: `FolderPolicy` (`manageShares`), `OrganizationPolicy` (`manageMembers`), `InvitationPolicy` (`create`/`delete`), `TodoPolicy` (auto-discovered). - Model scopes/helpers: `Folder::scopeVisibleTo` / `treeForVisibleTo` / `flattenTree` / creating hook; `Todo::scopeVisibleTo` / `nextPositionFor`. - Factories: `OrganizationFactory` (`personal`/`family`/`withMember`), `FolderFactory` (`inOrganization`/`sharedWithWorkspace`/`private`/`childOf`), `InvitationFactory` (`forFolder`/`forOrganization`/`accepted`/`expired`), `UserFactory` (`unsubscribed`). - Seeders pass `organization_id` explicitly. ## Phase 2 — Access scoping in pages ✅ - All three pages (folders, todo list, dashboard) use `visibleFolder` / `folderForAction` / `activeWorkspaceId()` and authorize with `can()` / `@can`. - Folder workspace label in the UI. - Tests: `tests/Feature/SharedAccessPagesTest.php` plus model-level coverage. ## Phase 3 — Sharing & invitations ✅ - `Invitation` model: `EXPIRY_DAYS = 14`; `booted()` creating hook (token `Str::random(64)`, `expires_at = Carbon::now()->addDays(14)`); `scopePending`; `isForFolder`/`isForWorkspace`; `folderRole`/`organizationRole`; `roleLabel`; `inviterName`/`inviteableName`; `accept(User)`. - `Folder::invitations()` MorphMany; `treeForVisibleTo` adds `withCount('shares')` (`shares_count`). - Mail: `InvitationMail` + `resources/views/mail/invitation.blade.php`. Sent synchronously (`Mail::to($email)->send(...)`); mail default driver `log`, `QUEUE_CONNECTION=database`. Invitations upserted on (`inviteable_type`, `inviteable_id`, `email`) with fresh token/expiry. - Accept page `resources/views/pages/invitations/⚡accept.blade.php`, route `invitations/{invitation:token}` name `invitations.accept` (auth-only). Seat-limit check; redirects to `dashboard`. - Folders page share modal (gated `manageShares`): visibility select (hidden + server-guarded for personal workspaces), collaborator list with role select + remove, invite-by-email + role, pending invitations + revoke. - Members page `resources/views/pages/workspace/⚡members.blade.php`, route `members` name `members` (subscribed). Seat usage, role change, remove (blocks self + owner; reassigns removed user to a personal workspace), invite (seat-limit aware), revoke. - Nav: "Members" item in `resources/views/layouts/app/sidebar.blade.php` and `header.blade.php`. - Tests: `InvitationTest`, `InvitationAcceptPageTest`, `FolderSharingTest`, `WorkspaceMembersTest` (helpers `familyWorkspaceFor`, `membersWorkspaceFor`). ## Phase 4 — Workspace creation & switching + billing polish ⏳ Planned, not started. Candidate work: - Workspace creation flow (create personal/family/organization workspace; ownership). - Active-workspace switching UI (updates `users.current_organization_id`) in sidebar/header. - Workspace settings (rename, members already on the members page). - Billing polish: ensure plan/seat limits and upgrade prompts align with workspace type (`config/workspaces.php` seat limits: personal=1, family=6, organization=null; `config/plans.php`: `subscription_type='default'`, `trial_days=14`, plan `pro`). - Additional migrations are allowed in Phase 4; Phases 1–3 migrations are frozen. --- ## Verification - `php artisan test` → 303 passed, 714 assertions. - `vendor/bin/pint --dirty --format agent` (Pint formats `.blade.php` too). - `vendor/bin/phpstan analyse --memory-limit=1G` (Larastan, level 7). Note: the default `composer types:check` crashes at the 128M memory limit — pass `--memory-limit=1G`. 17 pre-existing errors remain in unrelated files (console seeders, `Todo`, legacy `Folder` helpers, policies). All Phase 1–3 feature files are clean. ## Conventions & gotchas - `#[Fillable]`/`#[Hidden]` attributes; `scopeXxx()` naming; enums with `label()`. - Create files via `php artisan make:* --no-interaction`. - Livewire `Component` base has no `AuthorizesRequests`; pages use `abort_unless(auth()->user()->can(...), 403)`; blade uses `@can`. - **Blaze compiler bug:** Blade directives as attributes on a Flux component tag (`@selected()`/`@checked()` on ``) are mangled into a `ParseError`. Use `wire:model` (array dot paths) instead. Native `` is fine. - Livewire test harness renders `HttpException`/`AuthorizationException` into responses (`assertStatus(403)`); `ModelNotFoundException` propagates. `#[Locked]` props can't be `set()`. - Livewire `->set()` fires `updated` hooks (used with `memberRoles.{id}`, `collaboratorRoles.{id}`). - Guest invites: accept page behind `auth`; unsubscribed users bounce to pricing via `subscribed`/`EnsureSubscribed`.