GradAid

Version 2.1
Website: https://gradaid.online
Last Updated: 2025-04-30
Document Owner: jirissman

Table of Contents

1. Product Vision
2. Personas
3. User Scenarios
4. Product Requirements
5. Team Process and Development History
6. Technical Architecture
7. File Structure
8. Security, Privacy, and Reliability
9. Installation
10. Testing

Product Vision

For international students planning to attend graduate school in the US who need to draft documentation required for their applications. GradAid is an AI Driven Service Provider that provides students with freedom to be creative and tailor stories to their individual needs at a low-cost. Unlike educational consultancies, our product is available to users at any time and at a lower cost.

Personas

Persona 1 - Li Lei

Li Lei, age 24, is a Chinese graduate student completing his MS degree in Biomedical Science. Originally from China, he earned his bachelor's degree in Chemistry before pursuing his master's studies. Li is passionate about scientific research and is determined to pursue a PhD in the United States to further his academic career. Despite his strong research background, he struggles with academic writing in English and is unfamiliar with the specific expectations of U.S. graduate applications. Li hopes to craft compelling Statements of Purpose (SOPs) and Letters of Recommendation (LORs) that effectively showcase his research achievements and align with his PhD aspirations. He views GradAid as an essential tool to generate professional, grammatically accurate documents tailored to his needs while helping him refine his tone and clarity for a natural-sounding application.

Persona 2 - Astha Jain

Astha Jain, a 28-year-old from Jaipur, India, comes from a large family and was the first to attend college. She pursued her passion for medicine at Mahatma Gandhi University of Medical Sciences and Technology, earning a Bachelor of Medicine and Bachelor of Surgery (MBBS) degree with high marks. Although she initially aspired to become a surgeon, she faced challenges finding employment immediately after graduation. Relocating to New Delhi in search of opportunities, she worked as a server to support herself while continuing her job search. Eventually, she secured a position as a junior doctor at a family medicine practice, where she worked for two years until the practice closed due to financial difficulties. Following this setback, she accepted a nursing position at Jeewan Mala Hospital in New Delhi. This career detour, coupled with the demanding hours of her new role, has prompted her to re-evaluate her career path. She now plans to pursue a graduate degree in a growing and more lucrative field, such as computer science or finance. Having saved enough money to study in the United States, she hopes that a graduate degree from a top American university will open doors to high-paying jobs, enabling her to support her aging parents, whose ability to work is diminishing.

Persona 3 - Carlos Mendoza

Carlos Mendoza, age 26, is a software engineer from Mexico City with four years of experience in backend development. He earned his bachelor's degree in Computer Science from UNAM and has worked at a mid-sized tech company. Carlos has always been passionate about AI and machine learning and wants to pivot into research, but his current job focuses more on software development rather than deep AI work. He plans to apply for an MS in Artificial Intelligence in the United States to gain the necessary academic background to transition into AI research roles. However, he is unfamiliar with the research-heavy SOPs required for graduate applications and has limited experience writing formal academic documents in English. He is also unsure how to best frame his work experience to demonstrate its relevance to AI research. He hopes GradAid will help him craft a strong SOP that highlights his technical background while showcasing his research potential in AI.

User Scenarios

Scenario 1 - Li Lei

Li Lei, a 24-year-old Chinese graduate student completing his MS in Biomedical Science, is preparing to apply for PhD programs in the United States. With a BS in Chemistry and extensive research experience, he is eager to continue his academic journey in biomedical innovation. However, he faces significant challenges in crafting a compelling application due to his limited English proficiency and unfamiliarity with the tone, structure, and expectations of U.S. graduate admissions. Writing a strong Statement of Purpose (SOP) and securing well-crafted Letters of Recommendation (LORs) feels overwhelming, as he struggles to articulate his research achievements and career goals in a way that resonates with admissions committees.

To overcome these challenges, Li turns to GradAid, which helps him generate well-structured, grammatically accurate SOPs and LORs tailored to his background and aspirations. By inputting key details about his academic journey and research experience, he receives personalized drafts that he can refine using GradAid's tone adjustment and clarity-enhancing features. The platform also provides research-focused suggestions to ensure his documents align with the expectations of specific PhD programs. With GradAid's support, Li gains confidence in his application, knowing that his materials effectively highlight his strengths and are presented in a professional, natural-sounding manner.

Scenario 2 - Astha Jain

Astha is determined to pursue a graduate degree in the US, but the application process feels overwhelming. Remembering a friend's recommendation, she opens her browser and navigates to GradAid.com. Astha clicks the "Get Started" button and begins interacting with GradAid's AI chatbot.

