Implementation Roadmap

Related Flows: Dashboard | Create Survey | Organization Detail

Step-by-step implementation plan for Impact Pulse. Each step is a single PR that can be reviewed and merged independently. Steps are ordered by dependency (each builds on the previous).

Current State (What Works)

• Email/password registration and login
• Google OAuth sign-in
• Email verification (backend ready, needs Resend API key)
• Password reset flow (backend ready, needs Resend API key)
• Basic survey CRUD (create, list, get, update, delete)
• Basic question management (add questions to surveys)
• Public survey taking (submit responses)
• Maslow assessment (take, view results)
• Basic organization CRUD (create, list, get, update, delete)
• Basic member management (invite, accept, remove)
• Session management (start, save progress, complete, abandon)
• In-memory database for development
• Cosmos DB for production
• Deployed on Azure (backend API + frontend SWA)
• CI/CD via GitHub Actions

What Needs to Be Built

The implementation is organized into 6 phases. Each phase contains 3 to 6 PRs.

Phase 1: Foundation Fixes (Make What Exists Actually Work End-to-End)

PR 1.1: Fix Organization-Survey Relationship

Priority: Critical Estimate: Small

The frontend survey creation form has an organization selector, but the backend doesn't properly enforce the relationship. Fix:

• Survey creation must require organization_id (no personal surveys, all surveys belong to an org)
• Survey list endpoint: filter by organization
• Dashboard: show surveys grouped by organization
• Verify the organization_id foreign key works in the database

Files:

• backend/app/api/surveys/routes.py
• frontend/src/pages/CreateSurveyPage.tsx
• frontend/src/pages/DashboardPage.tsx

Test: Create a survey under an organization, verify it appears in the org's survey list.

PR 1.2: Fix Organization Member Invitation Flow

Priority: Critical Estimate: Medium

The invitation system exists in the backend but needs end-to-end verification:

• Backend: POST /organizations/{id}/members/invite sends invitation email via Resend
• Backend: GET /invitations/accept?token={token} accepts the invitation
• Frontend: Invite member form on org detail page
• Frontend: Accept invitation page at /invitations/accept
• Email template for invitation (already exists in services/email.py, needs invitation template)

Files:

• backend/app/api/organizations/routes.py (add invite email sending)
• backend/app/services/email.py (add invitation email template)
• frontend/src/pages/InvitationAcceptPage.tsx (wire to actual API)

Test: Invite a member by email, verify email received, click accept link, verify member appears in org.

PR 1.3: Set Up Resend Email (catalyzeup.ai domain)

Priority: Critical Estimate: Small

• Register catalyzeup.ai domain in Resend
• Add DNS records (SPF, DKIM, DMARC) to Cloudflare
• Store API key in kv-catalyzeup as resend-api-key-impactpulse
• Set RESEND_API_KEY on the App Service
• Test: registration triggers verification email, forgot password sends reset email

Files:

• Azure Key Vault configuration
• App Service environment variables
• Cloudflare DNS records

Test: Register a new user, verify email arrives from noreply@catalyzeup.ai.

PR 1.4: Scoring Engine Implementation

Priority: High Estimate: Medium

Implement the scoring system from the specification:

• Add scoring_config to question model
• Implement score calculation for all 5 types (direct_scale, binary, weighted_options, multi_select_sum, qualitative)
• Calculate and store scores when a survey response is submitted
• Return scores in the response API

Files:

• backend/app/models/question.py (add scoring_config)
• backend/app/services/scoring.py (new: scoring engine)
• backend/app/api/surveys/routes.py (calculate score on submit)

Spec: See Scoring System

Test: Submit a survey with known answers, verify calculated score matches expected value.

PR 1.5: Frontend Dashboard Overhaul

Priority: High Estimate: Medium

Replace the current basic dashboard with the NGO-focused design:

• Stats cards: Active Programs, Beneficiaries Reached, Surveys Completed, Impact Score
• Recent surveys table with organization, status, response count
• Maslow results summary card
• My organizations card with roles
• Pending invitations section
• Quick action buttons (Create Survey, Take Assessment)

Spec: See flows at /impact-pulse/dashboard

Files:

• frontend/src/pages/DashboardPage.tsx (full rewrite)
• frontend/src/config/api.ts (add any missing endpoints)

Test: Login, see populated dashboard with real data from API.

PR 1.6: Survey Creation with Question Builder

Priority: High Estimate: Large

Upgrade the survey creation flow:

• Organization selector dropdown
• Survey type selector (Impact Assessment, Needs Assessment, etc.)
• Question builder with all 4 types (Rating, Boolean, Multiple Choice, Text)
• Multiple choice option management (add/remove options)
• Scoring configuration per question (max_points, option weights)
• Settings: multiple attempts, max attempts, anonymous responses
• Save as Draft / Publish buttons

Spec: See flows at /impact-pulse/surveys/create

Files:

• frontend/src/pages/CreateSurveyPage.tsx (full rewrite)
• frontend/src/components/QuestionBuilder.tsx (new)

Test: Create a survey with mixed question types, publish it, verify questions saved correctly.

