MapScribe.ai

Inspiration

Most learning resources give you content but no direction. You can find a YouTube video on machine learning or a tutorial on music theory, but nothing tells you what to learn first, how each concept connects to the next, or whether you are actually making meaningful progress. We wanted to build something that acts less like a library and more like a mentor. Something that looks at your goal and says: here is exactly where to start, here is how it all fits together, and here is what to do next.

What it does

MapScribe.ai transforms any learning goal into a fully interactive, AI-generated knowledge map. You type a topic like web development, music theory, investing, or machine learning, and the platform instantly generates a structured graph of everything you need to learn, laid out in the order you should learn it.

Each node in the graph represents a concept with a full explanation, practice problems, and curated resources. Nodes are locked until their prerequisites are completed, enforcing a proper learning sequence rather than letting users skip ahead. As you mark concepts complete, the map updates in real time, edges animate, and new topics unlock.

Beyond the map itself, MapScribe.ai includes:

Multi-topic support. Save unlimited learning paths and switch between them without losing progress. Your machine learning graph stays exactly where you left it when you switch to music theory.

AI YouTube Snippet Finder. For any concept, the platform searches YouTube, reads the video transcript, and uses AI to identify the single best 60 to 90 second segment where the core idea is explained. The video embeds directly and starts at exactly that moment.

Live dashboard. Tracks your real learning streak, overall completion percentage, skill level radar, knowledge gaps, and personalized next step recommendations.

Practice and grading. Each node has AI-generated practice problems. Submit an answer and Gemini grades it, returns a score, detailed feedback, and a model answer.

Google Sign-In. Secure authentication so progress is always tied to your account.

How we built it

Frontend. Next.js with TypeScript and Tailwind CSS. The knowledge graph canvas is built on React Flow, giving us full control over custom nodes, edges, and locking logic.

Backend. FastAPI on Python 3.11 with SQLAlchemy and PostgreSQL. The backend handles graph generation, prerequisite resolution, progress tracking, streak calculation, and all AI calls. Every node is scoped to a specific goal ID so multiple learning topics can coexist in the database without interfering with each other.

AI. All graph generation, answer grading, and YouTube timestamp analysis runs through the Google Gemini API. The graph generation prompt produces a full JSON knowledge graph in a single call, including node descriptions, practice problems, prerequisite edges, and resource types per concept.

YouTube integration. We use yt-dlp to search YouTube programmatically, youtube-transcript-api to fetch full transcripts, and then send a timestamped transcript to Gemini with instructions to find the exact second where the concept is best explained. The resulting embed URL starts the video at that precise moment.

Infrastructure. Docker Compose orchestrates the full stack locally. PostgreSQL runs in a container with a persistent volume and the backend auto-creates all tables on startup.

Challenges we ran into

The prerequisite graph logic was one of the hardest problems. Nodes need to know not just their direct prerequisites but all transitive ancestors, so we implemented a recursive CTE in PostgreSQL to walk the entire dependency tree. Getting this right while keeping it performant required careful schema design.

The multi-topic architecture required a full schema redesign mid-project. Originally, all nodes were scoped to a user, which meant switching topics destroyed the previous graph. We introduced a goal ID foreign key on every node so each learning path is completely isolated, and built a migration path to preserve existing data.

The YouTube snippet feature went through several iterations. Early versions failed when transcripts were unavailable. The final implementation handles the YouTube-transcript-api v3.0, and includes regex-based fallback parsing when Gemini returns a malformed JSON response.

Accomplishments that we're proud of

Getting the full pipeline working end-to-end was the biggest win. A user types a topic, Gemini generates a coherent learning graph tailored to that goal, nodes lay out cleanly using our custom depth-first layout algorithm, progress persists accurately across sessions, and the AI finds a genuinely useful YouTube clip for any concept with specific time stamps.

We are particularly proud of the YouTube snippet finder. It is a technically layered feature combining web scraping, transcript parsing, and LLM reasoning that results in something that feels seamless when it works. You click a button, and the video jumps to exactly the right moment.

The multi-topic system is also something we are proud of. Most learning apps lock you into one path. MapScribe.ai lets you maintain completely separate knowledge graphs for different goals simultaneously, which is how real learners actually work.

What we learned

This project pushed us deep into API design and how to structure endpoints that stay consistent as the data model evolves underneath them. We learned a lot about graph data structures in the context of a real product, specifically how to represent, store, query, and render directed acyclic graphs in a way that is both correct and fast.

Working with LLM outputs in a production setting taught us to never trust model responses blindly. Every AI response goes through parsing, validation, and fallback handling. We also learned that structured JSON output requires as much care as the code that consumes it.

The YouTube-transcript-api v3.0 update broke our original implementation mid-build and forced us to adapt quickly, which was a good lesson in building resilient integrations against third-party libraries.

What's next for MapScribe.ai

Refining the AI recommendation engine to factor in time availability and learning style, expanding integrated practice problems with difficulty progression, building a mobile-responsive mind map view optimized for learning on the go, and adding learning time tracking so users can see actual hours invested alongside streak data. Futhermore, implementing a notification system, so the program can remind the user to extend their current learning streak, or learn a new topic for the day.