PrepFlow — From Study Material to an Actual Study Plan

Piyush — Mon, 05 Oct 2026 06:42:03 +0000

What if AI didn't just explain your notes, but actually figured out what you should study next?

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

I built PrepFlow because students don't usually have a shortage of study material.

They have the opposite problem.

Too much of it.

PDFs. Notes. Syllabi. Previous-year questions. Multiple subjects. Weak topics. Different confidence levels. And a deadline that keeps getting closer.

The difficult question isn't:

“What does this PDF say?”

It's:

“Given everything I need to learn, how should I spend the limited time I have left?”

That's the problem PrepFlow tries to solve.

🧠 The Idea

PrepFlow takes this:

                    BEFORE PREPFLOW

       ┌─────────┐   ┌─────────┐   ┌─────────┐
       │  PDFs   │   │  Notes  │   │  Syllabus│
       └────┬────┘   └────┬────┘   └────┬────┘
            │             │             │
            └─────────────┼─────────────┘
                          │
                          ▼
                  ┌───────────────┐
                  │     STUDENT   │
                  │               │
                  │ "What do I    │
                  │ study today?" │
                  └───────────────┘

and turns it into:

                     WITH PREPFLOW

 PDF / TEXT
     │
     ▼
┌──────────────┐
│   EXTRACT    │
│ page-aware   │
│ text         │
└──────┬───────┘
       ▼
┌──────────────┐
│    CHUNK     │
│ deterministic│
│ boundaries   │
└──────┬───────┘
       ▼
┌──────────────┐
│    GEMMA     │
│ understand   │
│ material     │
└──────┬───────┘
       ▼
┌──────────────┐
│   VERIFY     │
│ evidence +   │
│ structured   │
│ output       │
└──────┬───────┘
       ▼
┌──────────────┐
│   PRIORITIZE │
│ importance   │
│ weakness     │
│ urgency      │
│ difficulty   │
└──────┬───────┘
       ▼
┌──────────────┐
│    PLAN      │
│ capacity +   │
│ prerequisites│
│ revision     │
└──────┬───────┘
       ▼
┌──────────────────────────┐
│ TODAY                    │
│                          │
│ 1. Dynamic Programming  │
│ 2. Graph Traversal      │
│ 3. Revise Greedy        │
│                          │
│ 145 / 160 min planned   │
└──────────────────────────┘

The important part is that AI doesn't generate the final timetable.

That distinction shaped almost the entire architecture.

🎯 The Core Principle

I split the system into two responsibilities:

AI should do	Software should do
Understand unstructured material	Calculate available time
Identify topics	Calculate priority
Identify subtopics	Enforce capacity
Suggest prerequisites	Validate evidence
Estimate semantic difficulty	Persist state
Connect topics to source evidence	Schedule tasks
Interpret weak-topic hints	Schedule revision
Produce structured analysis	Handle progress
	Recover missed work

Why?

Because I don't want an LLM deciding whether:

“You have 120 minutes available, so I'll give you 157 minutes of work.”

That's not intelligence.

That's a bug.

So PrepFlow follows a simple rule:

AI interprets. Deterministic software decides.

🔄 The Full PrepFlow Pipeline

The repository currently implements the complete path from material ingestion through planning, daily execution, revision, and progress.

┌─────────────────────┐
│  STUDY SETUP        │
│                     │
│ Exam date           │
│ Hours/day            │
│ Study days           │
│ Weak topics          │
│ Confidence           │
│ Buffer               │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ MATERIAL INGESTION   │
│                     │
│ PDF / pasted text   │
│ Page preservation   │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ DETERMINISTIC       │
│ CHUNKING             │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ GEMMA               │
│                     │
│ Topics              │
│ Subtopics           │
│ Difficulty          │
│ Importance          │
│ Prerequisites       │
│ Evidence            │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ VALIDATION          │
│                     │
│ JSON → Zod          │
│ Evidence matching   │
│ Page derivation     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ KNOWLEDGE MODEL     │
│                     │
│ Subjects            │
│ Topics              │
│ Prerequisites       │
│ Evidence            │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ PRIORITY ENGINE     │
│                     │
│ Importance          │
│ Weakness            │
│ Foundation          │
│ Difficulty          │
│ Urgency             │
│ Emphasis            │
│ Evidence            │
│ Revision            │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ CAPACITY ENGINE     │
│                     │
│ Available minutes   │
│ Buffer              │
│ Revision reserve    │
│ Exam deadline       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ PLANNER             │
│                     │
│ MUST                │
│ SHOULD              │
│ IF TIME             │
│ DEFER               │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ DAILY EXECUTION     │
│                     │
│ Start               │
│ Complete            │
│ Skip                │
│ Progress            │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ REVISION + RECOVERY │
│                     │
│ +1 / +3 / +7        │
│ Missed tasks        │
│ Rebalance           │
│ Replan              │
└─────────────────────┘

🤖 Why This Isn't "Chat With Your PDF"

There are thousands of projects that can answer:

“Summarize chapter 4.”

That wasn't the product I wanted to build.

PrepFlow's model produces structured knowledge, not the final answer the student follows.

The application then transforms that knowledge into an executable workflow.

                 GENERIC PDF CHAT

PDF ──────► LLM ──────► Answer


                 PREPFLOW

PDF
 │
 ▼
Extraction
 │
 ▼
Chunking
 │
 ▼
Gemma
 │
 ▼
Structured Topics
 │
 ▼
Evidence Verification
 │
 ▼
Priority Engine
 │
 ▼
Capacity Engine
 │
 ▼
Planner
 │
 ▼
Daily Tasks
 │
 ▼
Progress
 │
 ▼
Revision

The difference is subtle but important:

The output isn't text.

The output is a decision system.

🔍 Evidence Is First-Class

One of the parts I cared about most was preventing the model from inventing study topics.

If Gemma says:

“Dynamic Programming is highly important.”

PrepFlow doesn't simply trust it.

The model must provide source evidence.

The system then checks that evidence against the extracted source text and derives the PDF page programmatically.

Gemma says:

Topic:
Dynamic Programming

Evidence:
"Dynamic programming solves problems
by combining solutions to overlapping
subproblems."

             │
             ▼

       SOURCE MATERIAL

             │
             ▼

     Does this exact evidence
       exist in the source?

        ┌────┴────┐
       YES        NO
        │          │
        ▼          ▼
    ACCEPT       REJECT
        │
        ▼
   derive PDF page

This gives each topic a traceable relationship back to the material.

The repository documents the same architecture: model output is parsed, schema-validated, then evidence-verified before topics are accepted.

🧮 How PrepFlow Decides What Matters

Not every topic deserves equal time.

PrepFlow combines multiple bounded factors:

Factor	What it represents
Importance	How important the topic is
Weakness	How weak the student is
Foundation	Whether other topics depend on it
Difficulty	How demanding it is
Urgency	How close the exam is
Emphasis	Explicit emphasis in the source
Evidence	Strength of supporting evidence
Revision	Need for later review

This produces a bounded priority score rather than asking the model to invent one.

                  TOPIC PRIORITY

Importance ────────┐
Weakness ──────────┤
Foundation ────────┤
Difficulty ────────┤
Urgency ───────────┤
Emphasis ──────────┼──► PRIORITY SCORE ──► PLAN
Evidence ──────────┤
Revision ──────────┘

⏱️ The Planner Knows When You Don't Have Enough Time

This was one of the most important product decisions.

Suppose the student has:

40.5 hours of estimated work

but only:

24 hours available

A typical AI timetable might confidently distribute everything across the available days.

PrepFlow doesn't.

It tells the truth.

ESTIMATED WORK
████████████████████████████████████████ 40.5h

AVAILABLE TIME
████████████████████████ 24.0h

                         ───────────────
                         16.5h OVERLOAD

Then it prioritizes the work:

Tier	Meaning
🔴 MUST	Highest-value work to protect
🟠 SHOULD	Important if capacity permits
🟡 IF TIME	Useful but lower priority
⚪ DEFER	Cannot realistically fit

The planner therefore answers two questions:

What should I study?
What should I stop pretending I can finish?

That second question is surprisingly important.

🧱 Prerequisites Matter

A study plan shouldn't tell someone to learn:

“Advanced Dynamic Programming”

before:

“Dynamic Programming fundamentals.”

PrepFlow models prerequisite relationships.

Arrays
  │
  ▼
