AI Study Companion

AI Study Companion is a full-stack learning platform that combines authentication, AI-powered study support, memory tracking, and personalized insights to help learners study more effectively over time.

Instead of behaving like a one-time chatbot, the system is designed to support a complete learning loop:

1. A learner signs up and logs in securely.
2. The learner can chat with the AI for concept explanations and guidance.
3. The learner can generate practice questions/quiz-style prompts.
4. The platform stores learning signals (memories, weak areas, mistakes).
5. The learner receives targeted insights and weak-topic feedback.

This creates a study experience that is interactive, adaptive, and personalized.

What the project does

At a practical level, this project acts as an AI-powered study assistant with persistent learning context.

It supports:

• User authentication with JWT access tokens.
• Conversational study help for asking topic-related questions.
• Question generation to practice and self-evaluate.
• Memory-aware learning support using stored learner interactions/signals.
• Weak-topic and mistake tracking so users can focus revision where it matters most.
• Syllabus-linked workflows to align study with user-specific curriculum data.

The backend exposes APIs for all these flows, and the frontend provides the user-facing learning interface.

How it works (end-to-end)

1) Authentication and user session

• Users register via /signup and log in via /login.
• On successful login, the backend returns a JWT bearer token.
• This token is included in protected requests (Authorization: Bearer <token>).
• Auth-protected routes ensure that memory and profile-related data is tied to the correct user.

2) AI-assisted learning interactions

• The frontend sends study/chat requests to backend API endpoints.
• Backend routes forward relevant prompts to the LLM service layer.
• The LLM integration (Groq-backed in this project) generates responses and question content.
• The frontend renders these responses as part of the learner’s active study flow.

3) Memory and performance signal capture

• The platform stores specific learning events (for example, memory records and outcomes tied to user progress).
• Memory services aggregate this data into useful categories such as weak topics and mistakes.
• These signals are not just stored—they are reused to personalize later responses and reports.

4) Insight generation and adaptive revision

• Based on saved memories/signals, the system exposes insight endpoints.
• Users can retrieve weak-topic summaries and mistake-focused feedback.
• This enables targeted revision rather than generic practice.

5) Frontend orchestration

• The React/Vite frontend manages pages and flows (login, quiz/chat/report/profile usage patterns).
• During development, Vite proxies /api/* calls to the FastAPI backend.
• The UI acts as the control layer while business logic, auth, and AI/data services are handled in the backend.

High-level architecture

Frontend (React + Vite + Tailwind)
        |
        | HTTP / JSON (JWT for protected routes)
        v
Backend API (FastAPI)
  - Auth routes (signup/login/protected/profile)
  - Chat & question generation routes
  - Memory and insight routes
  - Syllabus routes
        |
        | Service layer
        v
External integrations
  - Groq API (LLM responses/question generation)
  - Hindsight API (memory persistence/insight support)

Repository structure

• backend/ — FastAPI service, API routes, schemas, security utilities, and service modules.
• frontend/ — React + Vite client application for user interaction.
• README.md — Root-level project documentation (this file).

Backend overview

The backend is responsible for identity, API contracts, orchestration, and AI/data integrations.

Main backend responsibilities

• Validates and authenticates users.
• Issues and verifies JWT tokens.
• Exposes learning APIs for chat and question generation.
• Persists and retrieves learning memory data.
• Computes or fetches insight-oriented outputs (weak areas, mistakes, summaries).

Key backend areas

• app/api/routes/auth_routes.py — signup, login, protected user endpoints.
• app/api/routes/chat_routes.py — chat and question generation endpoints.
• app/api/routes/memory_routes.py — memory storage and insight retrieval flows.
• app/api/routes/syllabus_routes.py — syllabus upload/fetch operations.
• app/core/security.py — password hashing and JWT encode/decode helpers.
• app/services/llm_service.py — AI model request handling.
• app/services/memory_service.py — memory/inference support integration.

Frontend overview

The frontend provides the interactive study experience and consumes backend APIs.

Main frontend responsibilities

• Handles user login/signup UX.
• Sends authenticated requests using JWT.
• Displays AI responses and generated questions.
• Surfaces memory-driven reports/insights for the learner.
• Manages user interaction flows across study features.

Tech stack

Frontend

• JavaScript (React)
• Vite
• Tailwind CSS
• ESLint

Backend

• Python
• FastAPI
• Uvicorn
• Pydantic
• passlib + bcrypt (password hashing)
• python-jose (JWT)
• Alembic (DB migration tooling present in repo)

External services

• Groq API
• Hindsight API

Getting started

1) Clone repository

git clone https://github.com/Akhilesh-M03/ai_study_companion.git
cd ai_study_companion

2) Backend setup

cd backend
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

Create environment file:

copy .env.example .env

Run backend:

python main.py

API docs:

• Swagger UI: http://localhost:8000/docs

3) Frontend setup

In a new terminal:

cd frontend
npm install
copy .env.example .env
npm run dev

Frontend runs at:

• http://localhost:5173

During development, frontend /api requests are proxied to backend http://localhost:8000.

Environment variables

Backend (backend/.env)

Important variables include:

• SECRET_KEY — JWT signing key.
• DATABASE_URL — database connection string.
• ALLOWED_CORS_ORIGINS — comma-separated allowed origins.
• GROQ_API_KEY — required for AI generation.
• HINDSIGHT_API_KEY — required for memory-related features.

Frontend (frontend/.env)

Use the provided example file and configure API URL behavior as needed for deployment.

API summary (backend)

Representative endpoints (based on repository docs and route modules):

• POST /signup — create account.
• POST /login — authenticate and receive JWT token.
• GET /protected — validate authenticated access.
• GET /user/profile — retrieve user profile data.
• Chat/question endpoints for study assistance and question generation.
• Memory/insight endpoints for storing and retrieving learning signals.
• Syllabus endpoints for uploading/fetching curriculum context.

For complete request/response schemas, use the live FastAPI docs at /docs.

Language composition

• JavaScript: 61.2%
• Python: 33.7%
• CSS: 4.8%
• Other: 0.3%

Project purpose in one line

AI Study Companion helps learners move from one-off Q&A to a continuous learning cycle: ask, practice, remember, analyze weak areas, and improve with personalized feedback.