RepoRoast — About the Project
Inspiration
RepoRoast was inspired by a simple but painful developer experience: opening an unfamiliar GitHub repository and realizing that understanding how the system works takes far longer than reading individual files.
While reviewing repositories—especially hackathon projects, side projects, or AI-generated code—I noticed a pattern:
- Most tools summarize code superficially
- Others require tedious line-by-line exploration
- Almost none explain the system-level architecture clearly
What was missing was an explanation that was:
- Accurate
- Memorable
- Honest
That’s where the idea of a roast-style engineering podcast came from. Humor makes architecture stick—but only when it’s grounded in truth.
What I Learned
This project taught me the importance of architecture-first reasoning.
Key learnings:
- Building deterministic, rule-based code analysis without relying on AI
- Controlling large-model behavior by constraining inputs, not post-filtering outputs
- Designing systems where trust and reliability matter more than raw intelligence
- Using AI effectively with a single, well-structured reasoning call
I also learned that humor in technical systems only works when correctness is non-negotiable.
How I Built It
RepoRoast is built using Python and Flask, optimized for simplicity and reliability.
The system works in three major stages:
1. Repository Analysis (Non-AI)
- Ingests a public GitHub repository
- Preserves directory structure
- Classifies files and roles
- Constructs a complete architectural blueprint
- Fully deterministic and repeatable
2. Single AI Reasoning Step
- Only the blueprint is sent to the AI
- One batch call, no per-file prompts
- Prevents hallucinations
- Forces system-level reasoning
3. Multimodal Output
The AI generates:
- A two-speaker roast-style dialogue
- A Mermaid architecture diagram
- A developer reading guide
Audio output is produced using Google Text-to-Speech, with two distinct voices for clarity and engagement.
Design goal: maximize signal while minimizing AI surface area.
Challenges Faced
Controlling AI Behavior
The biggest challenge was avoiding over-engineering. Instead of adding more prompts or filters, I focused on designing better intermediate representations.
Humor vs Correctness
Every joke had to map directly to a real architectural decision. No exaggerations, no invented problems.
Demo Reliability
Live demos mattered.
- Rate limiting
- Caching
- Deterministic preprocessing
All were essential to ensure the system never failed under pressure.
Future Scope
RepoRoast is intentionally focused today: architecture-first understanding with a single reliable AI pass. Future improvements build on this foundation without changing the core philosophy.
Smarter Architectural Signals
- Dependency cycles
- Unused modules
- Cross-layer coupling
- Deeper static insights
All without adding per-file AI calls.
Private & Enterprise Repositories
Authenticated access for:
- Internal onboarding
- Code reviews
- Technical audits
Historical & Comparative Analysis
- Compare commits or branches
- Detect architectural drift
- Explain how a system evolved—and where it went wrong
Custom Roast Profiles
Selectable tones:
- Beginner-friendly
- Strict reviewer
- Production-readiness focused
Same constraints, different perspectives.
IDE & CI Integration
- Run as a pre-merge check
- IDE extensions
- Generate an architectural podcast when major structural changes occur
Vision
RepoRoast does not aim to replace human reviewers.
Its goal is to make architectural understanding fast, honest, and unavoidable—especially in large, messy, or unfamiliar codebases.
RepoRoast is an experiment in making software architecture:
- Understandable
- Verifiable
- Memorable
Without pretending that every codebase is perfect.
Log in or sign up for Devpost to join the conversation.