🧠 Pacely — AI Study Planner & Intelligent Scheduler

An intelligent, adaptive, full-stack study planning platform built with FastAPI and Vanilla JavaScript.
Featuring AI-assisted syllabus parsing, automatic missed-session redistribution, multi-hour block tracking, interactive weekly timetable grids, document RAG knowledge retrieval, real-time completion tracking, productivity analytics, peak time window insights, and customizable dark/light glassmorphic UI.

---

📑 Table of Contents

• ✨ Key Features
• 🏗️ System Architecture
• 💻 Tech Stack
• 🚀 Quick Start Guide
  • Prerequisites
  • 1. Backend Setup
  • 2. Running the Application
• 🐳 Docker Deployment
• ⚙️ Environment Configuration
• 📱 Modules & Interface Overview
• 🗄️ Comprehensive API Reference
• 🔒 Security & Data Privacy
• 🤝 Contributing & License

---

✨ Key Features

📅 1. Smart Adaptive Scheduling Engine

• Priority & Duration Allocation: Computes balanced daily time budgets based on subject difficulty, target hours, and exam deadlines.
• Auto-Adjustment for Missed Sessions: Missed or incomplete sessions are automatically swept forward and redistributed over upcoming study days without overwhelming daily limits.
• Multi-Hour Block Tracking: Merged multi-hour UI study sessions simultaneously update all backing database items upon completion, preserving exact daily progress totals across Dashboard, Daily Tasks, and Analytics views.

🕒 2. Interactive Timetable & Subject Palette

• Dynamic Subject Palette: Auto-assigns distinct, vibrant palette colors (Violet, Fuchsia, Cyan, Cobalt, Amber) to individual subjects to prevent visual clutter and green-block collisions.
• Custom Daily Routine Anchors: User-configured wake, sleep, lunch, rest break, and dinner windows that anchor study blocks naturally around daily life.
• Custom Routine Activities: Supports recurring commitments (College, Gym, Tuition, Work Shifts) with custom days, hours, and dedicated indigo badge styles.

🤖 3. AI Assistant with Document RAG

• Natural Language Goal Creation: Describe exam targets and timelines in plain English; the AI extracts structured subjects, estimated hours, and milestones.
• Document Knowledge Retrieval (RAG): Upload syllabus PDFs, lecture notes, or markdown files with automatic chunking and vector/keyword retrieval for grounded study recommendations.
• Multi-Session Chat Management: Persistent chat history with session pinning, custom renaming, and message deletions.

📊 4. In-Depth Analytics, Heatmaps & Peak Time Insights

• GitHub-Style Study Heatmap: 365-day visual consistency grid with explicit 5-stage intensity legend (Less [ ] [ ] [ ] [ ] [ ] More) tracking completed hours.
• Productivity by Time of Day: Analyzes completed sessions across six 4-hour time windows (12 AM–4 AM, 4 AM–8 AM, 8 AM–12 PM, 12 PM–4 PM, 4 PM–8 PM, 8 PM–12 AM) to pinpoint your peak productivity hours.
• Streak & Consistency Metrics: Real-time current streak, longest streak, and completion rate calculations.
• Dynamic Charts: 7-day velocity bar charts, 30-day cumulative trends, and subject distribution breakdowns powered by Chart.js.

🔔 5. Reminders, Security Modals & Dark/Light Glassmorphism

• Browser Push Notifications: Configurable session reminders, study nudge alerts, and daily motivation quotes.
• Solid Data & Privacy Popups: High-contrast, 100% opaque security modals for Password Updates, Data Wipes, and Account Deletions with zero text bleed-through.
• Smooth Dark / Light Theme Switcher: Fully synchronized CSS custom properties across sidebar, content cards, popups, and inputs with smooth 0.35s ease transitions.

---

🏗️ System Architecture

