Nexo: Turn Code into Stories You Can See and Hear

Nexo: The audiovisual GPS for code. We use Gemini and ElevenLabs to create visual maps and voice narration for repositories. See the flow, hear the logic, and understand complex systems in seconds.

Comment

Nexo: Turn Code into Stories You Can See and Hear 🚀

Project Story

💡 What Inspired Us

Every developer knows the pain: you join a new project, and you're immediately drowning in a sea of unfamiliar code. Thousands of files, cryptic function names, and zero documentation. You spend days—sometimes weeks—just trying to understand where to start.

We realized that while humanity has built incredible tools to write code, we've barely scratched the surface of tools to understand it. The inspiration struck us during a late-night debugging session: "What if code could tell its own story?"

Traditional documentation is static, outdated, and frankly... boring. But what if we could transform cold, lifeless text into a living, breathing narrative that you could both see and hear? What if onboarding to a codebase felt less like reading a technical manual and more like listening to an engaging podcast while watching an interactive map unfold?

That's when Nexo was born—a revolutionary platform that turns any GitHub repository into a multi-modal learning experience, combining AI-powered visual dependency graphs with podcast-style audio narration.

🎯 What Nexo Does

Nexo is an intelligent code documentation platform that transforms static repositories into interactive, multi-sensory experiences. Here's the magic:

  1. 🔗 Paste Any Repository URL
    Simply provide a GitHub link—no configuration, no SDK installation required.

  2. 🧠 AI-Powered Analysis
    Our Gemini-powered engine performs deep static analysis, extracting functions, classes, dependencies, and architectural patterns.

  3. 📊 Visual Code Maps
    Watch as your codebase transforms into an interactive dependency graph—zoom, pan, and click to explore module relationships and data flows.

  4. 🎧 Code Podcasts
    Listen to ElevenLabs-generated audio narrations that explain each file's purpose, logic, and integration points in natural, conversational language. Perfect for commuting, exercising, or giving your eyes a rest.

  5. ⚡ Lightning-Fast Access
    Once analyzed, documentation is cached and served instantly from our edge network—no waiting for subsequent visits.

🛠️ How We Built It

Building Nexo required orchestrating multiple cutting-edge technologies into a seamless pipeline:

🧠 Intelligence Layer

The Google Gemini API acts as our senior software architect:

  • Performs deep static analysis on repository code
  • Extracts function signatures, class hierarchies, and import graphs
  • Maps dependencies and call relationships
  • Generates human-readable summaries and architectural insights
  • Outputs structured JSON for downstream processing

Key Innovation: We developed smart chunking algorithms to handle repositories larger than Gemini's context window. The system prioritizes entry points and high-traffic modules, then incrementally analyzes related components while preserving semantic relationships.

