DeltaAI

AI-powered, agentic habit coach for college students
Meal planning, budget intelligence, productivity coaching, and cross-domain reasoning in one full-stack app.

Overview

DeltaAI is a full-stack platform built for Indian college students to help them manage everyday decisions across three connected domains:

• Eat Smart: AI meal planning within a daily INR budget, personalized to diet, fitness goals, and calorie needs
• Spend Smart: expense tracking, budget analysis, recurring spend detection, and spending alerts
• Do Smart: task management, AI-based prioritization, streak tracking, and Pomodoro logging

What makes the project different is the agentic layer: the assistant does not only answer chat prompts. It builds context from meals, habits, expenses, profile, and tasks, then produces proactive suggestions such as:

• flagging overspending before the month ends
• warning that a streak is at risk
• suggesting cheaper meals when the budget is tight
• surfacing overdue academic work with urgency-aware recommendations

Table Of Contents

• Features
• Architecture
• Tech Stack
• Repository Structure
• Getting Started
• Environment Variables
• API Overview
• AI System
• Seed Data
• Deployment
• Documentation
• Notes

Features

Student-Centric Domains

• Eat Smart: generates budget-aware Indian meal plans with calorie and protein estimates
• Spend Smart: tracks spending by category, shows summaries, budget alerts, semester planning, and recurring subscription detection
• Do Smart: manages tasks, deadlines, urgency scoring, and focus-session metrics

Agentic AI Workflows

• Autonomous morning briefings
• Cross-domain chat assistant with context from profile, meals, expenses, habits, and tasks
• Expense analysis and weekly performance reports
• AI-assisted task prioritization and onboarding baseline generation

Full-Stack Product Features

• JWT-based auth with bcrypt password hashing
• Password reset with OTP flow
• Onboarding flow that generates initial habits and a first meal plan
• Dashboard aggregation endpoint for efficient frontend loading
• Calendar support for academic events and study recommendations

Architecture

