Hackathon Theme A · Version 2.0 · February 2026
Built in 20 hours by Team 16 — Caffeine Crashers 🚀
| Name | GitHub |
|---|---|
| Yug Dalwadi | @YugDalwadi |
| Jimeet Shastri | @JIMEET2440 |
| Tanisha Ray | @coderTanisha22 |
| Jainam Shah | @jainam-not-a-robot |
- FocusForge
- Attention Economy on Campus — Android App
- 👥 Team — Caffeine Crashers (Team #16)
- 📌 Table of Contents
- 🎯 Problem Statement
- 💡 Solution Overview
- ✨ Features
- 🛠 Tech Stack
- 🏗 Architecture
- 🚀 Getting Started
- 📡 API Documentation
⚠️ Risk Register- 📁 Project Structure
- 🤝 Contributing
- � Environment Variables
- �📄 License
College isn't short on time — it's short on attention. Between notifications, reels, assignments, clubs, and social pressure, students constantly feel busy yet distracted. Most people struggle to focus, prioritize, or use their time intentionally.
Theme A challenges teams to build something that helps students:
- Take control of their time
- Reduce mental clutter and stress
- Make better decisions about where their focus goes
FocusForge is an Android application tackling the campus attention economy through four tightly integrated features:
| # | Feature | What it does |
|---|---|---|
| 1 | Suggestion Dashboard | Mode-aware AI feed (Acads / Clubs) showing what to focus on right now, backed by career goals, workload heatmap, and LLM-personalised motivational quotes |
| 2 | Dynamic Unified Calendar | Merges weekly timetable, institute academic calendar, Google Classroom deadlines, and Gmail-parsed club emails into one source of truth |
| 3 | App Usage Tracker & Peer Benchmarking | Reads Android screen-time data, computes a rolling institute average, and fires nudge notifications if productive usage drops below the 50th percentile |
| 4 | Group Pomodoro Sessions | Gamified collaborative focus sessions with real-time sync, peer accountability nudges, XP rewards, leaderboards, and voluntary self-pause |
- Dual Focus Mode Toggle — Switch between
Acads ModeandClubs & Projects Modeat any time - LLM-Ranked Action Items — Backend assembles context (deadlines, workload, career goals) and sends to Gemini Flash for a ranked JSON suggestion list
- Focus Heatmap — GitHub-style 90-day grid, colour-coded by mode (🟢 Acads / 🔵 Clubs)
- Motivational Quote — LLM-generated on every app open, personalised to career goals and current workload
- Workload Indicator — Computed as
deadline_density × urgency, displayed as a load meter
- Manual Weekly Timetable — Entered once, recurs every week automatically
- Google Classroom Sync — Assignment due dates auto-pulled via Classroom API v1
- Gmail Club Activity Parsing — Last 100 emails filtered by club senders → LLM extracts
{event_name, date, time, location, type}→ Pydantic-validated → upserted to DB - Admin Event Panel (Fallback) — Club secretaries post events manually when Gmail API is unavailable; admin approval before events appear on student calendars
- Institute Calendar CSV Upload — Admin uploads yearly holidays/fests; read-only for students
- Android
UsageStatsManagerintegration via Dart platform channel - App usage categorised as
Productive / Neutral / Distractionvia a DB config table (never hardcoded) - 7-day rolling average per category shown against anonymized institute average
- 50th percentile nudge — push notification fires when productive usage drops below peer median
- All cross-user comparisons use hashed user IDs — raw package names never shared
- Create/join sessions using a shareable 8-character invite code (2–8 members)
- Configurable 25 min focus / 5 min break (or custom)
- Real-time WebSocket sync — all members see the same timer state
- Voluntary Pause — local pause is invisible to peers; server detects via missing heartbeat acks
- XP Rewards — awarded only for server-verified completions (exploit-proof)
- Weekly Leaderboard per group
- Accountability Nudge — private push notification if focus time < group session median
- Badges — 7-day streak, 30-day streak, top-focus-member
| Layer | Technology | Rationale |
|---|---|---|
| Frontend | Flutter (Dart) | Material 3, Android platform channels, single codebase |
| Backend | FastAPI + Uvicorn (Python) | Async-first, native AI/LLM libs, auto OpenAPI docs |
| Database | PostgreSQL 16 + asyncpg | JSONB for usage logs, relational model for scheduling & gamification |
| Auth | Google OAuth 2.0 + JWT (python-jose) | Required for Classroom & Gmail API scopes; campus SSO |
| Realtime | WebSockets (websockets + web_socket_channel) |
Group Pomodoro timer sync across devices in real time |
| LLM | Gemini Flash (google-generativeai) |
Gmail parsing, suggestion scoring, motivational quotes |
| Google APIs | Classroom API v1 + Gmail API v1 | Assignment deadlines & club activity extraction |
| State Management | Flutter StatefulWidget / setState | Built-in Flutter state; no extra state-management library |
| ORM | SQLAlchemy (async) + Alembic | Type-safe queries and versioned DB migrations |
| Local Storage | shared_preferences + flutter_secure_storage |
Persistent prefs and encrypted token storage on device |
| HTTP Client | http (Flutter) · httpx (Backend) |
API calls from app; async backend-to-backend requests |
┌─────────────────────────────────────────────────────────────┐
│ Flutter Android App │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ │
│ │Dashboard │ │Calendar │ │ Usage │ │Pomodoro │ │
│ │(setState)│ │(http API)│ │ Tracker │ │(WebSocket│ │
│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ └────┬─────┘ │
└───────┼──────────────┼──────────────┼───────────────┼────────┘
│ HTTPS/REST │ │ │ WS
┌───────▼──────────────▼──────────────▼───────────────▼────────┐
│ FastAPI Backend │
│ /auth /suggestions /calendar /usage /ws/pomodoro │
│ │
│ ┌────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
│ │ LLM Service │ │ Google APIs │ │ WS Session Mgr│ │
│ │ (Gemini Flash) │ │ (Classroom + │ │ (timer ticks) │ │
│ └────────────────┘ │ Gmail) │ └───────────────┘ │
│ └─────────────────┘ │
└──────────────────────────┬────────────────────────────────────┘
│
┌─────────▼──────────┐
│ PostgreSQL 16 │
│ (asyncpg pool) │
└────────────────────┘
- Flutter SDK ≥ 3.x (latest stable)
- Python 3.11+
- PostgreSQL 16 running locally (or any accessible instance)
- A Google Cloud Project with Classroom API, Gmail API, and OAuth 2.0 enabled
- A Gemini API Key
# 1. Clone the repository
git clone https://github.com/caffeine-crashers/focusforge.git
cd focusforge/backend
# 2. Copy and fill in environment variables
cp .env.example .env
# → Edit .env with your Google Client ID/Secret and Gemini API key
# 3. Ensure PostgreSQL 16 is running and create the database
psql -U postgres -c "CREATE DATABASE focusforge;"
# 4. Set up Python environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# 5. Start the server (tables are auto-created on first run)
uvicorn app.main:app --reload --port 8000Interactive API docs: http://localhost:8000/docs
cd focusforge/flutter-frontend/Focusforge
# Install Flutter dependencies
flutter pub get
# Run on a connected Android device / emulator
flutter run
# Build release APK
flutter build apk --release
⚠️ Android Permission: On first launch, the app redirects to Settings forUsageStatsManageraccess. This is required for the App Usage Tracker. All other features work without it.
| Method | Endpoint | Description |
|---|---|---|
POST |
/auth/google |
Verify Google ID token — returns JWT |
POST |
/auth/dev-login |
Dev-only login (no OAuth) |
GET |
/auth/me |
Get current authenticated user |
GET |
/suggestions/{user_id}?mode=acads|clubs |
LLM-ranked suggestion list + quote |
GET |
/focus-log/{user_id}/heatmap |
90-day heatmap data |
GET |
/user/{user_id}/goals |
Get career goals |
PUT |
/user/{user_id}/goals |
Replace career goals |
GET |
/calendar/{user_id} |
Unified calendar events |
GET |
/timetable/{user_id} |
Get weekly timetable slots |
POST |
/timetable |
Add timetable slot |
DELETE |
/timetable/{slot_id} |
Remove timetable slot |
POST |
/calendar/sync/classroom |
Trigger Google Classroom sync |
POST |
/calendar/sync/gmail |
Trigger Gmail club email parse |
POST |
/admin/institute-calendar |
Upload institute CSV |
POST|GET|PATCH|DELETE |
/admin/events |
Admin event panel (fallback) |
POST |
/usage |
Submit batch usage snapshots |
GET |
/usage/{user_id}/rolling-average |
7-day averages + percentile rank |
GET |
/usage/{user_id}/should-nudge |
Check if nudge notification needed |
GET |
/usage/categories |
App category mappings |
POST |
/pomodoro/sessions |
Create Pomodoro session |
POST |
/pomodoro/sessions/join |
Join session with invite code |
GET |
/pomodoro/sessions/{session_id} |
Get session details |
WS |
/ws/pomodoro/{session_id} |
Real-time timer WebSocket |
GET |
/pomodoro/sessions/{session_id}/leaderboard |
Weekly XP leaderboard |
GET |
/pomodoro/badges/{user_id} |
User badges |
| Risk | Severity | Mitigation |
|---|---|---|
UsageStats permission denied |
🔴 High | Feature 3 fully opt-in; app works with Features 1, 2, and 4 |
| LLM returns malformed JSON | 🔴 High | Pydantic validation discards bad output; user prompted to add manually; retry with stricter prompt |
| Classroom OAuth scope not pre-approved for demo | 🔴 High | Test consent screen early; seed demo DB with assignment data as fallback |
| Gmail API unavailable or scope rejected | 🔴 High | Admin Event Panel lets club coordinators post events directly |
| WebSocket instability during demo | 🔴 High | Auto-reconnect implemented; can fall back to REST polling |
| LLM rate limits / cost overrun | 🟡 Medium | Per-user daily caps; 1h suggestion cache; pre-generate demo quotes offline |
| Pomodoro XP farming exploit | 🟡 Medium | XP awarded only for server-verified completions; client cannot self-report |
| PostgreSQL slow under concurrent usage snapshots | 🟡 Medium | asyncpg + batch inserts every 30 min; composite index on (user_id, date) |
INSOMNIAC/
├── backend/
│ ├── .env.example
│ ├── requirements.txt
│ └── app/
│ ├── main.py # FastAPI app entry point + lifespan
│ ├── config.py # Pydantic settings from .env
│ ├── database.py # Async SQLAlchemy engine + session
│ ├── logging_config.py # Logging setup
│ ├── models/
│ │ ├── user.py
│ │ ├── career_goal.py
│ │ ├── calendar.py # CalendarEvent, TimetableSlot
│ │ ├── usage.py # AppUsageLog, AppCategoryMapping
│ │ ├── focus_log.py
│ │ ├── pomodoro.py # PomodoroSession, SessionMember, UserXP, Badge
│ │ └── suggestion.py
│ ├── schemas/ # Pydantic request/response schemas
│ │ ├── user.py
│ │ ├── career_goal.py
│ │ ├── calendar.py
│ │ ├── usage.py
│ │ ├── pomodoro.py
│ │ └── suggestion.py
│ ├── routers/
│ │ ├── auth.py # Google ID token verify + JWT
│ │ ├── suggestions.py # Dashboard, LLM scoring, heatmap, goals
│ │ ├── calendar.py # Unified calendar, Classroom/Gmail sync, admin
│ │ ├── usage.py # App usage tracker + benchmarking
│ │ └── pomodoro.py # Group Pomodoro + WebSocket
│ └── services/
│ ├── auth.py # JWT create/decode helpers
│ ├── llm.py # Gemini Flash wrapper
│ ├── classroom_sync.py # Google Classroom API integration
│ ├── gmail_parser.py # Gmail club email LLM parsing
│ ├── suggestion_engine.py # LLM suggestion scoring
│ └── ws_manager.py # WebSocket session manager
│
└── flutter-frontend/Focusforge/ # Flutter Android app
├── pubspec.yaml
└── lib/
├── main.dart # App entry, MaterialApp, routes
├── login.dart # Google Sign-In screen
├── DashBoard.dart # Suggestion Dashboard + heatmap
├── classroomSection.dart # Unified Calendar view
├── UsageScreen.dart # App Usage Tracker screen
├── PomodoroScreen.dart # Group Pomodoro screen
├── SettingsScreen.dart # Settings screen
├── config/
│ └── app_config.dart # Base URL + endpoint constants
├── services/
│ ├── auth_service.dart
│ ├── classroom_service.dart
│ ├── pomodoro_service.dart
│ ├── usage_service.dart
│ └── usage_stats_platform_service.dart # Android MethodChannel (UsageStats)
└── widgets/
└── typewriter_text.dart
This project was built during a 20-hour hackathon. PRs and issues are welcome!
- Fork the repo
- Create your feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'feat: add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Create a .env file in the backend/ directory:
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/callback
# JWT
JWT_SECRET_KEY=your_random_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440
# Database
DATABASE_URL=postgresql+asyncpg://focusforge:focusforge@localhost:5432/focusforge
# LLM
GEMINI_API_KEY=your_gemini_api_key
# App
APP_ENV=developmentThis project is licensed under the MIT License — see the LICENSE file for details.
Made with ☕ and zero sleep by Team Caffeine Crashers · DevlUps Hackathon 2026