PrepFlow: Let Gemma Turn Your Syllabus Into a Study Plan

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 Enter fullscreen mode Exit fullscreen mode Copy the API environment example and configure it: Copy-Item apps/api/.env.example apps/api/.env Enter fullscreen mode Exit fullscreen mode Set the database and AI provider values in apps/api/.env, then apply the database migrations: npm run db:migrate Enter fullscreen mode Exit fullscreen mode Start the API and frontend in separate terminals: npm run dev:api Enter fullscreen mode Exit fullscreen mode npm run dev:web Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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