AcadBuddy

AI-powered academic workspace for subjects, revision, exams, and community learning.

Overview  ·  Features  ·  Architecture  ·  Screenshots  ·  Getting Started  ·  Environment Variables  ·  Documentation

---

Overview

AcadBuddy is a full-stack educational platform that helps students organize subjects, generate AI-assisted notes and reports, prepare for exams, run quick revision sessions, and share materials in a community feed.

The codebase is structured as a monorepo with two independently deployable services:

Component	Technology	Role
Frontend	React 19, Vite 7	SPA with dashboards, subject workspaces, Smart Studies, Quick Revision, community UI, protected routes, and toast notifications
Backend	Node.js 18+, Express 5	REST API handling auth (JWT access + refresh), subject management, context uploads, AI orchestration via OpenRouter, and Cloudinary media

---

Features

Learning and Workspace

Subjects — Per-subject hubs with context uploads (PDF and plain text), notes, reports, PPT outlines, exam tools, and saved content, all scoped to the authenticated user.

Answer Styles — Configurable tone, sections, and length presets that control how AI outputs are formatted and structured per subject.

Dashboard — Progress metrics, donut charts for topic mix and activity, recent generated content, and local recent-activity tracking powered by client-side state.

Focus Mode — Distraction-free reading overlay for generated content with clean typography and no chrome.

AI and Revision

OpenRouter — Unified LLM gateway enabling swappable model backends (Qwen and others) via a single API key configuration in the environment.

Smart Studies — Summaries and keyword extraction from uploaded images and PDFs using a multimodal pipeline on the backend.

Quick Revision — Prompt-only rapid revision packs that generate key points, definitions, and review questions without requiring file uploads.

Exam Suite — Blueprints, revision planners, rapid sheets, and mock papers, all scoped to the active subject context.

Community and Media

Community Feed — Posts with votes, comments, and topic filters; optional media attachments via Cloudinary. Designed for peer-to-peer study material sharing.

Cloudinary + Multer — Secure, validated file uploads with image optimization via Sharp on the backend pipeline.

Security and Quality

JWT Authentication — Short-lived access tokens with a dedicated refresh flow. Axios interceptors on the client handle silent token rotation.

Rate Limiting — Applied on all API routes via express-rate-limit to mitigate abuse and enforce fair use.

Helmet and CORS — Standard hardening applied at the Express application layer.

---

Architecture

The diagram below shows the high-level request and data flow across the system.

---

Technology Stack

Layer	Frontend	Backend
Runtime / Framework	React 19, Vite 7	Node.js 18+, Express 5
Data / State	Zustand	MongoDB, Mongoose 9
Routing	React Router 7	Express Router
UI / Animation	Tailwind CSS 3, Framer Motion	—
Data Visualization	Recharts	—
Icons	Lucide React	—
HTTP / Auth	Axios with interceptors	JWT, bcryptjs
AI Gateway	—	OpenRouter SDK (@openrouter/sdk)
File Handling	FormData uploads	Multer, Cloudinary, Sharp, pdf-parse
Security	—	Helmet, CORS, express-rate-limit

---

Screenshots

Landing Page	Dashboard

Profile	Sign Up

Preloader	Methodology

---

Repository Structure

acadbuddy/
├── README.md
├── basic-flowchart.png
├── backend/
│   ├── src/
│   │   ├── controllers/        # HTTP handlers
│   │   ├── models/             # Mongoose schemas
│   │   ├── routes/             # Route definitions
│   │   ├── services/           # AI orchestrator, integrations
│   │   ├── middleware/         # Auth and validation middleware
│   │   └── server.js           # Application entry point
│   ├── .env.sample
│   └── package.json
└── frontend/
    ├── public/                 # Static assets and demo screenshots
    ├── src/
    │   ├── components/         # Layout, UI, and feature modules
    │   ├── Pages/              # Route-level views
    │   ├── context/            # Toast and global providers
    │   ├── services/           # Axios API client
    │   ├── store/              # Zustand stores
    │   └── utils/
    ├── .env.sample
    └── package.json

---

Getting Started

Prerequisites

• Node.js 18 or newer
• MongoDB (local instance or MongoDB Atlas)
• Cloudinary account for media uploads
• OpenRouter API key for AI features

1. Clone the Repository

git clone https://github.com/your-org/acadbuddy.git
cd acadbuddy

2. Backend Setup

cd backend
npm install
cp .env.sample .env   # Windows: copy .env.sample .env

Edit .env and fill in the required values (see the Environment Variables section below).

npm run dev

The API server starts on the port defined in .env, commonly 7000 or 8000.

3. Frontend Setup

cd frontend
npm install
cp .env.sample .env

Set VITE_API_URL to your API base URL, for example http://localhost:7000/api (must include the /api suffix). The dev server runs on port 3000; the browser calls the backend directly—no Vite proxy.

npm run dev

Open the printed local URL, typically http://localhost:3000.

Production Build

# Build the frontend
cd frontend && npm run build

# Start the backend in production mode
cd backend && npm start

Serve the frontend/dist directory via your hosting layer (Vercel, Netlify, Nginx, etc.) and run the Node process with a process manager such as PM2. Ensure all environment variables are set on the host.

---

Environment Variables

Backend (backend/.env)

Variable	Description
PORT	Port the API server listens on
MONGO_URI	MongoDB connection string
JWT_SECRET	Secret key for access token signing
JWT_REFRESH_SECRET	Secret key for refresh token signing
OPENROUTER_API_KEY	Your OpenRouter API key
OPENROUTER_MODEL	Model identifier (e.g. qwen/qwen-2.5-72b-instruct)
CLOUDINARY_CLOUD_NAME	Cloudinary cloud name
CLOUDINARY_API_KEY	Cloudinary API key
CLOUDINARY_API_SECRET	Cloudinary API secret
BACKEND_URL	Public URL of this API (used for CORS and redirects)
CLIENT_URL	Public URL of the frontend (used for CORS)

See backend/.env.sample for the full reference.

Frontend (frontend/.env)

Variable	Description
VITE_API_URL	Full backend API base URL, including /api (e.g. https://your-app.onrender.com/api)

See frontend/.env.sample for the full reference.

---

Documentation

Document	Description
backend/Readme.md	API routes, Mongoose models, and backend-specific implementation notes
frontend/README.md	Frontend scripts, component structure, and client-specific configuration

---

License

Specify your license here and add a LICENSE file to the repository root before publishing publicly.

---

_{AcadBuddy — smarter study workflows.}