# Project export: Pathfinder AI This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: Cal Hacks 12.0 - Tagline: Pathfinder AI is your personal college matchmaker. In a few minutes, students sign in, answer a short questionnaire, and instantly receive data‑backed school recommendations tailored to their them. - Devpost: https://devpost.com/software/pathfinder-ai-honlp8 - GitHub: https://github.com/b0mung51/Pathfinder-AI - Video: https://www.youtube.com/embed/IFWQOOYEX3k?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 4 GitHub contributor(s) — b0mung51 (15 commits), haroonstar2 (13 commits), vchsi (12 commits), ryl2005 (12 commits) ## Devpost submission (written by the team) No Devpost description available. ## README (from the GitHub repository) # Pathfinder AI – Supabase + Django + React This repository provides an integrated full-stack implementation combining a Django REST API with a React frontend. Authentication and data management are handled via Supabase. ## System Architecture Overview - Frontend: React 18 (Vite build system, styled with Tailwind CSS) - State/Data: TanStack Query, Supabase JS client - Auth: Supabase (email/password + Google OAuth) - Backend: Django 5 + Django REST Framework + CORS headers - Tooling: TypeScript, ESLint, ShadCN UI components - LLM: Llama 2.7 HF ## Development Environment - Python 3.11+ - Node.js 20+ - PostgreSQL (managed via Supabase) Ensure both frontend and backend `.env` files are configured before running the application. --- ## 1. Supabase Setup 1. Create a Supabase project and enable the **Google** OAuth provider (Auth -> Providers -> Google). 2. Run the SQL in [`supabase/initial-setup.sql`](supabase/initial-setup.sql) from the Supabase SQL editor to create the `profiles` table, enable row-level security, and auto-seed profiles when new users sign up. 3. Record the project URL and anonymous API key for use in frontend and backend environment variables. 4. Do not commit keys or credentials to source control. Store them in your environment manager --- ## 2. Frontend (React) ```powershell cd frontend npm install npm run dev ``` The frontend relies on Supabase for user authentication and profile persistence: - Email/password sign up & sign in - Google OAuth sign-in (redirect handled by Supabase) - Persisted profiles (`profiles` table) keyed to the authenticated user Key Modules: - `src/lib/supabaseClient.ts` – shared Supabase client - `src/context/AuthContext.tsx` – wraps the app with session state + auth helpers - `src/pages/Auth.tsx` – auth UI wired to Supabase (email/password + Google) - `src/components/Navbar.tsx` – reflects auth state (sign in/out buttons) Environment variables: ``` VITE_API_BASE_URL=http://127.0.0.1:8000/api VITE_SUPABASE_URL=… VITE_SUPABASE_ANON_KEY=… ``` --- ## 3. Backend ```powershell cd backend pip install -r requirements.txt python manage.py migrate python manage.py runserver ``` Default settings give: - `/api/health/` – simple JSON healthcheck - `/api/placeholders/` – example DRF ViewSet - `/` – landing page to show the API is running Environment variables (`backend/.env.example`): ``` DJANGO_SECRET_KEY=change-me DJANGO_DEBUG=1 DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost DJANGO_CORS_ALLOW_ALL=1 ``` --- ## 4. Authentication and Data Model Extensions - **Profiles:** During user registration, the frontend automatically synchronizes user metadata to the `profiles` table via Supabase - **Protected routes:** Use the `useAuth` hook anywhere to read `user`, `session`, and helper functions. Gate pages or fetch user-specific data via Supabase queries or Django. - **Google OAuth:** Google OAuth is managed through Supabase’s redirect-based authentication flow, with session updates propagated through the frontend’s auth listener. --- ## 5. Command Reference | Command | Example | | --- | --- | | Install frontend deps | `npm install` | | Run frontend dev server | `npm run dev` | | Build production bundle | `npm run build` | | Create backend venv | `python -m venv .venv` | | Install backend deps | `pip install -r requirements.txt` | | Apply migrations | `python manage.py migrate` | | Start Django dev server | `python manage.py runserver` | | Seed Supabase tables | Execute [`supabase/initial-setup.sql`](supabase/initial-setup.sql) in Supabase | --- ## Detected evidence (automated analysis) Indexed codebase: 97 recognized source files, 376 KB. - CSS (language) — detected in the code - Django (technology) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - SQL (language) — detected in the code - Supabase (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code ## Codebase structure (from repository index) ### Files (106 of 106) ``` .gitignore backend/api/__init__.py backend/api/apps.py backend/api/college_search_results.json backend/api/pg_connector.py backend/api/reddit_college_cleaner.py backend/api/reddit_posts_with_colleges.json backend/api/reddit_scraper.py backend/api/reddit-supabase.py backend/api/serializers.py backend/api/urls.py backend/api/views.py backend/api/web_scraper.py backend/backend_project/__init__.py backend/backend_project/settings.py backend/backend_project/urls.py backend/backend_project/wsgi.py backend/manage.py backend/requirements.txt docs/match-score-endpoint.md frontend/components.json frontend/index.html frontend/package.json frontend/postcss.config.js frontend/src/App.css frontend/src/App.tsx frontend/src/components/CollegeCard.tsx frontend/src/components/CompareDialog.tsx frontend/src/components/Navbar.tsx frontend/src/components/ProgressBar.tsx frontend/src/components/ui/accordion.tsx frontend/src/components/ui/alert-dialog.tsx frontend/src/components/ui/alert.tsx frontend/src/components/ui/aspect-ratio.tsx frontend/src/components/ui/avatar.tsx frontend/src/components/ui/badge.tsx frontend/src/components/ui/breadcrumb.tsx frontend/src/components/ui/button.tsx frontend/src/components/ui/calendar.tsx frontend/src/components/ui/card.tsx frontend/src/components/ui/carousel.tsx frontend/src/components/ui/chart.tsx frontend/src/components/ui/checkbox.tsx frontend/src/components/ui/collapsible.tsx frontend/src/components/ui/command.tsx frontend/src/components/ui/context-menu.tsx frontend/src/components/ui/dialog.tsx frontend/src/components/ui/drawer.tsx frontend/src/components/ui/dropdown-menu.tsx frontend/src/components/ui/form.tsx frontend/src/components/ui/hover-card.tsx frontend/src/components/ui/input-otp.tsx frontend/src/components/ui/input.tsx frontend/src/components/ui/label.tsx frontend/src/components/ui/menubar.tsx frontend/src/components/ui/navigation-menu.tsx frontend/src/components/ui/pagination.tsx frontend/src/components/ui/popover.tsx frontend/src/components/ui/progress.tsx frontend/src/components/ui/radio-group.tsx frontend/src/components/ui/resizable.tsx frontend/src/components/ui/scroll-area.tsx frontend/src/components/ui/select.tsx frontend/src/components/ui/separator.tsx frontend/src/components/ui/sheet.tsx frontend/src/components/ui/sidebar.tsx frontend/src/components/ui/skeleton.tsx frontend/src/components/ui/slider.tsx frontend/src/components/ui/sonner.tsx frontend/src/components/ui/switch.tsx frontend/src/components/ui/table.tsx frontend/src/components/ui/tabs.tsx frontend/src/components/ui/textarea.tsx frontend/src/components/ui/toast.tsx frontend/src/components/ui/toaster.tsx frontend/src/components/ui/toggle-group.tsx frontend/src/components/ui/toggle.tsx frontend/src/components/ui/tooltip.tsx frontend/src/components/ui/use-toast.ts frontend/src/context/AuthContext.tsx frontend/src/hooks/use-mobile.tsx frontend/src/hooks/use-toast.ts frontend/src/hooks/useAuth.ts frontend/src/hooks/useCollegeRedditPosts.ts frontend/src/hooks/useCollegeSelection.ts frontend/src/index.css frontend/src/lib/supabaseClient.ts frontend/src/lib/utils.ts frontend/src/main.tsx frontend/src/pages/Auth.tsx frontend/src/pages/CollegeList.tsx frontend/src/pages/Dashboard.tsx frontend/src/pages/Index.tsx frontend/src/pages/NotFound.tsx frontend/src/pages/Profile.tsx frontend/src/pages/Questionnaire.tsx frontend/src/pages/Search.tsx frontend/src/types/college.ts frontend/src/vite-env.d.ts frontend/tailwind.config.ts frontend/tsconfig.app.json frontend/tsconfig.json frontend/tsconfig.node.json frontend/vite.config.ts README.md supabase/initial-setup.sql ``` ### Dependencies - backend/requirements.txt: django@==5.0.8, django-cors-headers@==4.4.0, djangorestframework@==3.15.2, gunicorn@==22.0.0, python-dotenv@>=1.1.0,<2.0.0, requests@==2.32.3 - frontend/package.json: @dnd-kit/core@^6.3.1, @dnd-kit/sortable@^10.0.0, @dnd-kit/utilities@^3.2.2, @eslint/js@^9.32.0, @hookform/resolvers@^3.10.0, @radix-ui/react-accordion@^1.2.11, @radix-ui/react-alert-dialog@^1.1.14, @radix-ui/react-aspect-ratio@^1.1.7, @radix-ui/react-avatar@^1.1.10, @radix-ui/react-checkbox@^1.3.2, @radix-ui/react-collapsible@^1.1.11, @radix-ui/react-context-menu@^2.2.15, @radix-ui/react-dialog@^1.1.14, @radix-ui/react-dropdown-menu@^2.1.15, @radix-ui/react-hover-card@^1.1.14, @radix-ui/react-label@^2.1.7, @radix-ui/react-menubar@^1.1.15, @radix-ui/react-navigation-menu@^1.2.13, @radix-ui/react-popover@^1.1.14, @radix-ui/react-progress@^1.1.7, @radix-ui/react-radio-group@^1.3.7, @radix-ui/react-scroll-area@^1.2.9, @radix-ui/react-select@^2.2.5, @radix-ui/react-separator@^1.1.7, @radix-ui/react-slider@^1.3.5, @radix-ui/react-slot@^1.2.3, @radix-ui/react-switch@^1.2.5, @radix-ui/react-tabs@^1.1.12, @radix-ui/react-toast@^1.2.14, @radix-ui/react-toggle@^1.1.9, @radix-ui/react-toggle-group@^1.1.10, @radix-ui/react-tooltip@^1.2.7, @supabase/supabase-js@^2.76.1, @tailwindcss/typography@^0.5.16, @tanstack/react-query@^5.83.0, @types/node@^22.16.5, @types/react@^18.3.23, @types/react-dom@^18.3.7, @vitejs/plugin-react-swc@^3.11.0, autoprefixer@^10.4.21, class-variance-authority@^0.7.1, clsx@^2.1.1, cmdk@^1.1.1, date-fns@^3.6.0, embla-carousel-react@^8.6.0, eslint@^9.32.0, eslint-plugin-react-hooks@^5.2.0, eslint-plugin-react-refresh@^0.4.20, globals@^15.15.0, input-otp@^1.4.2, lovable-tagger@^1.1.11, lucide-react@^0.462.0, next-themes@^0.3.0, postcss@^8.5.6, react@^18.3.1, react-day-picker@^8.10.1, react-dom@^18.3.1, react-hook-form@^7.61.1, react-resizable-panels@^2.1.9, react-router-dom@^6.30.1, recharts@^2.15.4, sonner@^1.7.4, supabase@^2.53.6, tailwind-merge@^2.6.0, tailwindcss@^3.4.17, tailwindcss-animate@^1.0.7, typescript@^5.8.3, typescript-eslint@^8.38.0, vaul@^0.9.9, vite@^7.1.12, zod@^3.25.76 ### Recent commits (newest first) - Add Llama 2.7 HF to README - Revise README for clarity and structure - Ignore local env and build artifacts - Merge pull request #2 from b0mung51/reddit-matcher - Added reddit posts to dialogue cards - Added 99 matched posts to the db - gunicorn - Demo Ready - Finished web scraping and added reddit to supabase - Added filter and delete functionality. Note. Make sure to keep your backend, since this one might be iffy. - Merge branch 'main' of https://github.com/b0mung51/Pathfinder-AI - AI integration 1.0 + UI update - Fixed Llama Grades Reporting, Some stats work - Fixed the degree programs - Merge branch 'main' of https://github.com/b0mung51/Pathfinder-AI - Switch from mcp to llm - Llama 2.7 Integration with data base - Fixed merges - Updated raw rates to percents - Merge pull request #1 from b0mung51/feature/drag_and_drop ## Key source files (fetched from GitHub, selected and truncated for size) ### docs/match-score-endpoint.md ```markdown # Match Score Endpoint The Django API exposes `GET /api/match-scores/`, which computes fit scores between a user's stored preferences and entries in the Supabase `colleges` table. Scores are derived from a heuristic model and can optionally be refined by a Hugging Face LLM. ## Request ``` GET /api/match-scores/?user_id=&limit=&use_llm= ``` | Parameter | Required | Description | |-----------|----------|-------------| | `user_id` | Yes | UUID that matches the row in `user_preferences`. | | `limit` | No | Maximum number of colleges to return (defaults to all). | | `use_llm` | No | Set to `true` / `1` to enable Hugging Face refinement (requires credentials). | ## Response ```json { "user_id": "cf1f1c6d-....", "match_count": 3, "llm_available": true, "using_llm": true, "results": [ { "college_id": 1, "college_name": "Example University", "location": "California", "average_cost": 28000, "acceptance_rate": 12.5, "ranking": 5, "score": 88.7, "heuristic_score": 86.4, "notes": [ "Fits within your stated budget.", "Academic profile aligns with historical admits.", "Highly ranked option in your results.", "LLM: Strong alignment between campus resources and stated goals." ], "llm": { "model_score": 88.7, "model_explanation": "LLM: Strong alignment between campus resources and stated goals." } } ] } ``` Heuristic scoring weights affordability, admissions competitiveness, and program ranking. If any metric is unavailable, the endpoint returns a baseline score with explanatory notes. When `use_llm=true` and Hugging Face credentials are configured, the heuristic score is sent to the model for refinement; both scores are included in the response alongside the model explanation. ## Configuration Add the following to `backend/.env` (service-role key or similar read access is required): ``` SUPABASE_URL=your-project-url SUPABASE_KEY=your-service-role-key HUGGINGFACE_API_KEY=your-hf-inference-api-key HUGGINGFACE_MODEL_ID=meta-llama/Llama-3.1-8B-Instruct HUGGINGFACE_TIMEOUT_SECONDS=30 ``` You can change `HUGGINGFACE_MODEL_ID` to any text-generation model available to your account. The timeout is configurable if the model is slow to respond. ## Next Steps - Persist results back into Supabase by writing to a `college_match_scores` table after the response is generated. - Gate the endpoint with authentication before exposing it to the frontend. - Adjust the prompt or parse logic to fit a specific model, or swap the heuristic for a fully model-driven workflow. - When calling from the Vite frontend, point `VITE_API_BASE_URL` to your Django API (e.g. `http://127.0.0.1:8000/api`) and include the signed-in Supabase user’s `id` in the query string. ``` ### backend/requirements.txt ``` django==5.0.8 djangorestframework==3.15.2 django-cors-headers==4.4.0 python-dotenv>=1.1.0,<2.0.0 requests==2.32.3 gunicorn==22.0.0 ``` ### frontend/package.json ``` { "name": "vite_react_shadcn_ts", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "vite build", "build:dev": "vite build --mode development", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@dnd-kit/core": "^6.3.1", "@dnd-kit/sortable": "^10.0.0", "@dnd-kit/utilities": "^3.2.2", "@hookform/resolvers": "^3.10.0", "@radix-ui/react-accordion": "^1.2.11", "@radix-ui/react-alert-dialog": "^1.1.14", "@radix-ui/react-aspect-ratio": "^1.1.7", "@radix-ui/react-avatar": "^1.1.10", "@radix-ui/react-checkbox": "^1.3.2", "@radix-ui/react-collapsible": "^1.1.11", "@radix-ui/react-context-menu": "^2.2.15", "@radix-ui/react-dialog": "^1.1.14", "@radix-ui/react-dropdown-menu": "^2.1.15", "@radix-ui/react-hover-card": "^1.1.14", "@radix-ui/react-label": "^2.1.7", "@radix-ui/react-menubar": "^1.1.15", "@radix-ui/react-navigation-menu": "^1.2.13", "@radix-ui/react-popover": "^1.1.14", "@radix-ui/react-progress": "^1.1.7", "@radix-ui/react-radio-group": "^1.3.7", "@radix-ui/react-scroll-area": "^1.2.9", "@radix-ui/react-select": "^2.2.5", "@radix-ui/react-separator": "^1.1.7", "@radix-ui/react-slider": "^1.3.5", "@radix-ui/react-slot": "^1.2.3", "@radix-ui/react-switch": "^1.2.5", "@radix-ui/react-tabs": "^1.1.12", "@radix-ui/react-toast": "^1.2.14", "@radix-ui/react-toggle": "^1.1.9", "@radix-ui/react-toggle-group": "^1.1.10", "@radix-ui/react-tooltip": "^1.2.7", "@supabase/supabase-js": "^2.76.1", "@tanstack/react-query": "^5.83.0", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "cmdk": "^1.1.1", "date-fns": "^3.6.0", "embla-carousel-react": "^8.6.0", "input-otp": "^1.4.2", "lucide-react": "^0.462.0", "next-themes": "^0.3.0", "react": "^18.3.1", "react-day-picker": "^8.10.1", "react-dom": "^18.3.1", "react-hook-form": "^7.61.1", "react-resizable-panels": "^2.1.9", "react-router-dom": "^6.30.1", "recharts": "^2.15.4", "sonner": "^1.7.4", "supabase": "^2.53.6", "tailwind-merge": "^2.6.0", "tailwindcss-animate": "^1.0.7", "vaul": "^0.9.9", "zod": "^3.25.76" }, "devDependencies": { "@eslint/js": "^9.32.0", "@tailwindcss/typography": "^0.5.16", "@types/node": "^22.16.5", "@types/react": "^18.3.23", "@types/react-dom": "^18.3.7", "@vitejs/plugin-react-swc": "^3.11.0", "autoprefixer": "^10.4.21", "eslint": "^9.32.0", "eslint-plugin-react-hooks": "^5.2.0", "eslint-plugin-react-refresh": "^0.4.20", "globals": "^15.15.0", "lovable-tagger": "^1.1.11", "postcss": "^8.5.6", "tailwindcss": "^3.4.17", "typescript": "^5.8.3", "typescript-eslint": "^8.38.0", "vite": "^7.1.12" } } ``` ### frontend/src/main.tsx ```typescript import { createRoot } from "react-dom/client"; import App from "./App.tsx"; import "./index.css"; createRoot(document.getElementById("root")!).render(); ``` ### frontend/src/App.tsx ```typescript import { Toaster } from "@/components/ui/toaster"; import { Toaster as Sonner } from "@/components/ui/sonner"; import { TooltipProvider } from "@/components/ui/tooltip"; import { AuthProvider } from "@/context/AuthContext"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { BrowserRouter, Routes, Route } from "react-router-dom"; import Index from "./pages/Index"; import Auth from "./pages/Auth"; import Questionnaire from "./pages/Questionnaire"; import Dashboard from "./pages/Dashboard"; import Search from "./pages/Search"; import CollegeList from "./pages/CollegeList"; import Profile from "./pages/Profile"; import NotFound from "./pages/NotFound"; const queryClient = new QueryClient(); const App = () => ( } /> } /> } /> } /> } /> } /> } /> {/* ADD ALL CUSTOM ROUTES ABOVE THE CATCH-ALL "*" ROUTE */} } /> ); export default App; ``` ### frontend/src/pages/Index.tsx ```typescript import { Button } from "@/components/ui/button"; import { Card } from "@/components/ui/card"; import { Navbar } from "@/components/Navbar"; import { useAuth } from "@/hooks/useAuth"; import { useNavigate } from "react-router-dom"; import { GraduationCap, Target, TrendingUp, Calendar } from "lucide-react"; import graduationIcon from "@/assets/graduation-icon.png"; export default function Index() { const navigate = useNavigate(); const { user, isAuthenticating } = useAuth(); return (
{/* Hero Section */}
Graduation