# Simplified chunking logic
async def chunk_repository(files: List[File]) -> List[Chunk]:
    """
    Break large codebases into analyzable chunks
    Prioritize: entry points → high-traffic files → dependencies
    """
    chunks = []
    prioritized = sort_by_importance(files)  # Based on imports, LOC

    for file_group in batch(prioritized, size=MAX_TOKENS // AVG_FILE_SIZE):
        chunks.append(create_semantic_chunk(file_group))

    return chunks

🎙️ Audio Synthesis Layer

ElevenLabs API transforms technical analysis into engaging narration:

  • Converts code summaries into conversational podcast scripts
  • Generates natural, human-like voice audio (using voices like Adam and Rachel)
  • Creates segmented chapters for different modules
  • Optimizes audio compression for web delivery

Challenge Overcome: ElevenLabs has processing latency. We solved this with:

  • Asynchronous job queues with real-time progress indicators
  • Pre-generation for popular repositories
  • MongoDB + CDN caching for instant playback on repeat visits

🏗️ Infrastructure Layer

  • FastAPI Backend: High-performance Python REST API with async/await for concurrent analysis
  • MongoDB Atlas: Stores graph metadata, audio links, and analysis results with optimized schemas for graph traversal
  • Docker/Podman: Containerized analysis environments ensure security and reproducibility
  • CloundFlare Cloud: Scalable compute for repository cloning and processing

🚩 Challenges We Faced

1. Context Window Limitations 🧩

The Problem:
Even Gemini's extended context window (128k tokens) couldn't handle enterprise codebases with millions of lines of code.

The Solution:
We developed a semantic chunking algorithm that:

  • Analyzes file structure first (shallow pass)
  • Prioritizes entry points (main.py, index.tsx, etc.)
  • Groups related modules using import graph analysis
  • Performs incremental deep analysis on high-priority sections

Math Behind It:
If we have:

  • N files averaging T tokens each
  • A context limit of C

The number of chunks required is:

We use 0.8C to leave room for prompts and response tokens.

2. Real-Time Audio Synthesis ⚡

The Problem:
ElevenLabs takes 10–30 seconds to generate high-quality audio — unacceptable for real-time UX.

The Solution:

  • Async Processing: Background jobs with WebSocket progress updates
  • Smart Caching: MongoDB stores generated audio; CDN serves it globally
  • Pre-generation: Popular repositories (React, Vue, etc.) analyzed proactively

🧠 What We Learned

The Power of Multi-Modal Learning

We discovered that combining visual graphs with auditory explanations creates a dual-encoding effect that significantly reduces cognitive load:

[ L_c \approx \frac{\text{Visual Flow} \cdot \text{Audio Context}}{T_x} ]

Where:

  • ( L_c ) = Cognitive Load (mental effort)
  • ( T_x ) = Complexity of raw documentation

Key Insights

  • 📊 65% of people are visual learners — graphs leverage spatial memory
  • 🎧 Auditory reinforcement creates dual encoding in memory
  • ⚡ Reduced context switching — see the big picture without jumping between files
  • 🧠 Pattern recognition — visual patterns reveal architectural insights text can't convey

🔧 Technical Lessons

🎨 Prompt Engineering Is an Art

We iterated 40+ times to ensure Gemini outputs strictly valid JSON for real-time rendering.
Small changes like:

“Respond ONLY with JSON, no markdown”

made huge differences.

🧯 AI Hallucination Mitigation

Always validate AI outputs against the actual code structure.
We cross-reference Gemini’s dependency graphs with static analysis to catch hallucinations.

🚀 Caching Is King

A well-designed cache strategy transformed 30-second analyses into instant experiences on repeat visits.

🧩 UX > Features

We cut 40% of planned features to polish the core experience.
A perfect podcast is better than a buggy podcast + 10 half-baked features.

🛡️ TypeScript Saves Time

Type safety caught hundreds of bugs before they reached production — especially in complex API integrations.

🎯 Conclusion

Nexo represents a paradigm shift in how developers interact with codebases. We've proven that technical documentation doesn't have to be dry, overwhelming, or outdated. By combining the power of AI-driven analysis with multi-modal learning experiences, we've created something truly unique: a platform that makes code exploration intuitive, engaging, and accessible.

Throughout this hackathon, we transformed an ambitious idea into a working product that addresses a real pain point every developer faces. We didn't just build features—we built an experience that respects how humans actually learn: through visual patterns, conversational narratives, and interactive exploration.

The challenges we overcame—from Gemini's context limitations to real-time audio synthesis—taught us invaluable lessons about system architecture, AI integration, and user experience design. Every obstacle became an opportunity to innovate, whether through semantic chunking algorithms, intelligent caching strategies, or asynchronous processing pipelines.

But more importantly, Nexo is just the beginning. The foundation we've built opens doors to countless possibilities: AI chat assistants that answer questions about your codebase, auto-generated documentation that stays current, collaborative learning sessions, and educational paths tailored to each developer's needs.

We envision a future where:

  • 🚀 Onboarding takes hours, not weeks
  • 🎓 Learning is immersive and enjoyable
  • 🤝 Knowledge is democratized across teams
  • 🌍 Every developer, regardless of experience, can understand any codebase

Nexo isn't just a hackathon project—it's a mission to make code human again.

To every developer who's ever felt lost in a new repository, who's spent countless hours deciphering legacy code, or who's wished documentation could just... explain things better—this is for you.

The code can now tell its own story. Welcome to Nexo.

Built with passion, powered by AI, designed for developers.

Hacktown-BSB Team | MLH Hackathon 2026

Share this project:

Updates