StudyFlow — Full-Stack AI Study Planner 🎓✨

StudyFlow is a production-quality, modern AI-powered study planner application built with FastAPI, MongoDB Atlas, Google Gemini AI, and a React + TypeScript + Vite + Tailwind CSS frontend.

It helps college students and technical learners turn subjects, exam deadlines, and available daily study hours into customized, day-by-day learning roadmaps and track their mastery.

---

🌟 Key Features

1. Authentication & Multi-Tenant Security

   • User registration and login with bcrypt password hashing.
   • Stateless JWT Bearer token authentication.
   • Strict data isolation ensuring users can only ever access their own subjects and study plans.

2. Subject Management (CRUD)

   • Create, list, inspect, update, and delete courses/subjects.
   • Configurable deadlines (ISO dates) and daily available study hours.
   • Cascading cleanup of associated plans upon subject deletion.

3. AI-Powered Structured Study Plan Generation

   • Seamless integration with Google Gemini via the official google-genai SDK.
   • Strict Pydantic response schema validation ensuring AI output is deterministic, structured, and never violates daily study duration caps.
   • Day-by-day breakdowns with concrete topic titles, actionable descriptions, and time estimates.

4. Task & Progress Tracking

   • Interactive topic/task completion toggle with real-time recalculated progress percentages.
   • Automated completion status aggregation per day and overall plan.

5. AI Concept Explainer

   • Instant tutor assistance for difficult concepts with analogies, real-world code/use-case examples, and key takeaways.
   • Direct 1-click shortcuts from any topic in a study plan to the AI explainer.

6. Responsive, Modern UI/UX

   • Clean, light aesthetic with subtle borders, smooth micro-animations, accessible labels, empty states, and loading spinners.
   • Fully responsive for mobile, tablet, and desktop viewports.

---

🏗️ Architecture & Technology Stack

graph TD
    Client[React + TypeScript + Vite + Tailwind CSS]
    API[FastAPI Backend Application]
    Auth[JWT Security & Bcrypt]
    DB[(MongoDB Atlas / Motor Async)]
    Gemini[Google Gemini AI Engine]

    Client -->|REST API over JSON| API
    API -->|Verify Token & Authenticate| Auth
    API -->|Async Non-blocking Queries| DB
    API -->|Structured Schema Generation| Gemini

Loading

Backend

• Python 3.12+ / 3.14
• FastAPI: Modern, high-performance async REST API framework with automatic Swagger OpenAPI documentation.
• Motor / PyMongo: Async non-blocking MongoDB driver.
• Pydantic v2 & Pydantic Settings: Request/response validation and environment config.
• PyJWT & Bcrypt: Password hashing and token security.
• Google GenAI SDK (google-genai): Official Gemini API integration.
• Pytest & Pytest-Asyncio & HTTPX: Comprehensive automated unit and integration testing suite.

Frontend

• React 18 & TypeScript
• Vite: Ultra-fast frontend build tooling and dev server.
• Tailwind CSS: Utility-first styling with custom palette and component tokens.
• React Router DOM: Client-side single-page app routing and protected routes.
• Axios: HTTP client with request interceptors for token management.
• Lucide React: Clean, modern icons.
• Vitest & React Testing Library: Component and form validation test suite.

---

📁 Project Structure

studyflow/
├── backend/
│   ├── app/
│   │   ├── core/               # App configuration, DB connection & security
│   │   │   ├── config.py
│   │   │   ├── database.py
│   │   │   └── security.py
│   │   ├── dependencies/       # Auth and user session dependencies
│   │   │   └── auth.py
│   │   ├── models/             # Data models
│   │   ├── routers/            # API endpoints (health, auth, subjects, plans, ai)
│   │   │   ├── health.py
│   │   │   ├── auth.py
│   │   │   ├── subjects.py
│   │   │   ├── plans.py
│   │   │   └── ai.py
│   │   ├── schemas/            # Pydantic validation schemas
│   │   │   ├── auth.py
│   │   │   ├── subject.py
│   │   │   ├── plan.py
│   │   │   └── ai.py
│   │   ├── services/           # External service wrappers
│   │   │   └── gemini_service.py
│   │   └── main.py             # FastAPI entrypoint & middleware
│   ├── tests/                  # Pytest test suite
│   │   ├── conftest.py
│   │   ├── test_health.py
│   │   ├── test_database.py
│   │   ├── test_auth.py
│   │   ├── test_subjects.py
│   │   ├── test_gemini.py
│   │   ├── test_plans.py
│   │   └── test_ai.py
│   ├── requirements.txt
│   ├── pytest.ini
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/         # Reusable UI components (Button, Input, Card, Navbar, etc.)
│   │   ├── hooks/              # useAuth context hook
│   │   ├── layouts/            # MainLayout wrapper
│   │   ├── pages/              # Pages: Login, Register, Dashboard, Subjects, SubjectDetail, PlanDetail, Explain
│   │   ├── services/           # Axios API client
│   │   ├── test/               # Vitest & React Testing Library suites
│   │   ├── types/              # TypeScript definitions
│   │   ├── App.tsx             # Route configuration
│   │   ├── main.tsx
│   │   └── index.css
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── tailwind.config.js
│   └── .env.example
├── docs/
│   └── architecture.md
├── .gitignore
└── README.md

