🏠 Overview › ✅ Implementation Tasks ›✅ epic-bulk-and-proxy-registration-mentor-selection-task-001

Proxy Mode Selector Screen scaffold and layout

epic-bulk-and-proxy-registration-mentor-selection-task-001 — Implement the Proxy Mode Selector Screen shell with a two-option entry card layout — 'On behalf of one peer mentor' vs 'Register for a group'. Set up route registration, screen scaffold using the design token system, and placeholder navigation targets for each mode. No business logic yet.

critical priority low complexity frontend pending frontend specialist Tier 0

Acceptance Criteria

Screen is reachable via its registered route from the coordinator's action menu or equivalent entry point
Screen displays exactly two tappable option cards: 'On behalf of one peer mentor' and 'Register for a group'
Each card uses design token values for padding, border radius, background color, and typography — zero hardcoded style values
Tapping each card navigates to a placeholder screen (e.g., a stub route showing the mode name) without crashing
Back navigation from the screen works correctly via the AppBar back button — no custom pop logic needed at this stage
Screen scaffold matches the app's standard page header pattern (same AppBar style as other coordinator screens)
Screen renders correctly at 320px, 390px, and 428px widths without overflow
No business logic, no provider reads, no Supabase calls in this task — pure layout scaffold
`flutter analyze` reports zero new errors or warnings after this task

Technical Requirements

frameworks
Flutter
performance requirements
Screen must render its first frame in under 16ms (single frame budget) — no heavy computation in build()
security requirements
Route must be guarded by coordinator role check — non-coordinator users must not be able to navigate to this route (implement guard or assert it is already enforced by the parent navigator)
ui components
ProxyModeSelectorScreen
ProxyModeOptionCard (new stateless widget)
Standard AppBar / PageHeader widget
Design token system (AppColors, AppSpacing, AppTypography, AppRadii)

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Create a `ProxyModeOptionCard` stateless widget that accepts `title`, `subtitle` (optional), `onTap`, and an `icon` parameter. This widget will be reused in both cards and will accept the audit trail explanation text in the next task. Register two stub routes (e.g., `/proxy/single` and `/proxy/group`) in the app's router — these will be replaced with real screens in subsequent tasks. Use `StatefulShellRoute` pattern consistent with the existing bottom nav setup if the route lives within the shell; otherwise use a modal route pushed from the action menu.

Keep the screen widget stateless — no `StatefulWidget` needed at this stage. Follow the existing coordinator screen file naming convention.

Testing Requirements

No automated tests required for this scaffold task. Manual verification: (1) navigate to the screen from the coordinator flow, (2) tap both cards and confirm stub navigation, (3) verify back navigation, (4) test on at least two screen sizes. A widget test for the layout will be written in a later task once business logic is added.

Component
Proxy Mode Selector Screen
ui low
Epic Risks (2)
medium impact medium prob technical

NHF coordinators may manage dozens of peer mentors across multiple chapters. If the multi-select list renders all contacts in a single unsorted ListView, performance degrades with 50+ items, and coordinators cannot efficiently locate a specific mentor, increasing the probability of selection errors and wrong-person proxy registrations.

Mitigation & Contingency

Mitigation: Use a SliverList with itemExtent for fixed-height rows to enable O(1) scroll position calculation. Implement the search filter using a debounce utility operating on an in-memory list (no extra API calls). Sort the contact list alphabetically by default. Add chapter-filter chips above the list for NHF's multi-chapter coordinators.

Contingency: If performance issues arise in testing with real data sets, introduce pagination with a 'load more' trigger at the bottom of the list and cache rendered rows using Flutter's AutomaticKeepAliveClientMixin.

high impact medium prob security

NHF has a complex 12-national-association / 9-region / 1,400-chapter hierarchy. It is ambiguous whether a coordinator can proxy-register for peer mentors outside their immediately assigned chapter. If the contact list is not correctly scoped by RLS, coordinators might see — and register on behalf of — peer mentors they do not manage, creating fraudulent activity records that skew Bufdir statistics.

Mitigation & Contingency

Mitigation: The Proxy Contact List Provider must query only peer mentors linked to the coordinator's own chapter scope via RLS. Add an explicit Supabase query test asserting that a coordinator from chapter A cannot retrieve peer mentors from chapter B. Display each mentor's chapter affiliation in the list row so coordinators can visually verify scope.

Contingency: If RLS scope is found to be too permissive in testing, apply a server-side coordinator_id filter as a secondary guard on the query. Block the feature release until the scope test passes consistently.

Quick Links
All Tasks Execution Plan