A month of stolen hours, broken APIs, and one idea that wouldn't let me go.
There's a specific kind of frustration that nobody really talks about when they tell you to "just contribute to open source."
It's not the frustration of not knowing how to code. It's the frustration of knowing how to code, sitting in front of a real codebase, and still having absolutely no idea where to begin.
That was me. And that feeling is what built Spectra.
The Moment It Started
I remember opening the Meshery repository for the first time like it was yesterday.
I'd been hearing about it in communities a massive, well-respected open source project. People were contributing, getting PRs merged, building their profiles. I wanted in. I cloned the repo, opened it in VS Code, and just... sat there.
The file tree went on forever. Folders inside folders inside folders. I didn't know if I should start with the README (which was long and mostly about setup), or browse the source (which was overwhelming), or just grep for something random and hope it led somewhere useful.
I felt all three things at once — frustrated that something this important felt so inaccessible, genuinely curious about what was inside, and honestly a little jealous of the people who seemed to just know how to navigate these things. Like there was some unspoken skill everyone else had developed and nobody had taught me.
I spent three days in that repo. Not contributing. Not opening a PR. Just reading files, backtracking, losing context, starting over.
That's when the question hit me, quietly, almost as an afterthought:
Why doesn't a tool exist that just shows you the architecture?
Not documentation. Not a README. An actual visual, intelligent map of how the code is organized — one that explains itself in plain English.
I couldn't find one. So I decided to build it.
What Spectra Is
Spectra is a codebase intelligence tool. You paste any public GitHub URL, hit Analyze, and within a few seconds you get an interactive architectural map of the entire repository — organized into tiers, explained in plain English, and explorable through AI-powered panels.
It shows you:
- The root of the project and what it does
- The major domains — the big logical chunks
- The sub-systems inside each domain
- The entry point files that actually run things
Click any node and get a breakdown of what it does, why it exists, how it works internally, and exactly where a newcomer should start. Open the chat and ask Sentinel anything — "where should I start?", "what's the most important file?", "how does authentication work here?"
It's the tool I wish had existed when I opened Meshery for the first time.
Building It — The Real Story
I want to be honest about what the past months actually looked like, because it wasn't a clean linear process and I think pretending otherwise would be doing a disservice to anyone reading this.
It started as just a vision
My original idea was simple:
- Take a GitHub repo
- Run it through an AI
- Get back a visual graph
That was the whole thing. I wasn't thinking about chat panels or onboarding guides or design systems. I just wanted the one core feature — analyze and visualize.
I'm a CS undergrad. I've been self-taught in a lot of ways alongside my degree — picking up frameworks, building side projects, learning by doing. I'd used FastAPI before. I'd built things in Next.js. But I'd never tried to wire an LLM into a real product, never built a node-canvas interface.
This was going to be a proper stretch.
Stealing time wherever I could
I didn't have dedicated "Spectra hours." I worked on this whenever I could steal time — between lectures, during lunch, after assignments were submitted at midnight. Some days I'd get two uninterrupted hours. Some days I'd get twenty minutes and spend most of it just re-reading where I'd left off.
There's something both humbling and motivating about that kind of building. You can't afford to waste the time you have. Every session had to move something forward.
The Part That Nearly Broke Me — The Backend
I want to be honest about this part specifically because it was the hardest and it's the part I'm most proud of getting through.
My vision was clear. The frontend, the visualization, the way the map should look and feel — I could see all of that in my head. That part excited me.
The backend was a different story.
Getting the GitHub API to reliably return a repo's file tree, handling rate limits gracefully, parsing that tree into something meaningful, building the prompt that would make the AI return consistent structured JSON every single time — every single one of these was its own mini-war.
The AI part especially. LLMs are creative in ways that are wonderful for conversation and catastrophic for structured data pipelines. I'd get perfect JSON ninety percent of the time. Then I'd try a different repo and get JSON wrapped in markdown code fences. Or JSON with a paragraph of commentary before it. Or valid JSON that failed my graph validation because a node had a tier value of "1" instead of 1.
I had to build a whole extraction and validation layer just to make the output reliable. I added Groq as the primary inference engine and Gemini with key rotation as a fallback. I wrote a _validate_graph() function that checks node count, edge count, required fields — and if anything fails, it tries again with a different model.
There were nights I'd spend hours debugging why a specific repo kept returning malformed output, fix it, and then find a different repo that broke it in a new way.
It was the most unglamorous part of the whole project. No beautiful UI, no satisfying visual result — just me, a terminal, and JSON that refused to cooperate.
But I kept coming back to that original feeling. The one I had sitting in front of Meshery. And it kept me going.
The Design — Where I Came Alive
If the backend was the part that tested my patience, the design was the part that gave me energy.
I care deeply about UI/UX. Not just making things pretty making things feel right. Making an interface that communicates what it is without needing instructions. Making interactions that feel satisfying, not just functional.
I chose a neobrutalist aesthetic deliberately. Thick black borders. Bold uppercase typography. Hard shadow offsets. High contrast everywhere. It's opinionated design — the kind that makes a product memorable instead of forgettable. In a world full of generic rounded-corner SaaS dashboards, I wanted Spectra to look like it had a personality.
Some specific decisions I'm proud of:
The tier-by-tier reveal animation. When the map loads, nodes don't all appear at once. They come in tier by tier — root first, then domains fan out, then sub-systems, then entry points. This isn't just aesthetic. The animation teaches you the hierarchy as it builds. You watch the structure emerge. By the time the last tier appears, you already have a mental model of the codebase's shape.
The SimulationWidget. A mini animated pipeline in the corner of the reveal page showing GitHub → Scraper → AI Brain → Map, with flying data packets between stages and a live terminal log. It's both a visual explainer and a piece of product personality.
The click animation on the Run button feels like a physical button press — it sinks down, loses its shadow, comes back up. Small detail. Huge feel difference.
The IntroModal. A three-step onboarding flow — name, role, goals — that saves to localStorage and never appears again. It took maybe a day to build and polish. But it transforms the first experience from "tool opened" to "tool that knows me." That matters.
Node expansion. When you click a node, five detail cards expand directly below it. The challenge was doing this without the camera jumping around. It feels like the map is breathing, not teleporting.
The Tech, Honestly
Here's what's running under the hood:
Backend:
- FastAPI for the async REST API — handles concurrent AI calls cleanly
- Groq with LLaMA 3.3 70B as the primary inference engine — it's fast, often under 2 seconds
- Gemini 2.0 Flash with multiple API key rotation as fallback
- GitHub's tree API for recursive file ingestion
- Custom layout engine for computing node positions by tier
Frontend:
- Next.js 16 with the App Router
- React Flow for the interactive node canvas
- Zustand for global state (the graph data persists across page navigations)
- Tailwind CSS for every style decision
- Three.js for the animated Sentinel orb on the homepage
- Lucide React for icons
Deployed on:
- Render — FastAPI backend
- Vercel — Next.js frontend
The whole infrastructure costs exactly zero dollars a month. The only real tradeoff is Render's free tier spins down after 15 minutes of inactivity — first request after that takes about 30-50 seconds to wake up. For a portfolio project, that's a completely acceptable tradeoff.
What I Actually Learned
Not the resume version. The real version.
Shipping teaches you things no amount of local testing does. The CORS errors, the hardcoded localhost URLs, the environment variable that wasn't baking into the build — none of these showed up until I actually deployed. I could have spent another week "preparing" and still hit every single one of them. Just ship and fix.
AI output is not a given, it's a contract you have to enforce. You can't just send a prompt and trust the response. You have to validate, sanitize, have fallbacks, and handle the weird edge cases. The prompt engineering layer of this project taught me more about working with LLMs than any tutorial I've read.
Design is a form of respect. Every interaction in Spectra — the animations, the button feels, the panel transitions — is a message to the user that says someone cared about your experience here. That matters to me. It's not decoration. It's communication.
Dedication looks unglamorous most of the time. It looks like twenty stolen minutes between classes. It looks like debugging the same JSON parsing issue for the third night in a row. It looks like almost closing the laptop and then opening it again because the idea still won't leave you alone. That's what a month of building actually looks like. And I wouldn't trade it.
Try It
Spectra → sspectra-ai.vercel.app
Paste any public GitHub URL and see what happens. Try https://github.com/meshery/meshery the repo that started all of this. Or try your own current project. Or a repo you've been meaning to explore but never had the map for.
If it saves you even one of those three-day "just reading files" sessions I went through, then the stolen hours were worth every minute.
GitHub: github.com/Xynash/Spectra
If this resonated, a ⭐ means a lot for a first public project. More to come !!
Ansh Sharma. CS undergrad, self-taught developer, UI/UX obsessive. Building things that should exist.
Top comments (1)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.