flowchart LR
    U[User] --> FE[Next.js Frontend]
    FE -->|/api/* rewrite| BE[FastAPI Backend]
    BE --> DB[(MongoDB Atlas)]
    BE --> AG[DeltaAgent]
    AG --> GW[AI Gateway]
    GW --> AN[Anthropic API]
    GW --> OR[OpenRouter API]

Loading

Request Flow

1. The frontend calls /api/* through Next.js rewrites.
2. FastAPI authenticates the request using JWT.
3. Routers access MongoDB collections directly for CRUD and analytics.
4. AI-powered endpoints call DeltaAgent, which builds a context snapshot from multiple domains.
5. The AI gateway chooses Anthropic or OpenRouter based on available API keys.

Tech Stack

Layer	Technologies
Frontend	Next.js 14, React 18, TypeScript, Tailwind CSS, Framer Motion, Recharts
Backend	FastAPI, Python 3.13+, pymongo, httpx, pydantic-settings, slowapi, cachetools
Database	MongoDB Atlas
AI	Anthropic Claude and OpenRouter fallback chain
Auth	JWT (HS256), bcrypt
Tooling	uv, npm
Deployment	Vercel (frontend), Railway (backend)

Repository Structure

project_delta/
├── backend/
│   ├── app/
│   │   ├── agent/          # Agent engine, AI gateway, prompts
│   │   ├── models/         # Pydantic request/response schemas
│   │   ├── routers/        # FastAPI route modules by domain
│   │   ├── auth.py         # JWT and password utilities
│   │   ├── cache.py        # In-memory TTL caching helpers
│   │   ├── config.py       # Settings and env loading
│   │   ├── database.py     # MongoDB connection and indexes
│   │   ├── dependencies.py # Shared app dependencies
│   │   └── main.py         # FastAPI app entrypoint
│   ├── run.py              # Local backend runner
│   ├── seed.py             # Demo data seeding script
│   └── Procfile
├── frontend/
│   ├── app/                # Next.js App Router pages/layouts
│   ├── components/         # Reusable UI components
│   ├── hooks/              # Client hooks
│   └── lib/                # Auth context and API client
├── .env.example
├── CODE_WIKI.md
├── pyproject.toml
└── railway.json

Getting Started

Prerequisites

• Python 3.13+
• uv
• Node.js 18+
• npm
• MongoDB Atlas connection string
• At least one AI provider key:
  • OPENROUTER_API_KEY for local testing
  • ANTHROPIC_API_KEY for production-oriented setup

1. Clone The Repository

git clone https://github.com/D9292S/project_delta.git
cd project_delta

2. Configure Backend Environment

cp .env.example .env

Edit .env and provide your values:

MONGODB_URI=your-mongodb-uri
JWT_SECRET=your-random-secret
OPENROUTER_API_KEY=sk-or-v1-your-key-here
ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=claude-sonnet-4-20250514
AI_MODEL=google/gemma-4-31b-it:free
DB_NAME=deltaai
CORS_ORIGINS=http://localhost:3000

3. Install Python Dependencies

uv sync

4. Run The Backend

cd backend
uv run run.py

Backend URLs:

• API: http://localhost:8000
• Swagger docs: http://localhost:8000/docs

5. Configure Frontend Environment

Create frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000

6. Install Frontend Dependencies And Run

cd frontend
npm install
npm run dev

Frontend URL:

• App: http://localhost:3000

Environment Variables

Backend .env

Variable	Required	Purpose
MONGODB_URI	Yes	MongoDB Atlas connection string
JWT_SECRET	Yes	JWT signing secret
DB_NAME	No	Database name, default deltaai
CORS_ORIGINS	No	Comma-separated allowed origins
OPENROUTER_API_KEY	Recommended for local	OpenRouter API access
AI_MODEL	No	Preferred OpenRouter model
ANTHROPIC_API_KEY	Recommended for production	Anthropic API access
ANTHROPIC_MODEL	No	Anthropic model name

Provider Selection

The backend auto-selects the AI provider based on which keys are configured:

ANTHROPIC_API_KEY	OPENROUTER_API_KEY	Provider Behavior
empty	set	OpenRouter only
set	empty	Anthropic only
set	set	Anthropic primary, OpenRouter fallback

Frontend frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:8000

API Overview

Authentication

• POST /api/auth/signup
• POST /api/auth/login
• GET /api/auth/me
• POST /api/auth/forgot-password
• POST /api/auth/reset-password

Profile And Onboarding

• POST /api/onboarding
• GET /api/profile
• PUT /api/profile

Chat And AI

• POST /api/chat
• GET /api/chat/history
• DELETE /api/chat/history
• GET /api/chat/briefing
• GET /api/chat/analyze-expenses
• GET /api/chat/weekly-report

Habits

• GET /api/habits
• POST /api/habits
• PATCH /api/habits/{id}/toggle
• DELETE /api/habits/{id}
• GET /api/habits/stats

Meals

• POST /api/meals/generate
• GET /api/meals/today
• GET /api/meals/history
• GET /api/meals/analytics
• DELETE /api/meals/{id}

Expenses

• GET /api/expenses
• POST /api/expenses
• DELETE /api/expenses/{id}
• GET /api/expenses/summary
• GET /api/expenses/alerts
• GET /api/expenses/subscriptions
• GET /api/expenses/semester-plan

Tasks

• GET /api/tasks
• POST /api/tasks
• PATCH /api/tasks/{id}/toggle
• DELETE /api/tasks/{id}
• POST /api/tasks/prioritize
• POST /api/tasks/pomodoro
• GET /api/tasks/pomodoro/stats

Dashboard, Health, Calendar

• GET /api/dashboard
• GET /api/dashboard/full
• GET /api/dashboard/briefing
• GET /api/dashboard/nudges
• GET /api/dashboard/weekly-report
• GET /api/dashboard/export
• GET /api/delta-score
• GET /api/calendar
• POST /api/calendar
• GET /api/calendar/upcoming
• DELETE /api/calendar/{id}
• GET /api/health
• GET /api/status

AI System

DeltaAI uses a ReAct-style agentic pattern:

1. Build context from profile, habits, meals, expenses, tasks, and health indicators
2. Detect issues such as overspending, overdue tasks, missing meal plans, or streak risk
3. Reason across domains, for example budget pressure influencing meal recommendations
4. Respond with concrete actions, priorities, and explanations

Core AI modules:

• backend/app/agent/engine.py: DeltaAgent core workflows
• backend/app/agent/openrouter.py: provider routing and fallback behavior
• backend/app/agent/prompts.py: prompt templates

Seed Data

Optional seeding script:

cd backend
uv run seed.py

The demo seed includes:

• habits with streak history
• recent meal plans
• categorized expenses
• tasks with different urgency levels
• sample chat history

Deployment

Backend

• Designed for Railway
• Configured through railway.json
• Start command runs uvicorn app.main:app

Frontend

• Designed for Vercel
• Set NEXT_PUBLIC_API_URL to the deployed backend origin
• Next.js rewrites proxy /api/* to the backend

Documentation

• Developer-facing code documentation: CODE_WIKI.md
• Root backend app entry: backend/app/main.py
• Frontend API client: frontend/lib/api.ts

Notes

• Currency is modeled in INR
• Default monthly budget fallback is ₹8,000
• Default daily meal budget logic uses roughly 40% of monthly budget spread across the month
• College is auto-detected from email domain when possible
• Auth endpoints are rate-limited
• JWT tokens expire after 30 days