Phase 2: Survey Taking Experience

PR 2.1: Multi-Type Survey Taking UI

Priority: High Estimate: Medium

The survey taking page needs to support all question types:

• Rating (0-5 scale with clickable buttons)
• Boolean (Yes/No radio buttons)
• Multiple Choice (radio buttons for single select)
• Text (textarea input)
• Progress bar with question counter
• Previous/Next navigation
• Submit on final question with thank-you screen

Spec: See flows at /impact-pulse/surveys/123/take

Files:

• frontend/src/pages/SurveyTakePage.tsx (rewrite)
• frontend/src/components/QuestionRenderer.tsx (new: renders question by type)

Test: Take a survey with all 4 question types, verify each renders correctly and responses save.

PR 2.2: Survey Session Auto-Save and Resume

Priority: High Estimate: Medium

• Auto-save partial responses as user answers questions
• Show "auto-saved" indicator
• Allow resuming an in-progress session
• Track time elapsed per question
• Session status management (in_progress, completed, abandoned)

Files:

• frontend/src/pages/SurveyTakePage.tsx (add auto-save)
• backend/app/api/sessions/routes.py (verify save/resume endpoints)

Test: Start a survey, answer 3 questions, close browser, reopen, verify session resumes at question 4.

PR 2.3: Survey Results and Score Display

Priority: High Estimate: Medium

After submitting a survey, show results:

• Overall score as percentage
• Per-question breakdown with points earned
• For Maslow: pyramid visualization with level scores
• Insights: strongest/weakest areas
• Comparison with previous attempts (if multi-attempt)

Files:

• frontend/src/pages/SurveyResultsPage.tsx (new or rewrite)
• frontend/src/components/ScoreBreakdown.tsx (new)

Test: Submit a survey, verify score displayed, retake and verify comparison shows.

PR 2.4: Survey Share and QR Code

Priority: Medium Estimate: Small

• Share page with public survey link
• Copy link button
• QR code generation (use a library like qrcode.react)
• Publish/Unpublish toggle
• Survey preview

Files:

• frontend/src/pages/SurveySharePage.tsx (rewrite)
• frontend/package.json (add qrcode.react)

Test: Share a survey, copy link, open in incognito, take survey successfully.

Phase 3: Organization Management

PR 3.1: Organization Detail Page with Tabs

Priority: High Estimate: Medium

Full organization management page:

• Members tab: table with name, email, role, joined date, remove button
• Surveys tab: table with survey title, status, responses, actions
• Pending Invitations tab: table with email, role, status, resend/cancel buttons
• Stats cards: members, surveys, responses, completion rate
• Invite Member button

Spec: See flows at /impact-pulse/organizations/123

Files:

• frontend/src/pages/OrganizationDetailPage.tsx (rewrite)
• frontend/src/components/MemberTable.tsx (new)
• frontend/src/components/InvitationTable.tsx (new)

Test: View org, see members, switch tabs, invite a member, see pending invitation.

PR 3.2: Role-Based Access Control (RBAC)

Priority: High Estimate: Medium

Enforce permissions based on org role:

• Owner: Full control (manage members, create surveys, view all results, delete org)
• Admin: Manage members, create surveys, view all results
• Member: Take surveys, view own results only

Files:

• backend/app/utils/permissions.py (new: permission checking helpers)
• backend/app/api/organizations/routes.py (add permission checks)
• backend/app/api/surveys/routes.py (add permission checks for org surveys)

Test: Login as Member, try to delete org (should fail). Login as Admin, create survey (should work).

PR 3.3: Survey Assignment to Organization Members

Priority: High Estimate: Medium

Users are invited to organizations, not surveys. Once a member, the admin assigns them to specific surveys.

Backend:

• New survey_assignments collection: { member_id, survey_id, organization_id, assigned_at, assigned_by, status, current_due_date, next_due_date, last_completed_at, reminders_sent, last_reminder_at }
• POST /organizations/{id}/surveys/{survey_id}/assign assigns members (individual or bulk)
• DELETE /organizations/{id}/surveys/{survey_id}/assign/{member_id} unassigns
• GET /organizations/{id}/surveys/{survey_id}/assignments lists all assignments with status
• GET /api/v1/me/assignments returns surveys assigned to the current user
• When a member completes a survey, update the assignment status to "completed" and calculate next_due_date

Frontend:

• Survey detail page (org context): "Assign Members" button opens a member picker
• Bulk assign: "Assign to all members" checkbox
• Assignment table showing member, status (pending/completed/overdue/waived), due date
• Member dashboard: "My Assigned Surveys" section showing what they need to take

Test: Assign survey to 3 members, verify they see it in their dashboard, complete one, verify status updates.

PR 3.4: Survey Recurrence and Reminder Drip Campaign

Priority: High Estimate: Medium

Surveys can repeat on a configurable interval. The system sends a 3-message drip campaign when a survey becomes due.

Backend:

