Date: December 6, 2025
Reviewer: QA Engineer
Scope: Browser-side (frontend) usability, logic, and workflow issues
Application: GrantFlow - Grant Management Platform
This report documents findings from a comprehensive review of the GrantFlow application's browser-side implementation. The review focused on usability, user experience, workflow logic, error handling, and consistency across the grant submission, review, and milestone management flows.
Key Areas Reviewed:
- Authentication and user flows
- Submission creation and management
- Review and voting workflows
- Milestone submission and approval
- Multisig transaction integration
- Error handling and user feedback
- UI/UX consistency and accessibility
Location: Submission creation form, milestone submission forms
Issue: When form validation fails or server errors occur, error messages are not prominently displayed to users. The error handling in validatedActionWithUser returns { error: string } but components may not be displaying these consistently.
Impact: Users submit forms multiple times without understanding why submissions fail, leading to frustration and data loss.
Recommendation:
- Add a prominent error banner/toast at the top of forms when errors occur
- Display field-specific validation errors inline with form fields
- Use consistent error styling (red background, clear icon, dismissible)
Files Affected:
src/app/(dashboard)/dashboard/submissions/new/page.tsxsrc/components/milestone-submission-form.tsxsrc/components/submissions/grantee-submission-view.tsx
Location: Milestone submission and approval workflow
Issue: The milestone status flow has unclear states. According to code:
- Status can be:
pending,in-review,completed,rejected - But there's no clear state for "submitted and awaiting review" vs "in progress"
- The
hasMilestoneBeenSubmittedfunction checks forsubmittedAtORdeliverables, but status might still bepending
Impact: Grantees may submit milestone work but not see it reflected as "submitted" in the UI, leading to confusion about whether their submission was received.
Recommendation:
- Add explicit
submittedstatus to milestone status enum - Update status flow:
pending→in_progress→submitted→in-review→completed/rejected - Clear visual distinction between "working on milestone" vs "submitted for review"
Files Affected:
src/lib/db/schema/milestones.tssrc/components/submissions/grantee-submission-view.tsxsrc/app/(dashboard)/dashboard/submissions/milestone-actions.ts
Location: Milestone approval and multisig voting
Issue: The multisig workflow is complex (first vote creates transaction, subsequent votes add signatures, final vote executes), but the UI doesn't clearly explain this to reviewers. The MilestoneVotingPanel component shows buttons but lacks explanatory text.
Impact: Reviewers may not understand:
- What happens when they click "Initiate Multisig Approval"
- That they're creating an on-chain transaction, not just voting
- The difference between "Approve Transaction" and "Execute Transaction"
- That execution requires threshold to be met first
Recommendation:
- Add informational tooltips/modals explaining the multisig flow
- Show step-by-step progress indicator (1. Initiate → 2. Vote → 3. Execute)
- Display clear messaging: "You will create a blockchain transaction that requires X signatures"
- Show what happens at each step before the user clicks
Files Affected:
src/components/milestone/milestone-voting-panel.tsxsrc/components/review/milestone-review-dialog.tsx
Location: Milestone submission form
Issue: When a grantee submits a milestone, there's no immediate visual feedback that the submission is being processed. The form may close or reload without indicating success/failure.
Impact: Users may submit multiple times thinking the first submission didn't work, or may not realize their submission was successful.
Recommendation:
- Show loading spinner/disabled state on submit button
- Display success toast notification: "Milestone submitted successfully! Awaiting review."
- Disable form fields while submitting
- Show confirmation dialog before submission if form has unsaved changes
Files Affected:
src/components/milestone-submission-form.tsxsrc/components/submissions/grantee-submission-view.tsx
Location: Submission creation form
Issue: While the backend validates that milestone amounts don't exceed total amount, there's no client-side validation or visual indicator showing:
- Total milestone amounts vs total grant amount
- Remaining amount after milestones
- Warning when milestones exceed 100% of grant
Impact: Users create submissions with invalid milestone totals and only find out after form submission, requiring them to re-enter data.
Recommendation:
- Add real-time calculation showing "Milestone Total: $X / $Y (Z% of grant)"
- Highlight in red when milestone total exceeds grant amount
- Disable submit button when totals don't match
- Show breakdown of each milestone amount
Files Affected:
src/app/(dashboard)/dashboard/submissions/new/page.tsx
Location: Submission creation - grant program selection
Issue: Grant programs are displayed as buttons with long text, making it hard to quickly scan and compare options. Critical information (funding range, focus areas) is buried in button text.
Impact: Users struggle to select the right grant program, may apply to wrong committees, and waste time reading through long button text.
Recommendation:
- Redesign as cards with clear hierarchy:
- Committee name (heading)
- Program name (subheading)
- Funding range (highlighted)
- Focus areas (tags/badges)
- Available amount vs total
- Add filter/search functionality
- Show program requirements upfront
Files Affected:
src/app/(dashboard)/dashboard/submissions/new/page.tsx
Location: Submission detail view (grantee perspective)
Issue: While getApplicationStage() returns stage information, the UI doesn't clearly show:
- What stage the submission is currently at
- What stages come next
- Timeline/estimated time for each stage
- What actions are required at current stage
Impact: Grantees don't understand where they are in the process or what to expect next, leading to confusion and support requests.
Recommendation:
- Add visual progress indicator/timeline showing all stages:
- Pending → In Review → Approved → Milestones → Completed
- Show current stage highlighted
- Display "Next steps" section with actionable items
- Add estimated time for each stage
Files Affected:
src/components/submissions/grantee-submission-view.tsx
Location: Reviewer submission view
Issue: When a reviewer has voted, the vote status is shown but:
- Easy to miss if page scrolls
- Not clearly visible in the submissions list
- No quick way to see all submissions where vote is needed vs completed
Impact: Reviewers waste time opening submissions they've already voted on, or miss submissions that need their vote.
Recommendation:
- Add vote status badge in submission cards/list view
- Add filter: "Needs My Vote" vs "Voted"
- Show vote status (approve/reject/abstain) in submission header
- Add "My Votes" section in reviewer dashboard
Files Affected:
src/app/(dashboard)/dashboard/review/review-dashboard-client.tsxsrc/components/submissions/reviewer-submission-view.tsx
Location: Submission creation form
Issue: Users fill out a long form with multiple sections (milestones, description, etc.) but there's no "Preview" or "Review Before Submit" step.
Impact:
- Users submit incomplete or incorrect information
- Can't catch typos or formatting issues
- No opportunity to verify milestone amounts add up correctly
Recommendation:
- Add "Preview Submission" button before final submit
- Show read-only preview with all information
- Allow editing from preview mode
- Highlight any missing required fields
Files Affected:
src/app/(dashboard)/dashboard/submissions/new/page.tsx
Location: Milestone submission
Issue: There's no validation that previous milestones are completed before submitting a new milestone. Code checks for previousMilestoneCommitSha but doesn't prevent submission if previous milestone is still pending.
Impact: Grantees may submit milestones out of order, causing confusion in review process.
Recommendation:
- Disable "Submit Milestone" button if previous milestone is not completed
- Show clear message: "Please complete Milestone X before submitting Milestone Y"
- Visual indicator showing milestone dependency chain
Files Affected:
src/components/milestone-submission-form.tsxsrc/app/(dashboard)/dashboard/submissions/milestone-actions.ts
Location: Discussion threads on submission pages
Issue: Discussion threads may load all messages at once without pagination. For submissions with many comments, this causes:
- Slow page load
- Poor performance
- Hard to find recent comments
Impact: Users experience lag when viewing active discussions, and may miss important recent comments.
Recommendation:
- Implement pagination (load 20-50 messages at a time)
- Add "Load More" button
- Show message count and "Jump to latest" button
- Lazy load older messages
Files Affected:
src/components/discussion/discussion-thread.tsx
Location: Throughout application
Issue: Button labels don't consistently indicate what action will be taken:
- "Submit" vs "Submit for Review" vs "Create Submission"
- "Approve" vs "Vote Approve" vs "Approve Transaction"
- "Review" is used for both viewing and voting
Impact: Users are uncertain about what clicking a button will do, leading to hesitation and mistakes.
Recommendation:
- Standardize button labels:
- Submission: "Submit Application"
- Milestone: "Submit Milestone for Review"
- Voting: "Approve Submission" / "Reject Submission"
- Multisig: "Initiate Transaction" / "Approve Transaction" / "Execute Payment"
- Add confirmation dialogs for irreversible actions
Location: Various pages (dashboard, submissions list, milestones)
Issue: Empty states show generic messages like "No submissions found" without:
- Guidance on what to do next
- Links to relevant actions (e.g., "Create your first submission")
- Help documentation links
Impact: New users don't know how to get started or what actions are available.
Recommendation:
- Add contextual empty states with:
- Friendly icon/illustration
- Clear message explaining why it's empty
- Primary action button (e.g., "Create Submission")
- Link to help/docs
Location: Throughout application
Issue: Dates are displayed in various formats:
- Some use
toLocaleDateString() - Some show relative time ("2 days ago")
- Some show full ISO dates
- No timezone indication
Impact: Users can't quickly understand when events occurred, especially for time-sensitive items like deadlines.
Recommendation:
- Standardize date formatting:
- Recent (< 24h): Relative time ("2 hours ago")
- This week: Day and time ("Monday 3:45 PM")
- Older: Full date ("Dec 6, 2025")
- Always show timezone (UTC or user's timezone)
- Add tooltip with full timestamp
Location: Submission creation form
Issue: The submission form is long and complex but has no auto-save or draft functionality. If a user accidentally closes the browser or loses connection, all work is lost.
Impact: Users lose hours of work, leading to frustration and abandonment.
Recommendation:
- Implement auto-save to localStorage every 30 seconds
- Show "Draft saved" indicator
- Allow "Save as Draft" button
- Load draft when returning to form
Location: Reviewer voting
Issue: When a reviewer rejects a submission or milestone, there's no confirmation dialog. This is an irreversible action that affects grantee funding.
Impact: Accidental rejections due to misclicks, no opportunity to reconsider.
Recommendation:
- Add confirmation dialog: "Are you sure you want to reject this submission? This action requires justification."
- Require feedback/justification before allowing rejection
- Show warning: "Rejection will notify the grantee and prevent approval until changes are made"
Location: Notification toasts and notification center
Issue: Notifications appear via SSE stream but:
- No sound/desktop notification options
- Easy to miss if user is on different tab
- No way to mark all as read
- No filtering (only unread vs all)
Impact: Users miss important notifications about milestone reviews, votes needed, etc.
Recommendation:
- Add desktop notification permissions prompt
- Sound alerts for high-priority notifications
- "Mark all as read" button
- Filter by type (submission, milestone, vote, comment)
- Badge count on notification icon
Location: Multisig voting panel
Issue: Wallet connection is required for multisig but:
- No clear explanation of why wallet is needed
- Connection state not persistent across page refreshes
- Multiple wallet options but no guidance on which to choose
- No indication of which wallet address should be used (must match signatory)
Impact: Reviewers struggle to connect wallets, may connect wrong wallet, and must reconnect frequently.
Recommendation:
- Add explanatory text: "Connect the Polkadot wallet that matches your committee signatory address"
- Show expected signatory addresses for the committee
- Validate connected address matches a signatory before allowing actions
- Persist connection state in session storage
- Show connection status prominently
Location: Submission form and milestone submission
Issue: GitHub repository URLs are validated but:
- No check if repository is accessible
- No verification that user has access to repo
- No preview of repository contents
- Commit fetching may fail silently
Impact: Users enter invalid or inaccessible repos, milestone submission fails when fetching commits.
Recommendation:
- Validate repository URL and accessibility on blur
- Show repository preview (name, description, last commit)
- Test commit fetching before submission
- Show error if repository is private and user doesn't have access
- Allow manual commit entry if GitHub API fails
Issue: No keyboard shortcuts for common actions:
- Submit form (Ctrl+Enter)
- Save draft (Ctrl+S)
- Navigate between submissions (arrow keys)
Recommendation:
- Add keyboard shortcuts for power users
- Document shortcuts in help menu
- Ensure all interactive elements are keyboard accessible
Issue: Complex forms and tables may not work well on mobile devices:
- Milestone form with commit selection
- Submission cards with long text
- Multisig voting panel
Recommendation:
- Test and optimize for mobile viewports
- Consider simplified mobile views for complex features
- Touch-friendly button sizes and spacing
Issue: Many async operations show no loading indicators:
- Fetching submissions list
- Loading discussion threads
- Fetching GitHub commits
- Processing votes
Recommendation:
- Add skeleton loaders for list views
- Show progress indicators for long operations
- Disable buttons during processing
- Show estimated time remaining for known long operations
Issue: No search or advanced filtering on:
- Submissions list
- Grant programs
- Discussion messages
Recommendation:
- Add search bar for submissions (by title, submitter, status)
- Filter by date range, amount, status
- Search within discussion threads
- Save filter presets
Issue: No breadcrumbs showing navigation path:
- Dashboard → Submissions → Submission #123 → Milestone #5
Impact: Users can't easily navigate back or understand where they are in the app hierarchy.
Recommendation:
- Add breadcrumb navigation to all detail pages
- Make breadcrumbs clickable for navigation
- Show current page in breadcrumb
Location: checkQuorumAndUpdateStatus function
Issue: Quorum is calculated based on active member count, but:
- Doesn't account for members who are inactive or unavailable
- No distinction between "voting members" and "all members"
- Threshold percentage might not match actual voting power
Recommendation:
- Add explicit "voting members" list separate from all members
- Show quorum status clearly: "2 of 3 votes required (66%)"
- Display who has voted and who hasn't
- Show time remaining if voting deadline exists
Location: Milestone review and rejection
Issue: When milestone is rejected:
- Status changes to
rejectedbut unclear what grantee should do next - No "resubmit" flow - grantee may not know they can resubmit
- Rejection feedback may be lost if milestone is resubmitted
Recommendation:
- Clear status: "Rejected - Resubmission Required"
- Add "Resubmit Milestone" button for rejected milestones
- Preserve rejection feedback/history
- Show rejection count and reasons
Location: Submission approval workflow
Issue: When submission is approved, milestones should become active, but:
- No clear indication that milestones are now "unlocked"
- Grantee may not be notified that they can start working
- Milestones might be created but status unclear
Recommendation:
- Automatically change milestone status from
pendingtoin_progressorpending(unlocked) when submission approved - Send notification: "Your submission was approved! You can now start working on milestones."
- Show milestone timeline with start dates
- Enable milestone submission buttons only after approval
Location: Multisig approval workflow
Issue: The multisig state is tracked in database but:
- No handling of failed transactions
- No timeout/expiration handling
- What happens if a signatory becomes inactive?
- No way to cancel/revoke a pending multisig transaction
Recommendation:
- Add transaction status tracking (pending, approved, executed, failed, expired)
- Handle timeouts - if transaction not executed within X blocks, allow new initiation
- Add "Cancel Transaction" option if threshold not met
- Show transaction expiration time
Location: Review voting system
Issue: Reviews have weight and isBinding fields but:
- UI doesn't show vote weights
- No explanation of what "binding" vote means
- Final votes have weight 2, but this isn't clear to reviewers
Recommendation:
- Display vote weights in review UI
- Explain binding votes: "This is a final binding vote that will complete the approval if quorum is met"
- Show vote impact: "Your vote has 2x weight as the final approval vote"
- Visual distinction between standard and binding votes
Location: src/components/review/milestone-review-dialog.tsx
Issue: The merged workflow (where blockchain transaction and review vote are combined) is confusing:
- The dialog shows wallet connection requirements, but reviewers may not understand they MUST connect wallet to approve
- If wallet connection fails during approval, the review submission is blocked entirely
- No clear indication that approve vote will trigger blockchain transaction automatically
- Reject/abstain votes don't need wallet, but this isn't clear upfront
Impact: Reviewers trying to approve milestones get stuck when wallet isn't connected, and may not understand why their vote can't be submitted.
Recommendation:
- Show clear workflow explanation: "To approve, you must connect your wallet. Approving will create/join a multisig transaction on-chain."
- Separate the workflow: Allow reviewers to submit review vote first, then handle blockchain transaction separately
- Show different paths: "Approve (requires wallet)" vs "Reject/Abstain (no wallet needed)"
- Add wallet connection check earlier in the flow, before vote selection
Files Affected:
src/components/review/milestone-review-dialog.tsx
Location: src/app/(dashboard)/dashboard/review/review-dashboard-client.tsx
Issue: The filter buttons have confusing labels:
- "Active" filter includes pending, in-review, changes-requested, AND approved
- "Pending" button filters by status but "Active" is a different concept (not rejected)
- Reviewers may expect "Active" to mean "needs action" not "not rejected"
- No filter for "Needs My Vote" specifically
Impact: Reviewers waste time filtering through approved submissions when they're looking for work to do.
Recommendation:
- Add explicit "Needs My Vote" filter
- Rename "Active" to "In Progress" or "Not Rejected"
- Show count badges on filters: "Pending (3)", "Needs My Vote (5)"
- Default view should be "Needs My Vote" if user has pending actions
Files Affected:
src/app/(dashboard)/dashboard/review/review-dashboard-client.tsx
Location: src/components/discussion/reviewer-voting.tsx
Issue: The vote summary shows counts but missing critical information:
- Doesn't show quorum requirement (e.g., "3 of 3 votes required")
- Doesn't show approval percentage needed (e.g., "66% approval required")
- Doesn't indicate if threshold is met for approval
- Doesn't show who hasn't voted yet (other committee members)
Impact: Reviewers can't tell if their vote will be decisive or if more votes are needed.
Recommendation:
- Show quorum status: "2 of 3 votes received (1 more needed for quorum)"
- Display approval threshold: "Requires 2 approve votes (66%) for approval"
- List all committee members with vote status (voted/not voted)
- Show projection: "Current: 2 approve, 0 reject → Will approve if threshold met"
- Highlight when reviewer's vote would be decisive
Files Affected:
src/components/discussion/reviewer-voting.tsx
Location: src/components/discussion/reviewer-voting.tsx
Issue: Reviewers can reject submissions/milestones without providing feedback. While feedback is "recommended" for rejections, it's not required.
Impact: Grantees receive rejections without explanation, making it impossible to improve and resubmit.
Recommendation:
- Make feedback required for reject votes
- Show warning: "Rejection without feedback makes it difficult for grantees to improve. Please provide detailed feedback."
- Validate: "Please provide at least 50 characters explaining why this is rejected"
- Show example feedback prompts based on common rejection reasons
Files Affected:
src/components/discussion/reviewer-voting.tsxsrc/components/review/milestone-review-dialog.tsx
Location: src/components/review/milestone-review-dialog.tsx
Issue: After submitting an approval vote with multisig transaction:
- Dialog closes immediately after blockchain transaction succeeds
- No indication if transaction was the first vote, subsequent vote, or final vote
- No confirmation showing transaction hash or execution status
- Reviewer may not know if payment was executed or still needs more signatures
Impact: Reviewers don't know if their approval completed the payment or if more votes are needed.
Recommendation:
- Show transaction result summary before closing dialog:
- "Transaction created: 0x1234... (1 of 2 signatures)"
- "Your signature added: 0x5678... (2 of 2 signatures - EXECUTING)"
- "Payment executed: 0x9abc... (Block #12345)"
- Add "View Transaction" link to block explorer
- Keep dialog open for 5 seconds to show result, then auto-close
- Show progress indicator: "Awaiting 1 more signature before execution"
Files Affected:
src/components/review/milestone-review-dialog.tsxsrc/components/milestone/milestone-voting-panel.tsx
Location: src/components/review/pending-actions-panel.tsx
Issue: Pending actions are shown but:
- No sorting by urgency (overdue milestones should be first)
- No distinction between "needs my vote" vs "waiting for others"
- Days old calculation may not account for business days
- Critical/urgent badges are shown but actions aren't sorted by urgency
Impact: Reviewers may miss urgent items or waste time on items that can wait.
Recommendation:
- Sort by urgency: Critical > Urgent > Normal
- Within urgency, sort by days old (oldest first)
- Group by: "Requires My Action" vs "Awaiting Others"
- Add "Mark as Reviewed" for items that don't need immediate action but reviewer wants to track
- Show "Overdue" badge for items past due date
Files Affected:
src/components/review/pending-actions-panel.tsx
Location: src/components/discussion/reviewer-voting.tsx
Issue: Once a reviewer votes, they cannot change their vote. The UI shows "You have already submitted your review" but doesn't explain:
- Why votes can't be changed (integrity of review process)
- What to do if they made a mistake
- How to add additional feedback after voting
Impact: Reviewers who realize they made an error have no recourse, leading to incorrect outcomes.
Recommendation:
- Add explanation: "Votes cannot be changed to maintain review integrity. If you need to add feedback, post a comment in the discussion."
- Allow adding comments/feedback after voting (separate from vote)
- For critical errors, allow admins to reset votes (with audit log)
- Show vote timestamp: "You voted Approve on Dec 6, 2025 at 3:45 PM"
Files Affected:
src/components/discussion/reviewer-voting.tsx
Issue: Reviewers reviewing multiple submissions have no way to compare them side-by-side or see patterns across submissions.
Recommendation:
- Add "Compare Submissions" feature (select 2-3 submissions)
- Show side-by-side comparison of key metrics (amount, milestones, labels)
- Highlight differences and similarities
- Help reviewers make consistent decisions
Location: src/app/(dashboard)/dashboard/review/review-dashboard-client.tsx
Issue: Submission cards in review dashboard don't show enough context:
- Doesn't show if other reviewers have voted
- Doesn't show how long submission has been waiting
- Doesn't show if reviewer is part of the reviewing committee
- Doesn't show submission history (resubmissions, previous rejections)
Impact: Reviewers can't quickly assess which submissions need attention or understand submission history.
Recommendation:
- Show vote progress: "2/3 votes (1 more needed)"
- Show wait time: "Pending for 5 days"
- Show committee badge if reviewer is member
- Show resubmission indicator: "Resubmitted - Previously rejected"
Files Affected:
src/app/(dashboard)/dashboard/review/review-dashboard-client.tsx
Location: src/components/review/milestone-review-dialog.tsx
Issue: When reviewing a milestone, reviewers don't see:
- Previous milestone reviews from same submission
- Submission approval history
- Grantee's response to previous feedback
- Other milestones' status in same submission
Impact: Reviewers make decisions in isolation without seeing the full picture of the grant progress.
Recommendation:
- Add "Submission Context" section showing:
- Submission approval date and votes
- Previous milestone reviews (approved/rejected)
- Grantee responses to feedback
- Timeline of all milestones
- Link to full submission view from milestone dialog
- Show consistency: "Previous milestones: 2 approved, 0 rejected"
Files Affected:
src/components/review/milestone-review-dialog.tsx
Issue: Submission cards show a lot of information but hard to scan:
- Long descriptions truncate awkwardly
- Important info (status, amount) not prominent enough
- Labels and badges compete for attention
Recommendation:
- Use card hierarchy: Status badge (top) → Title → Key metrics → Description (collapsed)
- Make amount and status more prominent (larger, bold)
- Use consistent color coding for statuses
- Add hover preview for full description
Issue: Milestone status is shown as badges but no overall progress:
- Can't quickly see "3 of 5 milestones completed"
- No visual progress bar
- Milestone timeline not clearly shown
Recommendation:
- Add progress bar: "3/5 Milestones Completed (60%)"
- Visual timeline showing completed, in-progress, and pending milestones
- Show amount paid vs total amount
- Estimated completion date based on milestone due dates
Issue: Committee and grant program details are scattered:
- Committee info shown in badges but not detailed
- Grant program requirements not visible before applying
- Focus areas shown but not explained
Recommendation:
- Add "View Program Details" modal/expandable section
- Show full program requirements, application template, milestone structure
- Link to committee page with full description
- Explain focus areas with examples
Issue: No handling for:
- Network disconnections during form submission
- API timeouts
- Rate limiting
Recommendation:
- Retry mechanism for failed requests
- Show connection status indicator
- Save form data locally before retry
- Clear error messages: "Connection lost. Your data was saved. Retry?"
Issue: Multiple users can edit discussions simultaneously:
- No conflict resolution
- Messages might be posted out of order
- No "user is typing" indicator
Recommendation:
- Real-time updates using WebSockets/SSE
- Show when other users are viewing/editing
- Timestamp-based conflict resolution
- "X is typing..." indicator in discussions
Issue: When users lack permissions, errors are generic:
- "You are not authorized" doesn't explain why
- No guidance on how to get permissions
- Silent failures in some cases
Recommendation:
- Specific error messages: "You need to be a committee member to review submissions"
- Link to contact admin or request access
- Show required permissions clearly
- Prevent actions rather than failing silently
Issue: Many interactive elements lack proper ARIA labels:
- Status badges not announced
- Button purposes not clear
- Form errors not associated with fields
Recommendation:
- Add
aria-labelto all icon-only buttons - Use
aria-liveregions for dynamic content (notifications, status updates) - Associate error messages with form fields using
aria-describedby - Test with screen readers (NVDA, JAWS, VoiceOver)
Issue: Status badges and text may not meet WCAG contrast requirements:
- Light blue/green badges on white background
- Muted text colors for descriptions
Recommendation:
- Test all color combinations with contrast checker
- Ensure minimum 4.5:1 ratio for text
- Don't rely solely on color to convey information (add icons/text)
Issue: Focus management in modals and dynamic content:
- Focus not trapped in modals
- Focus not returned after closing dialogs
- Keyboard navigation may skip important elements
Recommendation:
- Implement focus trap in all dialogs/modals
- Return focus to trigger element when closing
- Visible focus indicators on all interactive elements
- Logical tab order
Issue: Loading all submissions, milestones, or messages at once:
- No pagination on initial load
- Slow page renders with many items
- Memory usage with large datasets
Recommendation:
- Implement server-side pagination
- Virtual scrolling for long lists
- Lazy load images and non-critical content
- Cache frequently accessed data
Issue: Components may re-render unnecessarily:
- Discussion threads re-render on every message
- Form state updates cause full page re-renders
- No memoization of expensive calculations
Recommendation:
- Use React.memo for list items
- Memoize expensive calculations with useMemo
- Optimize state updates to prevent cascading re-renders
- Use React DevTools Profiler to identify bottlenecks
Issue: Wallet addresses and transaction hashes displayed in UI:
- No option to partially hide addresses (show only first/last chars)
- Full transaction hashes in URLs might be logged
Recommendation:
- Mask wallet addresses: "5FHne...94ty"
- Make addresses copyable but not fully visible by default
- Use relative URLs instead of full transaction hashes in browser history
- Add "Reveal full address" toggle for advanced users
Issue: Forms may be vulnerable to:
- CSRF attacks
- Double submission
- Malicious data injection
Recommendation:
- Verify CSRF tokens are implemented in all forms
- Disable submit buttons after first click
- Sanitize all user input
- Rate limit form submissions
-
End-to-End Submission Flow:
- Create submission → Review → Approve → Submit milestone → Review milestone → Approve → Multisig payment
-
Edge Cases:
- Submit milestone when previous not completed
- Vote on submission when already voted
- Execute multisig when threshold not met
- Submit form with invalid GitHub URL
-
Error Scenarios:
- Network failure during submission
- Invalid wallet connection
- GitHub API rate limit
- Database constraint violations
-
User Flows:
- New grantee creating first submission
- Reviewer reviewing multiple submissions
- Committee admin managing programs
- Grantee tracking milestone progress
Missing:
- Getting started guide for grantees
- Reviewer workflow guide
- Multisig transaction explanation
- FAQ for common questions
Recommendation:
- Add in-app help tooltips
- Create video tutorials for complex workflows
- Build comprehensive FAQ page
- Add contextual help buttons throughout app
Missing:
- Component API documentation
- Workflow state diagrams
- Data flow diagrams
- Testing guide
Recommendation:
- Document component props and usage
- Create architecture diagrams
- Document state management patterns
- Add integration testing examples
Immediate (This Sprint):
- Clear error messages on form submission (#1.1)
- Milestone status logic consistency (#1.2)
- Multisig flow explanation (#1.3)
- Submission processing feedback (#1.4)
Short Term (Next Sprint): 5. Grant program selection UI (#2.1) 6. Submission status progression (#2.2) 7. Reviewer vote status visibility (#2.3) 8. Preview before submission (#2.4)
Medium Term (Next Month): 9. All medium priority issues (#3.x) 10. Usability improvements (#4.x) 11. Logic and workflow fixes (#5.x)
Long Term (Next Quarter): 12. Performance optimizations (#9.x) 13. Comprehensive testing (#11.x) 14. Documentation (#12.x)
The GrantFlow application has a solid foundation but needs improvements in user feedback, workflow clarity, and error handling. The most critical issues are around communication - users need to understand what's happening, what to do next, and why things happen. The multisig workflow in particular needs better UX to guide reviewers through the blockchain transaction process.
Focusing on the immediate priorities will significantly improve user experience and reduce support burden. The application shows good technical architecture but needs polish in the user-facing aspects.
Report Generated: December 6, 2025
Next Review: After implementation of critical issues