---

⚙️ Setup & Running Locally

1. Prerequisites

• Python 3.12+ (tested on Python 3.14)
• Node.js 18+ and npm
• MongoDB Atlas connection string (or local MongoDB server)
• Google Gemini API Key

---

2. Backend Setup

cd backend

# Create virtual environment & activate
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env with your MONGODB_URL and GEMINI_API_KEY

# Start development server
uvicorn app.main:app --reload --port 8000

Backend will be live at http://localhost:8000.

• Swagger Interactive Documentation: http://localhost:8000/api/docs
• Health Check: http://localhost:8000/health

---

3. Frontend Setup

cd ../frontend

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

# Start development server
npm run dev

Frontend will be live at http://localhost:5173.

---

🧪 Running Automated Tests

Backend Tests (Pytest)

cd backend
source .venv/bin/activate
pytest -v

Frontend Tests (Vitest)

cd frontend
npm run test

Production Frontend Build Check

cd frontend
npm run build

---

📡 API Documentation & Endpoints

Method	Endpoint	Description	Auth Required
GET	/health	API Health Check	No
POST	/api/auth/register	Register new user account	No
POST	/api/auth/login	Login and obtain JWT Bearer token	No
GET	/api/auth/me	Fetch authenticated user profile	Yes
POST	/api/subjects	Create a new study subject	Yes
GET	/api/subjects	List subjects for current user	Yes
GET	/api/subjects/{id}	Get subject details	Yes
PATCH	/api/subjects/{id}	Update subject	Yes
DELETE	/api/subjects/{id}	Delete subject and its plans	Yes
POST	/api/subjects/{id}/generate-plan	Generate AI study plan with Gemini	Yes
GET	/api/plans	List study plans for current user	Yes
GET	/api/plans/{id}	Get detailed study plan roadmap	Yes
DELETE	/api/plans/{id}	Delete study plan	Yes
PATCH	/api/plans/{id}/topics/{topicId}/complete	Mark topic complete	Yes
PATCH	/api/plans/{id}/topics/{topicId}/uncomplete	Mark topic incomplete	Yes
PATCH	/api/tasks/{taskId}/complete	Mark task complete by ID	Yes
PATCH	/api/tasks/{taskId}/uncomplete	Mark task incomplete by ID	Yes
POST	/api/ai/explain	Explain concept with AI tutor	Yes

---

🎯 How I Would Explain This Project in an Interview

Why FastAPI?

FastAPI provides native asynchronous I/O (async/await), automatic Pydantic request/response data validation, and built-in interactive OpenAPI/Swagger documentation. For an AI application where network calls to AI APIs and databases are I/O bound, FastAPI's async runtime ensures high throughput without blocking threads.

Why MongoDB?

Study plans are hierarchical, document-oriented structures (a plan contains days, and days contain topics/tasks). MongoDB naturally stores and indexes hierarchical documents without expensive relational table joins, while allowing flexible queries and atomic sub-document updates with array filters.

Why Gemini?

Google Gemini provides industry-leading reasoning performance and native structured JSON schema output support (response_schema), allowing us to enforce strict Pydantic schemas so that AI output is always valid JSON matching our exact domain structure.

How Authentication Works:

1. The user registers with name, email, and password. The password is encrypted with a unique salt using bcrypt.
2. Upon login, credentials are verified and a signed JWT access token containing the user's ID as subject (sub) and an expiration timestamp is returned.
3. The frontend stores this token and includes Authorization: Bearer <token> on subsequent API calls.
4. FastAPI's get_current_user dependency decodes and verifies the JWT signature on every protected route.

How Data Flows from Frontend to Backend:

The React frontend triggers actions through typed Axios services in src/services/api.ts. The request passes through FastAPI routers, where Pydantic schemas validate types. The business logic executes asynchronously against MongoDB Atlas using motor, ensuring strict user_id filtering.

How AI Output is Validated:

We enforce a multi-layer validation pipeline:

1. Gemini is given a strict JSON schema via Pydantic model (StudyPlanGeneratedSchema).
2. The response is parsed and checked with Pydantic model_validate.
3. Post-validation algorithms check that topic durations do not exceed the student's daily available study hours.
4. Only fully validated plans are transformed and stored in MongoDB.

Key Challenges Solved:

• Ensuring AI Output Quality: Prevented hallucinations and invalid time allocations by designing structured schema prompts and auto-scaling topic minutes to fit within the user's daily budget.
• Strict Data Isolation: Implemented query scoping across every database query ensuring zero cross-tenant data leaks.
• Graceful Error Resilience: Implemented fallback model handling and sanitized error responses so internal stack traces or API keys are never exposed.