Final hackathon submission - CodeAtlas

DEMO_VIDEO_SCRIPT.md

@@ -0,0 +1,197 @@
+# 🎬 CodeAtlas Demo Video Script
+
+**Target Duration:** 2-3 minutes  
+**Format:** Screen recording with voiceover  
+**Tools:** OBS/Loom/QuickTime + microphone
+
+---
+
+## 📋 Pre-Recording Checklist
+
+- [ ] App running locally or on HuggingFace Space
+- [ ] Browser in incognito/clean state (no distracting tabs)
+- [ ] Screen resolution: 1920x1080 recommended
+- [ ] Microphone tested and working
+- [ ] API keys configured (Gemini, ElevenLabs)
+- [ ] Test repo URL ready: `https://github.com/gradio-app/gradio`
+
+---
+
+## 🎥 Video Structure
+
+### **INTRO (15 seconds)**
+
+**[Screen: Title card or app landing page]**
+
+> "Ever tried to understand a new codebase and felt completely lost? 
+> 
+> Meet CodeAtlas — an AI-powered tool that turns any GitHub repository into beautiful architecture diagrams, with voice explanations and interactive chat.
+>
+> Let me show you how it works."
+
+---
+
+### **SECTION 1: Analyze a Repository (45 seconds)**
+
+**[Screen: Generate page]**
+
+> "Start by pasting any GitHub URL. I'll use the Gradio repository as an example."
+
+**[Action: Paste `https://github.com/gradio-app/gradio` and click Generate]**
+
+> "CodeAtlas downloads the repository, filters out irrelevant files like node_modules and tests, and uses Google Gemini to analyze the code structure."
+
+**[Screen: Show loading indicator, then diagram appearing]**
+
+> "In seconds, you get a professional architecture diagram showing the main components, their relationships, and how data flows through the system."
+
+---
+
+### **SECTION 2: Explore the Diagram (30 seconds)**
+
+**[Screen: Explore page with diagram]**
+
+> "The diagram is fully interactive. You can adjust the layout direction..."
+
+**[Action: Change layout dropdown - TB to LR]**
+
+> "...modify spacing between nodes..."
+
+**[Action: Adjust rank/node separation sliders]**
+
+> "...and zoom in on specific areas."
+
+**[Action: Use zoom slider]**
+
+> "Every diagram is saved to history, so you can revisit previous analyses anytime."
+
+**[Action: Show history panel briefly]**
+
+---
+
+### **SECTION 3: Voice Narration (25 seconds)**
+
+**[Screen: Voice section in sidebar]**
+
+> "But here's where it gets really cool. Click the voice button, and CodeAtlas generates a natural audio explanation of the architecture."
+
+**[Action: Click Generate Voice / Play audio]**
+
+> "Powered by ElevenLabs, it's like having a senior engineer walk you through the codebase."
+
+**[Let audio play for 5-10 seconds as example]**
+
+---
+
+### **SECTION 4: AI Chat (25 seconds)**
+
+**[Screen: Chat panel]**
+
+> "Have questions? The AI chat knows everything about the codebase you just analyzed."
+
+**[Action: Type a question like "What is the main entry point of this application?"]**
+
+> "Ask about specific files, design patterns, or how components connect."
+
+**[Show AI response appearing]**
+
+> "It's context-aware and remembers your conversation."
+
+---
+
+### **SECTION 5: MCP Integration (20 seconds)**
+
+**[Screen: Settings page or MCP endpoint]**
+
+> "CodeAtlas is also an MCP server, meaning AI assistants like Claude can use it directly."
+
+**[Action: Show MCP endpoint URL or badge]**
+
+> "Four tools are exposed: analyze codebase, get architecture summary, chat with code, and list recent analyses."
+
+> "Connect it to Claude Desktop, Cursor, or any MCP-compatible client."
+
+---
+
+### **OUTRO (15 seconds)**
+
+**[Screen: App main page or GitHub repo]**
+
+> "CodeAtlas — understand any codebase in seconds, not hours.
+>
+> Try it free on HuggingFace Spaces, or check out the GitHub repo.
+>
+> Built for the MCP 1st Birthday Hackathon. Thanks for watching!"
+
+**[Screen: Show links]**
+- HuggingFace: `huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas`
+- GitHub: `github.com/aghilsabu/codeAtlas`
+
+---
+
+## 🎙️ Voiceover Tips
+
+1. **Pace:** Speak slightly slower than normal conversation
+2. **Energy:** Enthusiastic but not over the top
+3. **Pauses:** Leave 1-2 second gaps between sections for editing
+4. **Mistakes:** Don't restart — just pause and repeat the line (edit later)
+
+---
+
+## ✂️ Editing Notes
+
+- Add subtle background music (royalty-free, low volume)
+- Use zoom-in effects on key UI elements
+- Add text overlays for important URLs
+- Include captions/subtitles if possible
+- Export at 1080p, 30fps minimum
+
+---
+
+## 📤 Upload Checklist
+
+1. **YouTube:** Upload as unlisted or public
+2. **GitHub:** Drag video into a GitHub issue to get embed URL
+3. **README:** Update video placeholder with actual URL
+4. **Thumbnail:** Create eye-catching thumbnail with app screenshot
+
+---
+
+## 🎯 Key Messages to Convey
+
+- ✅ **Problem:** Understanding codebases is hard and time-consuming
+- ✅ **Solution:** AI-powered visualization + voice + chat
+- ✅ **Easy to use:** Just paste a URL
+- ✅ **Multiple AI models:** Gemini, GPT-4o support
+- ✅ **MCP-enabled:** Works with AI assistants
+- ✅ **Free to try:** Available on HuggingFace
+
+---
+
+## 📝 Alternative Short Script (60 seconds)
+
+For Twitter/X or short-form content:
+
+> "Paste a GitHub URL. Get an architecture diagram in seconds.
+>
+> [Show paste + generate]
+>
+> CodeAtlas uses AI to analyze any codebase and create professional visualizations.
+>
+> [Show diagram]
+>
+> Want to understand it better? Listen to an AI-generated explanation.
+>
+> [Play voice clip]
+>
+> Or ask questions in the chat.
+>
+> [Show chat]
+>
+> It's also an MCP server — connect it to Claude or Cursor.
+>
+> Try it free: huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas"
+
+---
+
+**Good luck with your recording! 🎬**