GradAid asks her a series of questions: her background, academic achievements, work experience, career aspirations, and preferred fields of study. Astha appreciates how GradAid's conversational interface makes it easy to share her story, even the less conventional parts. She explains her medical background, her shift to nursing, and her desire to transition into a more lucrative and stable career to support her parents. Based on Astha's input, GradAid's AI analyzes her profile and generates a list of potential graduate programs in computer science and finance at universities across the US. The recommendations are tailored to her academic record, work history, and career goals. Astha is impressed by the breadth and relevance of the suggestions.

Astha selects a few programs that pique her interest. She knows the Statement of Purpose (SOP) is crucial, and it's where she's been struggling the most. Thankfully, GradAid offers an SOP brainstorming tool. GradAid's AI generates a series of prompts and potential themes for her SOP, suggesting ways to connect her seemingly disparate experiences into a cohesive narrative. Astha finds this incredibly helpful, as she's able to recognize the transferable skills she's gained, like problem-solving, communication, and adaptability.

Scenario 3 - Carlos Mendoza

Carlos has started drafting his Statement of Purpose (SOP) for MS programs in AI, but he's struggling to connect his industry experience in backend development to his passion for machine learning. Unsure of how to frame his background, he logs into GradAid and inputs details about his education, work experience, and research interests.

GradAid analyzes his profile and suggests ways to highlight transferable skills from his software engineering background, such as his experience working with large datasets, optimization algorithms, and distributed computing. The AI-generated SOP draft weaves his technical experience into a compelling narrative, emphasizing how his work has naturally led him toward AI research. The platform also offers AI-powered editing tools to refine the language, ensuring his SOP is both professional and persuasive.

Scenario 4 - Carlos Mendoza

Carlos has shortlisted five MS programs in AI, each with slightly different focuses—some emphasize research, while others are more industry-oriented. He wants to tailor his SOP for each program but doesn't know how to efficiently modify his content.

Using GradAid's customization feature, he selects the target programs and receives program-specific suggestions for refining his SOP. The tool highlights key faculty members and research labs he should mention, recommends how to emphasize certain skills based on each program's focus, and adjusts the wording to align with the expectations of research vs. industry-focused programs. With GradAid's help, Carlos creates tailored versions of his SOP, increasing his chances of securing admission.

Product Requirements

Must Have – minimal for release, required for a useful product

Feature	User Story	Persona or Scenario	Technical Requirements	Completed by team member(s) or reason not completed
Interactive form to collect user information and store in a database.	As an aspiring graduate student, I need to provide information about myself through an interactive form.	All personas and scenarios	- Form must capture academic history, work experience, achievements, skills, and career goals - Progressive form with multi-step validation - Form state must persist between sessions - Data should be stored in Convex database with appropriate schema	Yue Zhang wrote the majority of code for this feature, Joseph Rissman supported with code review and backend tests.
User authentication.	As a multi-device user, I need to log in so that my activity and history are saved and synchronized across all devices.	Basic feature for all web applications	- Authentication via Clerk with email/password and OAuth options (Google, GitHub) - Account verification via email - Session management through Clerk SDK - Password reset functionality	Joseph Rissman set up user authentication through Clerk as a microservice and integrated it with the database and the UI.
Customized SOP generation, specific to university requirements.	As an applicant applying to many graduate programs, I need automated document creation based on my university choice so that I can focus more on my application strategy.	Astha's scenario	- University database with program-specific requirements - AI prompting system that incorporates university-specific details - Document template system with dynamic sections - Ability to generate multiple variations for different programs	Yue Zhang wrote the code for generating documents with the OpenAI API, using profile and program-specific information from the database. Nitin Krishna Bojji created a custom prompt to provide more personalized responses.
Customized SOP generation, specific to user information.	As a mid-career professional seeking a graduate degree abroad, I need to have my diverse background and skillset reflected in my SOP.	Astha's scenario	- AI model integration for personalized content generation - Natural language processing for coherent narrative creation - Tone and style adjustment features - Skill mapping algorithm to highlight relevant experiences	See above.
Cross-platform support.	As a global applicant with limited internet access, I need to interact with GradAid in a web browser on my phone.	Global accessibility requirement	- Responsive design using Tailwind CSS - Progressive Web App (PWA) features - Optimized asset loading for slow connections - Offline capability for document editing	Yue Zhang set up the project on Netlify to host the product on the internet. Yue Zhang and Joseph Rissman both contributed to ensuring the UI and UX is high-quality for both desktop and mobile users.
User authentication and data security (RBAC, OAuth, etc.)	As a privacy-conscious user, I need data encryption and security measures so that my personal information is protected from unauthorized access and potential leaks.	Common security concern	- HTTPS implementation - Data encryption at rest and in transit - GDPR and CCPA compliance measures - Clerk's role-based access control - Regular security audits	Joseph Rissman set up automated routing to ensure users cannot access the application features unless they are signed in through Clerk. Joseph Rissman and Yue Zhang designed all code to be focused on security, with multiple checks to ensure users can only access their own data. Joseph Rissman implemented a feature to allow users to delete their account and all associated data for extra security.

