StudyPath.ai

A full-stack application that generates personalized learning roadmaps visualized as interactive dependency graphs.

Features

• Generate structured learning plans with milestones and subtopics
• Interactive graph visualization of learning paths
• Real-time form validation and error handling
• Premium dark-theme UI with handcrafted components
• Rate limiting and CORS-protected API endpoints
• Optional PostgreSQL persistence for saved plans
• Responsive design across desktop and tablet

Tech Stack

Frontend: React 18, Vite, ReactFlow, TailwindCSS, Axios, Lucide React

Backend: FastAPI, Uvicorn, Pydantic, PostgreSQL (optional), Python 3.10+

Styling: Custom design system with dark theme, premium typography, and accessible components

Project Structure

studypath-ai/
├── backend/
│   ├── main.py                 # FastAPI app, endpoints, database logic
│   ├── requirements.txt         # Python dependencies
│   ├── migrations/              # PostgreSQL schema (optional)
│   ├── .env.example             # Environment template
│   └── venv/                    # Virtual environment
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ui/              # Reusable UI components
│   │   │   ├── Modal.jsx
│   │   │   ├── CustomNode.jsx
│   │   │   └── ErrorBoundary.jsx
│   │   ├── examples/            # Example implementations
│   │   ├── App.jsx              # Main application
│   │   ├── main.jsx
│   │   └── index.css            # Global styles
│   ├── public/
│   ├── tailwind.config.js       # Design tokens and theme
│   ├── vite.config.js
│   ├── package.json
│   └── .env.example
├── docker-compose.yml           # Local PostgreSQL setup
├── DESIGN_SYSTEM.md             # Component API and design tokens
├── QUICK_REFERENCE.md           # Quick lookup guide
└── README.md

Setup

Prerequisites

• Python 3.10 or higher
• Node.js 18 or higher
• npm or yarn

Backend Setup

1. Navigate to backend directory:

cd backend

2. Create and activate virtual environment:

python -m venv venv

On Windows:

venv\Scripts\activate.bat

On macOS/Linux:

source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Create .env file (optional):

cp .env.example .env

5. Start development server:

python main.py

Server runs on http://localhost:8000

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Create .env.local (optional):

cp .env.example .env.local

4. Start development server:

npm run dev

Frontend runs on http://localhost:5173

Environment Variables

Backend

Variable	Required	Default	Description
GEMINI_API_KEY	No	—	API key for plan generation service
DATABASE_URL	No	—	PostgreSQL connection string
ENVIRONMENT	No	development	Deployment environment
ALLOWED_ORIGINS	No	http://localhost:5173	CORS-allowed origins (comma-separated)
SENTRY_DSN	No	—	Sentry error tracking DSN

Frontend

Variable	Required	Default	Description
VITE_API_URL	No	http://localhost:8000	Backend API endpoint
VITE_APP_URL	No	http://localhost:5173	Frontend URL for sharing

Development

Running Both Services

Open two terminal windows:

Terminal 1 (Backend):

cd backend
python main.py

Terminal 2 (Frontend):

cd frontend
npm run dev

Both must run simultaneously. The frontend will fail to load plan data if the backend is not running.

Hot Reload

Frontend automatically reloads on file changes (Vite hot module replacement). Backend reloads on Python file changes when run with python main.py (uvicorn auto-reload).

Building for Production

Frontend:

cd frontend
npm run build
npm run preview  # Test production build locally

Output is in frontend/dist/

Backend: No build step required. Deploy main.py and requirements.txt to production environment.

API Endpoints

POST /generate-plan

Generates a personalized learning plan.

Request:

{
  "field_of_study": "Machine Learning",
  "proficiency_level": "Beginner"
}

Response:

{
  "plan_title": "Study Plan for Machine Learning",
  "milestones": [
    {
      "title": "Foundations",
      "description": "Core concepts and fundamentals",
      "subtopics": [
        {
          "title": "Linear Algebra",
          "description": "Matrices, vectors, and operations",
          "youtube_search_query": "linear algebra fundamentals"
        }
      ]
    }
  ]
}

Status Codes:

