DEV Community

Cover image for AcadFlow — I Built an AI Academic Operating System for My Friend Who Drowns in Deadlines Every Semester
Divyanshi Gupta
Divyanshi Gupta

Posted on

AcadFlow — I Built an AI Academic Operating System for My Friend Who Drowns in Deadlines Every Semester

#devchallenge #weekendchallenge #hf26challenge

Hacktoberfest Weekend Challenge: Build for a Friend Submission 🤝

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

My closest friend, Priya, is a third-year Computer Science student. Every semester, she drowns in the same chaos — missed assignment notifications buried in WhatsApp groups, half-remembered quiz dates, and study plans that collapse the moment a professor reschedules a lab.

She does not lack information. She has too much, scattered across five apps, three portals, and a camera roll full of screenshots.

I built AcadFlow — an AI Academic Operating System that solves exactly this problem. Instead of another generic planner or a ChatGPT wrapper that confidently invents fake deadlines, AcadFlow is a deterministic planning engine with open-source AI assistance.

What it does:

  • Academic Inbox: Paste raw WhatsApp announcements, upload syllabus PDFs, or voice-dictate assignment requirements. Open-source LLMs extract structured tasks, courses, and deadlines.
  • Zero-Hallucination Priority Engine: Every task gets a mathematically computed priority score (RED / ORANGE / YELLOW / GREEN). If a deadline is not explicitly stated, it stays null — the system never invents one.
  • Daily Planner: Generates focus blocks within a customizable study-hour budget, with cognitive breaks.
  • Adaptive Replanning (Signature Feature): When Priya reports "I only finished 45 minutes of DBMS instead of 90", AcadFlow recalculates the entire schedule — safely shifting low-priority tasks to tomorrow while preserving imminent exam revision. It explains its trade-offs in plain language.
  • Knowledge Base (RAG): Upload lecture notes and study guides. Ask questions grounded in actual indexed documents with source citations.
  • Workload Analytics: Tracks completion rates and learns that Priya consistently takes 30% longer on programming assignments, automatically adjusting future estimates.
  • Goals & Projects: Long-term milestone tracking and collaborative project management with AI blocker warnings.

Demo

Live Frontend (Vercel):

https://acadflow-devchallenge1.vercel.app

GitHub Pages (Landing Showcase):

https://divyanshigupta786.github.io/Acadflow-devchallenge1/

Try the Pre-loaded Demo Student Account:

  • Email: demo@acadflow.dev
  • Password: demo123

Pre-loaded with 5 real CS courses, 12 realistic tasks, an active daily schedule, indexed study documents, and a collaborative AI project — ready to explore immediately.

Code

GitHub logo divyanshigupta786 / Acadflow-devchallenge1

AcadFlow — AI-Powered Academic Operating System

From academic chaos to clarity.

AcadFlow is a production-quality, open-source AI academic productivity and planning platform. Designed for college and university students managing multiple courses, assignments, exams, projects, and extracurriculars, AcadFlow transforms fragmented academic information into an adaptive, personalized action plan.

1. Product Philosophy: Not Another Chatbot

Students do not have a lack of academic information; they have an academic information overload problem. Academic information is scattered across:

  • WhatsApp messages
  • Google Classroom
  • College ERP & Portals
  • Emails & PDFs
  • Screenshots & handwritten notes
  • Project chat threads

AcadFlow replaces manual planning with an academic decision and planning engine powered by open-source AI.

The Core Loop

INPUT ──► UNDERSTAND ──► PRIORITIZE ──► PLAN ──► EXECUTE ──► MONITOR ──► REPLAN

2. Signature Feature: Adaptive Replanning

When a student reports:

"I only completed 45 minutes of DBMS." or "I lost 2 hours today."

AcadFlow does not simply…

View on GitHub

Project Structure 

Acadflow-devchallenge1/
├── frontend/                 # Next.js 14 (App Router) + TypeScript + Tailwind
│   └── src/
│       ├── app/              # 17 pages: dashboard, tasks, inbox, courses, analytics...
│       ├── components/       # Sidebar, Navbar, ThemeToggle, Footer...
│       └── lib/              # api.ts, types.ts, utils.ts
├── backend/                  # Python 3.11 + FastAPI + SQLAlchemy
│   └── app/
│       ├── main.py           # Application entry point
│       ├── config.py         # Pydantic Settings + Supabase config
│       └── routers/          # Auth, tasks, courses, inbox, planner, AI endpoints
│           └── ai.py         # Ollama LLM + deterministic fallback + RAG
├── backend/tests/            # 13 test cases (pytest)
├── index.html                # Standalone self-contained landing page showcase
├── docker-compose.yml        # One-command stack: FastAPI + Next.js + PostgreSQL + Ollama
└── .github/workflows/        # CI + GitHub Pages automated deployment
Enter fullscreen mode Exit fullscreen mode

How I Built It

Open-Source AI Architecture

AcadFlow is built around a dual-intelligence architecture that decouples AI assistance from deterministic business logic:

1. Local LLM Inference via Ollama 

# backend/app/routers/ai.py
response = requests.post(
    f"{settings.OLLAMA_BASE_URL}/api/generate",
    json={
        "model": settings.OLLAMA_MODEL,  # qwen2.5:7b, llama3.2, mistral, gemma2
        "prompt": extraction_prompt,
        "stream": False,
    },
    timeout=60,
)
Enter fullscreen mode Exit fullscreen mode

Supported models: Qwen 2.5:7b, Llama 3.2, Mistral 7B, Gemma 2, plus any OpenAI-compatible local endpoint.

2. Anti-Hallucination Rules (Hardcoded) 