Want to Have – improves on a required feature or additional functionality

Feature	User Story	Persona or Scenario	Technical Requirements	Completed by team member(s) or reason not completed
Document management system.	As an applicant needing to update my application materials, I want to quickly find my relevant documents.	Returning user scenario	- Document versioning system - Search functionality with metadata filtering - Folder/tag organization structure - Export options (PDF, DOCX, TXT)	Yue Zhang implemented a document page where users can quickly see all of their documents sorted by application. Yue Zhang also implemented routing to allow users to access their documents for an application directly from the application detail page or even straight from the main dashboard.
Document formatting tools.	As an applicant preparing documents for various universities, I want to specify the format of downloaded documents.	All personas	- Template system with university-specific formatting - Typography and layout controls - Export format options with preview - APA/MLA/Chicago style adherence options	This feature was not completed. This was planned for implementation after MVP launch, but MVP launch was pushed back due to delays integrating AI document generation. At present, users can still copy and paste the document contents into a word processor of their choice, which is a typical user experience when interacting with AI chatbots.
Application tracking system (deadlines).	As an applicant managing multiple university applications, I want a system for tracking application deadlines so that I can ensure timely submissions and avoid missing critical dates	Li's persona	- Calendar integration - Notification system (email, in-app) - Status tracking workflow - Timeline visualization	Yue Zhang implemented the code for tracking application deadlines and displaying them to the user. Joseph Rissman implemented code to allow users to set custom deadlines for greater control of the application process.
Application tracking system (progress).	As someone that struggles with organization and planning, I want a feature for tracking the progress of my applications so that I can stay informed about their status and manage any required follow-up actions.	Astha's persona	- Kanban-style application board - Checklist functionality for application requirements - Progress indicators and metrics - Note-taking capabilities for each application	Yue Zhang wrote all of the code for this feature, however in the current state it is a bit primitive and not bug-free. Work on this feature was delayed due to Yue needing to work on the AI document generation after it became clear Nitin was not contributing to the project.
Program search.	As a prospective graduate student exploring various academic options, I want to interactively search through university programs and save them to a personalized list.	Carlos' persona	- University and program database - Advanced search filters (location, specialization, ranking, etc.) - Comparison tool for multiple programs - Save/favorite functionality with custom lists	Joseph Rissman wrote all of the code for graduate program search and save features. This should have been a must-have requirement as it is now a major part of the product that begins the user flow for creating applications and related documents. Nitin Krishna Bojji helped by web scraping data on universities and graduate programs that populated the database. Joseph Rissman contributed to web scraping by filling in missing data and cleaning incorrect data.

Nice to Have – things to do if there is time

Feature	User Story	Persona or Scenario	Technical Requirements	Completed by team member(s) or reason not completed
Speech-to-text and text-to-speech.	As an applicant with accessibility needs, I want GradAid to have speech recognition and speech generation capabilities.	Accessibility requirement	- Integration with Web Speech API - Voice command functionality - Text-to-speech for document review - Language and accent detection	This feature was not completed. To be honest, I don’t understand what this feature was supposed to do. Nitin really wanted this feature, but he did not work on it so it did not happen.
UI/UX design and testing.	As a user with limited computer literacy, I want the GradAid website to be inviting with a modern design.	Astha's persona	- Usability testing framework - A/B testing for UI elements - User session recording and analytics - Iterative design process based on feedback	Yue Zhang and Joseph Rissman both worked on the website design to ensure good UI and UX. The decision was made after the first project update to restart the website with the Shadcn/ui component library to provide the website with a consistent and clean look to it. Many users left positive feedback about the design saying it is “sleek” or “slick” and “easy to navigate” so I believe we accomplished this one.
AI-power document updates.	As someone who has gained a new qualification, I want to be able to update my SOPs and LORs so that my new accomplishment is included.	Carlos' persona	- Intelligent document comparison - Suggestion system for document improvements - Automatic update recommendations - Version control and history tracking	Yue Zhang wrote all of the code to make the documents editable. Additionally, users can update their profile information if they have new accomplishments or forgot to include something, then regenerate their documents.
University shortlisting.	As a prospective graduate student, I want to receive a shortlist of universities based on my experience and accomplishments.	Astha's scenario	- Recommendation algorithm based on user profile - Acceptance probability estimation - Program matching based on research interests - Geographic and financial considerations	This feature was not completed. Nitin did write a python function to perform this task, but he delivered it towards the end of the semester. At that point we were still trying to complete the MVP by implementing AI document generation because Nitin had not delivered anything else up to that point. Therefore, the rest of the team did not have the bandwidth to implement a new page for this feature or rewrite the python code so it could actually be used with our database and frontend.

