GitStation

GitStation turns any GitHub repo into an interactive railway map with plain-English explanations, guided tours, and an AI conductor, helping beginners find where to start contributing to open source.

Comment

Inspiration

Open source is one of the best ways to learn and get real experience, but getting started is intimidating. Beginners find a project they like, open the repo, see hundreds of files, and have no idea where to begin. Tools like GitDiagram show you the map of a codebase, but they don’t teach you how to read it. We wanted to build something that does both, and we leaned into the SBU Hacks “Steel and Steam” theme: every repo is a railway, each part of the codebase is a station, and the tracks show how everything connects.

What it does

  • The Map: paste any GitHub repo and get an interactive railway map of its architecture, grouped into lines (frontend, backend, database, config, external services)
  • Stations: click any station for a plain-English explanation, key points, connections, and its main files
  • Code viewer: open real files from GitHub with syntax highlighting and an AI summary of what each file does
  • Ask the Conductor: an AI assistant that knows which station or file you’re asking about. When an answer mentions another part of the code, it links right back to the map
  • The Grand Tour: a train walks you through the codebase station by station, in the order a beginner should read it
  • The Inspection: shows whether a project is active, whether it welcomes newcomers, which good first issues are open, and what languages it’s built with (as a freight train)
  • Nearby Trains: a timetable of beginner-friendly repos sorted by language, many already mapped

How we built it

The frontend is React + Vite with React Flow for the map, using custom station nodes and rail track edges, plus Tailwind and shadcn/ui. The backend is FastAPI.

When a user pastes a repo, the backend pulls the file tree, README, and key files from the GitHub REST API and sends them to Gemini, which returns structured JSON with the stations, connections, and explanations. We validate that output (unique IDs, every track points to a real station, fixed categories) and retry on bad output, then cache the result in Supabase (Postgres). The expensive generation only happens once per repo, so every user after that gets the map instantly.

The conductor gets the map, the selected station, and the real file contents with line numbers, so answers reference actual code instead of guesses. Tours and file summaries are generated once and cached too. Supabase Auth handles accounts, and the app is deployed on Vercel (frontend) and Render (backend) at gitstation.nyc.

Challenges we ran into

  • AI accuracy: early diagrams had made-up connections and duplicate stations, so we added strict validation, cleanup, and retries

  • Rate limits: we hit Gemini’s free tier limit mid-hackathon, which pushed us to add retries with a fallback model, caching everywhere, and abuse protection (per-user and per-IP limits, a daily cap, and a topic guardrail on the conductor)

  • Huge repos: giant monorepos produce maps that are too shallow to be useful, so we flag repos that are too big instead of showing something misleading

  • Deployment: a CORS bug in production turned out to be backend changes that never got committed, a good lesson in checking what actually shipped

  • Silent failures: the good first issues section always looked empty because renamed repos returned redirects the code never followed

Accomplishments that we're proud of

  • A fully deployed, working app on our own domain, built in within 36 hours

  • A cohesive railway theme across every page, from the map to the loading screens

  • AI answers that link back to the map instead of just being text

  • The Grand Tour, which turns a confusing repo into a guided path

  • Shared caching so expensive AI work happens once and every user benefits

What we learned

  • How to get reliable structured output from an LLM, and why it always needs validation

  • Caching is what makes AI apps fast and affordable

  • Building custom nodes, edges, and camera animations in React Flow

  • Deploying a full stack app with environment variables, CORS, and auth

  • Collaborating with feature branches, pull requests, and merge conflicts under pressure

What's next for GitStation

  • Mapping huge repos by subfolder

  • GitHub login

  • Guiding users from a specific good first issue to the exact files they need to change

  • Saving tour progress and notes for each repo

Built With

Share this project:

Updates

Submission history