feat: add Gradio web UI with interactive diagram explorer

src/ui/__init__.py

@@ -0,0 +1,17 @@
+"""
+CodeAtlas UI Module
+
+Gradio-based user interface components.
+"""
+
+from .app import create_app
+from .components import make_nav_bar, make_loading_html, make_stats_bar
+from .styles import CUSTOM_CSS
+
+__all__ = [
+    "create_app",
+    "make_nav_bar",
+    "make_loading_html",
+    "make_stats_bar",
+    "CUSTOM_CSS",
+]

src/ui/app.py

@@ -0,0 +1,666 @@
+"""
+CodeAtlas UI Application
+
+Main Gradio application with multi-page routing.
+Implements the three-page layout: Generate, Explore, Settings.
+"""
+
+import os
+import json
+import asyncio
+import logging
+import gradio as gr
+from pathlib import Path
+from typing import Optional, Tuple, List, Dict, Any
+
+from ..config import get_config, Config, SESSION_FILE, AUDIOS_DIR
+from ..core.repository import RepositoryLoader
+from ..core.analyzer import CodeAnalyzer
+from ..core.diagram import DiagramGenerator, LayoutOptions
+from ..integrations.voice import generate_audio_summary
+from .components import (
+    make_nav_bar,
+    make_loading_html,
+    make_stats_bar,
+    make_error_html,
+    make_empty_state_html,
+    make_hero_section,
+    make_footer,
+)
+from .styles import CUSTOM_CSS
+
+logger = logging.getLogger("codeatlas.ui")
+
+# Global instances
+_repository_loader: Optional[RepositoryLoader] = None
+_diagram_generator: Optional[DiagramGenerator] = None
+
+
+def get_repository_loader() -> RepositoryLoader:
+    """Get or create repository loader instance."""
+    global _repository_loader
+    if _repository_loader is None:
+        _repository_loader = RepositoryLoader()
+    return _repository_loader
+
+
+def get_diagram_generator() -> DiagramGenerator:
+    """Get or create diagram generator instance."""
+    global _diagram_generator
+    if _diagram_generator is None:
+        _diagram_generator = DiagramGenerator()
+    return _diagram_generator
+
+
+# Session state management
+def load_session_state() -> Dict[str, Any]:
+    """Load session state from file."""
+    try:
+        if SESSION_FILE.exists():
+            with open(SESSION_FILE, "r") as f:
+                return json.load(f)
+    except Exception as e:
+        logger.warning(f"Failed to load session: {e}")
+    return {
+        "dot_source": None,
+        "repo_name": "",
+        "stats": {},
+        "api_key": "",
+        "openai_api_key": "",
+        "elevenlabs_api_key": "",
+        "model": "Gemini 2.5 Pro",
+        "pending_request": None,
+    }
+
+
+def save_session_state(data: Dict[str, Any]) -> bool:
+    """Save session state to file."""
+    try:
+        existing = load_session_state()
+        existing.update(data)
+        with open(SESSION_FILE, "w") as f:
+            json.dump(existing, f)
+        return True
+    except Exception as e:
+        logger.warning(f"Failed to save session: {e}")
+        return False
+
+
+def get_current_model() -> str:
+    """Get the current model from session state."""
+    config = get_config()
+    return config.current_model
+
+
+def get_model_choices() -> List[str]:
+    """Get available model choices."""
+    config = get_config()
+    return list(config.models.all_models.keys())
+
+
+def create_app():
+    """Create the Gradio application with multi-page routing."""
+    config = get_config()
+    
+    # ==================== MAIN PAGE (Generate) ====================
+    with gr.Blocks(title="CodeAtlas - AI Codebase Visualizer", fill_height=True) as app:
+        gr.Navbar(visible=False)
+        
+        # State
+        file_input = gr.State(value=None)
+        
+        # Top nav bar
+        with gr.Row(elem_classes="nav-bar-row"):
+            nav_bar = gr.HTML(make_nav_bar("generate"))
+            model_selector = gr.Dropdown(
+                choices=get_model_choices(),
+                value=get_current_model(),
+                show_label=False,
+                container=False,
+                scale=0,
+                min_width=180,
+                elem_classes="model-dropdown-nav"
+            )
+        
+        # Hero section
+        gr.HTML(make_hero_section())
+        
+        # Input section
+        with gr.Row():
+            gr.Column(scale=1, min_width=50)
+            with gr.Column(scale=3, min_width=400):
+                github_input = gr.Textbox(
+                    placeholder="github.com/owner/repo or paste a GitHub URL",
+                    label="GitHub Repository",
+                    lines=1,
+                )
+                with gr.Row():
+                    analyze_btn = gr.Button("🚀 Generate Diagram", variant="primary", scale=2)
+                    upload_btn = gr.UploadButton("📁 Upload ZIP", file_types=[".zip"], scale=1, variant="secondary")
+                
+                error_msg = gr.HTML(visible=False)
+            gr.Column(scale=1, min_width=50)
+        
+        # Footer
+        gr.HTML(make_footer())
+        
+        # Event handlers
+        def start_analysis(file_path, github_url, selected_model):
+            """Validate input and prepare for analysis."""
+            logger.info(f"start_analysis: file={file_path}, url={github_url}, model={selected_model}")
+            
+            if not file_path and (not github_url or not github_url.strip()):
+                raise gr.Error("Please enter a GitHub URL or upload a ZIP file")
+            
+            session = load_session_state()
+            if not session.get("api_key"):
+                raise gr.Error("API Key not configured. Please go to Settings first.")
+            
+            # Save model selection and pending request
+            save_session_state({
+                "model": selected_model,
+                "pending_request": {
+                    "github_url": github_url.strip() if github_url else None,
+                    "file_path": file_path,
+                },
+                "dot_source": None,
+                "repo_name": "",
+                "stats": {},
+            })
+            
+            return gr.update(visible=False), None, True
+        
+        do_redirect = gr.State(False)
+        
+        # Wire up events
+        for trigger in [analyze_btn.click, github_input.submit]:
+            trigger(
+                fn=start_analysis,
+                inputs=[file_input, github_input, model_selector],
+                outputs=[error_msg, file_input, do_redirect]
+            ).success(
+                fn=None,
+                js="() => { window.location.href = '/explore'; }"
+            )
+        
+        upload_btn.upload(
+            fn=lambda f, m: start_analysis(f, "", m),
+            inputs=[upload_btn, model_selector],
+            outputs=[error_msg, file_input, do_redirect]
+        ).success(
+            fn=None,
+            js="() => { window.location.href = '/explore'; }"
+        )
+        
+        # Model change handler
+        def on_model_change(model):
+            save_session_state({"model": model})
+            config.current_model = model
+            config.save_to_session()
+        
+        model_selector.change(fn=on_model_change, inputs=[model_selector])
+        app.load(fn=get_current_model, outputs=[model_selector])
+    
+    # ==================== EXPLORE PAGE ====================
+    with app.route("explore") as explore_page:
+        current_dot = gr.State(value=None)
+        chat_history = gr.State(value=[])
+        
+        # Nav bar
+        with gr.Row(elem_classes="nav-bar-row"):
+            explore_nav = gr.HTML(make_nav_bar("explore"))
+            explore_model = gr.Dropdown(
+                choices=get_model_choices(),
+                value=get_current_model(),
+                show_label=False,
+                container=False,
+                scale=0,
+                min_width=180,
+                elem_classes="model-dropdown-nav"
+            )
+        
+        # Left sidebar - History & Layout
+        with gr.Sidebar(position="left", open=False):
+            gr.Markdown("#### 📜 History")
+            history_dropdown = gr.Dropdown(
+                choices=[],
+                label="Saved Diagrams",
+                interactive=True,
+            )
+            with gr.Row():
+                load_history_btn = gr.Button("Load", variant="primary", size="sm", scale=2)
+                refresh_history_btn = gr.Button("🔄", variant="secondary", size="sm", scale=1, min_width=40)
+            
+            gr.Markdown("---")
+            gr.Markdown("#### 📐 Layout")
+            layout_direction = gr.Dropdown(
+                choices=["Top → Down", "Left → Right", "Bottom → Up", "Right → Left"],
+                value="Top → Down",
+                label="Direction",
+            )
+            layout_splines = gr.Dropdown(
+                choices=["polyline", "ortho", "spline", "line"],
+                value="polyline",
+                label="Edge Style",
+            )
+            layout_nodesep = gr.Slider(0.1, 2.0, 0.5, step=0.1, label="Node Spacing")
+            layout_ranksep = gr.Slider(0.25, 3.0, 0.75, step=0.25, label="Layer Spacing")
+            zoom_slider = gr.Slider(0.25, 3.0, 1.0, step=0.1, label="Zoom")
+            apply_layout_btn = gr.Button("Apply Changes", variant="primary")
+        
+        # Right sidebar - Audio & Chat
+        with gr.Sidebar(position="right", open=False, width=400, elem_classes="sidebar-right"):
+            with gr.Row(elem_classes="audio-row"):
+                audio_gen_btn = gr.Button("🔊 Generate Audio", variant="primary", size="sm", elem_classes="audio-gen-btn")
+            audio_status = gr.HTML("", elem_classes="audio-status")
+            audio_player = gr.Audio(
+                label=None,
+                show_label=False,
+                type="filepath",
+                sources=[],
+                interactive=False,
+                elem_classes="audio-player-compact"
+            )
+            
+            gr.HTML('<div style="font-size: 0.85rem; font-weight: 600; color: #374151; padding: 0.5rem 0;">💬 Ask About Code</div>')
+            
+            chatbot = gr.Chatbot(
+                show_label=False,
+                placeholder="Ask questions about the architecture...",
+                elem_id="codeatlas-chat",
+                avatar_images=(None, "https://www.gstatic.com/lamda/images/gemini_sparkle_v002_d4735304ff6292a690345.svg"),
+                layout="panel",
+                autoscroll=True
+            )
+            
+            with gr.Column(elem_classes="chat-input-container"):
+                with gr.Row(elem_classes="chat-input-row"):
+                    chat_input = gr.Textbox(
+                        placeholder="Ask about the architecture...",
+                        show_label=False,
+                        scale=6,
+                        container=False,
+                        lines=1,
+                    )
+                    chat_send_btn = gr.Button("➤", variant="primary", size="sm", scale=1, min_width=40)
+        
+        # Main content
+        stats_output = gr.HTML("")
+        diagram_output = gr.HTML(make_loading_html("⏳", "Loading..."))
+        
+        # Async process function
+        async def process_pending_request():
+            """Process a pending analysis request with streaming updates."""
+            session = load_session_state()
+            pending = session.get("pending_request")
+            
+            # No pending request - show existing or empty
+            if not pending or not (pending.get("github_url") or pending.get("file_path")):
+                dot_source = session.get("dot_source")
+                if dot_source:
+                    generator = get_diagram_generator()
+                    diagram = generator.render(dot_source, repo_name=session.get("repo_name", ""))
+                    
+                    # Count nodes/edges for existing diagram
+                    node_count, edge_count = generator._count_nodes_edges(dot_source)
+                    
+                    stats = make_stats_bar(
+                        repo_name=session.get("repo_name", ""),
+                        files_processed=session.get("stats", {}).get("files_processed", 0),
+                        total_characters=session.get("stats", {}).get("total_characters", 0),
+                        model_name=session.get("model", ""),
+                        node_count=node_count,
+                        edge_count=edge_count,
+                    )
+                    yield diagram, stats, dot_source
+                else:
+                    yield make_empty_state_html(), "", None
+                return
+            
+            # Get request details
+            github_url = pending.get("github_url")
+            file_path = pending.get("file_path")
+            model_choice = session.get("model", "Gemini 2.5 Pro")
+            
+            config = get_config()
+            model_name = config.models.get_model_id(model_choice)
+            
+            # Get API key
+            if config.models.is_openai_model(model_name):
+                api_key = session.get("openai_api_key", "")
+                if not api_key:
+                    yield make_error_html("OpenAI API key required", "🔑", "/settings", "Add Key →"), "", None
+                    return
+            else:
+                api_key = session.get("api_key", "")
+                if not api_key:
+                    yield make_error_html("Gemini API key required", "🔑", "/settings", "Add Key →"), "", None
+                    return
+            
+            # Clear pending request
+            save_session_state({"pending_request": None})
+            
+            # Step 1: Download/Process
+            display_name = ""
+            yield make_loading_html("📥", "Downloading repository..." if github_url else "Processing file..."), "", None
+            await asyncio.sleep(0.1)  # Allow UI to update
+            
+            loader = get_repository_loader()
+            if github_url:
+                result = loader.load_from_github(github_url)
+                parts = github_url.rstrip("/").split("/")
+                display_name = "/".join(parts[-2:]) if len(parts) >= 2 else github_url
+            else:
+                result = loader.load_from_file(file_path)
+                display_name = Path(file_path).stem if file_path else "upload"
+            
+            if result.error:
+                yield make_error_html(result.error), "", None
+                return
+            
+            # Step 2: Show files found (display for 2s while not blocking)
+            yield make_loading_html(
+                "🔍", 
+                f"Extracted {result.stats.files_processed} files",
+                f"{result.stats.total_characters:,} characters • Preparing AI analysis..."
+            ), "", None
+            await asyncio.sleep(1.5)  # Show extraction results for 2 seconds
+            
+            # Step 3: AI Analysis - this step shows while actual analysis happens
+            yield make_loading_html(
+                "🧠",
+                "AI analyzing code structure...",
+                f"Using {model_choice}"
+            ), "", None
+            await asyncio.sleep(1.5)  # Brief pause to render before heavy work
+            
+            # Step 4: Generate diagram
+            try:
+                yield make_loading_html("🗺️", "Generating architecture diagram...", f"{model_choice} • This may take a moment..."), "", None
+                await asyncio.sleep(0.1)  # Allow UI to update
+                
+                analyzer = CodeAnalyzer(api_key=api_key, model_name=model_name)
+                analysis = analyzer.generate_diagram(result.context)
+                
+                if not analysis.success:
+                    yield make_error_html(analysis.error), "", None
+                    return
+                
+                # Prepare metadata for saving
+                diagram_metadata = {
+                    "model_name": model_choice,
+                    "files_processed": result.stats.files_processed,
+                    "total_characters": result.stats.total_characters,
+                }
+                
+                # Save results
+                save_session_state({
+                    "dot_source": analysis.content,
+                    "repo_name": display_name,
+                    "stats": result.stats.as_dict,
+                    "model": model_choice,
+                })
+                
+                # Render diagram with metadata
+                generator = get_diagram_generator()
+                diagram = generator.render(
+                    analysis.content, 
+                    repo_name=display_name, 
+                    save_to_history=True,
+                    metadata=diagram_metadata
+                )
+                
+                # Count nodes/edges for stats bar
+                node_count, edge_count = generator._count_nodes_edges(analysis.content)
+                
+                stats = make_stats_bar(
+                    repo_name=display_name,
+                    files_processed=result.stats.files_processed,
+                    total_characters=result.stats.total_characters,
+                    model_name=model_choice,
+                    node_count=node_count,
+                    edge_count=edge_count,
+                )
+                
+                yield diagram, stats, analysis.content
+                
+            except Exception as e:
+                logger.exception("Analysis failed")
+                yield make_error_html(str(e)), "", None
+        
+        def apply_layout(dot_source, direction, splines, nodesep, ranksep, zoom):
+            """Apply layout changes to the diagram."""
+            if not dot_source:
+                return make_empty_state_html("No diagram to adjust.")
+            
+            layout = LayoutOptions.from_ui(direction, splines, nodesep, ranksep, zoom)
+            generator = get_diagram_generator()
+            return generator.render(dot_source, layout)
+        
+        def load_from_history(selected):
+            """Load a diagram from history with metadata."""
+            if not selected:
+                return make_empty_state_html("Select a diagram."), "", None, [], []
+            
+            generator = get_diagram_generator()
+            dot_source, metadata = generator.load_from_history_with_metadata(selected)
+            
+            if not dot_source:
+                return make_error_html("Diagram not found"), "", None, [], []
+            
+            # Extract repo name from filename or metadata
+            name = selected.replace("raw_", "").replace(".dot", "")
+            parts = name.split("_")
+            repo_name = metadata.get("repo_name") if metadata else None
+            if not repo_name:
+                repo_name = "_".join(parts[:-2]) if len(parts) > 2 else parts[0] if parts else "local"
+            
+            diagram = generator.render(dot_source, repo_name=repo_name)
+            
+            # Always count nodes/edges from DOT source for accurate stats
+            node_count, edge_count = generator._count_nodes_edges(dot_source)
+            
+            # Build stats bar with all available metadata
+            stats = make_stats_bar(
+                repo_name=repo_name,
+                files_processed=metadata.get("files_processed", 0) if metadata else 0,
+                total_characters=metadata.get("total_characters", 0) if metadata else 0,
+                model_name=metadata.get("model_name", "") if metadata else "",
+                node_count=node_count,
+                edge_count=edge_count,
+                extra_info="📂 From history",
+            )
+            
+            return diagram, stats, dot_source, [], []
+        
+        def chat_about_diagram(message, history, dot_source):
+            """Chat about the loaded diagram."""
+            if not message or not message.strip():
+                return history, ""
+            
+            message = message.strip()
+            history = history or []
+            
+            if not dot_source:
+                history = history + [
+                    {"role": "user", "content": message},
+                    {"role": "assistant", "content": "⚠️ No diagram loaded. Please generate or load one first."}
+                ]
+                return history, ""
+            
+            session = load_session_state()
+            api_key = session.get("api_key", "")
+            model_choice = session.get("model", "Gemini 2.5 Pro")
+            
+            if not api_key:
+                history = history + [
+                    {"role": "user", "content": message},
+                    {"role": "assistant", "content": "⚠️ API key not configured. Go to Settings."}
+                ]
+                return history, ""
+            
+            try:
+                config = get_config()
+                model_name = config.models.get_model_id(model_choice)
+                analyzer = CodeAnalyzer(api_key=api_key, model_name=model_name)
+                
+                result = analyzer.chat(message, dot_source, history)
+                
+                response = result.content if result.success else f"❌ {result.error}"
+                history = history + [
+                    {"role": "user", "content": message},
+                    {"role": "assistant", "content": response}
+                ]
+                
+            except Exception as e:
+                logger.exception("Chat error")
+                history = history + [
+                    {"role": "user", "content": message},
+                    {"role": "assistant", "content": f"❌ Error: {str(e)}"}
+                ]
+            
+            return history, ""
+        
+        def handle_audio_gen(dot_source):
+            """Generate audio summary."""
+            audio_path, status = generate_audio_summary(dot_source)
+            if audio_path and audio_path.exists():
+                return status, str(audio_path)
+            return status, None
+        
+        def refresh_history_choices():
+            """Refresh the history dropdown with latest diagrams."""
+            choices = get_diagram_generator().get_history_choices()
+            return gr.update(choices=choices, value=None)
+        
+        # Event wiring
+        explore_page.load(fn=process_pending_request, outputs=[diagram_output, stats_output, current_dot])
+        explore_page.load(fn=lambda: [], outputs=[chat_history])
+        explore_page.load(fn=refresh_history_choices, outputs=[history_dropdown])
+        explore_page.load(fn=get_current_model, outputs=[explore_model])
+        
+        apply_layout_btn.click(
+            fn=apply_layout,
+            inputs=[current_dot, layout_direction, layout_splines, layout_nodesep, layout_ranksep, zoom_slider],
+            outputs=[diagram_output]
+        )
+        
+        refresh_history_btn.click(
+            fn=refresh_history_choices,
+            outputs=[history_dropdown]
+        )
+        
+        load_history_btn.click(
+            fn=load_from_history,
+            inputs=[history_dropdown],
+            outputs=[diagram_output, stats_output, current_dot, chat_history, chatbot]
+        )
+        
+        chat_send_btn.click(
+            fn=chat_about_diagram,
+            inputs=[chat_input, chatbot, current_dot],
+            outputs=[chatbot, chat_input]
+        )
+        
+        chat_input.submit(
+            fn=chat_about_diagram,
+            inputs=[chat_input, chatbot, current_dot],
+            outputs=[chatbot, chat_input]
+        )
+        
+        audio_gen_btn.click(
+            fn=handle_audio_gen,
+            inputs=[current_dot],
+            outputs=[audio_status, audio_player]
+        )
+        
+        explore_model.change(
+            fn=lambda m: save_session_state({"model": m}),
+            inputs=[explore_model]
+        )
+    
+    # ==================== SETTINGS PAGE ====================
+    with app.route("settings") as settings_page:
+        with gr.Row(elem_classes="nav-bar-row"):
+            settings_nav = gr.HTML(make_nav_bar("settings"))
+            settings_model = gr.Dropdown(
+                choices=get_model_choices(),
+                value=get_current_model(),
+                show_label=False,
+                container=False,
+                scale=0,
+                min_width=180,
+                elem_classes="model-dropdown-nav"
+            )
+        
+        gr.HTML('''
+            <div style="text-align: center; padding: 2rem 1rem 1.5rem;">
+                <h1 style="font-size: 1.75rem; font-weight: 700; color: #111827;">⚙️ API Keys</h1>
+                <p style="color: #6b7280; margin-top: 0.5rem;">Configure your API keys to enable all features</p>
+            </div>
+        ''')
+        
+        with gr.Row():
+            gr.Column(scale=1, min_width=50)
+            with gr.Column(scale=2, min_width=400):
+                settings_gemini = gr.Textbox(
+                    label="Google Gemini API Key (required)",
+                    placeholder="Get from aistudio.google.com/apikey",
+                    type="password",
+                    interactive=True
+                )
+                settings_openai = gr.Textbox(
+                    label="OpenAI API Key (optional)",
+                    placeholder="Get from platform.openai.com/api-keys",
+                    type="password",
+                    interactive=True
+                )
+                settings_elevenlabs = gr.Textbox(
+                    label="ElevenLabs API Key (optional, for audio)",
+                    placeholder="Get from elevenlabs.io/app/developers/api-keys",
+                    type="password",
+                    interactive=True
+                )
+                
+                save_btn = gr.Button("💾 Save Settings", variant="primary")
+                settings_status = gr.HTML("")
+            gr.Column(scale=1, min_width=50)
+        
+        # Settings events
+        def load_settings():
+            session = load_session_state()
+            return (
+                session.get("api_key", ""),
+                session.get("openai_api_key", ""),
+                session.get("elevenlabs_api_key", "")
+            )
+        
+        def save_settings(gemini_key, openai_key, elevenlabs_key):
+            if save_session_state({
+                "api_key": gemini_key,
+                "openai_api_key": openai_key,
+                "elevenlabs_api_key": elevenlabs_key,
+            }):
+                # Update config
+                config = get_config()
+                config.gemini_api_key = gemini_key
+                config.openai_api_key = openai_key
+                config.elevenlabs_api_key = elevenlabs_key
+                return '<p style="color: #059669; text-align: center;">✅ Settings saved!</p>'
+            return '<p style="color: #dc2626; text-align: center;">❌ Failed to save</p>'
+        
+        settings_page.load(fn=load_settings, outputs=[settings_gemini, settings_openai, settings_elevenlabs])
+        settings_page.load(fn=get_current_model, outputs=[settings_model])
+        
+        save_btn.click(
+            fn=save_settings,
+            inputs=[settings_gemini, settings_openai, settings_elevenlabs],
+            outputs=[settings_status]
+        )
+        
+        settings_model.change(
+            fn=lambda m: save_session_state({"model": m}),
+            inputs=[settings_model]
+        )
+    
+    return app, CUSTOM_CSS