Additional Product Features (Features not anticipated, but completed)

Feature	Reason Implemented	Completed by team member(s)
Landing page with hero section.	Since authentication was required for access to any website features, it became necessary to create a landing page that describes what GradAid is about.	Yue Zhang wrote the majority of code for this feature. Joseph Rissman implemented the sign-in and sign-up flows with Clerk.
Application dashboard.	With the growing complexity of GradAid being split across many pages, we needed a centralized dashboard to display the most important information to the user.	Yue Zhang wrote all of the code for this feature. The dashboard and the associated breakout pages (timeline, credit summary, applications, and activity) are all his work.
User onboarding.	It became clear that to generate personalized documents, we needed a minimum amount of information about the user. Onboarding forces the user to minimally complete their profile before they can access any other core features.	Yue Zhang wrote the code for user onboarding, walking them through the process of creating their profile. Joseph Rissman wrote the code that forces the user to complete onboarding before accessing critical features.
AI usage management.	Because we needed to use the OpenAI API to generate the document content, we needed to limit the amount of documents users can generate to prevent abuse.	Joseph Rissman wrote the backend code that tracks AI usage with credits, and enforces the limit when it is exceeded. Yue Zhang wrote the frontend code that displays the AI usage history and remaining credits to the user.
Logging user activity.	It might be difficult for users to remember what they were doing last if they come back after a while or why they had used up all their AI credits. This feature helps users keep track of their progress.	Joseph Rissman and Yue Zhang wrote the backend code that tracks different user activities. Yue Zhang wrote the frontend code that displays the activity to the user. Admittedly, this feature still has bugs that need to be fixed before it is fully usable.
Frequently asked questions page.	With the growing complexity of the website, it seemed reasonable to include an FAQ page to help users that get lost or have trouble with certain aspects.	Joseph Rissman wrote all of the code for this feature.
Contact form.	If users have any issues with the website, they can directly contact the developers through email to quickly get a response.	Joseph Rissman wrote all of the code for this feature.
Feedback form.	We wanted to collect user feedback to improve the website. Unfortunately, due to a certain team member not contributing to the project, our MVP launch was pushed back too far to be able to actually implement any of the suggested improvements before the end of the semester.	Joseph Rissman wrote all of the code for this feature.
Terms of service & privacy policy.	Although these are not legally binding documents that have not been looked at by a lawyer, it felt like including these legitimized the website.	Joseph Rissman wrote all of the code for this feature.

Team Process and Development History

The project started with the Admissions Alchemists team assigning initial responsibilities among its three members. Yue was designated to focus on frontend web development, Joseph assumed responsibility for backend development and database management, and Nitin was tasked with the AI-related aspects of the project.

During the initial phase of the semester, leading up to the first presentation, team members proceeded with development according to their assigned roles. Joseph selected a database provider and established initial SQL functions for user data and program information storage. Yue developed a custom landing page and dashboard interface. Nitin reported progress on fine-tuning a custom AI model.

Following the first mid-semester presentation, the team determined that the independent development approach was hindering the required pace of progress. Consequently, Joseph and Yue decided to restart the development process. This decision allowed them to leverage the experience gained since the project's inception, enabling them to reach the previous stage of development within approximately one week. Restarting provided an opportunity to collectively select a revised technology stack. Joseph opted for Convex as the database provider, citing its ease of integration with React. This transition also facilitated the adoption of TypeScript across the entire project, aiming to enhance development efficiency by standardizing the language for both frontend and backend components and simplifying troubleshooting. Yue proceeded to rebuild the frontend using React with TypeScript, incorporating the Shadcn component library to expedite development through reusable components. During this period, Nitin continued his assigned work on the LLM fine-tuning.