• Add to survey model: recurrence_enabled, recurrence_interval_days, reminder_intervals (default: [0, 3, 7])
• Background job (or cron): check assignments where next_due_date <= now and status != completed
• Drip campaign: send reminder emails at configured intervals (day 0, day 3, day 7 after due date)
• After all 3 reminders sent and still not completed: flag as "overdue"
• GET /organizations/{id}/overdue returns overdue members for admin dashboard
• Admin actions: POST .../extend (push due date), POST .../waive (skip this cycle), POST .../remind (manual reminder)

Frontend:

• Survey creation/edit: "Recurrence" section with interval selector (monthly, quarterly, semi-annual, annual, custom days)
• Survey creation/edit: "Reminder Schedule" with configurable intervals
• Organization dashboard: "Needs Attention" section showing overdue members
• Overdue row: member name, survey, days overdue, reminders sent, action buttons (Extend, Waive, Send Reminder)

Email templates:

• Reminder 1: "Your [Survey Name] assessment is ready"
• Reminder 2: "Reminder: [Survey Name] is still pending"
• Reminder 3: "Final reminder: Please complete [Survey Name]"
• All include direct survey link

Test: Create survey with 7-day recurrence, assign member, simulate completion, verify next_due_date calculated, simulate overdue, verify reminders sent and admin flagging.

Phase 4: Maslow Assessment Polish

PR 4.1: Maslow Results Visualization

Priority: Medium Estimate: Medium

Upgrade the Maslow results page:

• Pyramid visualization (CSS-based, matching the flows wireframe)
• Score per level with strength badges (Strong/Moderate/Needs Attention)
• Insights section with personalized recommendations
• Previous attempts comparison table with trend indicators

Spec: See flows at /impact-pulse/maslow/results

Files:

• frontend/src/pages/MaslowResultsPage.tsx (rewrite)
• frontend/src/components/MaslowPyramid.tsx (rewrite)

PR 4.2: Maslow Analytics Dashboard

Priority: Medium Estimate: Medium

• Score trends over time (chart or table)
• Level comparison (current vs previous)
• Recommended improvement areas with priority
• Organization-level Maslow aggregation (if admin)

Spec: See flows at /impact-pulse/maslow/analytics

Files:

• frontend/src/pages/MaslowAnalyticsPage.tsx (rewrite)

Phase 5: Pre/Post Impact Measurement

PR 5.1: Survey Templates

Priority: Medium Estimate: Medium

Pre-built survey templates for common NGO use cases:

• Community Health Assessment
• Youth Mentorship Pre/Post
• Food Security Baseline
• Volunteer Satisfaction
• Program Impact Evaluation
• Beneficiary Needs Assessment

Spec: See flows at /impact-pulse/surveys/templates

Files:

• backend/app/api/templates/routes.py (new)
• frontend/src/pages/SurveyTemplatesPage.tsx (new)
• backend/data/templates.json (template definitions)

PR 5.2: Before/After Comparison

Priority: High Estimate: Large

The core impact measurement feature:

• Link a baseline survey to a follow-up survey
• Calculate impact delta (overall and per-question)
• Show before/after comparison visualization
• Generate impact report summary

Files:

• backend/app/api/impact/routes.py (new)
• backend/app/services/impact.py (new: delta calculation)
• frontend/src/pages/ImpactReportPage.tsx (new)

PR 5.3: User Notification Preferences

Priority: Medium Estimate: Small

Note: The core reminder drip campaign is implemented in PR 3.4. This PR adds user-facing controls.

• User preference: opt out of reminders (per survey or global)
• Notification settings page: email frequency, quiet hours
• Unsubscribe link in reminder emails
• Admin override: can still send manual reminders even if user opted out

Phase 6: Production Hardening

PR 6.1: Error Handling and Loading States

Priority: Medium Estimate: Medium

• Consistent error handling across all pages
• Loading skeletons for all data-fetching pages
• Empty states for empty lists (no surveys, no organizations)
• Toast notifications for success/error actions

PR 6.2: Mobile Responsiveness

Priority: Medium Estimate: Medium

• All pages responsive on mobile (375px)
• Collapsible navigation
• Touch-friendly survey taking
• Mobile-optimized Maslow results

PR 6.3: Production Environment Setup

Priority: High Estimate: Medium

• Set up catalyzeup.ai production DNS and App Service
• Configure production environment variables
• Set up monitoring and logging
• Production Cosmos DB with proper indexes
• SSL certificates for custom domains

PR Assignment for Luca

Start with these in order:

1. PR 1.1: Fix Organization-Survey Relationship (gets the basics working)
2. PR 1.4: Scoring Engine Implementation (core business logic)
3. PR 1.6: Survey Creation with Question Builder (core UI)
4. PR 2.1: Multi-Type Survey Taking UI (core UX)
5. PR 2.2: Survey Session Auto-Save and Resume

Chip handles:

1. PR 1.3: Set Up Resend Email (infrastructure, needs domain verification)
2. PR 6.3: Production Environment Setup (infrastructure)

Each PR should:

• Branch from main
• Include backend tests where applicable
• Include screenshots of working UI
• Be reviewed before merge
• Update the relevant spec doc if behavior changes