• 200: Plan generated successfully
• 422: Invalid request format
• 429: Rate limit exceeded (10 requests per minute)
• 500: Server error

POST /plans

Generates and saves a plan to the database.

Request: Same as /generate-plan

Response:

{
  "id": "uuid",
  "slug": "machine-learning-abc123",
  "created_at": "2024-01-15T10:30:00Z"
}

Requires DATABASE_URL to be set.

GET /plans/{slug}

Retrieves a previously saved plan.

Response: Same as /generate-plan

Status Codes:

• 200: Plan found
• 404: Plan not found

Deployment

Frontend (Vercel)

1. Push code to GitHub
2. Connect repository to Vercel
3. Set environment variable: VITE_API_URL pointing to backend
4. Deploy (automatic on push to main)

Backend (Render or Docker)

Using Render:

1. Create new Web Service on Render
2. Connect GitHub repository
3. Set Start Command: uvicorn main:app --host 0.0.0.0 --port 8000
4. Add environment variables (GEMINI_API_KEY, DATABASE_URL, etc.)
5. Deploy

Using Docker:

docker build -t studypath-backend .
docker run -p 8000:8000 -e GEMINI_API_KEY=your_key studypath-backend

Database (PostgreSQL on Render)

1. Create PostgreSQL database on Render
2. Copy connection string to DATABASE_URL
3. Backend automatically initializes tables on startup

Optional Features

These features are fully implemented but not required to run the application:

• Plan Persistence: PostgreSQL integration for saving and sharing plans. Set DATABASE_URL to enable.
• Service Integration: External plan generation service. Set GEMINI_API_KEY to enable (otherwise uses mock data).
• Error Tracking: Sentry integration. Set SENTRY_DSN to enable.
• Storybook: Interactive component documentation. Run npm run storybook in frontend.

Design System

The frontend uses a premium dark theme called "Obsidian Luxe" with handcrafted components. The design system includes six reusable components: Button, Card, Input, Modal, Toast, and Topbar. All components follow accessibility standards (WCAG AA), use consistent spacing and typography, and feature smooth animations.

Color palette: deep obsidian (#0F0F12) for backgrounds, soft gold (#D4A64A) for accents, and high-contrast text (#E9E9EC). Typography uses Playfair Display serif for headings and Inter sans-serif for body text.

Detailed design documentation is in DESIGN_SYSTEM.md with component API, design tokens, and implementation examples.

Coding Conventions

Python (Backend):

• Follow PEP 8 style guide
• Use type hints for function parameters and returns
• Docstrings for all public functions and classes
• Prefer explicit over implicit (no magic)

JavaScript (Frontend):

• ES6+ syntax, prefer const over let
• Functional components with React hooks
• Prop types or TypeScript for component interfaces
• Components in PascalCase, files in camelCase or PascalCase
• Keep components focused; extract logic to custom hooks

Naming:

• Database tables: plural, lowercase (plans, users)
• API endpoints: lowercase with hyphens (generate-plan, not generatePlan)
• React components: PascalCase
• CSS classes: kebab-case from TailwindCSS utility classes

Formatting:

• 2 spaces for indentation (frontend), 4 spaces (backend)
• 80-character line limit for Python, 100 for JavaScript
• Trailing commas in multi-line structures
• No unused imports or variables

Contributing

Branch Naming

• feature/description for new features
• bugfix/description for bug fixes
• docs/description for documentation
• chore/description for maintenance tasks

Pull Requests

1. Create feature branch from main
2. Make focused commits with clear messages
3. Open PR with description of changes
4. Ensure all tests pass and no console errors
5. Await review before merging
6. Squash commits before merge if requested

Commit Messages

Use imperative mood, present tense:

• Add user authentication endpoint (not "Added" or "Adds")
• Fix graph node positioning (not "Fixed")
• Update component documentation (not "Updated")

License

MIT License. See LICENSE file for details.

Support

For issues or questions:

1. Check QUICK_REFERENCE.md for common tasks
2. Review DESIGN_SYSTEM.md for component documentation
3. Open a GitHub issue with clear reproduction steps
4. For bugs, include error messages and browser console output

---

Latest Update: December 2025 Version: 1.0.0
Status: Production Ready