After the decision to restart and collaborate more closely, the specific responsibilities of Joseph and Yue became more integrated. While Joseph retained primary responsibility for the backend and Convex server management, and Yue for the frontend and Netlify deployment, both adopted full-stack roles. They took ownership of specific features, developing both the necessary frontend and backend code. Joseph initially focused on the program search and save functionality, while Yue addressed the user profile and onboarding features. Completing these features required approximately two sprints because one of the sprints included Spring Break. Both Joseph and Yue contributed to the website layout and design, including the sidebar and header components. Joseph also managed the implementation of user authentication using Clerk. Nitin continued his task related to the custom LLM.

Upon completion of the profile and search features, development shifted to creating new applications and implementing a document editor. Joseph focused on the application creation feature, handling both frontend and backend aspects. Yue developed the document editor, also managing both frontend and backend code. This phase spanned another sprint, during which Joseph and Yue conducted code reviews for each other's previously completed features. Nitin reported completion of the LLM fine-tuning, however, challenges were encountered in deploying the model beyond a local environment. The subsequent sprint was allocated for developing an accessible API for the LLM.

With the application creation and document editing features implemented, the next step involved integrating them to complete the primary user flow. Joseph developed the frontend and backend components for creating new documents, while Yue finalized the dashboard's frontend and backend code, unifying the various elements. Code reviews continued between Joseph and Yue for their respective components. This sprint also included UI/UX refinement, ensuring consistency across the application by implementing a reusable page-wrapper component. As efforts to host the custom LLM on the cloud were unsuccessful, Nitin was assigned the task of developing code to utilize an existing LLM API, such as OpenAI or Llama.

During the penultimate sprint, the task of integrating an LLM API was reassigned to Yue to ensure project timelines were met. Yue developed the backend code to interface with the OpenAI API for generating custom application documents and integrated it with the existing frontend components, utilizing a prompt previously developed by Nitin. Concurrently, Joseph focused on creating support pages, including the FAQ, contact page, and feedback form, developing all associated frontend and backend code. He also refactored the Convex server functions for improved maintainability and adherence to best practices, and implemented an AI credit management system. Both Yue and Joseph reviewed and implemented input validation and sanitization across their previously developed components. With the AI generation feature completed by Yue, Nitin was tasked with web scraping program and university data for database population.

The final sprint involved Joseph and Yue writing tests for the codebase. Joseph processed the web-scraped data provided by Nitin, performing data cleaning, enrichment, and database population. Joseph and Yue collaborated on deploying the application to production servers and launching the website, allowing a week for user feedback collection. Several minor bug fixes and UI updates were implemented during this period, with continued code review between Joseph and Yue.

A significant factor in the successful completion of the MVP within only 6 sprints is the history of collaboration between Joseph and Yue. They have worked together on multiple academic projects in previous courses. Drawing upon their previous experiences, they adopted the approach of assigning full-stack feature ownership to individual members. This approach proved efficient for feature development and integration as it was supported by effective communication and collaboration. Maintaining distinct primary responsibilities for frontend and backend infrastructure ensured clear accountability for service provider management, while their joint efforts ensured seamless integration across all services. The effective collaboration between Joseph and Yue was instrumental in navigating project challenges and achieving the final objectives.

Technical Architecture

Development Tools

• TypeScript: Provides type safety, improved developer experience, and easier debugging across the full stack.
• Vite: A fast frontend build tool and development server that leverages native ES modules for quick startup and updates.
• Netlify: A platform for deploying and hosting web projects, offering serverless functions and automated builds from Git.
• React: A popular JavaScript library for building user interfaces based on reusable components.
• Convex: A full-stack development platform with a real-time database and serverless functions, built for TypeScript.
• Vitest: A Vite-native unit testing framework known for its speed and compatibility with Jest APIs.
• Zod: A TypeScript-first schema declaration and validation library used for data validation.
• Shadcn/ui: A collection of accessible and customizable UI components built with Radix UI and Tailwind CSS for React applications.
• Lucide: An open-source library providing simple and consistent vector (SVG) icons.
• Clerk: A service providing authentication, user management, and sign-in components for applications.
• Git: A distributed version control system used for tracking changes in codebases and collaborating on software projects.
• Svix: A service designed to reliably send and receive webhooks for application integrations.
• Tailwind CSS: A utility-first CSS framework that allows for rapid UI development by composing low-level utility classes.
• Framer Motion: A production-ready animation library for React, used to create fluid animations and gestures.
• Jotai: An atomic state management library for React, offering a flexible and primitive approach to managing application state.
• Resend: An API platform specifically designed for developers to manage and send transactional emails.
• OpenAI: An AI research company providing APIs (like GPT) that allow developers to integrate advanced AI models into applications.

