GradCompass

GradCompass is a comprehensive graduate school application platform designed to help students navigate the complex process of applying to graduate programs in the United States.

Features

• Program Search & Discovery: Browse and search thousands of graduate programs with advanced filtering
• Program Comparison: Compare multiple programs side by side
• Admissions Analytics: Visualize admissions trends and statistics
• Application Planner: Track application deadlines, requirements, and progress
• AI-Powered Recommendations: Get personalized program recommendations based on your profile
• Bookmark Management: Save programs you're interested in
• Timeline View: Visualize your application journey

Tech Stack

Frontend

• Next.js 16 - React framework for production
• React 19 - UI library
• TypeScript - Type safety
• Tailwind CSS - Utility-first CSS framework
• Zustand - State management
• React Query - Data fetching and caching

Backend

• FastAPI - Modern Python web framework
• Celery - Distributed task queue
• Supabase - PostgreSQL database and authentication
• LightGBM - Machine learning model for recommendations
• Algolia - Search engine

Infrastructure

• Docker - Containerization
• Nginx - Web server and reverse proxy
• Cloudflare R2 - Object storage
• Airflow - Data pipeline orchestration

Getting Started

Prerequisites

• Node.js 20+
• Python 3.12+
• Docker and Docker Compose
• Supabase account
• Algolia account (optional)

Installation

1. Clone the repository

git clone https://github.com/feiiiiii5/gradcompass.git
cd gradcompass

2. Install frontend dependencies

npm install

3. Install backend dependencies

cd apps/api
pip install -r requirements.txt

4. Set up environment variables

Copy the example environment files and configure them:

# Frontend
cp .env.example .env.local

# Backend
cd apps/api
cp .env.example .env

5. Start the development servers

Frontend:

npm run dev

Backend (with Docker):

cd infra
docker-compose up

Or using the convenience script:

python start.py

6. Open the application

Visit http://localhost:3000 in your browser.

Project Structure

gradcompass/
├── src/                    # Frontend source code
│   ├── app/               # Next.js App Router pages
│   ├── components/        # React components
│   ├── lib/               # Utility functions and libraries
│   ├── stores/            # Zustand state management
│   └── types/             # TypeScript type definitions
├── apps/
│   └── api/               # FastAPI backend
│       ├── app/
│       │   ├── core/      # Core configurations
│       │   ├── models/    # Database models
│       │   ├── routers/   # API routes
│       │   └── services/  # Business logic
│       └── models/        # ML models
├── pipeline/              # Data pipelines
│   ├── dags/              # Airflow DAGs
│   ├── scrapers/          # Web scrapers
│   └── parsers/           # Data parsers
├── infra/                 # Infrastructure configuration
├── scripts/               # Utility scripts
└── supabase/              # Database migrations

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you have any questions or need help, please open an issue on GitHub.

Acknowledgments

• Thanks to all contributors who have helped build this project
• Built with ❤️ for graduate school applicants