Case study 03

Repo Explainer

A web app for people who build with AI but cannot yet read the code it writes. Paste a public GitHub link and get a plain-English tour of what the project does, how the parts fit together, and where to start reading.

The idea

More and more people ship software they did not write line by line, me included. When something breaks, or a project on GitHub looks useful, they have no way in. I wanted a tool that gives a beginner the tour a senior engineer would give on their first day: what this is, how it is organized, which files matter, and where it could break.

What it does

• Reads a public repository through the GitHub API and shows its health from GitHub's own facts: activity, stars, license and size.
• Writes a plain-English tour and a Start Here map, a numbered route through the files worth reading first.
• Offers three lenses on the same code: Understand it, Judge it, and Work on it, each ending with prompts a beginner can paste into their own AI assistant.
• Answers questions about the code and shows which files each answer came from.
• For private projects, checks one pasted file for leaked passwords and keys, suggests a fix, and explains how to apply it step by step, written for someone who has never done it before.

Decisions I made

• Send the AI only what it needs. A repository can hold thousands of files. For each question the AI first picks a handful of relevant files from the file list, the server accepts only paths that really exist, and only those files are read. If the pick fails, a keyword search takes over.
• Code is data, never instructions. A repository could contain text written to steer the AI. Every file is fenced off and the model is told to treat it as material to explain.
• Secrets never reach the AI. The server masks anything that looks like a key or password before any code leaves it. Requests are sent with storage turned off, and nothing pasted is kept.
• Sign in with GitHub to stop abuse. My first limits counted visitors by network, and a phone or VPN got around them. Requiring a GitHub account, at least 30 days old, made every free credit belong to a real person. The app asks GitHub for public profile data only.
• Limits at every layer. A per-minute speed limit, daily credits per account, a shared daily pool for free use so it can never crowd out paying users, and a site-wide brake.
• Rules in code, not just in the prompt. When the AI kept breaking a rule, I enforced it on the server instead: demo and test files are skipped, notes about the tool's own limits are filtered out, and fix prompts are removed when no problem was found.
• Measure before choosing a model. I logged real token use per answer and tested a cheaper model against the same three projects. It found nothing anywhere, so I kept the better one. Quality is the product, and the savings were a fraction of a cent.
• Launch free, sell later. Subscriptions are built and tested in Stripe's test mode, but the paid plan stays behind one switch until the business side is fully set up.

What went wrong, and how I fixed it

• It called my own shortcut a bug. To save cost, long files are shortened before the AI sees them. The AI then reported those files as broken. Files are now marked as shortened, and any finding about a file it could not fully see is removed.
• "No tests" on projects with hundreds of tests. The AI only read six files, so it never saw the test folders. The server now counts test files across the whole project and hands the AI those facts.
• Judging demo code as the product. On a major web framework, every finding came from its examples folder. The lenses now skip example, test and documentation files and read the real code.
• Working on my laptop, failing on the live site. Sign-in timed out in production. I read the server logs, added time limits so failures showed up instead of hanging, and built a test page that checked each piece side by side. Storage worked everywhere except inside the framework's server, so I moved storage into a small separate function, protected by a secret, that the app calls.
• Billing edge cases. A cancellation date showed one day off because of time zones, and a subscriber could start a second subscription by mistake. Dates now display in UTC, and checkout refuses anyone who already has a plan.

How I built it

I built this with an AI assistant as my tutor, over eighteen working sessions. Each session added one layer: reading repositories, the first tour, retrieval, the map and health check, the lenses, the paste check, cost limits, subscriptions and webhooks, sign-in, quality testing, policies and consent, security checks, and launch. I tested every layer against real projects and broke it on purpose before moving on.

What is next

A Pro plan with 300 credits a month, file references that open straight to the code on GitHub, and a way to save and share a tour.

← Back to all work