Architecture Overview

GradAid employs a modern, modular architecture based on the model–view–controller (MVC) pattern, designed for maintainability, scalability, and flexibility. The system consists of several key components, mapped generally as frontend (view/controller) and backend (model).

Frontend Architecture

Built with React and using Vite as the build tool for a fast development experience, the frontend is deployed via Netlify. Key modules include:

• Graduate Program Module: Allows users to search for programs, save them, and start applications.
  • https://gradaid.online/search
  • https://gradaid.online/saved
  • https://gradaid.online/apply
• Document Editor: Rich-text editing interface for SOPs and LORs, allowing AI generation or manual editing.
  • https://gradaid.online/documents
• User Dashboard: Centralized location displaying saved documents, application insights, and user information.
  • https://gradaid.online/dashboard
• Onboarding & Profile: Handles user profile creation, updates, and initial setup.
  • https://gradaid.online/onboarding (only accessible if onboarding has not been completed)
  • https://gradaid.online/profile
• Application Management: Enables users to track application progress and access related documents.
  • https://gradaid.online/applications
  • https://gradaid.online/timeline
• Support Module: Provides helpful information and a contact interface (utilizing the Resend service via the backend).
  • https://gradaid.online/faq
  • https://gradaid.online/contact
  • https://gradaid.online/feedback
• Convex Client: Facilitates real-time communication with the backend using specific hooks (useQuery, useMutation, useAction).
• React Router: Handles client-side routing with nested routes and navigation for a seamless user workflow across modules.
• Reusable Components: Ensures a consistent design language and user experience across all pages.

Backend Architecture

Powered by Convex for serverless backend functionality, database, and real-time updates. Written in TypeScript for type safety across the full stack.

• Database Integration: Stores and retrieves user data (profiles, saved programs, applications) and documents. Data schema is defined in TypeScript. Convex provides reactive hooks (useQuery, useMutation, useAction) for frontend interaction, dynamically updating components as data changes.
• AI Document Generation: Uses the useAction hook to call the OpenAI API for AI-powered SOP/LOR generation based on user background, goals, and program details. Results are saved directly to the database.
• User Management: Authentication handled by Clerk. User information is synced from Clerk to the Convex database via Svix webhooks upon signup. Runtime authentication uses JWTs passed from Clerk to Convex for validating user sessions and restricting data access (users can only access their own data).
• Input Validation & Security: Uses Zod for input validation and sanitization to prevent injection attacks (e.g., XSS) and ensure data integrity. Multi-layered security protects against malicious database access.
• Microservice Integration:
  • Clerk: Manages user authentication and profiles.
  • OpenAI: Provides LLM capabilities for document generation.
  • Resend: Handles sending emails (e.g., the contact form).

Styling and UI Components

• Tailwind CSS: Utility-first CSS framework for responsive design.
• Shadcn: Component library providing consistent UI elements.
• Lucide: Icon library providing customizable SVG icons.
• Framer Motion: Animation library for fluid UI transitions and interactions.

Dependency Management

The system minimizes coupling through:

• Component-Based Design: Modular React components with defined responsibilities.
• API Abstraction: Consistent interfaces via Convex server functions and external API calls handled by the backend.
• State Management: Separation of UI state (managed within React components) and application data (managed by Convex).
• TypeScript: Ensures type safety and consistency across frontend and backend code within the same repository.

Deployment and Scalability

• Frontend: Deployed as a static site with dynamic capabilities via Netlify.
• Backend & Database: Leverages Convex's serverless infrastructure for auto-scaling compute and database resources.
• Authentication: Relies on Clerk's scalable infrastructure.

GradAid Architecture Diagram

File Structure

Below is the complete file structure for GradAid with detailed explanations for key files and directories:

