Skip to content

parthdiwane/Blindly

BranchesTags

Repository files navigation

Blindly

AI-powered daily planner that helps you organize your day. Features include:

  • AI-generated daily schedules with task breakdown
  • Google Calendar integration (sync events bi-directionally)
  • Canvas LMS integration (view assignments, auto-navigate to course websites)
  • Goal tracking and planning
  • "Welcome Back" overlay showing your progress when returning to the app

Table of Contents

  1. Prerequisites
  2. Quick Start
  3. Detailed Setup
  4. Environment Variables
  5. Running the Application
  6. Features
  7. Architecture
  8. Troubleshooting
  9. Development

Prerequisites

Before starting, ensure you have:

Requirement Version Check Command Install
Node.js 18+ node -v nodejs.org
Python 3.10-3.12 python3 --version brew install python@3.11 (macOS)
MongoDB 6+ mongod --version See MongoDB Setup

Quick Start

# 1. Clone the repository
git clone <your-repo-url>
cd SB-Hacks

# 2. Run the setup script
chmod +x setup.sh
./setup.sh

# 3. Configure environment variables (see below)

# 4. Start MongoDB (if not running)
# Option A: Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Option B: Local MongoDB
mongod --dbpath /path/to/data

# 5. Start the application
./run.sh

Open http://localhost:8080 in your browser.

Detailed Setup

1. Install Frontend Dependencies

npm install

2. Install Backend Dependencies

cd backend
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ..

3. MongoDB Setup

Option A: Docker (Recommended)

docker run -d -p 27017:27017 --name mongodb mongo:latest

Option B: MongoDB Atlas (Cloud)

  1. Create free account at mongodb.com/atlas
  2. Create a cluster and get your connection string
  3. Use the connection string in MONGODB_URI

Option C: Local Installation

  • macOS: brew install mongodb-community && brew services start mongodb-community
  • Ubuntu: sudo apt install mongodb && sudo systemctl start mongodb
  • Windows: Download from mongodb.com

4. Get API Keys

Gemini API Key (Required)

  1. Go to Google AI Studio
  2. Click "Create API Key"
  3. Copy the key (starts with AIza...)

Google OAuth (Optional - for Google login & Calendar)

  1. Go to Google Cloud Console
  2. Create a new project (or select existing)
  3. Configure OAuth consent screen:
    • User Type: External
    • App name: Blindly (or your name)
    • Scopes: email, profile, openid
    • For Calendar: Add https://www.googleapis.com/auth/calendar and https://www.googleapis.com/auth/calendar.events
  4. Create OAuth 2.0 Client ID:
    • Application type: Web application
    • Authorized redirect URIs: 
      http://localhost:8080/api/auth/callback/google
http://localhost:8080/api/calendar/connect
  5. Copy Client ID and Client Secret

GitHub OAuth (Optional - for GitHub login)

  1. Go to GitHub Developer Settings
  2. New OAuth App:
    • Homepage URL: http://localhost:8080
    • Callback URL: http://localhost:8080/api/auth/callback/github
  3. Copy Client ID and Client Secret

Environment Variables

Frontend: .env.local

Create .env.local in the project root:

# NextAuth Configuration (Required)
NEXTAUTH_URL=http://localhost:8080
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32

# MongoDB (Required)
MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE=blindly

# Backend URL (Required)
NEXT_PUBLIC_BACKEND_URL=http://127.0.0.1:8000
NEXT_PUBLIC_FRONTEND_URL=http://localhost:8080

# Google OAuth (Optional)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_CALENDAR_REDIRECT_URI=http://localhost:8080/api/calendar/connect

# GitHub OAuth (Optional)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Generate NEXTAUTH_SECRET:

openssl rand -base64 32

Backend: backend/.env

Create backend/.env:

# Gemini API (Required)
GEMINI_API_KEY=AIza...your-key-here

# MongoDB (Required)
MONGODB_URL=mongodb://localhost:27017
MONGODB_DATABASE=blindly

# JWT Secret (Required for auth)
JWT_SECRET_KEY=change-this-to-a-long-random-string

# Google OAuth (Optional - same as frontend)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# Frontend URL
FRONTEND_URL=http://localhost:8080

Running the Application

Using the run script (Recommended)

./run.sh

This starts both frontend (port 8080) and backend (port 8000).

Manual Start

Terminal 1 - Backend:

cd backend
source venv/bin/activate
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Terminal 2 - Frontend:

npm run dev

Verify Everything Works

  1. Frontend: http://localhost:8080
  2. Backend: http://localhost:8000 (should return {"detail":"Not Found"})
  3. Test API: curl http://localhost:8000/api/canvas/courses -H "X-User-ID: test"