study-planner/
├── backend/
│   ├── app/
│   │   ├── main.py               # FastAPI entrypoint + static file mounting
│   │   ├── config.py             # App configuration & environment variables
│   │   ├── database.py           # SQLAlchemy session engine & Base model
│   │   ├── models.py             # ORM models (User, Goal, Subject, Schedule, Progress, DailyTask, Documents)
│   │   ├── schemas.py            # Pydantic validation models
│   │   ├── auth.py               # JWT generation, token verification, bcrypt hashing
│   │   ├── planner.py            # Scheduling algorithm & missed task sweep engine
│   │   └── routers/
│   │       ├── auth_router.py         # Login, Registration, Social Auth, User info
│   │       ├── goals_router.py        # Goal lifecycle & schedule regeneration
│   │       ├── schedule_router.py     # Day & month schedule endpoints, task completion
│   │       ├── subjects_router.py     # Subject CRUD & hour tracking
│   │       ├── daily_tasks_router.py  # Ad-hoc daily checklist tasks
│   │       ├── progress_router.py     # Progress metrics, heatmaps, streaks, AI suggestions
│   │       ├── ai_router.py           # Document RAG, NLP goal parser, chat sessions
│   │       └── account_router.py      # Profile management, data export & account deletion
│   ├── requirements.txt          # Python backend dependencies
│   ├── Dockerfile                # Production container specification
│   └── .env.example              # Environment variables template
│
└── frontend/
    ├── index.html                # Authentication portal (Sign In / Register)
    ├── dashboard.html            # Main dashboard overview & today's agenda
    ├── timetable.html            # Weekly drag-and-drop timetable grid
    ├── planner.html              # Study goal builder & syllabus manager
    ├── calendar.html             # Monthly calendar view with day inspection
    ├── daily-tasks.html          # Daily checklist & custom task board
    ├── analytics.html            # Productivity metrics, trends, peak time slots & heatmaps
    ├── ai-assistant.html         # Conversational AI assistant & document workspace
    ├── subjects.html             # Subject catalog & progress overview
    ├── settings.html             # Routine configuration, theme switcher & data privacy modals
    ├── css/
    │   └── style.css             # Glassmorphic design system, opaque popups & typography tokens
    └── js/
        ├── api.js                # Centralized async API client & HTTP interceptors
        ├── auth.js               # Token management & session guards
        ├── layout.js             # Shared navigation sidebar, header & theme sync
        ├── subject-colors.js     # Consistent subject color palette generator
        ├── timetable-helper.js   # Timetable slot computation & routine anchor engine
        ├── dashboard.js          # Dashboard view controller & multi-hour block sync
        ├── timetable.js          # Timetable view controller & custom activities
        ├── calendar.js           # Calendar view controller
        ├── analytics.js          # Analytics, time-of-day productivity & heatmap controller
        ├── assistant.js          # AI Assistant chat & document RAG controller
        └── settings.js           # Preferences, daily routine & account security handlers

---

💻 Tech Stack

Backend

• Framework: FastAPI (Python 3.11+)
• ORM & Database: SQLAlchemy 2.x with SQLite (configurable to PostgreSQL)
• Validation: Pydantic v2
• Authentication: python-jose (JWT) + Passlib with bcrypt
• Server: Uvicorn (Development) / Gunicorn (Production)

Frontend

• Core: Pure Semantic HTML5, Modern CSS3 (CSS Variables, Flexbox/Grid, Glassmorphism), and Vanilla JavaScript (ES6+ Modules)
• Data Visualization: Chart.js
• Typography & Icons: Inter / Plus Jakarta Sans & SVG iconography
• Zero Build Tool Overhead: Runs instantly without requiring Webpack, Vite, or npm installs.

---

🚀 Quick Start Guide

Prerequisites

• Python 3.11+ installed (Download Python)
• Git installed

---

1. Backend Setup

1. Clone the repository:

   git clone https://github.com/your-username/study-planner.git
   cd study-planner/backend

2. Create and activate a virtual environment:

   • Windows (PowerShell / Command Prompt):

     python -m venv venv
     .\venv\Scripts\activate

   • macOS / Linux:

     python3 -m venv venv
     source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables:

   # Windows
   copy .env.example .env
   
   # macOS / Linux
   cp .env.example .env

---

2. Running the Application

Start the local development server:

uvicorn app.main:app --reload --port 8000

Once running, the backend automatically serves the full frontend web interface. Open your browser and navigate to:

http://127.0.0.1:8000

Interactive API Documentation:
Access the Swagger UI docs at http://127.0.0.1:8000/docs or ReDoc at http://127.0.0.1:8000/redoc.

---

🐳 Docker Deployment

To spin up the entire application using Docker:

# Build and run container
docker compose up --build -d

# Application is available at:
http://localhost:8000

---

⚙️ Environment Configuration

Configuration variables can be adjusted in backend/.env (copy backend/.env.example to get started):

Variable	Default Value	Description
SECRET_KEY	dev-secret-change-me-in-production	Secret key used for signing JWT authentication tokens
ACCESS_TOKEN_EXPIRE_MINUTES	10080 (7 Days)	Lifetime of generated JWT access tokens
DATABASE_URL	sqlite:///./study_planner.db	Database connection string
ALLOWED_ORIGINS	*	Allowed CORS origins for API requests
ENVIRONMENT	development	Runtime environment (development or production)
GROQ_API_KEY	(required for AI)	Groq API key that powers the AI Assistant (chat, quizzes, exam questions, summaries). Get a free key at console.groq.com/keys. Without it, the AI Assistant page displays a clear "AI Not Configured" state.
EMBEDDING_BASE_URL	http://localhost:11434	(Optional) Base URL of a local Ollama server, used for semantic document search.
EMBEDDING_MODEL	nomic-embed-text	(Optional) Ollama embedding model name.

