Product Requirements Document: ScholarshipFlow

1. Executive Summary

ScholarshipFlow is a centralized management platform designed to help students navigate the fragmented scholarship application landscape. By leveraging AI-driven semantic scraping, automated checklist generation, and durable notification workflows, the platform transforms a chaotic process into a structured, manageable pipeline. ScholarshipFlow ensures students never miss a deadline while providing a secure, encrypted vault for sensitive academic documents.

2. Problem Statement

Applying for scholarships is currently a manual, error-prone process. Students juggle dozens of tabs, varying requirements (essays, transcripts, letters of rec), and inconsistent deadlines across multiple websites and spreadsheets. This leads to "application fatigue," missed opportunities due to forgotten deadlines, and security risks from storing sensitive transcripts in unencrypted local folders or basic cloud storage.

3. Goals & Success Metrics

• Goal 1: Reduce the time spent manually creating checklists from scholarship URLs.
  • Metric: Average time to "Add Scholarship" (Target: < 30 seconds).
• Goal 2: Increase application completion rates.
  • Metric: % of tracked scholarships marked as "Submitted."
• Goal 3: Prevent missed deadlines.
  • Metric: 0% missed deadlines for users with active notification settings.
• Goal 4: Ensure top-tier data privacy.
  • Metric: 100% compliance with FERPA and COPPA 2026 amendments.

4. User Personas

1. High School Senior (Alex): Tech-savvy but overwhelmed by college prep. Needs a "source of truth" to track 20+ scholarships and needs reminders to stay on track.
2. Graduate Applicant (Maya): Focuses on highly specific research grants. Needs a secure way to store complex research papers and transcripts.
3. The Guidance Counselor (Mr. Henderson): Manages 100+ students. Needs to see aggregate progress and help students organize their requirements without manual check-ins.
4. The Parent (Sarah): Wants to assist their child in the process without being "annoying." Needs visibility into upcoming dates.

5. User Stories

• As a student, I want to paste a scholarship URL so that the system automatically extracts the deadline and required documents for me.
• As a student, I want a Kanban-style dashboard so that I can visually track my progress from "Draft" to "Awarded."
• As a student, I want to store my transcripts in an encrypted vault so that I don't have to search for them every time I apply.
• As a counselor, I want to create a "Shared Folder" of scholarships so that my students can immediately add them to their individual trackers.
• As a user, I want to receive a push notification 48 hours before a deadline so that I have time for final edits.

6. Functional Requirements

6.1 Scholarship Intake Engine

• Semantic AI Scraper: Integration with Firecrawl to extract JSON-structured data (Deadlines, Eligibility, Documents) from any URL.
• Chrome Extension: One-click saving of scholarships directly from a browser.

6.2 Management Dashboard

• Kanban Board: Using hello-pangea/dnd for drag-and-drop status tracking (Backlog, In Progress, Submitted, Result).
• Automated Checklists: Dynamic task lists generated per scholarship.

6.3 Secure Document Vault

• Zero-Knowledge Storage: Client-side AES-256-GCM encryption for all uploaded PDFs and images.
• One-Click Attachment: Ability to "attach" a vault document to a specific application requirement.

6.4 Notification & Sync Engine

• Two-Way Calendar Sync: Google/Outlook integration via Microsoft Graph and Google v3 APIs.
• Durable Alerts: Using Inngest to handle "sleep-until-deadline" logic for reliable notifications.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

• Framework: Next.js 16.1.3 (App Router, Turbopack, React 19).
• Styling: Tailwind CSS v4.0 (Utilizing container queries and @starting-style).
• Authentication: Clerk (Native Third-Party Auth integration with Supabase).
• Database: PostgreSQL via Supabase (with Row-Level Security).
• Workflows: Inngest (Durable execution for notifications).
• Scraping: Firecrawl Node.js SDK + Playwright.

7.2 Security & Compliance

• FERPA/COPPA: Implement "Privacy by Design" with mandatory 30-day data deletion workflows.
• Encryption: Web Crypto API for client-side encryption before uploading to Supabase Storage.

8. Data Model

Entities:

• Organization (Clerk Org): Tracks tenant data (e.g., a school or a family group).
• User: id, clerk_id, email, role, organization_id.
• Scholarship: id, title, url, deadline, amount, is_custom.
• Requirement: id, scholarship_id, title, type (Essay, Transcript, etc.), status.
• Application: id, user_id, scholarship_id, status (Enum), notes.
• VaultDocument: id, user_id, encrypted_blob_path, iv, filename_hash.