src/ui/components.py

@@ -0,0 +1,178 @@
+"""
+UI Components
+
+Reusable UI components for the Gradio interface.
+"""
+
+from typing import Optional, Dict
+
+
+def make_nav_bar(active_page: str) -> str:
+    """Generate the top navigation bar HTML.
+    
+    Args:
+        active_page: One of 'generate', 'explore', or 'settings'
+        
+    Returns:
+        HTML string for the navigation bar
+    """
+    links = [
+        ("generate", "/", "🚀 Generate"),
+        ("explore", "/explore", "🔍 Explore"),
+        ("settings", "/settings", "⚙️ Settings"),
+    ]
+    
+    nav_links = ""
+    for page_id, href, label in links:
+        active_class = "active" if page_id == active_page else ""
+        nav_links += f'<a href="{href}" class="{active_class}">{label}</a>'
+    
+    return f'''
+        <div class="top-nav-bar">
+            <div class="nav-links">
+                {nav_links}
+            </div>
+        </div>
+    '''
+
+
+def make_loading_html(emoji: str, message: str, submessage: str = "") -> str:
+    """Generate a loading animation HTML.
+    
+    Args:
+        emoji: Emoji to display with animation
+        message: Main loading message
+        submessage: Optional sub-message
+        
+    Returns:
+        HTML string for loading state
+    """
+    sub_html = f'<p class="loading-submessage">{submessage}</p>' if submessage else ""
+    return f'''
+        <div class="loading-container">
+            <div class="loading-emoji">{emoji}</div>
+            <p class="loading-message">{message}</p>
+            {sub_html}
+        </div>
+    '''
+
+
+def make_stats_bar(
+    repo_name: str = "",
+    files_processed: int = 0,
+    total_characters: int = 0,
+    model_name: str = "",
+    node_count: int = 0,
+    edge_count: int = 0,
+    extra_info: str = ""
+) -> str:
+    """Generate the stats bar HTML.
+    
+    Args:
+        repo_name: Repository name
+        files_processed: Number of files processed
+        total_characters: Total characters analyzed
+        model_name: AI model used
+        node_count: Number of nodes in diagram
+        edge_count: Number of edges in diagram
+        extra_info: Additional information to display
+        
+    Returns:
+        HTML string for stats bar
+    """
+    parts = []
+    
+    if repo_name:
+        parts.append(f'<span>📦 <strong>{repo_name}</strong></span>')
+    if files_processed:
+        parts.append(f'<span>📁 <strong>{files_processed}</strong> files</span>')
+    if total_characters:
+        parts.append(f'<span>📊 <strong>{total_characters:,}</strong> chars</span>')
+    if node_count:
+        parts.append(f'<span>🔵 <strong>{node_count}</strong> nodes</span>')
+    if edge_count:
+        parts.append(f'<span>🔗 <strong>{edge_count}</strong> edges</span>')
+    if model_name:
+        parts.append(f'<span>🤖 <strong>{model_name}</strong></span>')
+    if extra_info:
+        parts.append(f'<span>{extra_info}</span>')
+    
+    return f'<div class="stats-bar">{"".join(parts)}</div>'
+
+
+def make_error_html(message: str, emoji: str = "❌", link_href: str = "/", link_text: str = "← Try Again") -> str:
+    """Generate error display HTML.
+    
+    Args:
+        message: Error message to display
+        emoji: Emoji to show
+        link_href: Link destination
+        link_text: Link text
+        
+    Returns:
+        HTML string for error display
+    """
+    return f'''
+        <div class="error-container">
+            <div class="error-emoji">{emoji}</div>
+            <p class="error-message">{message}</p>
+            <a href="{link_href}" class="error-link">{link_text}</a>
+        </div>
+    '''
+
+
+def make_empty_state_html(message: str = "No diagram yet.", link_href: str = "/", link_text: str = "Generate one →") -> str:
+    """Generate empty state HTML.
+    
+    Args:
+        message: Message to display
+        link_href: Link destination
+        link_text: Link text
+        
+    Returns:
+        HTML string for empty state
+    """
+    return f'''
+        <div style="display: flex; align-items: center; justify-content: center; 
+                    min-height: 500px; color: #9ca3af; font-size: 1.1rem;">
+            {message} <a href="{link_href}" style="margin-left: 0.5rem; color: #f97316;">{link_text}</a>
+        </div>
+    '''
+
+
+def make_hero_section(
+    emoji: str = "🏗️",
+    title: str = "CodeAtlas",
+    subtitle: str = "Visualize any codebase architecture with AI"
+) -> str:
+    """Generate hero section HTML.
+    
+    Args:
+        emoji: Main emoji
+        title: Title text
+        subtitle: Subtitle text
+        
+    Returns:
+        HTML string for hero section
+    """
+    return f'''
+        <div class="hero-section">
+            <div class="hero-emoji">{emoji}</div>
+            <h1 class="hero-title">{title}</h1>
+            <p class="hero-subtitle">{subtitle}</p>
+        </div>
+    '''
+
+
+def make_footer() -> str:
+    """Generate footer HTML.
+    
+    Returns:
+        HTML string for footer
+    """
+    return '''
+        <div class="footer">
+            Built for MCP's 1st Birthday Hackathon 🎂 · 
+            Powered by Gemini + LlamaIndex + ElevenLabs + Modal
+        </div>
+    '''

