HandAll

HandAll is an AI-supported student planner built to keep classes, assignments, recovery time, side goals, and calendar imports in one flow. Instead of acting like a plain calendar, it helps students set up routines, import school schedules, discover goal-supporting events, and talk to an assistant that understands the planner context.

What HandAll Does

• Centralizes classes, tasks, imported calendar events, and personal goals in one interface.
• Uses AI-assisted planning to break work into manageable blocks and support schedule decisions.
• Lets students connect calendars, import .ics feeds, and preview converted events before syncing.
• Adds a visual layer for motivation, energy windows, side goals, and assistant-guided planning.
• Lets users change a motivation slider that resyncs the day's calendar, so the AI can rebalance tasks around how locked in, tired, or flexible the user feels in that moment.

Visual Product Tour

Landing and Authentication

The app starts with a simple landing page that frames HandAll as a guided planning tool rather than just another calendar.

Users can create an account directly or continue with Google for a faster setup flow.

Returning users land on a focused sign-in screen that takes them straight back into their planner.

Onboarding Flow

New users are guided through a three-step onboarding flow so the planner can personalize recommendations before the main dashboard opens.

Step 1 collects profile information and side goals. Those goals later feed into event discovery and long-term planning.

Step 2 captures routine preferences such as wake-up and sleep windows so the planner can respect energy boundaries. The time picker is built as a dedicated modal to keep routine setup simple and touch-friendly.

Step 3 connects the calendar layer, either through Google or .ics import, before finishing setup.

Calendar Sync and Import

HandAll supports calendar sync through Google Calendar and also supports private iCal links or file uploads.

The import dialog supports both URL sync and direct file upload, which helps students bring in university calendars or exported schedules without dealing with CORS issues in the browser.

Before events are committed, HandAll shows an import preview with converted tasks, category counts, and priority labeling so users can verify what is coming into the planner.

Planner and Calendar Experience

The main planner supports both day and week views, allowing users to zoom in on a single day or look at a fuller weekly plan.

Day view is useful for focused execution and quick task edits.

Week view gives a broader planning perspective and helps users see class load, study blocks, and recovery windows together.

The more populated weekly schedule shows how HandAll combines classes, study blocks, and lower-pressure recovery activities into the same planning surface.

Users can manually add new entries through a dedicated modal without leaving the calendar.

Existing entries can also be updated in place, which makes it easy to adjust start times, mark work done, or clean up the plan without leaving the weekly view.

The motivation slider also lives directly inside the planner. It gives the AI a fast signal about how intense or protected the day should feel, which lets HandAll reshape the daily schedule around a more relaxed mode or a stronger lock-in mode.

The built-in assistant is available inside the planner so users can ask for help without leaving the scheduling context.

It is intended for natural-language schedule support, task guidance, and general planning help based on the rest of the app state.

Goals and Event Discovery

One of HandAll's distinctive features is the Goals area, which looks beyond school deadlines and helps users build momentum on side ambitions.

The "Fun Events" view surfaces nearby experiences that can support balance and recovery.

The "Goal Events" view narrows results around a specific side goal, like learning guitar or learning Spanish, so the app can suggest more targeted opportunities.

The settings page also lets users maintain side goals over time, which feeds back into event discovery and future planning recommendations.

Settings and Personalization

The general settings page gives users a place to manage profile presence, XP, current level, and routine preferences in one place.

HandAll also gives immediate progress feedback when tasks are completed, so XP becomes part of the day-to-day planning loop rather than a separate hidden system.

The advanced settings view also shows active sync sources so users can see what is currently connected.

The broader settings flow supports the planner's routine-first behavior, while the motivation slider itself lives inside the calendar so users can adjust schedule intensity in context.

Core Features

AI-supported scheduling