9. API Specification (Internal)

| Endpoint | Method | Description | | :--- | :--- | :--- | | /api/scrape | POST | Takes URL, returns structured Scholarship JSON via Firecrawl. | | /api/vault/upload | POST | Accepts encrypted blob and IV; stores in Supabase. | | /api/sync/calendar | POST | Triggers immediate sync with Google/Outlook. | | /api/notifications/schedule | POST | Schedules an Inngest durable workflow for a deadline. |

10. UI/UX Requirements

• Visual Direction: "Clean Productivity." High-density information but with ample whitespace.
• Components:
  • Tailwind v4 Container Queries: Dashboard widgets must resize perfectly when the sidebar is collapsed.
  • Accessible Kanban: Must support keyboard navigation (hello-pangea/dnd).
  • Glassmorphism: Use backdrop-blur-xl for overlays to maintain context.
• Animations: Use @starting-style for instant, non-JS-heavy entry transitions for toast notifications.

11. Non-Functional Requirements

• Performance: < 100ms for UI interactions; Turbopack-optimized builds.
• Availability: 99.9% uptime (handled by Vercel/Supabase).
• Accessibility: WCAG 2.2 Level AA compliance.
• Scalability: Support for 1,000+ cards per user board using Pragmatic DnD principles if needed.

12. Out of Scope

• Scholarship Disbursement: We do not handle the actual money/funds.
• AI Essay Writing: We provide word count tracking and prompts, but not automated writing (to maintain academic integrity).
• Direct Application Submission: Most scholarship portals require their own login; we provide a link to the portal.

13. Risks & Mitigations

• Risk: Scholarship portals block Firecrawl scrapers.
  • Mitigation: Use Scrapfly with proxy rotation and residential IPs for high-resilience scraping.
• Risk: Students lose their encryption passphrase.
  • Mitigation: Implement a "Recovery Key" system similar to BitWarden/1Password.
• Risk: AI extraction hallucination.
  • Mitigation: Always present extracted data in a "Review & Confirm" modal before saving.

14. Implementation Tasks

Phase 1: Project Setup

• [ ] Initialize project with Next.js 16.1.3 and Turbopack
• [ ] Install and configure Tailwind CSS v4.0 with CSS-first theme
• [ ] Set up Clerk Authentication with Supabase Native Third-Party Auth integration
• [ ] Configure TypeScript with strict mode and path aliases

Phase 2: Core Data & Auth

• [ ] Define PostgreSQL schema in Supabase with organization_id for multi-tenancy
• [ ] Implement Row-Level Security (RLS) policies using auth.jwt() ->> 'sub'
• [ ] Build Clerk Webhook handler in Supabase Edge Functions to sync user profiles
• [ ] Create basic Auth middleware for route protection

Phase 3: AI Scraping & Dashboard

• [ ] Integrate Firecrawl Node.js SDK for semantic scholarship extraction
• [ ] Build "Add Scholarship" modal with "Review & Confirm" AI results
• [ ] Implement Kanban Dashboard using hello-pangea/dnd for status tracking
• [ ] Create automated checklist generator logic (Markdown to JSON)

Phase 4: Secure Vault & Files

• [ ] Implement Web Crypto API (AES-256-GCM) logic for client-side file encryption
• [ ] Set up Supabase Storage buckets with RLS for encrypted blobs
• [ ] Build Vault UI with chunked upload support (TUS) for large transcripts
• [ ] Create "Attach from Vault" functionality for scholarship requirements

Phase 5: Calendar & Notifications

• [ ] Implement Microsoft Graph and Google Calendar v3 OAuth flow
• [ ] Set up Inngest durable workflows for deadline reminder logic
• [ ] Build notification preference center (Email, Push, SMS via Novu)
• [ ] Implement two-way sync loop prevention with metadata signatures

Phase 6: Compliance & Polishing

• [ ] Audit for COPPA 2026 amendments (Parental consent flow for <13)
• [ ] Implement 30-day automated data purge for deleted accounts
• [ ] Final accessibility pass (WCAG 2.2) and keyboard navigation testing
• [ ] Deploy to Vercel with OpenTelemetry instrumentation enabled