☀️ Helio

AI-Powered Academic Study Planner

Plan smarter. Study better. Powered by AI.

---

Helio is a full-stack web application that helps students organize their academic life using AI. Simply add your subjects, tell Helio how many hours a day you can study, and let it generate a personalized weekly study plan, subject-specific tasks, and an AI chat assistant — all in one place.

🌐 Frontend: https://helio-kohl.vercel.app 🔧 Backend: https://helio-hlgy.onrender.com

---

📋 Table of Contents

1. Features
2. Tech Stack
3. Getting Started
4. Project Structure
5. API Reference
6. Environment Variables
7. Deployment
8. Contributing
9. License

---

✨ Features

• ✅ User Authentication — Secure sign-up and login using email & password via Better-Auth. Session tokens are stored locally for seamless re-authentication.
• ✅ Subject Management — Add subjects with a name, difficulty level (easy / medium / hard), and your daily available study hours. Remove subjects when you no longer need them.
• ✅ AI Study Plan Generation — Get a personalized 7-day weekly study plan generated by a large language model (Llama 3.3 70B via Groq), complete with sessions, focus topics, and time allocations.
• ✅ AI Task Generation — Automatically generate specific, actionable study tasks for each subject — covering reading, practice, revision, watching, and exercises.
• ✅ Task Tracking — Mark tasks as complete or delete them as you make progress.
• ✅ Local Caching — Study plans and tasks are saved in your browser's localStorage so they're available even when offline.
• ✅ AI Rate Limiting — Each user is limited to 20 AI requests per day, with daily auto-reset, tracked securely via MongoDB.

---

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
Angular	21	Core frontend framework (Standalone Components, Signals)
TypeScript	5.9	Strongly typed JavaScript
PrimeNG	21	Rich UI component library
Angular Material	21	Additional UI components and theming
RxJS	7.8	Reactive programming and HTTP handling
Vitest	Latest	Unit testing

Backend

Technology	Version	Purpose
Node.js + Express	5	REST API server
MongoDB + Mongoose	Latest	Database and ODM
Better-Auth	1.5	Email/password authentication with Bearer plugin
Groq SDK	Latest	LLM inference (Llama 3.3 70B model)
Google GenAI SDK	Latest	Additional AI capabilities
rate-limit-mongo	Latest	Per-user AI request rate limiting
dotenv / CORS / body-parser	Latest	Configuration, security, and request parsing

---

🚀 Getting Started

Prerequisites

Make sure you have the following installed before proceeding:

• Node.js v18 or higher
• npm v9 or higher
• MongoDB — local instance or a free MongoDB Atlas cluster
• A free Groq API key for AI features

1. Clone the Repository

git clone https://github.com/your-username/helio.git
cd helio

2. Set Up the Backend

cd server
npm install
cp .env.example .env

Open server/.env and fill in your values (see Environment Variables):

npm run dev
# Server starts on http://localhost:3000

3. Set Up the Frontend

Open a new terminal window:

cd planner
npm install
npm start
# App starts on http://localhost:4200

4. Build for Production

cd planner
npm run build

5. Run Tests

cd planner
npm test

---

📁 Project Structure

helio/
├── planner/                        # Angular 21 frontend (deployed on Vercel)
│   ├── src/
│   │   ├── app/
│   │   │   ├── core/
│   │   │   │   └── services/auth/  # Authentication service (login, logout, session)
│   │   │   ├── services/           # AI service, Subject service
│   │   │   ├── shell/              # App shell layout (navbar, sidebar, router outlet)
│   │   │   ├── app.routes.ts       # Route definitions with auth guards
│   │   │   └── app.config.ts       # Angular app configuration (providers, HTTP client)
│   │   └── environments/
│   │       ├── environment.ts      # Dev API URL (http://localhost:3000)
│   │       └── environment.prod.ts # Prod API URL (https://helio-hlgy.onrender.com)
│   └── package.json
│
└── server/                         # Node.js + Express 5 backend (deployed on Render)
    ├── config/
    │   ├── auth.js                 # Better-Auth configuration (MongoDB adapter, Bearer plugin)
    │   └── ai.js                   # Groq SDK setup and model configuration
    ├── App.js                      # Express app setup, middleware, and route registration
    ├── Server.js                   # Entry point — MongoDB connection and server start
    └── package.json

