DeltaAI — AI-Powered Agentic Habit Coach for College Students

DeltaAI is a full-stack AI habit coaching platform built for Indian college students. It uses a ReAct-style agentic AI system that autonomously reasons across three life domains:

• 🍽️ Eat Smart — AI-generated Indian meal plans within a daily INR budget, personalized to diet, health goals, and BMR
• 💰 Spend Smart — Expense logging, budget tracking, spending pattern analysis, and savings nudges
• ✅ Do Smart — AI-prioritized task management with deadline awareness and urgency scoring

The AI coach doesn't just respond to questions — it proactively detects issues across domains (budget overruns, missed meals, streak breaks, overdue tasks) and provides cross-domain intelligence (e.g., "you have an exam tomorrow, eat light and cheap").

---

Tech Stack

Layer	Technology
Backend	FastAPI, Python 3.13+, pymongo, httpx, pydantic-settings, uv
Frontend	Next.js 14 (App Router), TypeScript, TailwindCSS, Recharts, Framer Motion
Database	MongoDB Atlas
AI	Dual-provider: Anthropic Claude (production) + OpenRouter (free testing)
Auth	JWT (HS256, 30-day expiry), bcrypt password hashing
Deploy	Vercel (frontend) + Railway (backend)

---

Project Structure

project_delta/
├── backend/
│   ├── app/
│   │   ├── agent/
│   │   │   ├── engine.py       # ReAct agentic engine (cross-domain reasoning)
│   │   │   ├── openrouter.py   # Dual AI gateway (Anthropic + OpenRouter)
│   │   │   └── prompts.py      # System prompts and templates
│   │   ├── routers/
│   │   │   ├── auth.py         # Signup, login, password reset (OTP)
│   │   │   ├── onboarding.py   # Profile creation + AI baseline generation
│   │   │   ├── chat.py         # Agentic chat, briefings, weekly reports
│   │   │   ├── habits.py       # CRUD + streak tracking + stats
│   │   │   ├── meals.py        # AI meal generation + history
│   │   │   ├── expenses.py     # CRUD + summary aggregation
│   │   │   ├── tasks.py        # CRUD + AI priority scoring
│   │   │   ├── dashboard.py    # Consolidated snapshot for all widgets
│   │   │   ├── calendar.py     # Calendar data aggregation
│   │   │   └── health.py       # Health metrics endpoint
│   │   ├── models/             # Pydantic models (habit, meal, task, expense, profile)
│   │   ├── auth.py             # JWT utilities (hash, verify, create, decode)
│   │   ├── config.py           # Settings with dual-provider auto-detection
│   │   ├── database.py         # MongoDB async connection
│   │   ├── colleges.py         # Indian college email domain detection
│   │   └── main.py             # FastAPI app with CORS, rate limiting, lifespan
│   ├── seed.py                 # Demo data generator
│   ├── run.py                  # Dev server entry point (uvicorn + hot reload)
│   └── requirements.txt
├── frontend/
│   ├── app/
│   │   ├── (app)/              # Authenticated pages
│   │   │   ├── dashboard/      # Main dashboard with all widgets
│   │   │   ├── chat/           # AI coach chat interface
│   │   │   ├── habits/         # Habit tracker with streaks
│   │   │   ├── meals/          # Meal planner
│   │   │   ├── expenses/       # Expense tracker + charts
│   │   │   ├── tasks/          # Task manager
│   │   │   ├── calendar/       # Calendar view
│   │   │   ├── reports/        # Weekly AI reports
│   │   │   ├── settings/       # User settings
│   │   │   └── onboarding/     # New user onboarding flow
│   │   ├── signin/             # Login page
│   │   ├── forgot-password/    # Password recovery
│   │   └── page.tsx            # Landing page
│   ├── components/             # Reusable UI components
│   └── lib/                    # API client helpers
├── .env.example                # Environment template
├── pyproject.toml              # Python project config (uv)
└── railway.json                # Railway deployment config

---

Setup & Run

Prerequisites

• Python 3.13+ with uv
• Node.js 18+
• MongoDB Atlas account (free tier works)

1. Backend

# Clone the project
cd project_delta

# Install Python dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI and API keys (see Environment Variables below)

# Start backend (with hot reload)
cd backend
uv run run.py
# Backend runs at http://localhost:8000
# Swagger docs at http://localhost:8000/docs

2. Frontend

# In a new terminal
cd project_delta/frontend
npm install
npm run dev
# Frontend runs at http://localhost:3000

3. Seed Demo Data (Optional)

cd project_delta/backend
uv run seed.py
# Populates habits, meals, expenses, tasks, and chat history

---

Environment Variables

Backend .env