GradAid/
├── README.md                   # Project overview and setup instructions.
├── TESTING.md                  # Information about testing procedures.
├── components.json             # Configuration for shadcn/ui components.
├── convex                      # Backend logic using the Convex framework.
│   ├── README.md               # Overview of the Convex backend structure.
│   ├── _generated              # Auto-generated Convex files (API definitions, data model).
│   ├── aiCredits               # Manages AI credit usage and limits.
│   ├── applications            # Handles graduate program application data and logic.
│   ├── auth.config.ts          # Configuration for user authentication providers (e.g., Clerk).
│   ├── dashboard               # Data fetching and logic for the user dashboard.
│   ├── data                    # Static data files used for initialization or reference.
│   ├── documents               # Logic for managing user documents.
│   ├── feedback                # Handles user feedback submission.
│   ├── http.ts                 # Defines HTTP endpoints for external integrations (e.g., webhooks).
│   ├── init.ts                 # Initialization script for development environment data seeding.
│   ├── init_prod.ts            # Initialization script for production environment data seeding.
│   ├── programs                # Logic related to graduate programs (search, favorites).
│   ├── schema.ts               # Defines the database schema for Convex tables.
│   ├── search                  # Implements search functionality across programs/universities.
│   ├── services                # Contains integrations with third-party services.
│   │   ├── llm.ts              # Integration with Large Language Models (e.g., OpenAI).
│   │   └── resend.ts           # Integration with Resend email service.
│   ├── tests                   # Backend unit and integration tests for Convex functions.
│   ├── tsconfig.json           # TypeScript configuration specific to the Convex backend.
│   ├── universities            # Logic related to university data.
│   ├── userActivity            # Tracks user actions within the application.
│   ├── userProfiles            # Manages user profile data.
│   ├── users.ts                # Core user management logic within Convex.
│   └── validators.ts           # Reusable validation functions for Convex operations.
├── eslint.config.js            # Configuration for ESLint code linting.
├── index.html                  # Main HTML entry point for the Vite frontend application.
├── netlify.toml                # Configuration file for Netlify deployment.
├── package.json                # Project metadata, dependencies, and scripts.
├── scripts                     # Utility scripts for development or deployment tasks (e.g., web scraping).
├── src                         # Frontend source code (React/TypeScript/Vite).
│   ├── App.css                 # Global CSS styles for the App component.
│   ├── App.tsx                 # Main application component, sets up routing and layout.
│   ├── __tests__               # Frontend unit/integration tests for top-level components.
│   ├── assets                  # Static assets like images, logos, SVGs used in the frontend code.
│   │   └── svg                 # Subdirectory specifically for SVG assets.
│   ├── components              # Reusable UI components used across different pages/routes.
│   │   ├── __tests__           # Unit tests for specific components.
│   │   └── ui                  # Base UI components generated or copied from shadcn/ui.
│   ├── hooks                   # Custom React hooks for state management and encapsulating logic.
│   │   └── __tests__           # Unit tests for custom hooks.
│   ├── index.css               # Global CSS styles or resets.
│   ├── lib                     # Utility functions and shared libraries.
│   │   └── __tests__           # Unit tests for utility functions.
│   ├── main.tsx                # Entry point for the React application, renders the root component.
│   ├── routes                  # Page components and routing configuration using React Router.
│   │   └── __tests__           # Unit/integration tests for page components and route wrappers.
│   ├── store                   # State management setup (Jotai).
│   ├── test                    # Frontend testing setup and utilities.
│   └── vite-env.d.ts           # TypeScript definitions for Vite environment variables.
├── tsconfig.app.json           # TypeScript configuration for the frontend application code (src).
├── tsconfig.json               # Base TypeScript configuration for the entire project.
├── tsconfig.node.json          # TypeScript configuration for Node.js scripts/files (e.g., vite.config.ts).
└── vite.config.ts              # Configuration file for the Vite build tool.

Security, Privacy, and Reliability

Security and Privacy

Security and privacy are fundamental components of GradAid's architecture. Access to any section of the application beyond the public landing page necessitates user authentication via Clerk. This authentication process ensures user identity verification throughout the application session, establishing a foundation for robust security and privacy measures. Consequently, users are restricted to accessing only their own personal information. Data access controls are rigorously enforced whenever data is queried or modified, verifying that the requesting user possesses the appropriate permissions for the target data.

The only publicly accessible information stored within the database pertains to university and program details. As these records contain no personal information, they do not require the same level of access control. Furthermore, users retain the right to delete their accounts and all associated personal data at any time, reinforcing data privacy and user control.

Reliability

System reliability is achieved through the utilization of established and trusted infrastructure providers. The frontend, bundled using Vite, is hosted on Netlify, a reputable platform ensuring high availability and consistent internet accessibility for GradAid. The backend logic is executed as serverless functions hosted by Convex, which also manages the application's database.

