TimeForge

An AI-powered adaptive timetable maker that builds your weekly schedule based on your goals, priorities, and personal energy patterns — and adapts when life gets in the way.

Problem Statement

Students and self-learners struggle to consistently follow a schedule because life is unpredictable. Existing tools like Google Calendar require manual planning and don't adapt when something unexpected happens. When a plan breaks, most people abandon it entirely instead of rescheduling. TimeForge takes your goals and priorities, builds a weekly schedule automatically around your energy patterns, and intelligently reschedules when real-life interruptions happen.

Features

V1 — Static Generation

• Onboarding: college timing, sleep schedule, peak productivity window
• Add goals with priority and hours per week
• Auto-generate a time-blocked weekly timetable (high priority tasks placed in peak energy slots)
• Mark tasks as completed / not completed

V2 — Manual Control

• Manual task rescheduling and swapping
• Daily view alongside weekly view
• Task status tracking (pending / completed / rescheduled)

V3 — Smart Adaptation

• Daily mood/energy check-in
• Automatic slot adjustment based on patterns
• Habit-building suggestions

V4 — AI Agent

• Conversational replanning ("I have exams this week, replan my schedule")
• Pattern learning from user behavior (RAG-based personalization)
• Full constraint-aware rescheduling

Tech Stack

Layer	Technology
Frontend	React.js
Styling	Tailwind CSS
Backend	Node.js + Express.js
Database	MongoDB
Auth	JWT + bcrypt
AI (V2+)	Groq API
Frontend Hosting	Vercel
Backend Hosting	Render

Database Design

Collections: users, goals, preferences, timetable

See /docs (or project Notion) for full schema details.

API Routes

POST   /api/auth/register
POST   /api/auth/login

POST   /api/preferences
GET    /api/preferences
PUT    /api/preferences

POST   /api/goals
GET    /api/goals
PUT    /api/goals/:id
DELETE /api/goals/:id

POST   /api/timetable/generate
GET    /api/timetable
PATCH  /api/timetable/slot/:id

Project Structure

timeforge/
  ├── client/      # React + Tailwind frontend
  └── server/      # Express backend

Getting Started

# Clone the repo
git clone <repo-url>
cd timeforge

# Setup backend
cd server
npm install
npm run dev

# Setup frontend
cd ../client
npm install
npm run dev

Roadmap

• PRD & system design
• V1 — Core timetable generation
• V2 — Manual rescheduling
• V3 — Mood-based adaptation
• V4 — AI replanning agent

License

MIT