Variable	Required	Description
MONGODB_URI	✅	MongoDB Atlas connection string
JWT_SECRET	✅	Secret key for JWT token signing
OPENROUTER_API_KEY	For testing	OpenRouter API key (sk-or-...) for free model access
ANTHROPIC_API_KEY	For production	Anthropic API key (sk-ant-...) for direct Claude access
ANTHROPIC_MODEL	Optional	Claude model to use (default: claude-sonnet-4-20250514)
AI_MODEL	Optional	OpenRouter model (default: google/gemma-4-31b-it:free)
DB_NAME	Optional	Database name (default: deltaai)
CORS_ORIGINS	Optional	Allowed origins (default: http://localhost:3000)

AI Provider Auto-Detection

The backend automatically selects the AI provider based on which API key is configured:

ANTHROPIC_API_KEY	OPENROUTER_API_KEY	Provider Used
❌ Empty	✅ Set	OpenRouter — free models with smart fallback chain
✅ Set	❌ Empty	Anthropic — direct Claude API
✅ Set	✅ Set	Anthropic primary, OpenRouter fallback on failure

For local testing, leave ANTHROPIC_API_KEY empty and use a free OpenRouter key. For production, set ANTHROPIC_API_KEY with your Claude key.

Frontend .env.local

NEXT_PUBLIC_API_URL=http://localhost:8000

---

API Endpoints

Auth

Method	Endpoint	Description
POST	/api/auth/signup	Create account (auto-detects college from email)
POST	/api/auth/login	Login with email/password
GET	/api/auth/me	Get current user
POST	/api/auth/forgot-password	Request password reset OTP
POST	/api/auth/reset-password	Reset password with OTP

Onboarding & Profile

Method	Endpoint	Description
POST	/api/onboarding	Complete onboarding + generates AI baseline (habits + first meal plan)
GET	/api/profile	Get user profile
PUT	/api/profile	Update profile

AI Chat (Agentic)

Method	Endpoint	Description
POST	/api/chat	Cross-domain agentic chat with full context awareness
GET	/api/chat/history	Retrieve conversation history
DELETE	/api/chat/history	Clear conversation history
GET	/api/chat/briefing	Autonomous morning briefing (no prompt needed)
GET	/api/chat/analyze-expenses	Autonomous spending pattern analysis
GET	/api/chat/weekly-report	Comprehensive weekly performance report

Habits

Method	Endpoint	Description
GET	/api/habits	List all habits with streaks
POST	/api/habits	Create a new habit
PUT	/api/habits/{id}/toggle	Toggle habit completion
DELETE	/api/habits/{id}	Delete a habit
GET	/api/habits/stats	Aggregate habit statistics

Meals

Method	Endpoint	Description
POST	/api/meals/generate	AI-generate a meal plan for a given date and budget
GET	/api/meals/today	Get today's meal plan
GET	/api/meals/history	Meal plan history
DELETE	/api/meals/{id}	Delete a meal plan

Expenses

Method	Endpoint	Description
GET	/api/expenses	List expenses
POST	/api/expenses	Add an expense
DELETE	/api/expenses/{id}	Delete an expense
GET	/api/expenses/summary	Monthly summary with category breakdown

Tasks

Method	Endpoint	Description
GET	/api/tasks	List tasks
POST	/api/tasks	Create a task (auto AI priority scoring)
PUT	/api/tasks/{id}/toggle	Toggle task completion
DELETE	/api/tasks/{id}	Delete a task
POST	/api/tasks/prioritize	AI re-prioritize all pending tasks

Dashboard & Other

Method	Endpoint	Description
GET	/api/dashboard	Consolidated data snapshot for UI widgets
GET	/api/calendar	Calendar data aggregation
GET	/api/health	Health metrics
GET	/api/status	API health check

---

Agentic AI Architecture

DeltaAI uses a ReAct-style (Reason → Act → Observe) agentic loop:

User Message
     ↓
┌─────────────────────────────────────────┐
│  1. BUILD CONTEXT                       │
│  Fetch all user data: profile, habits,  │
│  meals, expenses, tasks, streaks, BMI   │
├─────────────────────────────────────────┤
│  2. AUTO-DETECT ISSUES                  │
│  Budget overruns, broken streaks,       │
│  overdue tasks, missed meals, health    │
├─────────────────────────────────────────┤
│  3. CROSS-DOMAIN REASONING             │
│  Exam tomorrow → suggest light meals    │
│  Budget tight → cheaper meal plans      │
│  Streak at risk → motivational nudge    │
├─────────────────────────────────────────┤
│  4. RESPOND WITH ACTIONS                │
│  Specific, data-driven, actionable      │
│  advice with ₹ amounts and time est.    │
└─────────────────────────────────────────┘

---

Seed Data

backend/seed.py populates the database with realistic demo data:

• 5 habits with 14-day streak histories (Water 💧 14d, Expenses 💰 9d, Exercise 🏃 7d, Reading 📚 5d, No Junk 🥗 3d)
• 3 meal plans for the last 3 days with Indian food items
• 15 expenses across 2 weeks (food, transport, study, entertainment, shopping)
• 6 tasks with varied urgency (DSA assignment, physics midterm, lab report, etc.)
• 8 chat messages simulating a coach-student conversation

---

Deployment

Backend (Railway)

• Configured via railway.json (Nixpacks builder)
• Set all env vars in Railway dashboard
• Set ANTHROPIC_API_KEY for production Claude access

Frontend (Vercel)

• Set NEXT_PUBLIC_API_URL to your Railway backend URL
• API calls are proxied via Next.js rewrites

---

Notes

• All monetary values are in Indian Rupees (₹ / INR)
• Default daily meal budget: ₹250 (40% of monthly budget / 30 days)
• Default monthly budget: ₹8,000
• College is auto-detected from email domain during signup
• Rate limiting is applied to auth endpoints (3 signups/min, 5 logins/min)
• JWT tokens expire after 30 days