Optional: Local Semantic Search (Ollama)

By default, document retrieval for the AI Assistant uses BM25/TF-IDF keyword matching—this works out of the box with zero extra setup. To enable semantic similarity search:

# 1. Install Ollama: https://ollama.com/download
# 2. Pull the embedding model
ollama pull nomic-embed-text
# 3. Ollama runs on http://localhost:11434 by default. The backend detects it automatically
#    and blends semantic similarity into search rankings.

---

📱 Modules & Interface Overview

Page / Module	URL Path	Key Functionality
Authentication	/index.html	Secure registration, login, password reset, and session persistence
Dashboard	/dashboard.html	Today's study agenda, multi-hour completion checkboxes, quick stats, and smart recommendations
Timetable	/timetable.html	Weekly 7-day grid with hourly slots, routine anchors, custom activities, and drag-and-drop rearrangement
Goal Planner	/planner.html	Create study goals, set exam deadlines, and adjust subject target hours
Calendar	/calendar.html	Monthly overview with color-coded subject badges, deadline markers, and daily session inspection
Daily Tasks	/daily-tasks.html	Checklist for ad-hoc study items, practice problems, mock tests, and quick revisions
Analytics	/analytics.html	Weekly hour breakdowns, 30-day velocity trends, 365-day consistency heatmap, and time-of-day productivity slots
AI Assistant	/ai-assistant.html	Multi-session AI chat workspace with syllabus PDF/doc upload and RAG document grounding
Settings	/settings.html	Routine window customization, theme switcher, opaque security modals, data export, and account deletion

---

🗄️ Comprehensive API Reference

🔐 Authentication (/api)

• POST /api/register — Create a new student account
• POST /api/login — Authenticate credentials and retrieve JWT token
• POST /api/social-login — OAuth / Social login provider handshake
• GET /api/me — Retrieve profile data for authenticated user

🎯 Goals & Syllabus (/api)

• POST /api/create-goal — Create a study plan with target deadline and subjects
• GET /api/goals — List all active and archived goals
• GET /api/goals/active — Fetch current primary active goal
• PUT /api/goals/{id} — Update goal parameters or dates
• DELETE /api/goals/{id} — Remove a goal and its associated schedule
• POST /api/regenerate-plan — Recalculate schedule allocations

📅 Schedule & Tasks (/api)

• GET /api/schedule — Fetch schedule items for a date range
• GET /api/schedule/month — Retrieve month-aggregated summary for calendar
• PUT /api/complete-task/{id} — Mark a schedule session completed / incomplete
• GET /api/daily-tasks — Retrieve ad-hoc daily tasks for a date
• POST /api/daily-tasks — Create a new daily checklist task
• PATCH /api/daily-tasks/{id} — Toggle task completion status
• DELETE /api/daily-tasks/{id} — Delete a daily checklist item

📊 Progress & Insights (/api)

• GET /api/progress — Fetch daily progress hours history
• GET /api/statistics — Aggregate streak metrics, completion rates, and subject totals
• GET /api/heatmap — 365-day heatmap data format
• GET /api/ai-suggestion — AI-generated recommendation based on current progress
• GET /api/reminder — Daily study session reminder summary

🤖 AI & Documents (/api)

• POST /api/parse-goal — Extract structured subjects and deadlines from free text
• POST /api/documents/upload — Upload syllabus or notes PDF/DOCX/TXT for RAG chunking
• GET /api/documents — List user's indexed documents
• DELETE /api/documents/{id} — Delete an uploaded document
• GET /api/chat/history — Fetch chat history and saved sessions
• POST /api/ask — Send prompt to AI assistant with document grounding

---

🔒 Security & Data Privacy

• Password Security: All passwords are salted and hashed using bcrypt before database persistence.
• Stateless Authentication: Secure JWT tokens with configurable expiration and standard bearer header verification.
• Scoped User Data: Database queries strictly enforce user_id ownership constraints to isolate user data.
• Opaque Security Dialogs: Password updates and account deletion popups feature solid non-transparent backgrounds to prevent text bleed-through.
• Privacy Controls: Dedicated self-service endpoints to export data, clear study records, or permanently delete accounts.

---

🤝 Contributing & License

Contributions, feature ideas, and pull requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License.