---

📡 API Reference

All protected routes require a valid Bearer token in the Authorization header:

Authorization: Bearer <your_token>

🔐 Auth (via Better-Auth)

Method	Endpoint	Description	Auth Required
POST	/api/auth/sign-up/email	Register a new user	No
POST	/api/auth/sign-in/email	Login and receive a token	No
POST	/api/auth/sign-out	Logout and invalidate session	Yes
GET	/api/auth/get-session	Fetch the current user session	Yes

📚 Subjects

Method	Endpoint	Description	Auth Required
POST	/api/subjects/add	Add a new subject	Yes
GET	/api/subjects-list/get	Get all subjects for the current user	Yes
DELETE	/api/subjects/delete/:id	Delete a subject by ID	Yes

Subject body example:

{
  "name": "Data Structures",
  "difficulty": "hard",
  "hoursPerDay": 2
}

🤖 AI

Method	Endpoint	Description	Auth Required	Rate Limited
POST	/api/ai/generate-plan	Generate a 7-day AI study plan	Yes	Yes (20/day)
POST	/api/ai/generate-tasks	Generate tasks for a specific subject	Yes	No
POST	/api/ai/chat	Chat with the AI academic assistant	Yes	No

🏥 Health

Method	Endpoint	Description
GET	/health	Check if the server is running

---

🔑 Environment Variables

Backend (server/.env)

Variable	Description	Example
MONGO_URI	MongoDB connection string	mongodb+srv://user:pass@cluster.mongodb.net/helio
BETTER_AUTH_SECRET	Secret key for Better-Auth token signing	a-long-random-secret-string
BETTER_AUTH_URL	Base URL of the backend server	http://localhost:3000
GROQ_API_KEY	API key from Groq Console	gsk_...
PORT	Port the server runs on	3000
FRONTEND_URL	(Optional) Frontend URL for CORS	http://localhost:4200

Frontend

The frontend uses Angular environment files instead of a .env file. No manual configuration needed for local development — just ensure your backend is running on http://localhost:3000.

For production, update planner/src/environments/environment.prod.ts with your deployed backend URL.

---

☁️ Deployment

Frontend — Vercel

The planner/ directory is deployed on Vercel.

1. Push your repository to GitHub.
2. Import the repo in Vercel and set the Root Directory to planner.
3. Vercel auto-detects Angular and configures the build (npm run build) and output directory (dist/planner/browser).
4. No additional environment variables are needed — the production API URL is baked into environment.prod.ts.

Backend — Render

The server/ directory is deployed on Render.

1. Create a new Web Service on Render and connect your GitHub repo.
2. Set the Root Directory to server and the Start Command to npm start.
3. Add all environment variables from the table above in Render's dashboard under Environment.
4. Render provides a public URL (e.g. https://helio-hlgy.onrender.com) — use this as your BETTER_AUTH_URL.

⚠️ Note: Render free-tier services spin down after inactivity. The first request after a cold start may take 30–60 seconds.

CORS Configuration

The backend allows requests from the following origins:

• http://localhost:4200 (local development)
• https://helio-kohl.vercel.app (production frontend)
• Any helio-*.vercel.app subdomain (preview deployments)

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository by clicking the Fork button on GitHub.
2. Clone your fork locally:

   git clone https://github.com/your-username/helio.git

3. Create a new branch for your feature or bugfix:

   git checkout -b feature/your-feature-name

4. Make your changes and commit them with a clear message:

   git commit -m "feat: add your feature description"

5. Push to your fork:

   git push origin feature/your-feature-name

6. Open a Pull Request on the original repository and describe what you've changed and why.

Please make sure your code follows the existing style, and that all tests pass before submitting a PR.

---

📄 License

This project is licensed under the MIT License.

You are free to use, modify, and distribute this project for personal or commercial purposes, as long as the original license and copyright notice are included.

---

Made with ❤️ and ☀️ by Omkar