• Breaks large work into smaller planning blocks.
• Supports assistant-driven planning inside the app.
• Balances structure with lower-pressure recovery activities.
• Modifies the daily plan using AI based on the current motivation slider state.
• Uses the motivation slider to shift between gentler recovery-oriented planning and stronger lock-in scheduling.
• Includes burnout-aware scheduling logic so tasks are distributed in a way that helps prevent students from overloading themselves.

Routine-aware planning

• Captures wake-up and sleep windows during onboarding.
• Keeps schedule decisions grounded in how the user actually works.
• Surfaces motivation and energy controls directly in the planner UI.

Calendar integration

• Google Calendar connection.
• Private iCal URL support.
• Direct .ics upload.
• Preview-before-import workflow for safer syncing.

Side goals and growth

• Stores long-term goals like fitness, music, or language learning.
• Discovers fun and goal-supporting opportunities nearby.
• Connects planning with life outside class deadlines.

Progress and rewards

• Includes an XP system that rewards completed tasks.
• Uses task completion as a way to make progress visible and reinforce consistency.
• Tracks user progress directly inside the product through the profile and planner experience.

Tech Stack

Frontend

• React 18
• TypeScript
• Vite
• Tailwind CSS
• Zustand
• Radix UI and shadcn-style component patterns

Backend

• Node.js
• Express
• SQLite
• Supabase Auth

AI backend

• Python
• FastAPI
• LangGraph
• OpenAI via langchain-openai

Local Development

Prerequisites

• Node.js 18 or newer
• Python 3.9 or newer
• A Supabase project for authentication
• An OpenAI API key
• Optional Google Calendar credentials for calendar integration

Install

git clone https://github.com/MrFiscus/HandAll.git
cd HandAll
npm run setup

Run the app

npm run dev

This starts:

• the Node backend
• the Vite frontend
• the Python AI service

Environment setup

HandAll uses variables across the root, backend, and frontend. A practical local setup looks like this.

Root or backend .env:

# Supabase
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

# OpenAI
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o-mini

# Planner / AI service
HANDALL_PLANNER_URL=http://127.0.0.1:8011

# Event discovery
FIRECRAWL_API_KEY=your_firecrawl_api_key

# Google Calendar / OAuth
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CALENDAR_ID=primary
GOOGLE_SERVICE_ACCOUNT_FILE=service_account.json
# or use GOOGLE_SERVICE_ACCOUNT_JSON instead of a file
GOOGLE_SERVICE_ACCOUNT_JSON=
GOOGLE_OAUTH_CLIENT_ID=your_google_oauth_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_google_oauth_client_secret

# Optional debug flags
HANDALL_EXPOSE_ERRORS=1
HANDALL_CHAT_TEST_OPENAI=1
LOG_LEVEL=INFO

# Optional Postgres override
DATABASE_URL=

Frontend frontend/.env:

VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_AGENT_API_URL=http://127.0.0.1:8011

Notes:

• If DATABASE_URL is not set, the app falls back to the local SQLite database.
• GOOGLE_SERVICE_ACCOUNT_FILE is useful locally, while GOOGLE_SERVICE_ACCOUNT_JSON is better for hosted environments.
• SUPABASE_ANON_KEY can still be used as a fallback in some Python paths, but SUPABASE_KEY is the cleaner primary name in this repo.

Project Structure

• frontend/ - React application and UI components
• backend/ - Node backend, calendar sync, and persistence
• backend/main.py - FastAPI entry point for AI routes
• backend/planner.py - planning and decomposition logic
• backend/agent.py - conversational assistant logic
• images/ - screenshots used in the README

Team

• Evan Bhandari - Calendar UI and sync optimization
• Smaran Pokharel - Google Calendar connect flow and product integration
• Sandesh Dhakal - Frontend and presentation
• Tenzing Gurung - AI planner and motivation sync logic

Project Context

HandAll was built for the Nepal-US Hackathon 2026.

The full idea, product direction, implementation, and coding were completed within a 36-hour hackathon sprint.