src/ui/styles.py

@@ -0,0 +1,399 @@
+"""
+UI Styles
+
+Custom CSS for the CodeAtlas Gradio interface.
+"""
+
+CUSTOM_CSS = """
+/* Animation for loading states */
+@keyframes pulse { 
+    0%, 100% { transform: scale(1); opacity: 1; } 
+    50% { transform: scale(1.1); opacity: 0.8; } 
+}
+
+@keyframes spin {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+}
+
+/* Hide Gradio's built-in navigation */
+.nav-holder { display: none !important; }
+footer, header, nav { display: none !important; visibility: hidden !important; height: 0 !important; }
+.route-nav { display: none !important; }
+
+/* Remove top spacing */
+html, body { margin: 0 !important; padding: 0 !important; }
+.gradio-container { padding: 0 !important; margin: 0 !important; }
+.main { padding-top: 0 !important; margin-top: 0 !important; }
+
+/* Top navigation bar */
+.top-nav-bar {
+    display: flex;
+    justify-content: flex-start;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    background: linear-gradient(to right, #ffffff, #fafafa);
+    border-bottom: 1px solid #e5e7eb;
+    box-shadow: 0 1px 3px rgba(0,0,0,0.04);
+}
+
+.top-nav-bar .nav-links {
+    display: flex;
+    gap: 0.25rem;
+    align-items: center;
+}
+
+.top-nav-bar .nav-links a {
+    padding: 0.5rem 1rem;
+    border-radius: 8px;
+    text-decoration: none;
+    color: #4b5563;
+    font-weight: 500;
+    font-size: 0.9rem;
+    transition: all 0.2s ease;
+}
+
+.top-nav-bar .nav-links a:hover {
+    background: #f3f4f6;
+    color: #111827;
+}
+
+.top-nav-bar .nav-links a.active {
+    background: linear-gradient(135deg, #f97316 0%, #ea580c 100%);
+    color: white;
+    box-shadow: 0 2px 4px rgba(249, 115, 22, 0.3);
+}
+
+/* Nav bar row */
+.nav-bar-row {
+    display: flex !important;
+    flex-direction: row !important;
+    align-items: center !important;
+    justify-content: space-between !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    background: linear-gradient(to right, #ffffff, #fafafa) !important;
+    border-bottom: 1px solid #e5e7eb !important;
+}
+
+/* Model dropdown styling */
+.model-dropdown-nav {
+    min-width: 200px !important;
+    max-width: 240px !important;
+}
+
+.model-dropdown-nav label { display: none !important; }
+
+.model-dropdown-nav input,
+.model-dropdown-nav button {
+    padding: 0.4rem 2rem 0.4rem 0.75rem !important;
+    border: 1px solid #e5e7eb !important;
+    border-radius: 8px !important;
+    background: white !important;
+    font-size: 0.85rem !important;
+    height: 32px !important;
+}
+
+.model-dropdown-nav input:hover,
+.model-dropdown-nav button:hover {
+    border-color: #f97316 !important;
+}
+
+/* Button styles */
+button.primary, button[class*="primary"] {
+    background: linear-gradient(135deg, #f97316 0%, #ea580c 100%) !important;
+    border: none !important;
+    box-shadow: 0 2px 4px rgba(249, 115, 22, 0.3) !important;
+    transition: all 0.2s ease !important;
+}
+
+button.primary:hover, button[class*="primary"]:hover {
+    box-shadow: 0 4px 8px rgba(249, 115, 22, 0.4) !important;
+    transform: translateY(-1px) !important;
+}
+
+button.secondary, button[class*="secondary"] {
+    border: 1px solid #e5e7eb !important;
+    background: white !important;
+    color: #374151 !important;
+    transition: all 0.2s ease !important;
+}
+
+button.secondary:hover, button[class*="secondary"]:hover {
+    border-color: #f97316 !important;
+    color: #f97316 !important;
+    background: #fff7ed !important;
+}
+
+/* Form inputs */
+input, textarea, select {
+    transition: all 0.2s ease !important;
+}
+
+input:focus, textarea:focus {
+    border-color: #f97316 !important;
+    box-shadow: 0 0 0 3px rgba(249, 115, 22, 0.1) !important;
+}
+
+/* Diagram container */
+.diagram-box {
+    background: white;
+    border-radius: 16px;
+    padding: 1.5rem;
+    overflow: auto;
+    min-height: 500px;
+    max-height: 80vh;
+    box-shadow: 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -1px rgba(0,0,0,0.06);
+    border: 1px solid #f3f4f6;
+}
+
+.diagram-inner {
+    transition: transform 0.2s ease-out;
+}
+
+/* Stats bar */
+.stats-bar {
+    display: flex;
+    gap: 1.5rem;
+    padding: 0.75rem 1.25rem;
+    background: linear-gradient(to right, #f9fafb, #ffffff);
+    border-radius: 10px;
+    margin-bottom: 1rem;
+    flex-wrap: wrap;
+    border: 1px solid #f3f4f6;
+    box-shadow: 0 1px 2px rgba(0,0,0,0.04);
+}
+
+.stats-bar span { 
+    font-size: 0.85rem;
+    color: #4b5563;
+}
+
+.stats-bar span strong {
+    color: #111827;
+}
+
+/* Right sidebar */
+.sidebar-right.sidebar {
+    height: calc(100vh - 60px) !important;
+}
+
+.sidebar-right .sidebar-content {
+    display: flex !important;
+    flex-direction: column !important;
+    height: 100% !important;
+    padding: 0.5rem !important;
+    gap: 0.5rem !important;
+}
+
+/* Audio section */
+.sidebar-right .audio-row {
+    flex-shrink: 0 !important;
+}
+
+.sidebar-right .audio-player-compact {
+    flex-shrink: 0 !important;
+}
+
+.sidebar-right .audio-player-compact audio {
+    height: 36px !important;
+}
+
+.sidebar-right .audio-gen-btn {
+    padding: 0.5rem 1.25rem 0.5rem 1rem !important;
+    border-radius: 8px !important;
+    font-weight: 600 !important;
+    font-size: 0.85rem !important;
+}
+
+.sidebar-right .audio-status {
+    font-size: 0.85rem !important;
+    color: #059669 !important;
+    margin-top: 0.25rem !important;
+    font-weight: 600 !important;
+}
+
+/* Chat styling */
+#codeatlas-chat {
+    flex: 1 1 auto !important;
+    min-height: 0 !important;
+    height: 100% !important;
+    border: none !important;
+    background: transparent !important;
+    overflow: hidden !important;
+}
+
+#codeatlas-chat .message {
+    max-width: 100% !important;
+    padding: 0.5rem !important;
+    border-radius: 8px !important;
+}
+
+#codeatlas-chat .message.user {
+    background: #fff7ed !important;
+    border: 1px solid #fed7aa !important;
+}
+
+#codeatlas-chat .message.bot {
+    background: #ffffff !important;
+    border: 1px solid #e5e7eb !important;
+}
+
+.sidebar-right .chat-input-container {
+    flex-shrink: 0 !important;
+    padding-top: 0.5rem !important;
+    border-top: 1px solid #e5e7eb !important;
+}
+
+.chat-input-row {
+    display: flex !important;
+    gap: 0.5rem !important;
+    align-items: center !important;
+}
+
+.chat-input-row input,
+.chat-input-row textarea {
+    flex: 1 1 auto !important;
+}
+
+.chat-input-row button {
+    width: 44px !important;
+    height: 40px !important;
+    padding: 0 !important;
+    border-radius: 8px !important;
+}
+
+/* Left sidebar */
+.sidebar {
+    background: #fafafa !important;
+}
+
+.sidebar h4, .sidebar .markdown h4 {
+    color: #374151 !important;
+    font-size: 0.85rem !important;
+    font-weight: 600 !important;
+    text-transform: uppercase !important;
+    letter-spacing: 0.05em !important;
+}
+
+.sidebar hr {
+    border-color: #e5e7eb !important;
+    margin: 0.75rem 0 !important;
+}
+
+/* Loading states */
+.loading-container {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    min-height: 400px;
+    text-align: center;
+}
+
+.loading-emoji {
+    font-size: 4rem;
+    animation: pulse 1.5s ease-in-out infinite;
+}
+
+.loading-message {
+    font-size: 1.2rem;
+    margin-top: 1rem;
+    font-weight: 500;
+    color: #374151;
+}
+
+.loading-submessage {
+    color: #6b7280;
+    margin-top: 0.5rem;
+    font-size: 0.9rem;
+}
+
+/* Hero section */
+.hero-section {
+    text-align: center;
+    padding: 3rem 1rem 2rem 1rem;
+}
+
+.hero-emoji {
+    font-size: 4rem;
+    margin-bottom: 0.75rem;
+    filter: drop-shadow(0 4px 6px rgba(0,0,0,0.1));
+}
+
+.hero-title {
+    font-size: 2.25rem;
+    font-weight: 700;
+    color: #111827;
+    margin: 0;
+    letter-spacing: -0.02em;
+}
+
+.hero-subtitle {
+    color: #6b7280;
+    margin-top: 0.75rem;
+    font-size: 1.05rem;
+    font-weight: 400;
+}
+
+/* Footer */
+.footer {
+    text-align: center;
+    color: #9ca3af;
+    font-size: 0.8rem;
+    margin-top: 4rem;
+    padding: 1.5rem;
+    border-top: 1px solid #f3f4f6;
+}
+
+/* Card styling */
+.card {
+    background: white;
+    border-radius: 12px;
+    border: 1px solid #f3f4f6;
+    box-shadow: 0 1px 3px rgba(0,0,0,0.05);
+    padding: 1rem;
+}
+
+/* Error styling */
+.error-container {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    min-height: 400px;
+    text-align: center;
+}
+
+.error-emoji {
+    font-size: 3rem;
+    margin-bottom: 1rem;
+}
+
+.error-message {
+    color: #dc2626;
+    font-size: 1.1rem;
+}
+
+.error-link {
+    margin-top: 1rem;
+    color: #f97316;
+}
+
+/* Mobile responsiveness */
+@media (max-width: 768px) {
+    .top-nav-bar {
+        flex-direction: column;
+        gap: 0.5rem;
+    }
+    
+    .stats-bar {
+        flex-direction: column;
+        gap: 0.5rem;
+    }
+    
+    .hero-title {
+        font-size: 1.75rem;
+    }
+}
+"""