Features

Daily Planning

  • Enter tasks in natural language
  • AI generates optimized schedule with time slots
  • Drag-and-drop timeline view
  • Track step-by-step progress on tasks

Google Calendar Integration

  1. Connect Google account in sidebar
  2. Calendar events automatically sync to your plan
  3. Create events from tasks
  4. Bi-directional sync

Canvas LMS Integration

  1. Enter your Canvas URL (e.g., ucsb.instructure.com)
  2. Generate API key in Canvas: Account > Settings > New Access Token
  3. View assignments due this week
  4. AI navigates to assignment pages and finds GitHub starter code links
  5. One-click to open VS Code with project setup

Welcome Back Overlay

  • Shows progress on in-progress tasks when returning to the app
  • Speedometer showing overall completion
  • Quick jump to continue where you left off

Architecture

SB-Hacks/
├── app/                    # Next.js App Router
│   ├── api/               # API routes (NextAuth, Calendar)
│   ├── page.tsx           # Main application page
│   ├── layout.tsx         # Root layout with providers
│   └── globals.css        # Global styles (Tailwind)
├── components/            # React components
│   ├── Timeline.tsx       # Schedule timeline view
│   ├── TaskItem.tsx       # Individual task card
│   ├── AuthModal.tsx      # Login/signup modal
│   └── WelcomeBackOverlay.tsx
├── lib/                   # Frontend utilities
│   ├── auth.ts           # Auth configuration
│   ├── mongodb.ts        # MongoDB client
│   └── desktop.ts        # VS Code integration
├── backend/              # FastAPI Backend
│   ├── main.py          # FastAPI app entry
│   ├── config.py        # Environment configuration
│   ├── api/
│   │   └── routes.py    # API endpoints
│   └── services/
│       ├── gemini_service.py          # Gemini AI integration
│       ├── mongodb_service.py         # MongoDB operations
│       ├── planning_service.py        # Schedule generation
│       ├── assignment_analyzer_service.py  # Canvas assignment AI
│       └── goals_service.py           # Goal planning
└── public/               # Static assets

Tech Stack

  • Frontend: Next.js 16, React 19, TypeScript, Tailwind CSS
  • Backend: FastAPI, Python 3.11, Pydantic
  • Database: MongoDB (with Motor async driver)
  • AI: Google Gemini 1.5 Flash
  • Auth: NextAuth.js with MongoDB adapter

Troubleshooting

Backend won't start

"Module not found"

cd backend
source venv/bin/activate
pip install -r requirements.txt

"GEMINI_API_KEY not found"

  • Create backend/.env with your Gemini API key
  • Verify: cat backend/.env | grep GEMINI

"Connection refused" to MongoDB

# Check if MongoDB is running
nc -z localhost 27017 && echo "MongoDB OK" || echo "MongoDB not running"

# Start with Docker
docker start mongodb || docker run -d -p 27017:27017 --name mongodb mongo:latest

Frontend issues

"Module not found"

rm -rf node_modules package-lock.json
npm install

Port already in use

# Kill processes on ports
lsof -ti:8080 | xargs kill -9  # Frontend
lsof -ti:8000 | xargs kill -9  # Backend

Canvas integration not working

  1. Verify Canvas URL format: school.instructure.com (no https://)
  2. Verify API key is valid (test in Canvas)
  3. Check backend logs for errors: tail -f the backend terminal

Google OAuth errors

"redirect_uri_mismatch"

  • Add exact redirect URIs to Google Cloud Console: 
    http://localhost:8080/api/auth/callback/google
http://localhost:8080/api/calendar/connect

"Access blocked: App not verified"

  • Add your email to test users in OAuth consent screen
  • Or publish the app for production

Development

Adding new features

  1. Backend endpoints: backend/api/routes.py
  2. Frontend pages: app/ directory
  3. Components: components/ directory
  4. Services: backend/services/

Database collections

  • users - User accounts and settings
  • plans - Daily plans with tasks
  • sessions - NextAuth sessions
  • google_tokens - OAuth tokens for Calendar

Running tests

# Backend
cd backend && python -m pytest

# Frontend
npm test

Deployment

Vercel (Frontend)

  1. Push to GitHub
  2. Import project in Vercel
  3. Set environment variables
  4. Deploy

Backend (Railway/Render/Fly.io)

  1. Create Dockerfile or use platform's Python buildpack
  2. Set environment variables
  3. Ensure MongoDB Atlas connection string

Environment for Production

# .env.local (production)
NEXTAUTH_URL=https://your-domain.com
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/blindly
NEXT_PUBLIC_BACKEND_URL=https://your-backend.com

License

MIT

Credits

Built at SB Hacks 2026

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages