DEV Community: Piyush

PrepFlow: Let Gemma Turn Your Syllabus Into a Study Plan

Piyush — Sun, 25 Oct 2026 05:29:22 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady 🦥

What I Built

I built PrepFlow, an open-source study planner that turns a syllabus and notes into a prioritized, day-by-day plan for an exam.

The task I wanted to make easier is the planning around studying: pulling topics out of course material, estimating how much work they need, deciding what to study first, and fitting it all around the time left before an exam. When a day gets missed, the plan needs to recover too.

PrepFlow takes text or a text-based PDF, an exam date, and the time available to study. It uses Gemma to propose subjects and topics from the material. Then the application checks the model’s work, estimates effort, prioritizes topics, and schedules study and revision sessions.

Each topic includes a quote from the source material, so students can check where it came from. If the work does not fit before the exam, PrepFlow explains the capacity problem and shows what it protects and defers.

The aim is simple: spend less time organizing study and more time learning.

Demo

There is no hosted demo yet. PrepFlow has not been deployed or tested with real users. You can run it locally by following the setup guide in the repository.

Local setup

You’ll need Node.js 22.22.2 or newer, PostgreSQL, and either a local Ollama model or a configured hosted AI provider. Docker is optional.

git clone https://github.com/piyusshhjangid/PrepFlow.git
cd PrepFlow
npm install
npm run db:up
ollama pull gemma4:e4b

Copy the API environment example and configure it:

Copy-Item apps/api/.env.example apps/api/.env

Set the database and AI provider values in apps/api/.env, then apply the database migrations:

npm run db:migrate

Start the API and frontend in separate terminals:

npm run dev:api

npm run dev:web

Then open http://localhost:5173. The README includes Windows setup instructions for using PostgreSQL without Docker, environment-variable details, and troubleshooting.

Code

Repository: piyusshhjangid/PrepFlow on GitHub

The repository contains the full-stack application, setup instructions, architecture and pipeline docs, and a preserved browser-only prototype with its own evaluation materials.

The supported application is the full-stack monorepo:

apps/web         React + TypeScript + Vite frontend
apps/api         Express + TypeScript backend
packages/shared  Zod schemas and types shared by frontend and backend
Prisma           PostgreSQL schema and migrations
docs/            Setup, architecture, AI, security, planning, and deployment docs
experiments/     Preserved browser-only prototype and its separate evaluation

The main application and the browser-only prototype came from different branches and have different architectures. I kept the prototype under experiments/sloth-browser-prototype/ rather than mixing its browser-only design into the full-stack app. Its evaluation files describe that prototype; they are not benchmarks of the full-stack application.

The analysis and planning flow

Text or text-based PDF
        ↓
Extract and split material into chunks
        ↓
Gemma proposes subjects and topics
        ↓
Parse and validate the model response
        ↓
Check evidence against the original material
        ↓
Merge topics and estimate effort
        ↓
Save analysis to PostgreSQL
        ↓
Prioritize topics and build a capacity-aware plan
        ↓
Study tasks, revision, and progress

The repository also contains an architecture illustration for the preserved browser-only prototype. It is not a diagram of the full-stack app:

How I Built It

PrepFlow is a TypeScript monorepo. The frontend uses React, Vite, and Tailwind. The API uses Express and TypeScript. PostgreSQL stores application data through Prisma, and shared Zod schemas keep validation consistent between the frontend and backend.

Let the model interpret; let application code decide

Gemma has a specific role: it reads study material and proposes structured subjects and topics. The model does not decide the final schedule.

The API parses the model response and validates it against a schema. It then checks the proposed topic evidence against the original material. Application code handles persistence, topic merging, effort estimates, priorities, prerequisite handling, available capacity, dates, and revision scheduling.

That boundary makes the result easier to inspect. The model can help interpret text, while the important planning rules stay in code.

Evidence students can inspect

PrepFlow checks whether a proposed quote can be found in the source material. Evidence gets a support label:

direct means the evidence closely supports the topic.
nearby means related evidence appears close to the match.
weak means the match is uncertain and should be treated cautiously.

Weak evidence is surfaced as a caution instead of being silently presented as strong support. The topic also keeps its source quote so a student can review it.

Importance is checked against material emphasis too. If the model marks a topic as highly important without a supporting emphasis cue in the source, PrepFlow lowers the importance to medium. The goal is to avoid treating a model’s confident wording as proof.

A plan that accounts for time

Planning is deterministic. PrepFlow uses the exam date, study days, daily time budget, topic importance, confidence, weak-topic status, and prerequisites to organize work.

The plan includes revision sessions after studying a topic, and avoids scheduling revision after the final study day. If all the work will not fit, PrepFlow reports the mismatch and shows what was deferred rather than hiding the capacity problem.

The app also includes a daily task view, task completion tracking, progress, missed-work recovery, and plan rebalancing. Rebalancing creates a new plan version while preserving completed work.

Main application API

The API exposes endpoints for analysis, plans, and daily work. For example:

POST /api/exams/:examId/analysis
GET  /api/exams/:examId/analysis/result
POST /api/exams/:examId/plan
GET  /api/exams/:examId/plan/today
POST /api/exams/:examId/plan/rebalance
POST /api/study-tasks/:taskId/complete

Testing and verification

The repository includes shared, API, frontend, and PostgreSQL integration tests. Automated AI tests use a deterministic fake provider so they do not need a model or network access.

I have not verified a real Gemma run for this submission, and the app has not been deployed. The full test and build suite also has not been verified locally on my machine, so I’m not claiming production readiness or real-model quality results.

Why Does Open Innovation Matter?

Open-weight AI makes it possible to build a local inference path. PrepFlow can run Gemma through Ollama, giving users the option to process their study materials with a model running on their configured machine.

The model layer is also replaceable. A hosted provider is supported too, but the parsing, validation, evidence checks, and planning rules live in the application. Those rules can be inspected and improved without depending on a closed API to decide how a student should spend their time.

There is a privacy trade-off to be clear about: when a hosted provider is configured, material chunks are sent to that provider. Local Ollama inference is the option for keeping model requests local, but I have not verified a real Gemma run for this submission.

Open source also made it possible to preserve and compare the browser prototype separately from the full-stack application. The prototype remains available for its own code and evaluation artifacts without confusing its results with the main app.

What’s Next

The next useful validation is a real end-to-end session: run a real Gemma model on sample study material, inspect the resulting evidence and plan, capture genuine screenshots, and test the workflow with students who consent to give feedback.

That would help answer the questions automated checks can’t: do the source quotes make the topics trustworthy, does the plan feel realistic, and is the recovery flow helpful after a missed day?

My Agent Session

I don’t have a shareable agent-session link for this submission.

The Lazy Payoff

I haven’t measured minutes saved or tested PrepFlow with real students, so I can’t claim a specific time-saving number yet.

The intended payoff is fewer rounds of copying topics into a planner, guessing how much time they need, and rebuilding the schedule after a disruption. PrepFlow handles that planning work and shows its reasoning, so students can spend less energy organizing and more time studying.

Prize Categories

Best Use of Gemma: PrepFlow includes a local Gemma-through-Ollama integration. A real-model run is not yet verified or shown in a public demo, so the integration is implemented but not demonstrated here.

hf26challenge #devchallenge #hacktoberfest #ai #opensource

BriefBill: Turning Messy Client Briefs into Professional Proposals with Gemma

Piyush — Sun, 18 Oct 2026 19:38:10 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge — Week 2: Side Hustle.

What I Built

Freelancers often receive client requests through scattered messages, rough notes, or vague descriptions. Turning those into a clear proposal takes time—and missing a requirement early can lead to confusion later.

I built BriefBill, an AI-powered proposal generator that helps freelancers turn a messy client brief into a structured, editable proposal.

BriefBill is designed to help freelancers:

Extract key requirements from a client's brief.
Organize deliverables, assumptions, and unanswered questions.
Draft a professional proposal that can be reviewed and edited.
Work with a structured proposal instead of starting from a blank page.
Prepare a client-ready document using the proposal's editing and print/export workflow.

The intended users are independent freelancers and small service businesses that want to spend less time formatting proposals and more time delivering their work.

The business idea is straightforward: if BriefBill saves freelancers time and helps them communicate scope more clearly, it could become a useful paid tool. That is a hypothesis I want to validate with real users.

Demo

Try BriefBill: https://briefbill.onrender.com/

The application is publicly deployed. Try entering a realistic client brief and review the generated proposal, including the extracted requirements, deliverables, assumptions, and questions.

Code

GitHub repository: https://github.com/piyusshhjangid/BriefBill

The repository contains the application source code and setup instructions.

I wanted this to be more than an AI prompt wrapped in a UI. The project includes a structured generation workflow, validation, and tests around the application's behavior.

How I Built It

BriefBill combines a web application with a Gemma-powered proposal-generation workflow.

The AI integration uses Gemma 4 26B A4B IT, accessed through Google's Gemini API. The model helps interpret unstructured client briefs and produce structured proposal content.

The core workflow is:

Input: The freelancer provides a client brief.
Analysis: Gemma interprets the request and identifies requirements, deliverables, assumptions, and missing information.
Validation: The generated output is checked against the application's expected structure.
Proposal creation: The structured result is presented in an editable proposal workflow.
Finalization: The freelancer can review the content and prepare it for sharing or printing.

One important design decision is to keep proposal content generation separate from deterministic application logic. AI is useful for interpreting ambiguous language and drafting content; calculations and other predictable operations should be handled by application code rather than relying on the model to do arithmetic correctly.

Testing and verification

Before deployment, I ran the project's automated checks:

131 tests passed across 8 test files.
Production build completed successfully.
Lint checks passed.
Formatting checks passed.
The live-inference verification command succeeded locally, and the returned output passed schema validation.

The live-inference check was a functional verification, not a benchmark. I am not claiming a particular accuracy rate or production-scale performance from it.

Why Does Open Innovation Matter?

For a project like BriefBill, the quality of the result depends on how well a model handles ordinary but ambiguous language.

A freelancer might write something like:

“I need a simple website for my bakery with a menu, contact form, and a way to update products. Can you give me a quote?”

Turning that into a useful proposal requires more than rewriting the sentence. The system needs to identify the requested work, recognize what remains unclear, and organize the information into something a client can review.

Gemma gave me a model I could integrate into that workflow and evaluate as part of a real application. The open-weight model ecosystem also creates opportunities for developers to experiment with different deployment approaches, compare models, and build more specialized products around their capabilities.

For this version, I use the Gemini API rather than claiming to self-host the model. That distinction matters: open-weight models can expand developer choice, but the actual hosting and inference setup still determines the costs, privacy properties, and operational constraints of an application.

My goal with BriefBill is to demonstrate a practical use of an open-weight model—not just ask it a question, but make it one component of a product with a defined audience, a repeatable workflow, and validation around its output.

Prize Categories

Primary category: Best Use of Gemma

BriefBill integrates Gemma into a concrete workflow for transforming unstructured client requests into structured proposals.

What I Want to Improve Next

The next step is to get feedback from freelancers who regularly prepare client proposals. I want to learn whether the generated structure is genuinely useful, which parts need the most editing, and whether the tool saves enough time to justify paying for it.

Other priorities include improving proposal quality for different freelance services, refining error handling, and evaluating the experience with a broader range of real-world briefs.

BriefBill is a working starting point, and I want to improve it based on actual usage rather than assumptions.

Built for the Hacktoberfest Open-Source AI Challenge — Week 2: Side Hustle.

devchallenge #hf26challenge

🌿 PocketWalk: Building an AI-Assisted Walking Planner With Deterministic Fallbacks

Piyush — Mon, 12 Oct 2026 04:03:27 +0000

A small experiment in making AI useful without making it responsible for everything.

What if planning a short walk took less effort than deciding whether to go outside?

PocketWalk is an AI-assisted walking planner that turns a few simple preferences into a structured walking plan. Choose a duration, select a difficulty, optionally enter a city, and get a practical three-step plan designed to help you spend less time planning and more time walking.

But the interesting part isn't just generating a plan with AI. It's deciding what should happen when AI returns unexpected output, a provider is unavailable, or a generated suggestion needs additional validation.

That is the engineering problem I wanted to explore.

Live app: https://pocketwalk.onrender.com
Demo video: [INSERT YOUR DEMO VIDEO URL]
Source code: [INSERT YOUR GITHUB REPOSITORY URL]

🌱 01. The Problem: Planning Shouldn't Become Another Task

Going for a walk sounds simple, but even a small decision can involve several questions:

How much time do I have?

Should I take an easy walk or something more active?

What should I do during the walk?

What if I don't know the area?

Can I get a useful suggestion without creating another account or sharing unnecessary information?

I wanted to build a small tool that reduces this friction.

PocketWalk focuses on a deliberately narrow workflow:

Input

Purpose

Duration

Plan a 10, 20, or 40-minute walk

Difficulty

Choose easy or normal

Optional city

Supply location context when available

Generated plan

Receive a structured, three-step walking experience

The product deliberately avoids accounts, persistent walking history, GPS tracking, and notifications.

The objective is not to build another giant wellness platform. It is to make one small activity easier to start.

🏗️ 02. Architecture: Where AI Fits in the System

PocketWalk uses a React and TypeScript frontend with an Express-based backend. The AI integration is designed to support a Gemma-compatible provider path, alongside a deterministic fallback.

The important architectural decision is that model output should not automatically become trusted application output.

flowchart TD
A[React + TypeScript UI] --> B[Express API]
B --> C[Request Validation]
C --> D{AI Provider Available?}
D -->|Yes| E[AI Generation]
D -->|No| F[Deterministic Fallback]
E --> G[Parse and Validate Output]
G -->|Valid| H[Structured Walk Plan]
G -->|Invalid| F
F --> H
H --> I[Display Plan to User]

This is a conceptual view of the intended flow. Confirm exact module boundaries and error paths against the current source code before treating it as a complete implementation diagram.

The responsibilities are intentionally separated

Frontend — React and TypeScript

Collects user preferences, submits requests, and presents the resulting walking plan.

Backend — Express

Handles API requests and provides a controlled boundary between the UI, external providers, and application logic.

AI integration

Generates contextual suggestions when a configured provider is available. The project supports a Gemma-compatible path, but the recorded demo does not show a live Gemma inference.

Validation and fallback

Generated output must be parsed and checked rather than accepted blindly. The fallback provides a deterministic alternative when AI generation is unavailable or unsuitable.

This separation also makes it easier to change providers without making the entire application dependent on one model.

💻 03. Engineering Detail: Treating AI Output as Untrusted

One of the most important lessons from this project is that a successful API response does not automatically mean a useful or safe application response.

An AI provider can return malformed JSON, unexpected fields, missing values, or suggestions that fail application-specific checks.

The following simplified TypeScript example illustrates the validation boundary. It is an explanatory example, not a verbatim excerpt from PocketWalk.

type WalkDifficulty = "easy" | "normal";

type WalkRequest = {
durationMinutes: 10 | 20 | 40;
difficulty: WalkDifficulty;
city?: string;
};

function validateWalkRequest(
input: unknown
): WalkRequest | null {
if (typeof input !== "object" || input === null) {
return null;
}

const value = input as Record;

const validDuration =
value.durationMinutes === 10 ||
value.durationMinutes === 20 ||
value.durationMinutes === 40;

const validDifficulty =
value.difficulty === "easy" ||
value.difficulty === "normal";

if (!validDuration || !validDifficulty) {
return null;
}

if (
value.city !== undefined &&
typeof value.city !== "string"
) {
return null;
}

return {
durationMinutes: value.durationMinutes,
difficulty: value.difficulty,
...(typeof value.city === "string"
? { city: value.city }
: {}),
};
}

Why this boundary matters

It prevents arbitrary values from entering the core planning workflow.

It makes the supported request shape explicit.

It gives the backend a predictable contract.

It allows invalid input to be rejected before expensive provider calls.

In production code, I would prefer a shared runtime schema validator for stronger type inference, precise error messages, and consistent validation across routes.

Model output needs its own validation

Request validation is only the first boundary. AI-generated output requires independent checks.

type WalkStep = {
title: string;
description: string;
};

type WalkPlan = {
steps: WalkStep[];
};

// Illustrative validation boundary.
// A real implementation must validate every field and constraint.
function validatePlanShape(
value: unknown
): value is WalkPlan {
if (typeof value !== "object" || value === null) {
return false;
}

const steps = (value as Record).steps;

return (
Array.isArray(steps) &&
steps.length === 3 &&
steps.every(
(step) =>
typeof step === "object" &&
step !== null &&
typeof (step as Record).title === "string" &&
typeof (step as Record).description === "string"
)
);
}

This checks structure, not real-world safety. Even a structurally valid plan may contain an inappropriate recommendation.

That distinction is essential: schema validation can establish that output has the expected shape; it cannot prove that a route is safe or that every recommendation is correct.

🛡️ 04. Fallbacks, Determinism, and Safety

AI availability should not be the single point of failure for a small utility.

PocketWalk includes a deterministic fallback path so the core experience can remain useful without a successful AI response.

The intended behavior can be summarized as follows:

Situation

Design response

Valid request

Continue through the planning workflow

Provider available

Attempt AI-assisted generation

Invalid generated structure

Reject it rather than trusting it

Provider unavailable

Use deterministic fallback behavior

Safety-related concern

Apply application-level checks and provide appropriate caveats

The project includes parsing, schema validation, business rules, and deterministic safety filters. These checks reduce avoidable errors, but they do not guarantee that a walking route is safe.

PocketWalk should not be presented as a live navigation or emergency-response system. Users should exercise judgment, follow local conditions, and use established navigation or emergency services when necessary.

Why I chose a fallback-first mindset

A demo that works only when a particular model is available is fragile.

A more resilient design separates the application's basic utility from the availability of its AI provider. This also makes testing easier because deterministic behavior can be exercised without depending on external model responses.

🎨 05. The User Experience: Keep the Interface Focused

PocketWalk is designed around a short interaction rather than a complicated dashboard.

The main flow is:

Choose a walk duration.

Select the desired difficulty.

Optionally provide a city.

Generate and review the plan.

Decide whether the suggested activity fits the situation.

The interface should make the next action obvious and avoid asking for information that the core experience does not require.

Suggested visual placements for the published article:

[SCREENSHOT 1 — Home screen] Show the actual deployed app and its primary controls.

[SCREENSHOT 2 — Generated plan] Show the three-step output and its readability on desktop or mobile.

[SCREENSHOT 3 — Fallback behavior] Show the real fallback experience, if it can be captured reliably.

[SCREENSHOT 4 — Responsive UI] Show the same workflow at a mobile viewport.

Use screenshots from the real application rather than stock images. A short GIF of the complete interaction would be even more useful near the beginning of the article.

🔄 06. The Request Lifecycle

The following sequence shows the logical responsibilities involved in generating a plan.

sequenceDiagram
actor User
participant UI as React UI
participant API as Express API
participant AI as AI Provider
participant V as Validation
participant F as Fallback

User->>UI: Select preferences
UI->>API: Submit walk request
API->>API: Validate request
API->>AI: Request generated plan
AI-->>API: Candidate output
API->>V: Parse and validate

alt Output passes checks
    V-->>API: Validated plan
else Provider or output failure
    API->>F: Create fallback plan
    F-->>API: Deterministic plan
end

API-->>UI: Return plan
UI-->>User: Display result

This is a logical sequence diagram, not evidence that every branch was exercised in the recorded demo. The fallback path is part of the documented design; the demo uses fallback behavior rather than a live Gemma inference.

🧪 07. Testing and Verification

A project should be evaluated by what was tested, not just by how polished the demo looks.

The project verification snapshot recorded the following test counts:

Test suite

Recorded result

Backend tests

636

Frontend tests

151

Browser checks — suite 1

Browser checks — suite 2

Browser checks — suite 3

These are counts from the recorded verification artifacts, not a claim that every test represents a unique feature or that every production integration is verified.

The project also recorded build, bundle-scan, documentation-check, and audit checks. The exact status of each check should be confirmed against the latest repository state before publication.

What the test counts do not prove

Passing local tests does not automatically establish that:

A live Gemma request succeeds in production.

Live weather data is available in every environment.

Sentry events are reaching a configured external project.

A Docker image builds successfully.

GitHub Actions has completed successfully.

Every generated walking suggestion is safe.

The recorded demo does not demonstrate live Gemma inference, live weather verification, Sentry ingestion, a Docker build, or a GitHub Actions run.

I would rather state those limitations clearly than imply that unverified integrations work.

🚀 08. Deployment

PocketWalk is deployed at:

https://pocketwalk.onrender.com

The recorded deployment check confirmed that the application was reachable and that the root page returned HTTP 200.

The documented production configuration uses the deterministic AI fallback (GEMMA_PROVIDER=none), the Open-Meteo weather provider configuration, and disabled Sentry reporting. A configured weather provider is not, by itself, proof that every live weather request succeeds.

This deployment was useful for validating the real application entry point, but it should not be confused with verification of every optional integration.

🧠 09. Why This Is an Open Innovation Project

I wanted PocketWalk to explore a broader engineering principle: AI should be an optional capability that improves a useful product, not a dependency that makes the product unusable without it.

That principle influences several design choices:

Provider flexibility: avoid coupling the entire application to one model.

Deterministic behavior: retain a useful fallback when generation is unavailable.

Explicit validation: separate model output from trusted application data.

Minimal data collection: avoid accounts, persistent history, and unnecessary tracking.

Honest evaluation: distinguish local tests, deployed behavior, and integrations that remain unverified.

These decisions make the project easier to reason about and give future contributors clearer places to improve it.

📚 10. What I Learned

Building PocketWalk reinforced several lessons for me as a student developer.

AI integration is more than calling an API.
Parsing, validation, failure handling, and predictable behavior are part of the feature.
A fallback is a product decision.
It protects the basic experience from depending entirely on an external service.
Tests and deployment evidence answer different questions.
A passing test suite, a successful build, and a reachable deployment are separate forms of evidence.
Safety claims need boundaries.
Validation can reject known invalid patterns, but it cannot certify that a route is safe in the real world.
Scope matters.
A small tool with a clear purpose can be a better learning project than a much larger application with many disconnected features.

🔭 11. What I Would Improve Next

The next steps should be driven by verified gaps rather than adding features for their own sake.

Add a repeatable integration test for a real Gemma-compatible provider.

Verify live weather behavior with both successful responses and provider failures.

Confirm external Sentry event ingestion with an intentional, safe test event.

Run and record a reproducible Docker build.

Verify the complete GitHub Actions workflow from a clean commit.

Improve accessibility, mobile interaction, and error-state feedback.

Document the limits of generated suggestions and the fallback behavior.

Each item should be marked complete only after there is reproducible evidence.

🌍 12. Closing

PocketWalk started with a simple question: can an AI-assisted tool make going for a walk easier without making the experience unnecessarily complicated?

The result is a small walking planner built around a focused UI, a backend API, AI-assisted generation, validation, and deterministic fallback behavior.

It is not a certified navigation system, and the recorded demo does not prove every optional integration works live. Those boundaries are part of the project story, too.

For me, the most valuable takeaway is that building with AI means designing for the moments when AI is unavailable, incorrect, or simply not needed.

Sometimes the best AI product is the one that knows when not to depend on AI.

Project links

Live application: https://pocketwalk.onrender.com

Demo video: https://youtu.be/wruSn74VnNU

GitHub repository: https://github.com/piyusshhjangid/PocketWalk

Challenge: https://dev.to/challenges/hacktoberfest-week1-2026-10-05

devchallenge #hf26challenge #react #typescript

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