Recursion
  │
  ▼
Dynamic Programming
  │
  ├──────────────► Knapsack
  │
  └──────────────► Longest Common Subsequence

The planner can therefore account for foundational topics instead of treating every topic as an independent checkbox.

📅 A Plan Is Not Finished When It Is Generated

Real students miss tasks.

That's normal.

So PrepFlow treats planning as a feedback loop:

          ┌──────────────┐
          │ INITIAL PLAN │
          └──────┬───────┘
                 │
                 ▼
          ┌──────────────┐
          │     TODAY    │
          └──────┬───────┘
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
     COMPLETE   SKIP    MISS
        │        │        │
        └────────┴────────┘
                 │
                 ▼
        ┌─────────────────┐
        │ RECOVERY /      │
        │ REBALANCE       │
        └────────┬────────┘
                 │
                 ▼
          NEW PLAN VERSION

Completed work is preserved.

Unfinished work can be recovered or re-planned.

This is much closer to how real studying works than generating one static timetable.

🔁 Revision Is Built Into the Plan

Studying a topic once isn't enough.

PrepFlow schedules revision sessions after learning using spaced intervals.

Conceptually:

LEARN
  │
  ├──── +1 study day ────► REVISION 1
  │
  ├──── +3 study days ────► REVISION 2
  │
  └──── +7 study days ────► REVISION 3

The planner also respects the exam boundary and available study days.

🏗️ Architecture

The repository is a TypeScript monorepo containing the React frontend, Express/TypeScript API, and shared schemas/types.

PrepFlow/
│
├── apps/
│   ├── api/
│   │   ├── domain/
│   │   │   ├── planning/
│   │   │   └── analysis/
│   │   │
│   │   ├── infrastructure/
│   │   │   ├── prisma/
│   │   │   ├── PDF extraction
│   │   │   └── AI providers
│   │   │
│   │   └── HTTP API
│   │
│   └── web/
│       ├── React
│       ├── TypeScript
│       ├── Vite
│       └── Tailwind
│
├── packages/
│   └── shared/
│       └── Zod schemas + shared types
│
├── docs/
│   ├── analysis.md
│   ├── planning.md
│   └── decisions/
│
└── PostgreSQL + Prisma

🧠 Why the AI Layer Is Replaceable

I didn't want the entire application to become dependent on one model.

The architecture therefore separates:

                APPLICATION

                    │
                    ▼
             ┌─────────────┐
             │ AI PROVIDER │
             │ INTERFACE   │
             └──────┬──────┘
                    │
          ┌─────────┼─────────┐
          ▼         ▼         ▼
       Ollama     Gemini     Fake
       + Gemma     + Gemma   Provider

The model can change without rewriting the planning engine, database layer, or frontend.

The repository currently exposes ollama, gemini, and fake provider modes.

🛡️ AI Security and Trust Boundaries

The system treats uploaded study material as untrusted input.

USER MATERIAL
     │
     │ untrusted
     ▼
┌──────────────┐
│ nonce +      │
│ delimiters   │
└──────┬───────┘
       ▼
     GEMMA
       │
       ▼
┌──────────────┐
│ tolerant     │
│ JSON parsing │
└──────┬───────┘
       ▼
┌──────────────┐
│ Zod schema   │
│ validation   │
└──────┬───────┘
       ▼
┌──────────────┐
│ source       │
│ evidence     │
│ verification │
└──────┬───────┘
       ▼
     ACCEPT

The model receives no application secrets or tools.

Its output is never treated as trusted application state.

The repository also documents bounded retries, analysis concurrency limits, upload limits, CORS controls, and environment-based secrets.

🧪 Testing the Important Parts

I didn't want the project to only work in a happy-path demo.

The current test suite covers multiple layers:

Layer	What is tested
Shared	Schemas and shared logic
API	Business logic and routes
Web	Frontend behavior
HTTP	End-to-end API routing
Planning	Priority, capacity, scheduling
Randomized invariants	Planner safety properties
PostgreSQL	Real persistence
Concurrency	Rebalance/version behavior
PDF extraction	Real document parsing

Current validation:

423 automated tests passing

and

20/20 real PostgreSQL integration tests passing

The integration tests include persistence and concurrent plan-rebalancing scenarios.