# The LLM is explicitly instructed:
# "If you are not 100% certain of the deadline from the text, set deadline to null."
# "Never invent, estimate, or assume deadlines."
# Inferred estimates are tagged ai_estimate=True and shown visually in the UI.
Enter fullscreen mode Exit fullscreen mode

3. Deterministic Priority Engine (Zero LLM Involvement) 

Priority Score = (Urgency + Importance + Workload + Dependency Risk + Exam Proximity)
                 ─────────────────────────────────────────────────────────────────────
                                   Completion Progress Factor

RED    >= 75  →  Imminent deadline (<24h), exam, or overdue
ORANGE 50-74  →  Due within 48h or blocking teammates
YELLOW 25-49  →  Standard runway assignments
GREEN  < 25   →  Extended deadlines or completed
Enter fullscreen mode Exit fullscreen mode

4. Adaptive Replanning Engine 

def replan(student_report: str, active_tasks: list, today_budget_minutes: int):
    # 1. Parse what was completed vs planned
    # 2. Recalculate remaining workload per task
    # 3. Identify tasks safely shiftable (low priority, distant deadline)
    # 4. Preserve imminent exam revision and high-stakes deadlines
    # 5. Return new schedule + plain-language trade-off explanation
Enter fullscreen mode Exit fullscreen mode

5. Knowledge Base RAG

  • Documents are chunked, embedded with BGE Embeddings, stored in pgvector.
  • Queries retrieve top-k chunks by cosine similarity.
  • Every AI answer includes source citations linking back to the original document.

Tech Stack

Layer Technology
Frontend Next.js 14 (App Router), TypeScript, Tailwind CSS, Lucide Icons
Backend Python 3.11, FastAPI, Pydantic v2, SQLAlchemy 2.0, Uvicorn
Database SQLite (local dev) / PostgreSQL + pgvector / Supabase
AI Inference Ollama — Qwen 2.5, Llama 3.2, Mistral, Gemma 2 + Deterministic Fallback
Embeddings & RAG BGE Embeddings + cosine similarity via pgvector
UI Design Cormorant Garamond + Poppins, cream/teal palette, dark/light theme
Containerization Docker + Docker Compose
Deployment Vercel (frontend) + GitHub Pages + GitHub Actions CI/CD
Tests Pytest — 13 test cases

Why Does Open Innovation Matter?

1. Student Privacy Cannot Be Negotiated

A proprietary closed API like GPT-4 would mean sending every student's assignment text, course names, exam schedules, and study patterns to a third-party commercial server. With Ollama, no academic data ever leaves Priya's laptop.

2. Zero Cost = Universal Access

University students do not have budgets for $20/month API subscriptions. With open-weight models (Llama, Qwen, Gemma — all free, all local), the entire system runs on a consumer laptop with 8–16GB RAM. A closed API would price out the exact students who need it most — those in emerging economies without premium subscription budgets.

3. Deterministic Reliability Over Probabilistic Drift

The most critical feature — the Priority Engine and Adaptive Replanning — uses zero AI. It runs deterministic math. This architectural decision was only possible because open-source models forced intentionality: use AI only where it adds value, hardcode everything where correctness is non-negotiable. Proprietary APIs tempt developers to "just ask GPT what priority this task should be" — leading to hallucinated urgency and fabricated deadlines. Open-source models prevented this anti-pattern.

4. Community Auditability for Academic Tools

Any tool that affects a student's study plan and exam preparation must be transparent. With open-source models and a fully open-source codebase, any student, professor, or researcher can audit exactly how AcadFlow makes its recommendations. Closed APIs are black boxes. Open innovation means accountability.

My Agent Session

This project was built with Google Antigravity (AGY) AI coding assistant. The session covered:

  • Designing the deterministic priority scoring system and anti-hallucination pipeline
  • Building the Adaptive Replanning Engine
  • Full Next.js 14 App Router frontend with 17 pages
  • Real-time dark/light theme toggle with localStorage persistence
  • Supabase + PostgreSQL backend integration
  • GitHub Actions CI/CD pipeline
  • Live Vercel deployment and debugging (including fixing a @/lib/api gitignore exclusion bug mid-deployment)

Prize Categories

  • Open Source AI — Built entirely on open-weight models (Ollama, Qwen, Llama, Gemma, BGE Embeddings). Zero proprietary closed APIs.
  • Best Use of AI — Deterministic + AI hybrid architecture solving real academic planning with zero hallucination guarantees.
  • Best Deployed Project — Live on Vercel (Next.js frontend) and GitHub Pages (showcase).
  • Student Developer — Built by a student, for a student.

Acceptance Criteria

  • [x] Register, login, and JWT session handling
  • [x] One-click seeded demo student account (demo@acadflow.dev)
  • [x] Academic Inbox (raw text, PDF upload, voice input)
  • [x] Open-source LLM extraction with zero-hallucination deterministic fallback
  • [x] Review & edit extracted items before saving
  • [x] Deterministic Priority Engine (RED / ORANGE / YELLOW / GREEN)
  • [x] Daily planner with study hour budget selector
  • [x] Signature Feature: Adaptive Replanning with plain-language trade-off explanation
  • [x] Workload estimation with personalized programming multipliers
  • [x] Course pages with strong/weak topic tracking and AI study recommendations
  • [x] Knowledge Base RAG with grounded source citations
  • [x] Project Mode with team roles and AI blocker warnings
  • [x] Long-term Goals with milestone checklists
  • [x] Workload Analytics with completion rates and insights
  • [x] Smart contextual notifications
  • [x] Docker Compose ready (PostgreSQL + pgvector + Ollama)
  • [x] 13 automated test cases (pytest)
  • [x] Light/Dark theme toggle with localStorage persistence
  • [x] Deployed live on Vercel and GitHub Pages

Built with love for every student who has ever missed a deadline they were certain they remembered.

Top comments (0)