DEPLOY_HF.md

@@ -0,0 +1,246 @@
+# 🚀 Deploy CodeAtlas to HuggingFace Space
+
+Complete step-by-step guide to deploy CodeAtlas to the MCP-1st-Birthday HuggingFace Space for hackathon submission.
+
+---
+
+## 📋 Pre-Deployment Checklist
+
+Before deploying, ensure you have:
+
+- [ ] HuggingFace account
+- [ ] Access to `MCP-1st-Birthday` organization (request if needed)
+- [ ] Demo video recorded and uploaded to GitHub
+- [ ] Social media post published (X/Twitter) — **REQUIRED by hackathon**
+- [ ] README.md updated with actual video and social post links
+- [ ] All code committed to GitHub
+
+---
+
+## Step 1: Install HuggingFace CLI
+
+```bash
+pip install huggingface_hub
+```
+
+---
+
+## Step 2: Login to HuggingFace
+
+```bash
+huggingface-cli login
+```
+
+When prompted:
+1. Go to https://huggingface.co/settings/tokens
+2. Create a new token with **Write** access
+3. Paste the token in terminal
+
+---
+
+## Step 3: Create the HuggingFace Space
+
+1. Go to https://huggingface.co/new-space
+2. **Owner:** Select `MCP-1st-Birthday` organization
+3. **Space name:** `CodeAtlas`
+4. **License:** MIT
+5. **SDK:** Gradio
+6. **Hardware:** CPU Basic (free tier is fine)
+7. Click **Create Space**
+
+---
+
+## Step 4: Clone Your GitHub Repo (if not already)
+
+```bash
+# If starting fresh
+git clone https://github.com/aghilsabu/codeAtlas.git
+cd codeAtlas
+```
+
+---
+
+## Step 5: Add HuggingFace Space as Git Remote
+
+```bash
+# Add HF Space as a second remote
+git remote add hf https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+
+# Verify remotes
+git remote -v
+# Should show:
+# origin  https://github.com/aghilsabu/codeAtlas.git (fetch/push)
+# hf      https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas (fetch/push)
+```
+
+---
+
+## Step 6: Update README with Real Links
+
+Before pushing, update these placeholders in `README.md`:
+
+### Demo Video
+Replace this line:
+```
+https://github.com/user-attachments/assets/YOUR_VIDEO_ID
+```
+With your actual GitHub video URL (upload video to a GitHub issue/PR to get the link).
+
+### Social Media Post
+Replace this link:
+```
+https://x.com/your-post-link
+```
+With your actual X/Twitter post URL. **This is REQUIRED by hackathon rules!**
+
+---
+
+## Step 7: Commit All Changes
+
+```bash
+# Stage all changes
+git add -A
+
+# Commit
+git commit -m "Final hackathon submission - CodeAtlas"
+
+# Push to GitHub first (backup)
+git push origin main
+```
+
+---
+
+## Step 8: Push to HuggingFace Space
+
+```bash
+# Push to HF Space (this triggers deployment)
+git push hf main
+```
+
+If you get authentication errors:
+```bash
+# Use token-based URL
+git remote set-url hf https://<YOUR_HF_USERNAME>:<YOUR_HF_TOKEN>@huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+git push hf main
+```
+
+---
+
+## Step 9: Configure Secrets on HuggingFace
+
+Go to: **https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/settings**
+
+Scroll to **"Repository secrets"** and add:
+
+| Secret Name | Required | How to Get |
+|-------------|----------|------------|
+| `GEMINI_API_KEY` | ✅ **Yes** | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
+| `OPENAI_API_KEY` | Optional | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
+| `ELEVENLABS_API_KEY` | Optional | [elevenlabs.io/app/developers](https://elevenlabs.io/app/developers/api-keys) |
+
+⚠️ **Without GEMINI_API_KEY, the app won't work!**
+
+---
+
+## Step 10: Wait for Build & Verify
+
+1. **Watch the build:** https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/logs
+2. Build takes ~2-5 minutes
+3. Once "Running" appears, test the app
+
+### Test Checklist
+
+- [ ] App loads at https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+- [ ] Can analyze a GitHub repo (try: `https://github.com/gradio-app/gradio`)
+- [ ] Diagram generates correctly
+- [ ] Voice narration works (if ElevenLabs key added)
+- [ ] MCP endpoint responds: https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/gradio_api/mcp/sse
+
+---
+
+## 🔧 Troubleshooting
+
+### Build Fails
+```bash
+# Check logs at:
+https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/logs
+```
+Common issues:
+- Missing dependency in `requirements.txt`
+- Python version mismatch
+- Import errors
+
+### App Crashes on Startup
+- Verify `GEMINI_API_KEY` secret is set
+- Check that `app.py` exists in root directory
+- Look for import errors in logs
+
+### "No Space Disk Space"
+- Go to Settings → Factory Reboot
+- Or delete old files from `data/` folder
+
+### MCP Endpoint Not Working
+- Ensure `mcp_server=True` in `demo.launch()`
+- Test SSE endpoint directly in browser
+- Check that Gradio version is 5.x+
+
+### Permission Denied on Push
+```bash
+# Re-authenticate
+huggingface-cli login
+
+# Or use token in URL
+git remote set-url hf https://YOUR_USERNAME:YOUR_TOKEN@huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+```
+
+---
+
+## 📝 Hackathon Submission Requirements
+
+Per hackathon rules, ensure your submission has:
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| Submitted to `MCP-1st-Birthday` org | ⬜ | Must push to org Space, not personal |
+| Track tag in README | ✅ | `mcp-in-action-track-consumer` |
+| Social media post link | ⬜ | **REQUIRED** - Update README |
+| Demo video | ⬜ | Recommended - Update README |
+| Original work (Nov 14-30) | ✅ | Must be created during hackathon |
+
+---
+
+## 🔗 Quick Reference Links
+
+| Resource | URL |
+|----------|-----|
+| **Live App** | https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas |
+| **MCP SSE Endpoint** | https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/gradio_api/mcp/sse |
+| **Space Settings** | https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/settings |
+| **Build Logs** | https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/logs |
+| **Hackathon Page** | https://huggingface.co/MCP-1st-Birthday |
+| **HF Tokens** | https://huggingface.co/settings/tokens |
+
+---
+
+## ⚡ Quick Deploy Commands (TL;DR)
+
+```bash
+# One-time setup
+pip install huggingface_hub
+huggingface-cli login
+git remote add hf https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+
+# Deploy
+git add -A && git commit -m "Deploy to HF"
+git push origin main  # Backup to GitHub
+git push hf main      # Deploy to HF Space
+
+# Then add secrets at:
+# https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas/settings
+```
+
+---
+
+**Deadline: November 30, 2025, 11:59 PM UTC** ⏰
+
+Good luck! 🎉

README.md

@@ -8,14 +8,8 @@ sdk_version: "5.0.0"
 app_file: app.py
 pinned: false
 license: mit
-short_description: AI-powered codebase visualization with voice narration
 tags:
   - mcp-in-action-track-consumer
-  - mcp-in-action-track-enterprise
-  - mcp-in-action-track-creative
-  - building-mcp-track-consumer
-  - building-mcp-track-enterprise
-  - building-mcp-track-creative
   - mcp
   - gradio
   - llamaindex

SOCIAL_MEDIA_POST.md

@@ -0,0 +1,139 @@
+# Social Media Posts for CodeAtlas
+
+## Twitter/X Post
+
+```
+🎂 Submitting CodeAtlas for @HuggingFace MCP's 1st Birthday Hackathon!
+
+🏗️ Transform ANY GitHub repo into beautiful AI-generated architecture diagrams with voice narration in seconds!
+
+✨ Features:
+• 🗺️ AI-generated Graphviz diagrams
+• 🔊 @elevenlabsio voice explanations  
+• 💬 Chat with your codebase
+• 🤖 MCP Server integration
+
+🛠️ Built with:
+@Gradio | @LlamaIndex | @GoogleAI Gemini | @OpenAI GPT-5 | @elevenlabsio | @modal_labs
+
+🚀 Try it FREE: https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+
+📺 Demo: https://youtu.be/J8dcTLzNgpE
+
+#MCP1stBirthday #AI #CodeVisualization #Gradio #Gemini #OpenAI #LlamaIndex #Hackathon
+```
+
+---
+
+## Alternative Shorter Version (280 chars)
+
+```
+🎂 CodeAtlas - My entry for @HuggingFace MCP's 1st Birthday Hackathon!
+
+Turn any GitHub repo into AI-generated architecture diagrams with voice narration 🗺️🔊
+
+Built with Gradio, LlamaIndex, Gemini, OpenAI & ElevenLabs
+
+Try: https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+Demo: https://youtu.be/J8dcTLzNgpE
+
+#MCP1stBirthday
+```
+
+---
+
+## LinkedIn Version
+
+```
+🎂 Excited to submit CodeAtlas for HuggingFace's MCP 1st Birthday Hackathon!
+
+CodeAtlas is an AI-powered tool that transforms GitHub repositories into beautiful, interactive architecture diagrams with voice narration - making code understanding effortless.
+
+🌟 Key Features:
+• Instant repository analysis with AI
+• Interactive Graphviz architecture diagrams
+• Natural voice explanations via ElevenLabs TTS
+• Context-aware chat about your codebase
+• MCP Server integration for AI agents
+
+💡 Perfect for:
+✓ Onboarding new developers
+✓ Code reviews
+✓ Documentation
+✓ Understanding complex codebases
+
+🛠️ Tech Stack:
+Gradio, LlamaIndex, Google Gemini 3.0, OpenAI GPT-5, ElevenLabs, Modal, FastMCP
+
+🚀 Try it live: https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+📺 Watch demo: https://youtu.be/J8dcTLzNgpE
+
+Built in just 2 weeks for the MCP 1st Birthday Hackathon. Would love your feedback! 🙌
+
+#MCP1stBirthday #AI #MachineLearning #CodeVisualization #HuggingFace #OpenAI #Hackathon #OpenSource
+```
+
+---
+
+## Thread Version (for longer Twitter posts)
+
+**Tweet 1:**
+```
+🎂 Submitting CodeAtlas for @HuggingFace MCP's 1st Birthday Hackathon!
+
+An AI tool that turns GitHub repos into beautiful architecture diagrams with voice narration 🗺️🔊
+
+Thread 🧵👇
+```
+
+**Tweet 2:**
+```
+✨ What it does:
+• Paste any GitHub URL
+• AI analyzes the codebase
+• Get interactive Graphviz diagrams
+• Listen to architecture explanations
+• Chat to understand the code better
+
+Try: https://huggingface.co/spaces/MCP-1st-Birthday/CodeAtlas
+```
+
+**Tweet 3:**
+```
+🛠️ Built with best-in-class AI tools:
+• @Gradio for UI
+• @LlamaIndex for RAG
+• @GoogleAI Gemini 3.0
+• @OpenAI GPT-5
+• @elevenlabsio for voice
+• @modal_labs for deployment
+• FastMCP for protocol integration
+```
+
+**Tweet 4:**
+```
+📺 Watch it in action: https://youtu.be/J8dcTLzNgpE
+
+Perfect for:
+✓ Onboarding devs
+✓ Code reviews
+✓ Documentation
+✓ Learning new frameworks
+
+#MCP1stBirthday #AI #CodeVisualization
+```
+
+---
+
+## Copy Instructions:
+
+1. ✅ **Twitter/X Post:** https://x.com/aghilsabu/status/1995249175336997350?s=20
+2. ✅ **LinkedIn Post:** https://www.linkedin.com/posts/aghilsabu_codeatlas-ai-powered-codebase-visualization-share-7401015482310393857-vHRg
+3. ✅ Both links updated in README.md
+4. Ready to commit and deploy!
+
+**Tips:**
+- Tag relevant companies/projects to increase visibility
+- Post during peak hours (9-11 AM or 1-3 PM EST)
+- Add a screenshot or video preview if possible
+- Engage with comments to boost the algorithm

src/ui/components.py

@@ -173,7 +173,5 @@ def make_footer() -> str:
     return '''
         <div class="footer">
             Built for MCP's 1st Birthday Hackathon 🎂 · 
-            <a href="https://github.com/aghilsabu/codeAtlas" target="_blank">GitHub</a> · 
-            <a href="https://x.com/aghilsabu" target="_blank">@aghilsabu</a>
         </div>
     '''