Currently, GradAid operates on the free tiers of these services, which imposes certain bandwidth limitations. While the existing bandwidth is adequate for current traffic levels, the architecture is designed for scalability. Both frontend and backend services can theoretically be scaled significantly to accommodate substantial increases in user demand, ensuring the application remains resilient under high traffic loads. Additionally, both Netlify and Convex incorporate rate limiting mechanisms as a protective measure against malicious activities, such as Distributed Denial-of-Service (DDoS) attacks, thereby mitigating potential service disruptions.

Microservice Dependency

At present, strategies to mitigate dependencies on specific microservices have not been implemented. Replacing critical services like Clerk (for authentication) and Resend (for email delivery) would present challenges due to their significant integration within the codebase. While the OpenAI service could be substituted with an alternative Large Language Model (LLM) API with relative ease, the reliance on Clerk and Resend constitutes an identified limitation in the current architecture.

Despite this dependency, these microservices provide substantial benefits in terms of security and reliability compared to developing equivalent functionalities in-house. Clerk offers robust user management security, and Resend addresses essential email security protocols. A future architectural objective is to reduce tight coupling with specific microservices, thereby enhancing the flexibility to integrate alternative solutions as needed.

Installation

Recommended Access

The primary and recommended way to use GradAid is through the official hosted version available at: https://gradaid.online

This avoids the need for complex local setup and configuration of external services.

Local Development Setup

If you intend to contribute to development or require a local instance, follow the steps below. Be aware that this process involves setting up accounts and configuring several third-party services.

Prerequisites

You will need to configure the following services:

• Convex:
  • Serves as the backend and database.
  • Account required: https://convex.dev
  • Optional: For a fully local setup without a Convex cloud account, you can explore local deployments (currently in beta, may have limitations).
• Clerk:
  • Handles user authentication.
  • Account required: https://clerk.com
  • Set your Clerk API keys within your Convex project's environment variables.
  • See Clerk integration docs: Clerk & Convex Auth, Clerk Convex Integration.
• OpenAI:
  • Required for document generation features.
  • Account and API key required: https://openai.com/
  • Set your OPENAI_API_KEY within your Convex project's environment variables.
• Resend: (Optional for Local Development)
  • Used for sending contact emails in the production version.
  • Not strictly required for local development if email functionality is not needed.
  • If not using Resend, you may need to comment out or remove code sections referencing the RESEND_API_KEY to prevent build errors.

Configuration

1. Environment Variables: Ensure all required API keys (Clerk, OpenAI) are correctly set as environment variables in your Convex deployment settings.
2. Clerk Webhooks: Configure webhooks in your Clerk project dashboard to synchronize user data with your Convex backend, as described in the Convex documentation.

Running the Application

1. Start the Backend: Open your terminal in the project root directory and run the Convex development server:

   npm run dev:backend

2. Start the Frontend: Open a new terminal window in the project root directory and start the Vite development server:

   npm run dev:frontend

3. Access Locally: Once both processes are running, you can access the GradAid application in your web browser at http://localhost:5173.

Testing

GradAid employs a comprehensive testing suite comprising over 600 tests, including unit, User Interface (UI), and integration tests. Due to testing being incorporated later in the development cycle, end-to-end (E2E) testing is currently absent, and the extent of integration testing is limited relative to unit and UI tests.

Despite these limitations, the project maintains substantial code coverage, measured at 83% for functions and 94% for lines of code. This high coverage level provides significant protection against regressions in critical application functionalities. While acknowledging that further refinement is always possible to address all potential edge cases, the existing test suite offers thorough validation of the current codebase.

The Vitest framework serves as the foundation for all testing procedures. Frontend testing utilizes the React Testing Library, running within a jsdom environment powered by Vitest. Backend testing employs the convex-test library, which leverages Vitest to simulate a mock database within the edge-runtime environment. Code coverage metrics are generated using the V8 coverage provider integrated with Vitest.

Initial efforts were made to introduce end-to-end testing using WebdriverIO; however, integration challenges, particularly with the authentication system, prevented its successful implementation within the available timeframe. A key objective for future development includes the full implementation of end-to-end testing, potentially utilizing WebdriverIO or an alternative framework.

Running Tests Locally

To execute the test suite in a local development environment, follow these steps:
Note that installation is not required to run tests. All tests run on a local version of the Convex database and mock all API calls so they can be run without setting up any services.

1. Install Dependencies: Ensure all necessary project packages are installed by running the following command in your terminal:

   npm install

   Alternatively, you can use the shorthand:

   npm i

2. Run Tests: Execute the complete test suite once using this command:

   npm run test:once

3. Check Test Coverage: To generate and view the test coverage report after running the tests, use the command:

   npm run test:coverage