📊 What the Test Numbers Actually Mean

AUTOMATED TESTS

Shared       ████████████████████  22
API          ████████████████████ 358
Web          ████████████████████ 43
                                  ───
TOTAL                              423

Real database integration:

PostgreSQL integration

Passed     ████████████████████ 20
Failed                           0

I also validated the PDF extraction pipeline against a real academic PDF and compared the extracted page structure against the source.

🧰 Technology Stack

Layer	Technology	Why
Frontend	React + TypeScript	Component-based UI
Build	Vite	Fast development/build
Styling	Tailwind CSS	Consistent UI system
Backend	Node.js + Express	Lightweight API
Language	TypeScript	Shared type safety
Validation	Zod	Runtime contracts
Database	PostgreSQL	Relational persistence
ORM	Prisma	Type-safe DB access
PDF	PDF.js	Page-aware extraction
AI	Gemma	Open-weight material analysis
Local AI	Ollama	Local model execution
Testing	Vitest	Fast automated testing
CI	GitHub Actions	Automated verification

🌍 Why Open Innovation Matters

Study material can be surprisingly sensitive.

It can contain:

Personal information
University documents
Assignments
Private notes
Exam preparation
Proprietary material

That's why I wanted PrepFlow's architecture to support local/open-weight AI, rather than making a cloud LLM the only possible path.

Gemma sits behind an AI-provider abstraction instead of being hardcoded into the application's business logic.

That gives the project a useful property:

The intelligence can evolve without rebuilding the product around a single AI provider.

🆚 What PrepFlow Is — And Isn't

PrepFlow is	PrepFlow isn't
AI-assisted planning	A generic chatbot
Evidence-backed analysis	Blind LLM output
Deterministic scheduling	LLM-generated timetable
Capacity-aware	“Everything fits” fantasy
Revision-aware	One-time checklist
Explainable	Black-box prioritization
Open-weight AI compatible	Locked to one provider
Built around execution	Just another note summarizer

💡 The Engineering Lesson

The biggest thing I learned wasn't how to connect an AI model to a backend.

It was learning where not to use AI.

A tempting architecture would have been:

PDF
 │
 ▼
LLM
 │
 ▼
"Here is your study plan."

It's easy.

It's also difficult to trust.

PrepFlow instead looks more like:

                 AI
                  │
                  ▼
        UNDERSTAND THE MATERIAL
                  │
                  ▼
             STRUCTURED DATA
                  │
                  ▼
        ┌────────────────────┐
        │ DETERMINISTIC CODE │
        │                    │
        │ Validate           │
        │ Prioritize         │
        │ Calculate          │
        │ Schedule           │
        │ Revise             │
        │ Recover            │
        └─────────┬──────────┘
                  │
                  ▼
             REAL PLAN

That separation gives me much more confidence in the system.

🚀 What's Next

PrepFlow is intentionally an MVP.

The next areas I'd explore are:

Area	Possible improvement
Documents	OCR for scanned PDFs
AI	More provider/model evaluation
Knowledge	Better prerequisite inference
Planning	Calendar-aware scheduling
Progress	More sophisticated learning models
AI runtime	Additional local/open-weight providers
UX	Topic editing and plan refinement
Validation	Larger real-student testing

The current repository roadmap already separates the completed repository/database, ingestion, AI analysis, and planning milestones from later topic-review, polish, deployment, and real-user testing.

🔗 Try It

Source Code

github.com/piyusshhjangid/PrepFlow

Local Development

npm install
npm run db:migrate
npm run db:seed

npm run dev:api
npm run dev:web

Then open the web application.

The repository also documents the local Gemma/Ollama and hosted Gemma provider setup.

❤️ Why “Build for a Friend” Matters

Building for a friend changes the question.

Instead of:

“What AI feature can I add?”

you start asking:

“What is actually making this person's life harder?”

For PrepFlow, the answer was:

Students don't necessarily need more study material.

They need help turning the material they already have into a realistic sequence of actions.

So that's what I built.

Not another chatbot.

Not another PDF summarizer.

A system that tries to answer one deceptively difficult question:

What should I study next?

Built for the Hacktoberfest Weekend Challenge — Build for a Friend.

devchallenge #weekendchallenge #hf26challenge #gemma

DEV Community: Piyush