Find Your Perfect College Path

PathFinder AI uses intelligent matching to connect you with colleges that align with your goals, preferences, and academic profile.

{/* Features Section */}

Everything You Need to Plan Your College Journey

Smart College Matches

Personalized recommendations using AI that align with your academic strengths and preferences.

Goal Tracking

Track application milestones, deadlines, and progress toward your top-choice schools.

Data-Driven Insights

Understand admissions trends, acceptance rates, and financial aid options tailored to you.

Unified Planning

Build your college list, schedule visits, and keep notes all in one place.

); } ``` ### frontend/postcss.config.js ```javascript export default { plugins: { tailwindcss: {}, autoprefixer: {}, }, }; ``` ### frontend/vite.config.ts ```typescript import { defineConfig } from "vite"; import react from "@vitejs/plugin-react-swc"; import path from "path"; import { componentTagger } from "lovable-tagger"; // https://vitejs.dev/config/ export default defineConfig(({ mode }) => ({ server: { host: "::", port: 8080, }, plugins: [react(), mode === "development" && componentTagger()].filter(Boolean), resolve: { alias: { "@": path.resolve(__dirname, "./src"), }, }, })); ``` ### backend/manage.py ```python #!/usr/bin/env python import os import sys def main() -> None: """Run administrative tasks.""" os.environ.setdefault("DJANGO_SETTINGS_MODULE", "backend_project.settings") try: from django.core.management import execute_from_command_line except ImportError as exc: raise ImportError( "Couldn't import Django. Make sure it is installed and available on your PYTHONPATH." ) from exc execute_from_command_line(sys.argv) if __name__ == "__main__": main() ``` ### frontend/index.html ```html PathFinder AI - Your Path to the Perfect College
``` [86 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]