diff --git a/CodeGeneration/README.MD b/CodeGeneration/README.MD
new file mode 100644
index 0000000000..9e34b4dfe5
--- /dev/null
+++ b/CodeGeneration/README.MD
@@ -0,0 +1,341 @@
+## Continue VS Code Extension
+
+AI-powered coding assistant integrated with enterprise GenAI Gateway. Provides code completion, chat, and code editing capabilities using locally deployed language models.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Advanced Features](#advanced-features)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Overview
+
+Continue VS Code Extension enables developers to leverage enterprise-deployed Llama 3.2 3B model for code assistance through GenAI Gateway. Provides autocomplete, chat, and editing capabilities with Keycloak authentication.
+
+---
+
+## Features
+
+**Autocomplete**
+- Real-time code completion
+- Multiline code generation
+- Context-aware suggestions
+- Configurable debounce and timeout
+
+**Chat Mode**
+- Interactive Q&A about code
+- Code explanations
+- Problem-solving assistance
+- Keyboard shortcut: `Ctrl+L`
+
+**Edit Mode**
+- Targeted code modifications
+- Inline transformations
+- Context-aware refactoring
+- Keyboard shortcut: `Ctrl+I`
+
+---
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph "Developer Workstation"
+        A[VS Code IDE]
+        B[Continue Extension]
+    end
+
+    subgraph "Enterprise Infrastructure"
+        C[GenAI Gateway<br/>LiteLLM]
+        D[Keycloak<br/>OAuth2 Auth]
+    end
+
+    subgraph "Kubernetes Cluster"
+        E[AI Model Pods<br/>Llama 3.2 3B]
+    end
+
+    A -->|Code Context| B
+    B -->|HTTPS Request<br/>API Key| C
+    C -->|Validate Token| D
+    D -->|Auth Success| C
+    C -->|Inference Request| E
+    E -->|Model Response| C
+    C -->|Response| B
+    B -->|Display Results| A
+
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#f0e1ff
+    style D fill:#ffe1e1
+    style E fill:#e1ffe1
+```
+
+Developer types code in VS Code. Continue extension sends authenticated request to GenAI Gateway. Gateway validates credentials with Keycloak and routes to model. Model generates response. Result displayed in VS Code.
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+- VS Code (latest stable version)
+- GenAI Gateway access with Keycloak authentication
+- API key from Gateway administrator
+
+### Verify VS Code Installation
+
+```bash
+code --version
+```
+
+---
+
+## Quick Start
+
+### Install Continue Extension
+
+1. Open VS Code
+2. Press `Ctrl+Shift+X` to open Extensions
+3. Search for "Continue"
+4. Install: **Continue - open-source AI code agent**
+5. Publisher: **Continue**
+
+Command line installation:
+
+```bash
+code --install-extension Continue.continue
+```
+
+### Configure Extension
+
+1. Press `Ctrl+Shift+P`
+2. Type "Continue: Open config.yaml"
+3. Replace contents with configuration below
+4. Update `apiBase` and `apiKey` with your credentials
+5. Reload VS Code: `Ctrl+Shift+P` → "Developer: Reload Window"
+
+---
+
+## Configuration
+
+Configuration file location:
+
+**Windows:**
+```
+C:\Users\<username>\.continue\config.yaml
+```
+
+**macOS/Linux:**
+```
+~/.continue/config.yaml
+```
+
+### Basic Configuration
+
+```yaml
+name: GenAI Gateway Config
+version: 1.0.0
+schema: v1
+
+tabAutocompleteOptions:
+  multilineCompletions: "always"
+  debounceDelay: 2500
+  maxPromptTokens: 100
+  prefixPercentage: 1.0
+  suffixPercentage: 0.0
+  maxSuffixPercentage: 0.0
+  modelTimeout: 5000
+  showWhateverWeHaveAtXMs: 2000
+  useCache: true
+  onlyMyCode: true
+  useRecentlyEdited: true
+  useRecentlyOpened: true
+  useImports: true
+  transform: true
+  experimental_includeClipboard: false
+  experimental_includeRecentlyVisitedRanges: true
+  experimental_includeRecentlyEditedRanges: true
+  experimental_includeDiff: true
+  disableInFiles:
+    - "*.md"
+
+models:
+  - name: "Llama 3.2 3B"
+    provider: openai
+    model: "meta-llama/Llama-3.2-3B-Instruct"
+    apiBase: "https://api.example.com/v1"
+    apiKey: "your-api-key-here"
+    ignoreSSL: true
+    contextLength: 8192
+    completionOptions:
+      maxTokens: 1024
+      temperature: 0.3
+      stop:
+        - "\n\n"
+        - "def "
+        - "class "
+    requestOptions:
+      maxTokens: 1024
+      temperature: 0.3
+    autocompleteOptions:
+      maxTokens: 256
+      temperature: 0.2
+      stop:
+        - "\n\n\n"
+        - "# "
+    roles:
+      - chat
+      - edit
+      - apply
+      - autocomplete
+    promptTemplates:
+      autocomplete: "{{{prefix}}}"
+
+useLegacyCompletionsEndpoint: true
+experimental:
+  inlineEditing: true
+allowAnonymousTelemetry: false
+```
+
+### Required Updates
+
+1. **apiBase**: Your GenAI Gateway URL with `/v1` suffix
+2. **apiKey**: API key from Gateway administrator
+3. **model**: Exact model name `meta-llama/Llama-3.2-3B-Instruct`
+
+For detailed configuration options and advanced setup, refer to [SETUP_GUIDE.md](./SETUP_GUIDE.md).
+
+### Verify Configuration
+
+```bash
+export API_KEY="your-api-key-here"
+export API_BASE="https://api.example.com/v1"
+```
+
+```bash
+curl -k $API_BASE/models \
+  -H "Authorization: Bearer $API_KEY"
+  ```
+
+```bash
+curl -k $API_BASE/chat/completions \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.2-3B-Instruct",
+    "messages": [{"role": "user", "content": "What is Python?"}],
+    "max_tokens": 50
+  }'
+```
+
+---
+
+## Usage
+
+### Agent mode
+
+**How to Use:**
+1. Open Continue sidebar
+2. Switch to Agent mode
+3. Give task instruction
+4. Review and approve file operations
+5. Verify results
+
+**Preview:**  Requested "Create a FastAPI application with two routes". The model generated the code and created a new file with the complete implementation including imports, app initialization, and route definitions.
+
+![Agent Mode Demo](./src/agent-mode.png)
+
+![Agent Mode Demo](./src/agent-mode.gif)
+
+### Autocomplete
+
+**How to Use:**
+1. Start typing code
+2. Pause 3 seconds
+3. Accept with `Tab` or reject by continuing to type
+
+Enable/disable via "Continue" button in status bar.
+
+**Preview:**  Started typing to create an endpoint for the sample FastAPI application and paused. The model generated the code for the endpoint and provided a prompt to accept or reject the code.
+
+![Autocomplete Demo](./src/autocomplete-demo.png)
+
+![Autocomplete Demo](./src/autocomplete-demo.gif)
+
+
+
+---
+
+### Chat Mode
+
+**How to Use:**
+1. Press `Ctrl+L`
+2. Type question
+3. Press Enter
+4. Review response
+
+Context providers:
+- Highlight code for automatic inclusion
+- `@Files` - Reference specific files
+- `@Terminal` - Include terminal output
+
+**Preview:** Asked how does FastAPI handles request validation in the current file and received the response with a suggestion, which can be viewed in the screenshots below
+
+![Chat Mode Demo](./src/chat-mode.png)
+
+![Chat Mode Demo](./src/chat-mode-1.png)
+
+
+![Chat Mode Demo](./src/chat-mode.gif)
+
+
+---
+
+### Edit Mode
+
+**How to Use:**
+1. Highlight code
+2. Press `Ctrl+I`
+3. Type instruction
+4. Review diff
+5. Accept or reject
+
+
+**Preview:** Highlighted the code file and provided a prompt to "convert every endpoint to async". The model generated a difference showing the original code and proposed changes and provided a prompt to accept or reject the code.
+
+![Edit Mode Demo](./src/edit-mode-demo.png)
+
+
+
+![Edit Mode Demo](./src/edit-mode.gif)
+
+
+---
+
+## Advanced Features
+
+**Custom Rules**
+- Define custom system prompts and context for specific project needs
+- Control AI behavior with project-specific guidelines
+
+**MCP Servers**
+- Extend functionality with Model Context Protocol servers
+- Add custom tools and external integrations
+
+For detailed setup instructions on creating custom rules and MCP servers, refer to [SETUP_GUIDE.md](./SETUP_GUIDE.md).
+
+---
+
+## Troubleshooting
+
+For comprehensive troubleshooting guidance, common issues, and solutions, refer to:
+
+[Troubleshooting Guide - TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
diff --git a/CodeGeneration/SETUP_GUIDE.md b/CodeGeneration/SETUP_GUIDE.md
new file mode 100644
index 0000000000..a04449ecf3
--- /dev/null
+++ b/CodeGeneration/SETUP_GUIDE.md
@@ -0,0 +1,1443 @@
+# Continue Extension Setup Guide
+
+Comprehensive configuration guide for Continue VS Code extension with GenAI Gateway backend using Meta Llama 3.2 3B Instruct model.
+
+## Table of Contents
+
+- [Understanding Continue Modes](#understanding-continue-modes)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Configuration Variables Reference](#configuration-variables-reference)
+- [FIM Template Formats](#fim-template-formats)
+- [Feature Usage](#feature-usage)
+- [Best Practices](#best-practices)
+- [Advanced Configuration](#advanced-configuration)
+- [Custom Rules](#custom-rules)
+- [MCP Servers](#mcp-servers-model-context-protocol)
+
+---
+
+## Understanding Continue Modes
+
+Continue provides five interaction modes for different development workflows:
+
+### 1. Chat Mode
+
+Interactive AI assistant for code discussions and problem-solving.
+
+**Capabilities:**
+- Answer questions about code
+- Explain code functionality
+- Provide implementation suggestions
+- Debug issues with conversation context
+
+**Keyboard Shortcuts:**
+- VS Code: `Ctrl+L` (Windows/Linux) or `Cmd+L` (Mac)
+
+**How It Works:**
+- Gathers context from selected code, current file, and conversation history
+- Constructs prompt with user input and context
+- Streams real-time response from AI model
+- Provides action buttons to apply, insert, or copy code
+
+**Best For:** Quick interactions, code explanations, iterative problem-solving
+
+### 2. Edit Mode
+
+Targeted code modifications using natural language instructions.
+
+**Capabilities:**
+- Refactor selected code
+- Add documentation and comments
+- Fix bugs in specific sections
+- Convert code between languages
+- Apply formatting changes
+
+**Keyboard Shortcut:** `Ctrl+I` (Windows/Linux) or `Cmd+I` (Mac)
+
+**How It Works:**
+1. Captures highlighted code and current file contents
+2. Sends context and user instructions to AI model
+3. Streams proposed changes with diff formatting
+4. User accepts or rejects changes
+
+**Best For:** Precise, localized code modifications
+
+### 3. Autocomplete
+
+Intelligent inline code suggestions as you type.
+
+**Capabilities:**
+- Context-aware code completion
+- Multi-line suggestions
+- Function implementations
+- Boilerplate code generation
+
+**Keyboard Shortcuts:**
+- Accept: `Tab`
+- Reject: `Esc`
+- Partial accept: `Ctrl+→` or `Cmd+→`
+- Force trigger: `Ctrl+Alt+Space` or `Cmd+Alt+Space`
+
+**How It Works:**
+- Uses debouncing to prevent requests on every keystroke
+- Retrieves relevant code snippets from codebase
+- Caches suggestions for rapid reuse
+- Post-processes AI output (removes tokens, fixes indentation)
+
+**Best For:** Fast, inline coding assistance without breaking flow
+
+### 4. Plan Mode
+
+Read-only exploration mode for safe codebase analysis.
+
+**Capabilities:**
+- Read project files
+- Search code using grep and glob patterns
+- View repository structure and diffs
+- Fetch web content for context
+- NO file editing or terminal commands
+
+**Keyboard Shortcut:** `Ctrl+.` or `Cmd+.` to cycle modes
+
+**How It Works:**
+- Same as Agent mode but filters tools to read-only operations
+- Prevents accidental modifications
+- Allows safe exploration of unfamiliar codebases
+
+**Best For:** Understanding codebases, planning implementations before execution
+
+### 5. Agent Mode
+
+Autonomous coding assistant with tool access for complex, multi-step tasks.
+
+**Capabilities:**
+- Read and analyze multiple files
+- Create and edit files
+- Run terminal commands
+- Search codebase
+- Execute multi-step implementations
+
+**Keyboard Shortcut:** `Ctrl+.` or `Cmd+.` to cycle modes
+
+**How It Works:**
+- Receives available tools alongside user requests
+- Model proposes tool calls (read file, edit file, run command)
+- User grants permission (or auto-approval if configured)
+- Tool executes and returns results
+- Process repeats iteratively until task complete
+
+**Requirements:**
+- Model must support tool calling (function calling)
+- Requires larger context windows for multi-step operations
+
+**Best For:** Implementing features, fixing bugs, running tests, refactoring
+
+---
+
+## Installation
+
+### Step 1: Install Continue Extension
+
+1. Open VS Code
+2. Go to Extensions (`Ctrl+Shift+X`)
+3. Search for "Continue"
+4. Install: **Continue - open-source AI code agent**
+5. Publisher: **Continue**
+6. Extension ID: `Continue.continue`
+
+### Step 2: Verify Installation
+
+- Continue icon should appear in left sidebar
+- Test keyboard shortcut: `Ctrl+L` should open Continue chat
+- Status bar should show "Continue" button
+
+---
+
+## Configuration
+
+### Configuration File Location
+
+Continue uses a YAML configuration file located at:
+
+**Windows:**
+```
+C:\Users\<username>\.continue\config.yaml
+```
+
+**macOS/Linux:**
+```
+~/.continue/config.yaml
+```
+
+**Access via Command Palette:**
+1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
+2. Type: "Continue: Open config.yaml"
+3. Press Enter
+
+### Complete Configuration
+
+Replace your `config.yaml` with the following configuration:
+
+```yaml
+name: GenAI Gateway Config
+version: 1.0.0
+schema: v1
+
+tabAutocompleteOptions:
+  multilineCompletions: "always"
+  debounceDelay: 3000
+  maxPromptTokens: 100
+  prefixPercentage: 1.0
+  suffixPercentage: 0.0
+  maxSuffixPercentage: 0.0
+  modelTimeout: 10000
+  showWhateverWeHaveAtXMs: 2000
+  useCache: true
+  onlyMyCode: true
+  useRecentlyEdited: true
+  useRecentlyOpened: true
+  useImports: true
+  transform: true
+  experimental_includeClipboard: false
+  experimental_includeRecentlyVisitedRanges: true
+  experimental_includeRecentlyEditedRanges: true
+  experimental_includeDiff: true
+  disableInFiles:
+    - "*.md"
+
+models:
+  - name: "Llama 3.2 3B (Chat & Agent + Autocomplete)"
+    provider: openai
+    model: "meta-llama/Llama-3.2-3B-Instruct"
+    apiBase: "https://api.example.com/v1"
+    apiKey: "your-api-key-here"
+    ignoreSSL: true
+    contextLength: 8192
+    completionOptions:
+      maxTokens: 2048
+      temperature: 0.1
+      stop:
+        - "\n\n"
+        - "def "
+        - "class "
+    requestOptions:
+      maxTokens: 2048
+      temperature: 0.1
+    autocompleteOptions:
+      maxTokens: 256
+      temperature: 0.2
+      stop:
+        - "\n\n\n"
+        - "# "
+    roles:
+      - chat
+      - edit
+      - apply
+      - autocomplete
+    promptTemplates:
+      autocomplete: "{{{prefix}}}"
+
+useLegacyCompletionsEndpoint: true
+experimental:
+  inlineEditing: true
+allowAnonymousTelemetry: false
+```
+
+### Apply Configuration
+
+1. Save the `config.yaml` file
+2. Reload VS Code: `Ctrl+Shift+P` → "Developer: Reload Window"
+
+### Required VS Code Settings
+
+Continue requires specific VS Code settings to function properly. These settings **override** values in `config.yaml`, so they must be configured correctly.
+
+#### Access VS Code Settings
+
+**Method 1: Command Palette**
+1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
+2. Type: "Preferences: Open User Settings (JSON)"
+3. Press Enter
+
+**Method 2: Settings UI**
+1. Go to File → Preferences → Settings
+2. Click the "Open Settings (JSON)" icon in the top right
+
+#### Critical Settings
+
+Add the following settings to your `settings.json` file:
+
+```json
+{
+    // ===== CONTINUE.DEV CONFIGURATION =====
+
+    // Enable tab-based autocomplete
+    "continue.enableTabAutocomplete": true,
+
+    // Disable Continue telemetry for privacy
+    "continue.telemetryEnabled": false,
+
+    // Enable console logs for debugging (optional)
+    "continue.enableConsole": true,
+
+    // ===== INLINE SUGGESTIONS (REQUIRED) =====
+
+    // CRITICAL: Must be enabled for Continue to work
+    "editor.inlineSuggest.enabled": true,
+
+    // Show inline suggestion toolbar always
+    "editor.inlineSuggest.showToolbar": "always",
+
+    // Enable inline edits (for Edit mode)
+    "editor.inlineSuggest.edits.enabled": true
+}
+```
+
+#### Why These Settings Matter
+
+**continue.enableTabAutocomplete**
+- Controls whether autocomplete is enabled globally
+- Can be toggled via status bar "Continue" button
+- Must be `true` for autocomplete to work
+
+**continue.telemetryEnabled**
+- Controls anonymous usage data collection
+- Set to `false` for privacy
+- No code or sensitive data is sent when enabled
+
+**continue.enableConsole**
+- Shows detailed logs in VS Code Output panel
+- Useful for debugging connection issues
+- Access logs: View → Output → Select "Continue" from dropdown
+
+**editor.inlineSuggest.enabled**
+- **CRITICAL**: VS Code's master switch for inline suggestions
+- Without this, Continue's network requests are blocked
+- Must be `true` or Continue will not function
+
+**editor.inlineSuggest.showToolbar**
+- Controls visibility of inline suggestion toolbar
+- Set to `"always"` for easier acceptance/rejection of suggestions
+
+**editor.inlineSuggest.edits.enabled**
+- Enables inline editing capabilities
+- Required for Edit mode (`Ctrl+I`) to work properly
+
+#### Settings Priority
+
+Settings are applied in this order (later overrides earlier):
+
+1. Continue hardcoded defaults (in extension source code)
+2. `config.yaml` settings
+3. **VS Code User Settings (highest priority)**
+
+This means VS Code settings **override** config.yaml values. For example:
+- If `config.yaml` has autocomplete enabled but VS Code settings has `"continue.enableTabAutocomplete": false`, autocomplete will be **disabled**
+- Always check VS Code settings first when troubleshooting
+
+#### Apply Settings
+
+1. Save `settings.json`
+2. Reload VS Code: `Ctrl+Shift+P` → "Developer: Reload Window"
+3. Verify Continue is active: Status bar should show "Continue" button
+
+---
+
+## Configuration Variables Reference
+
+### Global Settings
+
+**name**
+- Description: Display name for the configuration
+- Type: String
+- Purpose: Identifies configuration in Continue UI
+- Example: `"GenAI Gateway Config"`
+
+**version**
+- Description: Configuration version
+- Type: String
+- Purpose: Track configuration changes
+- Example: `"1.0.0"`
+
+**schema**
+- Description: Configuration schema version
+- Type: String
+- Purpose: Ensure compatibility with Continue extension
+- Example: `"v1"`
+
+### tabAutocompleteOptions
+
+Global settings controlling autocomplete behavior across all files.
+
+**multilineCompletions**
+- Description: Enable multi-line code completions
+- Type: String
+- Values: `"always"`, `"never"`, `"auto"`
+- Purpose: Control when autocomplete generates multiple lines
+- Recommended: `"always"` for full function implementations
+
+**debounceDelay**
+- Description: Wait time in milliseconds after typing stops before triggering autocomplete
+- Type: Integer (milliseconds)
+- Purpose: Prevent excessive API calls on every keystroke
+- Recommended: `3000` (3 seconds) for CPU-based inference
+- Note: Lower values (500-1000ms) work better with GPU inference
+
+**maxPromptTokens**
+- Description: Maximum tokens sent as context to autocomplete model
+- Type: Integer
+- Purpose: Limit context size for faster inference
+- Recommended: `100` for quick responses
+- Note: Larger values provide more context but slower responses
+
+**prefixPercentage**
+- Description: Percentage of context taken from code before cursor (0.0 to 1.0)
+- Type: Float
+- Purpose: Balance prefix vs suffix context
+- Recommended: `1.0` (100% prefix, no suffix) for faster processing
+
+**suffixPercentage**
+- Description: Percentage of context taken from code after cursor (0.0 to 1.0)
+- Type: Float
+- Purpose: Provide code after cursor as context
+- Recommended: `0.0` for FIM-based models unless suffix is needed
+
+**maxSuffixPercentage**
+- Description: Maximum allowed suffix context (0.0 to 1.0)
+- Type: Float
+- Purpose: Cap suffix context even when enabled
+- Recommended: `0.0` unless using Fill-in-Middle extensively
+
+**modelTimeout**
+- Description: Maximum wait time for model response in milliseconds
+- Type: Integer (milliseconds)
+- Purpose: Prevent indefinite waiting on slow inference
+- Recommended: `10000` (10 seconds) for CPU inference, `5000` for GPU
+- Critical: Must be longer than typical model inference time
+
+**showWhateverWeHaveAtXMs**
+- Description: Display partial completion after X milliseconds
+- Type: Integer (milliseconds)
+- Purpose: Show incomplete suggestions if model is slow
+- Recommended: `2000` (2 seconds)
+
+**useCache**
+- Description: Cache autocomplete results for reuse
+- Type: Boolean
+- Purpose: Reuse previous completions for identical contexts
+- Recommended: `true` for better performance
+
+**onlyMyCode**
+- Description: Limit context to user-written code (exclude dependencies)
+- Type: Boolean
+- Purpose: Reduce noise from third-party libraries
+- Recommended: `true` for cleaner suggestions
+
+**useRecentlyEdited**
+- Description: Include recently edited files in context
+- Type: Boolean
+- Purpose: Provide relevant context from active development
+- Recommended: `true` for better context awareness
+
+**useRecentlyOpened**
+- Description: Include recently opened files in context
+- Type: Boolean
+- Purpose: Include files you're currently working with
+- Recommended: `true`
+
+**useImports**
+- Description: Include imported modules and libraries in context
+- Type: Boolean
+- Purpose: Understand dependencies and APIs
+- Recommended: `true` for better API completions
+
+**transform**
+- Description: Apply post-processing transformations to completions
+- Type: Boolean
+- Purpose: Clean up and format model output
+- Recommended: `true` for better formatting
+
+**experimental_includeClipboard**
+- Description: Include clipboard contents in context
+- Type: Boolean
+- Purpose: Use copied code as context
+- Recommended: `false` (privacy concern, unstable feature)
+
+**experimental_includeRecentlyVisitedRanges**
+- Description: Include code ranges recently viewed
+- Type: Boolean
+- Purpose: Context from browsing history
+- Recommended: `true` for enhanced context
+
+**experimental_includeRecentlyEditedRanges**
+- Description: Include specific code ranges recently edited
+- Type: Boolean
+- Purpose: Focus on active editing areas
+- Recommended: `true`
+
+**experimental_includeDiff**
+- Description: Include git diff in context
+- Type: Boolean
+- Purpose: Understand recent changes
+- Recommended: `true` for change-aware completions
+
+**disableInFiles**
+- Description: File patterns where autocomplete is disabled
+- Type: Array of glob patterns
+- Purpose: Prevent autocomplete in specific file types
+- Example: `["*.md", "*.txt", "*.json"]`
+- Recommended: Disable in markdown, config files
+
+### models
+
+Array of model configurations. Each model represents a connection to an AI model endpoint.
+
+**name**
+- Description: Display name for the model in Continue UI
+- Type: String
+- Purpose: Identify model in dropdowns and status messages
+- Example: `"Llama 3.2 3B (Chat & Agent + Autocomplete)"`
+
+**provider**
+- Description: API provider type
+- Type: String
+- Values: `openai`, `anthropic`, `ollama`, `huggingface`, etc.
+- Purpose: Determines API format and authentication method
+- Recommended: `openai` for OpenAI-compatible endpoints (LiteLLM, vLLM, etc.)
+
+**model**
+- Description: Model identifier sent to API endpoint
+- Type: String
+- Purpose: Specify which model to use on the backend
+- Example: `"meta-llama/Llama-3.2-3B-Instruct"`
+- Note: Must match exact model name registered in GenAI Gateway (case-sensitive)
+
+**apiBase**
+- Description: Base URL for API endpoint
+- Type: String (URL)
+- Purpose: Backend service URL
+- Example: `"https://api.example.com/v1"`
+- Required: Must include `/v1` suffix for OpenAI-compatible APIs
+- Note: Replace `api.example.com` with your actual GenAI Gateway URL
+
+**apiKey**
+- Description: Authentication key for API access
+- Type: String
+- Purpose: Authenticate requests to GenAI Gateway
+- Example: `"your-api-key-here"`
+- Security: Never commit real API keys to version control
+- Note: Obtain from GenAI Gateway administrator
+
+**ignoreSSL**
+- Description: Skip SSL certificate verification
+- Type: Boolean
+- Purpose: Allow self-signed certificates
+- Recommended: `true` for internal deployments with self-signed certs
+- Security: Only use on trusted internal networks
+
+**contextLength**
+- Description: Maximum context window in tokens
+- Type: Integer
+- Purpose: Define model's maximum input capacity
+- Example: `8192` for Llama 3.2 3B
+- Note: Set according to model's actual capacity, not higher
+
+### completionOptions
+
+Settings applied to chat and edit mode responses.
+
+**maxTokens**
+- Description: Maximum tokens in model response
+- Type: Integer
+- Purpose: Limit response length
+- Recommended: `2048` for chat/edit modes
+- Note: Lower values (1024) if encountering context window errors
+
+**temperature**
+- Description: Randomness in generation (0.0 to 2.0)
+- Type: Float
+- Purpose: Control creativity vs consistency
+- Recommended: `0.1` for code generation (deterministic)
+- Range: `0.0` (deterministic) to `2.0` (very creative)
+
+**stop**
+- Description: Stop sequences to terminate generation
+- Type: Array of strings
+- Purpose: Prevent over-generation
+- Example: `["\n\n", "def ", "class "]`
+- Recommended: Language-specific keywords and double newlines
+
+### requestOptions
+
+Alternative settings for chat/edit modes (overrides completionOptions if present).
+
+**maxTokens**
+- Description: Same as completionOptions.maxTokens
+- Purpose: Explicit control for request-level settings
+
+**temperature**
+- Description: Same as completionOptions.temperature
+- Purpose: Request-level temperature override
+
+### autocompleteOptions
+
+Settings specifically for autocomplete mode (overrides completionOptions for autocomplete).
+
+**maxTokens**
+- Description: Maximum tokens in autocomplete suggestions
+- Type: Integer
+- Purpose: Keep completions short and fast
+- Recommended: `256` for quick inline suggestions
+- Note: Shorter = faster inference
+
+**temperature**
+- Description: Randomness in autocomplete (0.0 to 2.0)
+- Type: Float
+- Purpose: Control consistency of suggestions
+- Recommended: `0.2` for consistent, predictable completions
+- Note: Higher values create more varied but less reliable suggestions
+
+**stop**
+- Description: Stop sequences for autocomplete
+- Type: Array of strings
+- Purpose: Prevent excessive continuation
+- Example: `["\n\n\n", "# "]`
+- Recommended: Triple newlines, comment markers
+
+### roles
+
+Array of Continue modes this model handles.
+
+**Available Roles:**
+- `chat` - Chat mode interactions
+- `edit` - Edit mode transformations
+- `apply` - Apply code suggestions
+- `autocomplete` - Inline autocomplete
+
+**Purpose:** Assign specific models to specific tasks
+
+**Example:** Single model handling all roles:
+```yaml
+roles:
+  - chat
+  - edit
+  - apply
+  - autocomplete
+```
+
+### promptTemplates
+
+Custom prompt formats for different modes.
+
+**autocomplete**
+- Description: Template for autocomplete prompts
+- Type: String with mustache variables
+- Purpose: Format code context for model
+- Variables:
+  - `{{{prefix}}}` - Code before cursor
+  - `{{{suffix}}}` - Code after cursor
+  - `{{{filename}}}` - Current file name
+  - `{{{language}}}` - Programming language
+- Example: `"{{{prefix}}}"` for prefix-only completion
+- See [FIM Template Formats](#fim-template-formats) for advanced examples
+
+### useLegacyCompletionsEndpoint
+
+**Description:** Use `/v1/completions` instead of `/v1/chat/completions` for autocomplete
+**Type:** Boolean
+**Purpose:** Required for FIM-based autocomplete with many models
+**Recommended:** `true` for Llama, CodeLlama, StarCoder models
+**Note:** Modern chat models may work without this, but legacy endpoint is more reliable
+
+### experimental
+
+Experimental features under development.
+
+**inlineEditing**
+- Description: Enable inline edit mode
+- Type: Boolean
+- Purpose: Edit code directly in editor (vs sidebar diff)
+- Recommended: `true` for better UX
+
+### allowAnonymousTelemetry
+
+**Description:** Send anonymous usage data to Continue developers
+**Type:** Boolean
+**Purpose:** Help improve Continue extension
+**Recommended:** `false` for privacy, `true` to support development
+**Privacy:** No code or sensitive data is sent when enabled
+
+---
+
+## FIM Template Formats
+
+Fill-in-Middle (FIM) allows models to complete code based on context before and after the cursor position. Different models use different FIM token formats.
+
+### Basic Prefix-Only Format
+
+Simplest format using only code before cursor.
+
+```yaml
+promptTemplates:
+  autocomplete: "{{{prefix}}}"
+```
+
+**Use case:** When model doesn't support FIM or suffix context is not needed.
+
+### Llama and CodeLlama Format
+
+Standard format used by Meta's Llama and CodeLlama models.
+
+```yaml
+promptTemplates:
+  autocomplete: "<|fim_prefix|>{{{prefix}}}<|fim_suffix|>{{{suffix}}}<|fim_middle|>"
+```
+
+**Tokens:**
+- `<|fim_prefix|>` - Marks beginning of prefix context
+- `<|fim_suffix|>` - Marks beginning of suffix context
+- `<|fim_middle|>` - Marks where model should generate completion
+
+**Use case:** Llama 3.x, CodeLlama 7B/13B/34B models
+
+### StarCoder Format
+
+Format used by BigCode's StarCoder models.
+
+```yaml
+promptTemplates:
+  autocomplete: "<fim_prefix>{{{prefix}}}<fim_suffix>{{{suffix}}}<fim_middle>"
+```
+
+**Tokens:**
+- `<fim_prefix>` - Prefix marker (no pipes)
+- `<fim_suffix>` - Suffix marker (no pipes)
+- `<fim_middle>` - Generation marker (no pipes)
+
+**Use case:** StarCoder, StarCoder2, StarCoderBase models
+
+### DeepSeek Coder Format
+
+Format used by DeepSeek Coder models.
+
+```yaml
+promptTemplates:
+  autocomplete: "<|fim▁begin|>{{{prefix}}}<|fim▁hole|>{{{suffix}}}<|fim▁end|>"
+```
+
+**Tokens:**
+- `<|fim▁begin|>` - Marks beginning (note the ▁ character)
+- `<|fim▁hole|>` - Marks gap to fill
+- `<|fim▁end|>` - Marks end of context
+
+**Use case:** DeepSeek Coder 1.3B/6.7B/33B models
+
+### CodeGemma Format
+
+Format used by Google's CodeGemma models.
+
+```yaml
+promptTemplates:
+  autocomplete: "<|fim_prefix|>{{{prefix}}}<|fim_suffix|>{{{suffix}}}<|fim_middle|>"
+```
+
+**Note:** Same as Llama format
+
+**Use case:** CodeGemma 2B/7B models
+
+### Custom Format with File Context
+
+Enhanced format including file metadata.
+
+```yaml
+promptTemplates:
+  autocomplete: |
+    File: {{{filename}}}
+    Language: {{{language}}}
+
+    <|fim_prefix|>{{{prefix}}}<|fim_suffix|>{{{suffix}}}<|fim_middle|>
+```
+
+**Additional variables:**
+- `{{{filename}}}` - Current file name
+- `{{{language}}}` - Programming language
+
+**Use case:** When model benefits from explicit file context
+
+### Determining FIM Format
+
+Check model documentation or training details:
+
+1. **Llama/CodeLlama family:** Use `<|fim_prefix|>` format with pipes
+2. **StarCoder family:** Use `<fim_prefix>` format without pipes
+3. **DeepSeek family:** Use `<|fim▁begin|>` format with special character
+4. **Unknown models:** Start with prefix-only `"{{{prefix}}}"`, then test with Llama format
+
+### Testing FIM Templates
+
+Verify FIM template works correctly:
+
+1. Configure template in config.yaml
+2. Reload VS Code
+3. Create test file with known completion
+4. Type partial code and pause
+5. Check if completion is relevant and correctly positioned
+
+**Example test:**
+```python
+def fibonacci(n):
+    # Pause here and check if completion continues logically
+```
+
+---
+
+## Feature Usage
+
+### Using Chat Mode
+
+**Purpose:** Ask questions, get explanations, solve problems
+
+**Steps:**
+1. Press `Ctrl+L` to open chat
+2. Type your question or request
+3. Press Enter
+4. Review response
+5. Use action buttons:
+   - **Apply**: Replace highlighted code with suggestion
+   - **Insert**: Add suggestion at cursor position
+   - **Copy**: Copy to clipboard
+
+**Adding Context:**
+- Highlight code before opening chat (auto-included)
+- Use `@Files` to reference specific files
+- Use `@Terminal` to include terminal output
+- Use `@Codebase` to search entire project
+
+**Examples:**
+```
+"Explain how this function works"
+"Fix the bug in the highlighted code"
+"Refactor this to use async/await"
+"@Files package.json - What dependencies can I update?"
+```
+
+### Using Edit Mode
+
+**Purpose:** Make targeted changes to selected code
+
+**Steps:**
+1. Highlight code to modify
+2. Press `Ctrl+I`
+3. Type instruction (e.g., "Add error handling")
+4. Press Enter
+5. Review diff preview
+6. Accept or reject changes
+
+**Examples:**
+```
+"Add JSDoc comments"
+"Convert to TypeScript"
+"Optimize for performance"
+"Add input validation"
+"Handle edge cases"
+```
+
+### Using Autocomplete
+
+**Purpose:** Get real-time code suggestions while typing
+
+**Setup:**
+1. Click "Continue" in status bar
+2. Enable "Tab Autocomplete"
+3. Start typing code
+4. Suggestions appear automatically
+
+**Accepting Suggestions:**
+- `Tab`: Accept full suggestion
+- `Esc`: Reject suggestion
+- `Ctrl+→` (or `Cmd+→`): Accept word-by-word
+- `Ctrl+Alt+Space`: Force trigger suggestion
+
+**Best Practices:**
+- Write clear function names and comments
+- Use type annotations (TypeScript/Python)
+- Provide meaningful variable names
+- Context helps improve suggestions
+
+**Examples of When Autocomplete Shines:**
+```python
+def calculate_fibonacci(n: int) -> int:
+    # Autocomplete suggests full implementation
+```
+
+```javascript
+// After typing: const fetchUserData = async (userId) =>
+// Autocomplete suggests: { try { const response = await... }
+```
+
+### Using Plan Mode
+
+**Purpose:** Explore codebase safely before making changes
+
+**Steps:**
+1. Open Continue sidebar
+2. Click mode selector dropdown
+3. Choose "Plan"
+4. Ask questions or request analysis
+5. Review read-only findings
+6. Switch to Agent mode to implement changes
+
+**Safe Operations:**
+- Read files, search code, view diffs
+- No file modifications possible
+- Cannot run terminal commands
+
+**Examples:**
+```
+"Show me all API endpoints in this project"
+"Find where user authentication is implemented"
+"Analyze the database schema structure"
+"List all TODO comments in the codebase"
+```
+
+### Using Agent Mode
+
+**Purpose:** Complex, multi-step tasks requiring file operations
+
+**Steps:**
+1. Open Continue sidebar
+2. Click mode selector dropdown
+3. Choose "Agent"
+4. Type task instruction
+5. Review proposed tool calls
+6. Grant permission for each operation
+7. Verify final changes
+
+**Tool Permission:**
+- Agent asks before: Reading files, editing files, running commands
+- Review each proposed action carefully
+- Can reject individual tool calls
+
+**Examples:**
+```
+"Implement a new authentication middleware in Express"
+"Fix all ESLint errors in the src directory"
+"Add unit tests for the UserService class"
+"Refactor the database connection to use connection pooling"
+```
+
+---
+
+## Best Practices
+
+### For Chat Mode
+
+1. Start new session for different topics (`Ctrl+L`)
+2. Provide context by highlighting code or using `@Files`
+3. Be specific: "Fix the null pointer error on line 45" vs "Fix bugs"
+4. Ask follow-up questions to refine responses
+
+### For Edit Mode
+
+1. Highlight exact code section to modify
+2. Give clear instructions: "Add type hints" vs "Improve code"
+3. Review diffs before accepting
+4. Use VS Code undo (`Ctrl+Z`) if needed
+
+### For Autocomplete
+
+1. Enable strategically (disable during presentations or pairing)
+2. Review suggestions before accepting
+3. Learn what triggers good suggestions
+4. Provide context with clear function signatures and comments
+
+### For Plan Mode
+
+1. Explore codebase before implementing changes
+2. Understand project structure first
+3. Safe analysis with no risk of breaking code
+
+### For Agent Mode
+
+1. Review proposed tool calls before accepting
+2. Break complex tasks into smaller operations
+3. Commit code before running agent tasks
+4. Monitor tool execution and verify outputs
+
+### Performance Optimization
+
+1. Keep `contextLength` within model capacity
+2. Set reasonable `maxTokens` to reduce latency
+3. Use lower temperature (0.1-0.3) for consistent output
+4. Autocomplete caching is automatic, no action needed
+
+### Security and Privacy
+
+1. Never commit API keys to version control
+2. Use environment variables or secure vaults for keys
+3. All processing happens on your GenAI Gateway (no external services)
+4. Use `ignoreSSL: true` only for trusted self-signed certificates
+
+---
+
+## Advanced Configuration
+
+### Custom Rules
+
+Rules allow you to define custom system prompts and behavior guidelines for Continue. Rules can be project-specific or global, helping tailor AI responses to your coding standards and requirements.
+
+#### What Are Rules?
+
+Rules are markdown files containing instructions that are automatically included in the context when interacting with Continue. They guide the model's behavior, enforce coding standards, or provide project-specific context.
+
+**Use Cases:**
+- Enforce coding style guidelines
+- Define project-specific conventions
+- Add company policies or security requirements
+- Provide context about project architecture
+- Set response format preferences
+
+#### Creating Global Rules
+
+Global rules apply to all projects.
+
+**Location:**
+```
+Windows: C:\Users\<username>\.continue\rules\
+macOS/Linux: ~/.continue/rules/
+```
+
+**Steps:**
+
+1. Create the rules directory:
+```bash
+# Windows
+mkdir C:\Users\<username>\.continue\rules
+
+# macOS/Linux
+mkdir -p ~/.continue/rules
+```
+
+2. Create a rule file (e.g., `coding-style.md`):
+```markdown
+# Coding Style Guidelines
+
+Follow these conventions when generating code:
+
+## Python
+- Use type hints for all function parameters and return values
+- Follow PEP 8 style guide
+- Maximum line length: 100 characters
+- Use docstrings for all functions and classes
+
+## JavaScript/TypeScript
+- Use const/let instead of var
+- Prefer arrow functions for callbacks
+- Use async/await instead of promises
+- Add JSDoc comments for all functions
+
+## General
+- Write clear, descriptive variable names
+- Add comments for complex logic
+- Include error handling
+- Write modular, reusable code
+```
+
+3. Rules are automatically loaded when Continue starts
+
+#### Creating Project-Specific Rules
+
+Project rules apply only to a specific project.
+
+**Location:**
+```
+<project-root>/.continue/rules/
+```
+
+**Steps:**
+
+1. Navigate to your project root
+2. Create the rules directory:
+```bash
+mkdir -p .continue/rules
+```
+
+3. Create a project rule file (e.g., `architecture.md`):
+```markdown
+# Project Architecture
+
+This project follows a microservices architecture.
+
+## Structure
+- `/api` - REST API endpoints
+- `/services` - Business logic layer
+- `/models` - Database models
+- `/utils` - Utility functions
+
+## Database
+- PostgreSQL with SQLAlchemy ORM
+- Migrations in `/migrations`
+
+## Authentication
+- JWT tokens for API authentication
+- Keycloak for user management
+
+## Code Generation Guidelines
+- All new endpoints must include authentication
+- Add unit tests for all new services
+- Use async/await for database operations
+```
+
+#### Rule Examples
+
+**Security Rule** (`.continue/rules/security.md`):
+```markdown
+# Security Guidelines
+
+When generating code:
+- Never log sensitive information (passwords, API keys, tokens)
+- Validate all user inputs
+- Use parameterized queries to prevent SQL injection
+- Sanitize data before rendering in HTML
+- Always use HTTPS for external API calls
+```
+
+**Documentation Rule** (`.continue/rules/documentation.md`):
+```markdown
+# Documentation Standards
+
+All functions must include:
+- Brief description of purpose
+- Parameter descriptions with types
+- Return value description
+- Example usage
+- Exceptions that may be raised
+
+Format:
+```python
+def function_name(param1: type1, param2: type2) -> return_type:
+    """
+    Brief description.
+
+    Args:
+        param1: Description of param1
+        param2: Description of param2
+
+    Returns:
+        Description of return value
+
+    Raises:
+        ExceptionType: When this exception occurs
+
+    Example:
+        >>> function_name(value1, value2)
+        expected_output
+    """
+```
+```
+
+**Testing Rule** (`.continue/rules/testing.md`):
+```markdown
+# Testing Requirements
+
+When creating new features:
+- Write unit tests for all functions
+- Aim for 80% code coverage
+- Include edge cases and error scenarios
+- Mock external dependencies
+
+Test file structure:
+- Test files in `/tests` directory
+- Mirror source directory structure
+- Name test files: `test_<module_name>.py`
+```
+
+#### Using Rules
+
+Rules are automatically included in context. You can reference them explicitly:
+
+1. In Chat mode, rules influence all responses
+2. In Edit mode, rules guide code transformations
+3. In Agent mode, rules affect code generation decisions
+
+**Note:** Rules add to context token count. Keep rules concise to avoid exceeding context limits with smaller models.
+
+---
+
+### MCP Servers (Model Context Protocol)
+
+MCP servers extend Continue's functionality by adding custom tools, context providers, and external integrations. They enable Continue to interact with databases, APIs, file systems, and other services.
+
+#### What Is MCP?
+
+Model Context Protocol is a standard for connecting AI assistants to external tools and data sources. MCP servers provide:
+- Custom context providers (fetch data from external sources)
+- Custom tools (perform actions like API calls, database queries)
+- Integration with external services
+
+#### Use Cases
+
+- Query databases directly from Continue
+- Fetch documentation from internal wikis
+- Integrate with project management tools
+- Access company knowledge bases
+- Call internal APIs for data retrieval
+- Run custom scripts and automation
+
+#### MCP Server Installation
+
+MCP servers are configured in `config.yaml` under the `mcpServers` section.
+
+**Basic Structure:**
+```yaml
+mcpServers:
+  server-name:
+    command: node
+    args:
+      - /path/to/server/index.js
+    env:
+      API_KEY: your-api-key
+```
+
+#### Example: Filesystem MCP Server
+
+Access local file system through Continue.
+
+**Install MCP Server:**
+```bash
+npm install -g @modelcontextprotocol/server-filesystem
+```
+
+**Add to config.yaml:**
+```yaml
+mcpServers:
+  filesystem:
+    command: node
+    args:
+      - /usr/local/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js
+      - /path/to/allowed/directory
+    env: {}
+```
+
+**Usage in Continue:**
+- Access files outside workspace
+- Read configuration files from system directories
+- Query logs from application directories
+
+#### Example: PostgreSQL MCP Server
+
+Query databases directly from Continue.
+
+**Install MCP Server:**
+```bash
+npm install -g @modelcontextprotocol/server-postgres
+```
+
+**Add to config.yaml:**
+```yaml
+mcpServers:
+  postgres:
+    command: node
+    args:
+      - /usr/local/lib/node_modules/@modelcontextprotocol/server-postgres/dist/index.js
+    env:
+      POSTGRES_CONNECTION_STRING: postgresql://user:password@localhost:5432/database
+```
+
+**Usage in Continue:**
+```
+"@postgres - Show me the schema for the users table"
+"@postgres - Query all orders from last month"
+"@postgres - Find customers with more than 10 orders"
+```
+
+#### Example: GitHub MCP Server
+
+Integrate with GitHub repositories.
+
+**Install MCP Server:**
+```bash
+npm install -g @modelcontextprotocol/server-github
+```
+
+**Add to config.yaml:**
+```yaml
+mcpServers:
+  github:
+    command: node
+    args:
+      - /usr/local/lib/node_modules/@modelcontextprotocol/server-github/dist/index.js
+    env:
+      GITHUB_TOKEN: your-github-token
+```
+
+**Usage in Continue:**
+```
+"@github - Show open pull requests"
+"@github - List recent issues"
+"@github - Get commit history for main branch"
+```
+
+#### Creating Custom MCP Server
+
+Build custom MCP servers for internal tools and services.
+
+**1. Create Server Project:**
+```bash
+mkdir my-mcp-server
+cd my-mcp-server
+npm init -y
+npm install @modelcontextprotocol/sdk
+```
+
+**2. Create Server Code (`index.js`):**
+```javascript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+// Create server instance
+const server = new Server(
+  {
+    name: 'my-custom-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define custom tool
+server.setRequestHandler('tools/list', async () => {
+  return {
+    tools: [
+      {
+        name: 'query_internal_api',
+        description: 'Query internal company API',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            endpoint: {
+              type: 'string',
+              description: 'API endpoint to query',
+            },
+            params: {
+              type: 'object',
+              description: 'Query parameters',
+            },
+          },
+          required: ['endpoint'],
+        },
+      },
+    ],
+  };
+});
+
+// Implement tool execution
+server.setRequestHandler('tools/call', async (request) => {
+  if (request.params.name === 'query_internal_api') {
+    const { endpoint, params } = request.params.arguments;
+
+    // Call your internal API
+    const response = await fetch(`https://internal-api.company.com/${endpoint}`, {
+      method: 'GET',
+      headers: { 'Authorization': `Bearer ${process.env.API_KEY}` },
+    });
+
+    const data = await response.json();
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(data, null, 2),
+        },
+      ],
+    };
+  }
+});
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+**3. Add to config.yaml:**
+```yaml
+mcpServers:
+  my-custom-server:
+    command: node
+    args:
+      - /path/to/my-mcp-server/index.js
+    env:
+      API_KEY: your-internal-api-key
+```
+
+**4. Use in Continue:**
+```
+"@my-custom-server - Query the users endpoint"
+"@my-custom-server - Get latest metrics from analytics"
+```
+
+#### MCP Server Best Practices
+
+**Security:**
+- Store sensitive credentials in environment variables
+- Never commit API keys to version control
+- Use read-only access where possible
+- Validate all inputs before processing
+
+**Performance:**
+- Cache frequently accessed data
+- Implement request timeouts
+- Limit result set sizes
+- Use pagination for large datasets
+
+**Error Handling:**
+- Return clear error messages
+- Log errors for debugging
+- Handle network failures gracefully
+- Provide fallback responses
+
+**Documentation:**
+- Document all available tools
+- Provide clear input schemas
+- Include usage examples
+- Document environment variables required
+
+#### Troubleshooting MCP Servers
+
+**Server Not Loading:**
+1. Check `command` path is correct
+2. Verify Node.js is installed: `node --version`
+3. Check server is executable
+4. Review VS Code Output → Continue for errors
+
+**Tool Not Appearing:**
+1. Reload VS Code after config changes
+2. Check server implements `tools/list` handler
+3. Verify tool schema is valid
+4. Check Continue output logs
+
+**Tool Execution Fails:**
+1. Verify environment variables are set correctly
+2. Check network connectivity to external services
+3. Validate API credentials
+4. Review error messages in Continue output
+
+---
+
+## Troubleshooting
+
+For comprehensive troubleshooting guidance, common issues, and solutions, refer to [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
+
+---
+
+## Additional Resources
+
+- Continue Documentation: https://docs.continue.dev/
+- Continue GitHub: https://github.com/continuedev/continue
+- Continue Discord: https://discord.gg/NWtdYexhMs
+- LiteLLM Documentation: https://docs.litellm.ai/
diff --git a/CodeGeneration/TROUBLESHOOTING.md b/CodeGeneration/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..68c669c006
--- /dev/null
+++ b/CodeGeneration/TROUBLESHOOTING.md
@@ -0,0 +1,614 @@
+# Troubleshooting Guide
+
+Common issues encountered during setup and operation of Continue VS Code extension with GenAI Gateway, along with solutions.
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [Configuration Issues](#configuration-issues)
+- [Authentication Issues](#authentication-issues)
+- [Autocomplete Issues](#autocomplete-issues)
+- [Chat Mode Issues](#chat-mode-issues)
+- [Edit Mode Issues](#edit-mode-issues)
+- [Plan and Agent Mode Issues](#plan-and-agent-mode-issues)
+- [Performance Issues](#performance-issues)
+- [General Debugging](#general-debugging)
+
+---
+
+## Installation Issues
+
+### Continue Extension Not Found
+
+**Solution:**
+
+1. Open VS Code Extensions (`Ctrl+Shift+X`)
+2. Search for exact name: "Continue"
+3. Publisher must be "Continue"
+4. Extension ID: `Continue.continue`
+5. Verify VS Code is updated to latest version
+
+### Continue Icon Not Appearing
+
+**Solution:**
+
+1. Restart VS Code completely
+2. Check Extensions view - ensure extension is enabled
+3. Look for Continue icon in Activity Bar (left sidebar)
+4. Test keyboard shortcut `Ctrl+L`
+5. Reinstall extension if issue persists
+
+---
+
+## Configuration Issues
+
+### Config File Not Found
+
+**Solution:**
+
+Configuration file location:
+
+**Windows:**
+```
+C:\Users\<username>\.continue\config.yaml
+```
+
+**macOS/Linux:**
+```
+~/.continue/config.yaml
+```
+
+Create the file via Command Palette: `Ctrl+Shift+P` → "Continue: Open config.yaml"
+
+### Invalid YAML Syntax
+
+**Solution:**
+
+1. Use spaces for indentation (not tabs)
+2. Verify quotes around special characters
+3. Check list and array formatting
+4. Validate with online YAML validator
+5. Compare against working example in README
+
+### Model Not Found
+
+**Solution:**
+
+1. Model names are case-sensitive
+2. Verify exact model name from Gateway:
+```bash
+curl -k https://api.example.com/v1/models \
+  -H "Authorization: Bearer your-api-key-here"
+```
+3. Update config with exact match from response
+4. For this setup, use: `meta-llama/Llama-3.2-3B-Instruct`
+
+### API Base URL Errors
+
+**Solution:**
+
+1. URL must include `/v1` suffix:
+```yaml
+apiBase: "https://api.example.com/v1"
+```
+2. Verify URL is accessible:
+```bash
+curl -k https://api.example.com/v1/models
+```
+3. Remove trailing slashes from URL
+
+### Model Timeout Missing
+
+**Critical Issue:** Autocomplete requests fail with "Operation Aborted" errors.
+
+**Solution:**
+
+Add `modelTimeout` to `tabAutocompleteOptions` in config.yaml:
+```yaml
+tabAutocompleteOptions:
+  modelTimeout: 10000
+```
+
+This setting is critical for CPU-based inference which takes 5-10 seconds. Default timeout is 150ms, which is too short.
+
+### Settings Not Applied from Config
+
+**Issue:** Config.yaml changes do not take effect.
+
+**Solution:**
+
+VS Code settings have the highest priority and override config.yaml values. Check these in order:
+
+1. **VS Code User Settings (Highest Priority):** Open `settings.json` and verify critical settings:
+   - `editor.inlineSuggest.enabled: true` (CRITICAL - must be enabled)
+   - `continue.enableTabAutocomplete: true`
+
+   See [SETUP_GUIDE.md - Required VS Code Settings](./SETUP_GUIDE.md#required-vs-code-settings) for complete configuration details.
+
+2. **Continue UI Settings:** Click Continue icon → Settings (gear icon) and verify:
+   - Autocomplete Timeout: 10000ms
+   - Autocomplete Debounce: 3000ms
+   - Max Tokens: Match your config
+
+3. **Reload VS Code:** `Ctrl+Shift+P` → "Developer: Reload Window"
+
+**Settings Priority Order:**
+```
+VS Code User Settings (settings.json) > Continue UI Settings > config.yaml > Hardcoded Defaults
+```
+
+---
+
+## Authentication Issues
+
+### Invalid API Key
+
+**Solution:**
+
+1. Verify API key matches Gateway credentials
+2. Test API key manually:
+```bash
+curl -k https://api.example.com/v1/models \
+  -H "Authorization: Bearer your-api-key-here"
+```
+3. Check for extra spaces in API key
+4. Ensure `sk-` prefix is present
+5. Request new API key if expired
+
+### SSL Certificate Errors
+
+**Solution:**
+
+Add to config for self-signed certificates:
+```yaml
+ignoreSSL: true
+verifySsl: false
+```
+
+Only use on trusted internal networks.
+
+### Connection Timeout
+
+**Solution:**
+
+1. Verify network connectivity:
+```bash
+ping api.example.com
+```
+2. Check Gateway status:
+```bash
+curl -k https://api.example.com/health
+```
+3. Verify firewall allows outbound HTTPS (port 443)
+4. Check DNS resolution
+5. Ensure VPN is connected if required
+
+---
+
+## Autocomplete Issues
+
+### No Suggestions Appearing
+
+**Solution:**
+
+1. Enable autocomplete in status bar:
+   - Click "Continue" in status bar
+   - Check "Enable Tab Autocomplete"
+2. Verify model has `autocomplete` role in config
+3. Check `useLegacyCompletionsEndpoint: true` is set
+4. Verify `modelTimeout: 10000` is present in `tabAutocompleteOptions`
+5. Restart VS Code
+6. Test after pausing 3 seconds following typing
+
+### Autocomplete Timeouts
+
+**Issue:** All autocomplete requests timeout with "Operation Aborted" error.
+
+**Solution:**
+
+Add or update `modelTimeout` in config.yaml:
+```yaml
+tabAutocompleteOptions:
+  modelTimeout: 10000
+```
+
+CPU-based inference requires 5-10 seconds. Default 150ms timeout is insufficient.
+
+### Multiple Rapid Requests
+
+**Issue:** Too many autocomplete requests sent in short time (10+ per minute).
+
+**Solution:**
+
+1. Increase `debounceDelay` in config.yaml:
+```yaml
+tabAutocompleteOptions:
+  debounceDelay: 3000
+```
+2. Type complete line before pausing
+3. Wait for debounce timer to expire (3 seconds)
+4. Avoid typing while autocomplete is generating
+
+### Suggestions Continue After Accepting
+
+**Solution:**
+
+1. Start typing immediately after pressing Tab
+2. Debounce timer resets with new keystrokes
+3. Disable autocomplete temporarily if distracting
+
+### Autocomplete in Markdown Files
+
+**Solution:**
+
+Autocomplete is disabled in `.md` files by default. To enable:
+
+1. Edit config.yaml:
+```yaml
+tabAutocompleteOptions:
+  disableInFiles:
+    # - "*.md"  # Comment out to enable
+```
+2. Reload VS Code
+
+### Low Quality or Repetitive Completions
+
+**Issue:** Completions generate repetitive or irrelevant code.
+
+**Solution:**
+
+1. Verify `autocompleteOptions` is configured:
+```yaml
+autocompleteOptions:
+  maxTokens: 256
+  temperature: 0.2
+  stop:
+    - "\n\n\n"
+    - "# "
+```
+2. Check temperature is low (0.2) for consistency
+3. Ensure `maxTokens` is limited (256) for faster completions
+4. Test in clean files without repetitive patterns
+
+---
+
+## Chat Mode Issues
+
+### No Response in Chat
+
+**Solution:**
+
+1. Check VS Code Output panel:
+   - View → Output
+   - Select "Continue" from dropdown
+2. Test API manually:
+```bash
+curl -k https://api.example.com/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key-here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.2-3B-Instruct",
+    "messages": [{"role": "user", "content": "Hello"}],
+    "max_tokens": 50
+  }'
+```
+3. Verify model has `chat` role in config
+4. Restart VS Code
+5. Start fresh chat session (`Ctrl+L`)
+
+### Context Too Large Errors
+
+**Issue:** Error message stating context exceeds model's maximum capacity.
+
+**Solution:**
+
+1. Reduce `maxTokens` in config:
+```yaml
+completionOptions:
+  maxTokens: 1024
+```
+2. Limit highlighted code blocks
+3. Reduce `@Files` references to 2-3 files
+4. Start fresh chat session
+5. Avoid including large files (>1000 lines)
+
+---
+
+## Edit Mode Issues
+
+### Edit Mode Not Responding
+
+**Solution:**
+
+1. Verify model has `edit` role in config
+2. Check keyboard shortcut:
+   - Windows/Linux: `Ctrl+I`
+   - Mac: `Cmd+I`
+3. Try alternative method:
+   - Highlight code
+   - Open Continue sidebar
+   - Switch to Edit mode manually
+4. Check VS Code Output panel for errors
+
+### Diff Not Showing
+
+**Solution:**
+
+1. Ensure code is highlighted before pressing `Ctrl+I`
+2. Provide clear instruction in edit prompt
+3. Wait for model response to complete
+4. Check Output panel for errors
+
+---
+
+## Plan and Agent Mode Issues
+
+### Context Window Exceeded in Plan Mode
+
+**Issue:** Error message "max_tokens is too large" when using Plan mode.
+
+**Example Error:**
+```
+'max_tokens' or 'max_completion_tokens' is too large: 2048.
+This model's maximum context length is 8192 tokens and your
+request has 5638 input tokens
+```
+
+**Solution:**
+
+Plan mode includes large system prompts (5000+ tokens). Reduce response tokens:
+
+1. Lower `maxTokens` in config:
+```yaml
+completionOptions:
+  maxTokens: 1024
+```
+2. Avoid complex tasks requiring long responses
+3. Disable tools in UI settings if not needed:
+   - Open Continue sidebar
+   - Click settings icon
+   - Disable unused tool options
+
+### Context Window Exceeded in Agent Mode
+
+**Issue:** Similar to Plan mode but with higher token usage (7000-9000 tokens).
+
+**Solution:**
+
+Agent mode requires more context than Plan mode. Apply same fixes:
+
+1. Reduce `maxTokens` to 1024 or lower
+2. Break tasks into smaller operations
+3. Use simpler instructions
+4. Consider using Chat or Edit mode for single operations
+
+### Agent Mode Disabled or Limited
+
+**Solution:**
+
+1. Verify model supports tool calling
+2. Check Continue output logs for compatibility messages
+3. Use Plan mode as alternative for read-only operations
+4. Use Edit mode for single file modifications
+
+### Tool Call Failures
+
+**Solution:**
+
+1. Review tool permission prompts carefully
+2. Verify file paths exist before operations
+3. Check write permissions for file edits
+4. Break complex tasks into 1-2 step operations
+
+---
+
+## Performance Issues
+
+### Slow Response Times
+
+**Solution:**
+
+1. Test network latency:
+```bash
+ping api.example.com
+```
+2. Reduce context size in config:
+```yaml
+contextLength: 4096
+completionOptions:
+  maxTokens: 1024
+```
+3. Limit context providers:
+   - Avoid `@Codebase` for large projects
+   - Limit `@Files` to 2-3 files
+   - Exclude large files
+4. Verify Gateway has sufficient resources
+
+### High Memory Usage
+
+**Solution:**
+
+1. Restart VS Code to clear cache
+2. Avoid `@Codebase` on large projects
+3. Close unused VS Code windows
+4. Limit file references in context
+
+### Autocomplete Latency
+
+**Issue:** Autocomplete takes too long to respond.
+
+**Solution:**
+
+1. Verify `debounceDelay` is set appropriately:
+```yaml
+tabAutocompleteOptions:
+  debounceDelay: 3000
+```
+2. Check `maxPromptTokens` is limited:
+```yaml
+tabAutocompleteOptions:
+  maxPromptTokens: 100
+```
+3. Reduce `maxTokens` in `autocompleteOptions`:
+```yaml
+autocompleteOptions:
+  maxTokens: 256
+```
+4. Set `prefixPercentage: 1.0` and `suffixPercentage: 0.0` to reduce context
+
+---
+
+## General Debugging
+
+### Check Continue Version
+
+1. Open Extensions (`Ctrl+Shift+X`)
+2. Find Continue extension
+3. Verify version is latest
+4. Update if outdated
+
+### Enable Debug Logging
+
+1. Open VS Code Developer Tools:
+   - `Ctrl+Shift+P` → "Toggle Developer Tools"
+2. Click Console tab
+3. Look for Continue errors
+
+### View Continue Output
+
+1. Open Output panel: View → Output
+2. Select "Continue" from dropdown
+3. Review logs for errors and warnings
+
+### Reset Configuration
+
+Backup and reset config if all else fails:
+
+```bash
+# Windows
+copy C:\Users\USERNAME\.continue\config.yaml config.yaml.backup
+del C:\Users\USERNAME\.continue\config.yaml
+
+# Linux/Mac
+cp ~/.continue/config.yaml config.yaml.backup
+rm ~/.continue/config.yaml
+```
+
+Restart VS Code and reconfigure from scratch.
+
+### Test Gateway Directly
+
+Bypass Continue to isolate issues:
+
+```bash
+# Test models endpoint
+curl -k https://api.example.com/v1/models \
+  -H "Authorization: Bearer your-api-key-here"
+
+# Test chat endpoint
+curl -k https://api.example.com/v1/chat/completions \
+  -H "Authorization: Bearer your-api-key-here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.2-3B-Instruct",
+    "messages": [{"role": "user", "content": "Test"}],
+    "max_tokens": 50
+  }'
+
+# Test completions endpoint
+curl -k https://api.example.com/v1/completions \
+  -H "Authorization: Bearer your-api-key-here" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.2-3B-Instruct",
+    "prompt": "def hello():\n    ",
+    "max_tokens": 100
+  }'
+```
+
+If manual tests work, the issue is in Continue configuration.
+
+### Verify Configuration Values
+
+Check that critical values are present in config.yaml:
+
+```yaml
+tabAutocompleteOptions:
+  debounceDelay: 3000
+  modelTimeout: 10000
+  maxPromptTokens: 100
+
+models:
+  - autocompleteOptions:
+      maxTokens: 256
+      temperature: 0.2
+```
+
+### Restart Checklist
+
+1. Reload Continue: Command Palette → "Continue: Reload"
+2. Restart VS Code: Close and reopen
+3. Clear cache: Delete `~/.continue/cache/` folder
+4. Reinstall extension: Uninstall → Restart → Install → Restart
+
+### Common Configuration Mistakes
+
+**Missing modelTimeout:**
+```yaml
+# Wrong - missing modelTimeout
+tabAutocompleteOptions:
+  debounceDelay: 3000
+
+# Correct
+tabAutocompleteOptions:
+  debounceDelay: 3000
+  modelTimeout: 10000
+```
+
+**Wrong API Base URL:**
+```yaml
+# Wrong - missing /v1 suffix
+apiBase: "https://api.example.com"
+
+# Correct
+apiBase: "https://api.example.com/v1"
+```
+
+**Missing autocompleteOptions:**
+```yaml
+# Wrong - only completionOptions
+models:
+  - completionOptions:
+      maxTokens: 2048
+
+# Correct - both sections
+models:
+  - completionOptions:
+      maxTokens: 2048
+    autocompleteOptions:
+      maxTokens: 256
+      temperature: 0.2
+```
+
+**Missing Legacy Endpoint:**
+```yaml
+# Wrong - missing setting
+experimental:
+  inlineEditing: true
+
+# Correct
+useLegacyCompletionsEndpoint: true
+experimental:
+  inlineEditing: true
+```
+
+---
+
+## Additional Help
+
+If issues persist after following this guide:
+
+1. Check Continue documentation: https://docs.continue.dev/
+2. Review [SETUP_GUIDE.md](./SETUP_GUIDE.md) for detailed configuration, FIM templates, custom rules, and MCP servers
+3. Verify GenAI Gateway logs for backend errors
+4. Contact Gateway administrator for API issues
diff --git a/CodeGeneration/src/agent-mode.gif b/CodeGeneration/src/agent-mode.gif
new file mode 100644
index 0000000000..a5f62ee3fa
Binary files /dev/null and b/CodeGeneration/src/agent-mode.gif differ
diff --git a/CodeGeneration/src/agent-mode.png b/CodeGeneration/src/agent-mode.png
new file mode 100644
index 0000000000..0477e507dc
Binary files /dev/null and b/CodeGeneration/src/agent-mode.png differ
diff --git a/CodeGeneration/src/autocomplete-demo.gif b/CodeGeneration/src/autocomplete-demo.gif
new file mode 100644
index 0000000000..ded05274a9
Binary files /dev/null and b/CodeGeneration/src/autocomplete-demo.gif differ
diff --git a/CodeGeneration/src/autocomplete-demo.png b/CodeGeneration/src/autocomplete-demo.png
new file mode 100644
index 0000000000..1eb914d2bd
Binary files /dev/null and b/CodeGeneration/src/autocomplete-demo.png differ
diff --git a/CodeGeneration/src/chat-mode-1.png b/CodeGeneration/src/chat-mode-1.png
new file mode 100644
index 0000000000..c0c039be2b
Binary files /dev/null and b/CodeGeneration/src/chat-mode-1.png differ
diff --git a/CodeGeneration/src/chat-mode.gif b/CodeGeneration/src/chat-mode.gif
new file mode 100644
index 0000000000..058eabdf53
Binary files /dev/null and b/CodeGeneration/src/chat-mode.gif differ
diff --git a/CodeGeneration/src/chat-mode.png b/CodeGeneration/src/chat-mode.png
new file mode 100644
index 0000000000..78280f21f0
Binary files /dev/null and b/CodeGeneration/src/chat-mode.png differ
diff --git a/CodeGeneration/src/edit-mode-demo.png b/CodeGeneration/src/edit-mode-demo.png
new file mode 100644
index 0000000000..4d21ff83f3
Binary files /dev/null and b/CodeGeneration/src/edit-mode-demo.png differ
diff --git a/CodeGeneration/src/edit-mode.gif b/CodeGeneration/src/edit-mode.gif
new file mode 100644
index 0000000000..85bccca411
Binary files /dev/null and b/CodeGeneration/src/edit-mode.gif differ
diff --git a/CodeTranslation/.env.example b/CodeTranslation/.env.example
new file mode 100644
index 0000000000..048c7a2a47
--- /dev/null
+++ b/CodeTranslation/.env.example
@@ -0,0 +1,22 @@
+# Backend API Configuration
+BACKEND_PORT=5001
+
+# Keycloak Authentication
+BASE_URL=https://your-enterprise-api.com
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your-client-secret
+
+# Model Configuration - CodeLlama-34b-instruct
+INFERENCE_MODEL_ENDPOINT=CodeLlama-34b-Instruct-hf
+INFERENCE_MODEL_NAME=codellama/CodeLlama-34b-Instruct-hf
+
+# LLM Settings
+LLM_TEMPERATURE=0.2
+LLM_MAX_TOKENS=4096
+
+# Code Translation Settings
+MAX_CODE_LENGTH=10000
+MAX_FILE_SIZE=10485760
+
+# CORS Configuration
+CORS_ALLOW_ORIGINS=["http://localhost:5173", "http://localhost:3000"]
diff --git a/CodeTranslation/.gitignore b/CodeTranslation/.gitignore
new file mode 100644
index 0000000000..7499b4114d
--- /dev/null
+++ b/CodeTranslation/.gitignore
@@ -0,0 +1,60 @@
+# Environment variables
+.env
+.env.local
+.env.production
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+venv/
+env/
+ENV/
+.venv
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+.npm
+.yarn
+package-lock.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Build outputs
+dist/
+*.log
+
+# Temporary files
+*.tmp
+tmp/
+temp/
diff --git a/CodeTranslation/README.md b/CodeTranslation/README.md
new file mode 100644
index 0000000000..a6105a6920
--- /dev/null
+++ b/CodeTranslation/README.md
@@ -0,0 +1,294 @@
+## Code Translation
+
+A full-stack code translation application that converts code between programming languages using AI.
+The system integrates a FastAPI backend powered by CodeLlama-34b-instruct, alongside a modern React + Vite + Tailwind CSS frontend for an intuitive translation experience.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick Start Deployment](#quick-start-deployment)
+- [User Interface](#user-interface)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Overview
+
+The **Code Translation** application demonstrates how large language models can be used to translate code between different programming languages. It accepts source code in one language, processes it through CodeLlama-34b-instruct, and returns translated code in the target language. This project integrates seamlessly with cloud-hosted APIs or local model endpoints, offering flexibility for research, enterprise, or educational use.
+
+---
+
+## Features
+
+**Backend**
+
+- Code translation between 6 languages (Java, C, C++, Python, Rust, Go)
+- PDF code extraction with pattern recognition
+- CodeLlama-34b-instruct for accurate translations
+- Enterprise inference endpoints
+- Keycloak authentication for secure API access
+- Comprehensive error handling and logging
+- File validation and size limits
+- CORS enabled for web integration
+- Health check endpoints
+- Modular architecture (config + models + services)
+
+**Frontend**
+
+- Side-by-side code comparison interface
+- Language selection dropdowns (6 languages)
+- PDF file upload with drag-and-drop support
+- Real-time character counter with limits
+- Modern, responsive design with Tailwind CSS
+- Built with Vite for fast development
+- Live status updates
+- Copy to clipboard functionality
+- Mobile-friendly
+
+---
+
+## Architecture
+
+Below is the architecture as it consists of a server that waits for code input or PDF uploads. Once code is provided, the server calls the CodeLlama model to translate the code to the target language.
+
+```mermaid
+  graph TB
+      subgraph "User Interface"
+          A[React Frontend<br/>Port 3000]
+          A1[Code Input]
+          A2[PDF Upload]
+          A3[Language Selection]
+      end
+
+      subgraph "FastAPI Backend"
+          B[API Server<br/>Port 5001]
+          C[PDF Service]
+          D[API Client]
+      end
+
+      subgraph "External Services"
+          E[Keycloak Auth]
+          F[CodeLlama-34b Model]
+      end
+
+      A1 --> B
+      A2 --> B
+      A3 --> B
+      B --> C
+      C -->|Extracted Code| B
+      B --> D
+      D -->|Get Token| E
+      E -->|Access Token| D
+      D -->|Translate Code + Token| F
+      F -->|Translated Code| D
+      D --> B
+      B --> A
+
+      style A fill:#e1f5ff
+      style B fill:#fff4e1
+      style F fill:#e1ffe1
+```
+
+This application is built with enterprise inference capabilities using Keycloak for authentication and CodeLlama-34b-instruct for code translation.
+
+**Service Components:**
+
+1. **React Web UI (Port 3000)** -  Provides side-by-side code comparison interface with language selection, PDF upload, and real-time translation results
+
+2. **FastAPI Backend (Port 5001)** -  Handles code validation, PDF extraction, Keycloak authentication, and orchestrates code translation through CodeLlama model
+
+**Typical Flow:**
+
+1. User enters code or uploads a PDF through the web UI.
+2. The backend validates the input and extracts code if needed.
+3. The backend authenticates with Keycloak and calls CodeLlama model.
+4. The model translates the code to the target language.
+5. The translated code is returned and displayed to the user.
+6. User can copy the translated code with one click.
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+Before you begin, ensure you have the following installed:
+
+- **Docker and Docker Compose**
+- **Enterprise inference endpoint access** (Keycloak authentication)
+
+### Verify Docker Installation
+
+```bash
+# Check Docker version
+docker --version
+
+# Check Docker Compose version
+docker compose version
+
+# Verify Docker is running
+docker ps
+```
+---
+
+## Quick Start Deployment
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/opea-project/GenAIExamples.git
+cd GenAIExamples/CodeTranslation
+```
+
+### Set up the Environment
+
+This application requires an `.env` file in the root directory for proper configuration. Create it with the commands below:
+
+```bash
+# Create the .env file
+cat > .env << EOF
+# Backend API Configuration
+BACKEND_PORT=5001
+
+# Required - Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Required - Model Configuration
+INFERENCE_MODEL_ENDPOINT=CodeLlama-34b-Instruct-hf
+INFERENCE_MODEL_NAME=codellama/CodeLlama-34b-Instruct-hf
+
+# LLM Settings
+LLM_TEMPERATURE=0.2
+LLM_MAX_TOKENS=4096
+
+# Code Translation Settings
+MAX_CODE_LENGTH=10000
+MAX_FILE_SIZE=10485760
+
+# CORS Configuration
+CORS_ALLOW_ORIGINS=["http://localhost:5173", "http://localhost:3000"]
+EOF
+```
+
+Or manually create `.env` with:
+
+```bash
+# Backend API Configuration
+BACKEND_PORT=5001
+
+# Required - Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Required - Model Configuration
+INFERENCE_MODEL_ENDPOINT=CodeLlama-34b-Instruct-hf
+INFERENCE_MODEL_NAME=codellama/CodeLlama-34b-Instruct-hf
+
+# LLM Settings
+LLM_TEMPERATURE=0.2
+LLM_MAX_TOKENS=4096
+
+# Code Translation Settings
+MAX_CODE_LENGTH=10000
+MAX_FILE_SIZE=10485760
+
+# CORS Configuration
+CORS_ALLOW_ORIGINS=["http://localhost:5173", "http://localhost:3000"]
+```
+
+**Note**: The docker-compose.yaml file automatically loads environment variables from `.env` for the backend service.
+
+### Running the Application
+
+Start both API and UI services together with Docker Compose:
+
+```bash
+# From the CodeTranslation directory
+docker compose up --build
+
+# Or run in detached mode (background)
+docker compose up -d --build
+```
+
+The API will be available at: `http://localhost:5001`  
+The UI will be available at: `http://localhost:3000`
+
+**View logs**:
+
+```bash
+# All services
+docker compose logs -f
+
+# Backend only
+docker compose logs -f backend
+
+# Frontend only
+docker compose logs -f frontend
+```
+
+**Verify the services are running**:
+
+```bash
+# Check API health
+curl http://localhost:5001/health
+
+# Check if containers are running
+docker compose ps
+```
+
+## User Interface
+
+**Using the Application**
+
+Make sure you are at the localhost:3000 url
+
+You will be directed to the main page which has each feature
+
+![User Interface](images/ui.png)
+
+The interface provides:
+
+Translate code:
+
+- Select source language from dropdown (Java, C, C++, Python, Rust, Go)
+- Select target language from dropdown
+- Enter or paste your code in the left textarea
+- Click "Translate Code" button
+- View translated code in the right textarea
+- Click "Copy" to copy the result
+
+Upload a PDF:
+
+- Scroll to the "Alternative: Upload PDF" section
+- Drag and drop a PDF file, or
+- Click "browse" to select a file
+- Wait for code extraction to complete
+- Extracted code appears in the source code box
+
+**UI Configuration**
+
+When running with Docker Compose, the UI automatically connects to the backend API. The frontend is available at `http://localhost:3000` and the API at `http://localhost:5001`.
+
+
+For production deployments, you may want to configure a reverse proxy or update the API URL in the frontend configuration.
+
+### Stopping the Application
+
+
+```bash
+docker compose down
+```
+
+---
+
+## Troubleshooting
+
+For comprehensive troubleshooting guidance, common issues, and solutions, refer to:
+
+[Troubleshooting Guide - TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
diff --git a/CodeTranslation/TROUBLESHOOTING.md b/CodeTranslation/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..7f80ab539c
--- /dev/null
+++ b/CodeTranslation/TROUBLESHOOTING.md
@@ -0,0 +1,128 @@
+# Troubleshooting Guide
+
+This document contains all common issues encountered during development and their solutions.
+
+## Table of Contents
+
+- [API Common Issues](#api-common-issues)
+- [UI Common Issues](#ui-common-issues)
+
+### API Common Issues
+
+#### "API client not initialized. Check Keycloak configuration."
+
+**Solution**:
+
+1. Create a `.env` file in the root directory
+2. Add your Keycloak credentials:
+   ```
+   BASE_URL=https://api.example.com
+   KEYCLOAK_CLIENT_ID=api
+   KEYCLOAK_CLIENT_SECRET=your_client_secret
+   ```
+3. Restart the server
+
+#### "Code too long. Maximum length is 10000 characters"
+
+**Solution**:
+
+- The limit exists due to model context window constraints
+- Break your code into smaller modules
+- Translate one class or function at a time
+- Or adjust `MAX_CODE_LENGTH` in `.env` if needed
+
+#### "Source language not supported"
+
+**Solution**:
+
+- Only 6 languages are supported: Java, C, C++, Python, Rust, Go
+- Check the `/languages` endpoint for the current list
+- Ensure language names are lowercase (e.g., "python" not "Python")
+
+#### Import errors
+
+**Solution**:
+
+1. Ensure all dependencies are installed: `pip install -r requirements.txt`
+2. Verify you're using Python 3.10 or higher: `python --version`
+3. Activate your virtual environment if using one
+
+#### Server won't start
+
+**Solution**:
+
+1. Check if port 5001 is already in use: `lsof -i :5001` (Unix) or `netstat -ano | findstr :5001` (Windows)
+2. Use a different port by updating `BACKEND_PORT` in `.env`
+3. Check the logs for specific error messages
+
+#### PDF upload fails
+
+**Solution**:
+
+1. Verify the file is a valid PDF
+2. Check file size (must be under 10MB by default)
+3. Ensure the PDF contains extractable text (not just images)
+4. Check server logs for detailed error messages
+
+#### Translation returns empty result
+
+**Solution**:
+
+1. Verify Keycloak authentication is working (check `/health` endpoint)
+2. Check if the model endpoint is accessible
+3. Try with simpler code first
+4. Check server logs for API errors
+
+#### "No module named 'pypdf'"
+
+**Solution**:
+
+```bash
+pip install pypdf
+```
+
+## UI Common Issues
+
+### API Connection Issues
+
+**Problem**: "Failed to translate" or "Failed to upload PDF"
+
+**Solution**:
+
+1. Ensure the API server is running on `http://localhost:5001`
+2. Check browser console for detailed errors
+3. Verify CORS is enabled in the API
+4. Test API directly: `curl http://localhost:5001/health`
+
+### Build Issues
+
+**Problem**: Build fails with dependency errors
+
+**Solution**:
+
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Styling Issues
+
+**Problem**: Styles not applying
+
+**Solution**:
+
+```bash
+# Rebuild Tailwind CSS
+npm run dev
+```
+
+### Character Counter Not Updating
+
+**Problem**: Character counter shows 0 / 10,000 even with code
+
+**Solution**:
+
+1. Clear browser cache
+2. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
+3. Restart the dev server
diff --git a/CodeTranslation/api/.dockerignore b/CodeTranslation/api/.dockerignore
new file mode 100644
index 0000000000..bd6b932c3e
--- /dev/null
+++ b/CodeTranslation/api/.dockerignore
@@ -0,0 +1,29 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.gitignore
+.mypy_cache
+.pytest_cache
+.hypothesis
+*.swp
+*.swo
+*~
+.DS_Store
+.env
+.env.local
diff --git a/CodeTranslation/api/Dockerfile b/CodeTranslation/api/Dockerfile
new file mode 100644
index 0000000000..c5028908c5
--- /dev/null
+++ b/CodeTranslation/api/Dockerfile
@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port
+EXPOSE 5001
+
+# Run the application
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "5001"]
diff --git a/CodeTranslation/api/config.py b/CodeTranslation/api/config.py
new file mode 100644
index 0000000000..e4e7fc57e2
--- /dev/null
+++ b/CodeTranslation/api/config.py
@@ -0,0 +1,44 @@
+"""
+Configuration settings for Code Translation API
+"""
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Custom API Configuration for Keycloak
+BASE_URL = os.getenv("BASE_URL", "https://api.example.com")
+KEYCLOAK_REALM = os.getenv("KEYCLOAK_REALM", "master")
+KEYCLOAK_CLIENT_ID = os.getenv("KEYCLOAK_CLIENT_ID", "api")
+KEYCLOAK_CLIENT_SECRET = os.getenv("KEYCLOAK_CLIENT_SECRET")
+
+# Model Configuration for CodeLlama-34b-instruct
+INFERENCE_MODEL_ENDPOINT = os.getenv("INFERENCE_MODEL_ENDPOINT", "CodeLlama-34b-Instruct")
+INFERENCE_MODEL_NAME = os.getenv("INFERENCE_MODEL_NAME", "codellama/CodeLlama-34b-Instruct-hf")
+
+# Validate required configuration
+if not KEYCLOAK_CLIENT_SECRET:
+    raise ValueError("KEYCLOAK_CLIENT_SECRET must be set in environment variables")
+
+# Application Settings
+APP_TITLE = "Code Translation API"
+APP_DESCRIPTION = "AI-powered code translation service using CodeLlama-34b-instruct"
+APP_VERSION = "1.0.0"
+
+# File Upload Settings
+MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+ALLOWED_EXTENSIONS = {".pdf"}
+
+# Code Translation Settings
+SUPPORTED_LANGUAGES = ["java", "c", "cpp", "python", "rust", "go"]
+MAX_CODE_LENGTH = 10000  # characters
+LLM_TEMPERATURE = 0.2  # Lower temperature for more deterministic code generation
+LLM_MAX_TOKENS = 4096
+
+# CORS Settings
+CORS_ALLOW_ORIGINS = ["*"]  # Update with specific origins in production
+CORS_ALLOW_CREDENTIALS = True
+CORS_ALLOW_METHODS = ["*"]
+CORS_ALLOW_HEADERS = ["*"]
diff --git a/CodeTranslation/api/models.py b/CodeTranslation/api/models.py
new file mode 100644
index 0000000000..fd5386b52d
--- /dev/null
+++ b/CodeTranslation/api/models.py
@@ -0,0 +1,68 @@
+"""
+Pydantic models for request/response validation
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class TranslateRequest(BaseModel):
+    """Request model for code translation"""
+    source_code: str = Field(..., min_length=1, description="Source code to translate")
+    source_language: str = Field(..., description="Source programming language")
+    target_language: str = Field(..., description="Target programming language")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "source_code": "def hello():\n    print('Hello World')",
+                "source_language": "python",
+                "target_language": "java"
+            }
+        }
+
+
+class TranslateResponse(BaseModel):
+    """Response model for code translation"""
+    translated_code: str = Field(..., description="Translated code")
+    source_language: str = Field(..., description="Source language")
+    target_language: str = Field(..., description="Target language")
+    original_code: str = Field(..., description="Original source code")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "translated_code": "public class Main {\n    public static void main(String[] args) {\n        System.out.println(\"Hello World\");\n    }\n}",
+                "source_language": "python",
+                "target_language": "java",
+                "original_code": "def hello():\n    print('Hello World')"
+            }
+        }
+
+
+class UploadPdfResponse(BaseModel):
+    """Response model for PDF upload"""
+    message: str = Field(..., description="Success message")
+    extracted_code: str = Field(..., description="Extracted code from PDF")
+    status: str = Field(..., description="Operation status")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "message": "Successfully extracted code from 'code.pdf'",
+                "extracted_code": "def hello():\n    print('Hello World')",
+                "status": "success"
+            }
+        }
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check"""
+    status: str = Field(..., description="Health status")
+    model_configured: bool = Field(..., description="Whether model is configured")
+    keycloak_authenticated: bool = Field(..., description="Whether Keycloak auth is successful")
+
+
+class SupportedLanguagesResponse(BaseModel):
+    """Response model for supported languages"""
+    languages: list[str] = Field(..., description="List of supported programming languages")
diff --git a/CodeTranslation/api/requirements.txt b/CodeTranslation/api/requirements.txt
new file mode 100644
index 0000000000..b4622e7c38
--- /dev/null
+++ b/CodeTranslation/api/requirements.txt
@@ -0,0 +1,9 @@
+fastapi==0.115.5
+uvicorn==0.32.1
+pydantic==2.10.3
+pydantic-settings==2.6.1
+python-multipart==0.0.17
+requests==2.32.3
+httpx==0.28.1
+openai==1.57.2
+pypdf==6.1.1
diff --git a/CodeTranslation/api/server.py b/CodeTranslation/api/server.py
new file mode 100644
index 0000000000..f8347fde8a
--- /dev/null
+++ b/CodeTranslation/api/server.py
@@ -0,0 +1,233 @@
+"""
+FastAPI server with routes for Code Translation API
+"""
+
+import os
+import tempfile
+import logging
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, File, UploadFile, HTTPException, status
+from fastapi.middleware.cors import CORSMiddleware
+
+import config
+from models import (
+    TranslateRequest, TranslateResponse, UploadPdfResponse,
+    HealthResponse, SupportedLanguagesResponse
+)
+from services import (
+    get_api_client, extract_code_from_pdf, validate_pdf_file
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context manager for FastAPI app"""
+    # Startup
+    try:
+        api_client = get_api_client()
+        app.state.api_client = api_client
+        logger.info("✓ API client initialized with Keycloak authentication")
+    except Exception as e:
+        logger.error(f"Failed to initialize API client: {str(e)}")
+        app.state.api_client = None
+
+    yield
+
+    # Shutdown
+    logger.info("Shutting down Code Translation API")
+
+
+# Initialize FastAPI app
+app = FastAPI(
+    title=config.APP_TITLE,
+    description=config.APP_DESCRIPTION,
+    version=config.APP_VERSION,
+    lifespan=lifespan
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.CORS_ALLOW_ORIGINS,
+    allow_credentials=config.CORS_ALLOW_CREDENTIALS,
+    allow_methods=config.CORS_ALLOW_METHODS,
+    allow_headers=config.CORS_ALLOW_HEADERS,
+)
+
+
+# ==================== Routes ====================
+
+@app.get("/")
+def root():
+    """Root endpoint"""
+    return {
+        "message": "Code Translation API is running",
+        "version": config.APP_VERSION,
+        "status": "healthy",
+        "api_client_authenticated": app.state.api_client is not None
+    }
+
+
+@app.get("/health", response_model=HealthResponse)
+def health_check():
+    """Detailed health check"""
+    return HealthResponse(
+        status="healthy",
+        model_configured=bool(config.INFERENCE_MODEL_NAME),
+        keycloak_authenticated=app.state.api_client is not None and app.state.api_client.is_authenticated()
+    )
+
+
+@app.get("/languages", response_model=SupportedLanguagesResponse)
+def get_supported_languages():
+    """Get list of supported programming languages"""
+    return SupportedLanguagesResponse(
+        languages=config.SUPPORTED_LANGUAGES
+    )
+
+
+@app.post("/translate", response_model=TranslateResponse)
+def translate_code_endpoint(request: TranslateRequest):
+    """
+    Translate code from one language to another
+
+    - **source_code**: Code to translate
+    - **source_language**: Source programming language (java, c, cpp, python, rust, go)
+    - **target_language**: Target programming language (java, c, cpp, python, rust, go)
+    """
+    if not app.state.api_client:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="API client not initialized. Check Keycloak configuration."
+        )
+
+    # Validate languages
+    if request.source_language.lower() not in config.SUPPORTED_LANGUAGES:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Source language '{request.source_language}' not supported. Supported: {', '.join(config.SUPPORTED_LANGUAGES)}"
+        )
+
+    if request.target_language.lower() not in config.SUPPORTED_LANGUAGES:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Target language '{request.target_language}' not supported. Supported: {', '.join(config.SUPPORTED_LANGUAGES)}"
+        )
+
+    # Check code length
+    if len(request.source_code) > config.MAX_CODE_LENGTH:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Code too long. Maximum length is {config.MAX_CODE_LENGTH} characters"
+        )
+
+    try:
+        logger.info(f"Translating code from {request.source_language} to {request.target_language}")
+
+        # Translate code using API client
+        translated_code = app.state.api_client.translate_code(
+            source_code=request.source_code,
+            source_lang=request.source_language,
+            target_lang=request.target_language
+        )
+
+        if not translated_code:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Translation failed. No output received from model."
+            )
+
+        logger.info(f"✓ Successfully translated code")
+
+        return TranslateResponse(
+            translated_code=translated_code,
+            source_language=request.source_language,
+            target_language=request.target_language,
+            original_code=request.source_code
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error translating code: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error translating code: {str(e)}"
+        )
+
+
+@app.post("/upload-pdf", response_model=UploadPdfResponse)
+async def upload_pdf(file: UploadFile = File(...)):
+    """
+    Upload a PDF file and extract code from it
+
+    - **file**: PDF file containing code (max 10MB)
+    """
+    tmp_path = None
+    try:
+        # Read file content
+        content = await file.read()
+        file_size = len(content)
+
+        # Validate file
+        validate_pdf_file(file.filename, file_size, config.MAX_FILE_SIZE)
+
+        logger.info(f"Processing PDF: {file.filename} ({file_size / 1024:.2f} KB)")
+
+        # Save to temporary file
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp:
+            tmp.write(content)
+            tmp_path = tmp.name
+            logger.info(f"Saved to temporary path: {tmp_path}")
+
+        # Extract code from PDF
+        extracted_code = extract_code_from_pdf(tmp_path)
+
+        if not extracted_code.strip():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="No code content could be extracted from the PDF"
+            )
+
+        logger.info(f"✓ Successfully extracted code from PDF: {file.filename}")
+
+        return UploadPdfResponse(
+            message=f"Successfully extracted code from '{file.filename}'",
+            extracted_code=extracted_code,
+            status="success"
+        )
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+    except Exception as e:
+        logger.error(f"Error processing PDF: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing PDF: {str(e)}"
+        )
+    finally:
+        # Clean up temporary file
+        if tmp_path and os.path.exists(tmp_path):
+            try:
+                os.remove(tmp_path)
+                logger.info(f"Cleaned up temporary file: {tmp_path}")
+            except Exception as e:
+                logger.warning(f"Could not remove temporary file: {str(e)}")
+
+
+# Entry point for running with uvicorn
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=5001)
diff --git a/CodeTranslation/api/services/__init__.py b/CodeTranslation/api/services/__init__.py
new file mode 100644
index 0000000000..223ab23723
--- /dev/null
+++ b/CodeTranslation/api/services/__init__.py
@@ -0,0 +1,13 @@
+"""
+Services module exports
+"""
+
+from .api_client import get_api_client, APIClient
+from .pdf_service import extract_code_from_pdf, validate_pdf_file
+
+__all__ = [
+    'get_api_client',
+    'APIClient',
+    'extract_code_from_pdf',
+    'validate_pdf_file'
+]
diff --git a/CodeTranslation/api/services/api_client.py b/CodeTranslation/api/services/api_client.py
new file mode 100644
index 0000000000..ee41827973
--- /dev/null
+++ b/CodeTranslation/api/services/api_client.py
@@ -0,0 +1,150 @@
+"""
+API Client for Keycloak authentication and API calls
+"""
+
+import logging
+import requests
+import httpx
+from typing import Optional
+import config
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+    """
+    Client for handling Keycloak authentication and API calls
+    """
+
+    def __init__(self):
+        self.base_url = config.BASE_URL
+        self.token = None
+        self.http_client = None
+        self._authenticate()
+
+    def _authenticate(self) -> None:
+        """
+        Authenticate and obtain access token from Keycloak
+        """
+        token_url = f"{self.base_url}/token"
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": config.KEYCLOAK_CLIENT_ID,
+            "client_secret": config.KEYCLOAK_CLIENT_SECRET,
+        }
+
+        try:
+            response = requests.post(token_url, data=payload, verify=False)
+
+            if response.status_code == 200:
+                self.token = response.json().get("access_token")
+                logger.info(f"✓ Access token obtained: {self.token[:20]}..." if self.token else "Failed to get token")
+
+                # Create httpx client with SSL verification disabled
+                self.http_client = httpx.Client(verify=False)
+
+            else:
+                logger.error(f"Error obtaining token: {response.status_code} - {response.text}")
+                raise Exception(f"Authentication failed: {response.status_code}")
+
+        except Exception as e:
+            logger.error(f"Error during authentication: {str(e)}")
+            raise
+
+    def get_inference_client(self):
+        """
+        Get OpenAI-style client for code generation inference
+        Uses CodeLlama-34b-instruct endpoint
+        """
+        from openai import OpenAI
+
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{config.INFERENCE_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+
+    def translate_code(self, source_code: str, source_lang: str, target_lang: str) -> str:
+        """
+        Translate code from one language to another using CodeLlama-34b-instruct
+
+        Args:
+            source_code: Code to translate
+            source_lang: Source programming language
+            target_lang: Target programming language
+
+        Returns:
+            Translated code
+        """
+        try:
+            client = self.get_inference_client()
+
+            # Create prompt for code translation
+            prompt = f"""Translate the following {source_lang} code to {target_lang}.
+Only output the translated code without any explanations or markdown formatting.
+
+{source_lang} code:
+```
+{source_code}
+```
+
+{target_lang} code:
+```"""
+
+            logger.info(f"Translating code from {source_lang} to {target_lang}")
+
+            # Use completions endpoint for CodeLlama
+            response = client.completions.create(
+                model=config.INFERENCE_MODEL_NAME,
+                prompt=prompt,
+                max_tokens=config.LLM_MAX_TOKENS,
+                temperature=config.LLM_TEMPERATURE,
+                stop=["```"]  # Stop at closing code block
+            )
+
+            # Handle response structure
+            if hasattr(response, 'choices') and len(response.choices) > 0:
+                choice = response.choices[0]
+                if hasattr(choice, 'text'):
+                    translated_code = choice.text.strip()
+                    logger.info(f"Successfully translated code ({len(translated_code)} characters)")
+                    return translated_code
+                else:
+                    logger.error(f"Unexpected response structure: {type(choice)}, {choice}")
+                    return ""
+            else:
+                logger.error(f"Unexpected response: {type(response)}, {response}")
+                return ""
+        except Exception as e:
+            logger.error(f"Error translating code: {str(e)}", exc_info=True)
+            raise
+
+    def is_authenticated(self) -> bool:
+        """
+        Check if client is authenticated
+        """
+        return self.token is not None
+
+    def __del__(self):
+        """
+        Cleanup: close httpx client
+        """
+        if self.http_client:
+            self.http_client.close()
+
+
+# Global API client instance
+_api_client: Optional[APIClient] = None
+
+
+def get_api_client() -> APIClient:
+    """
+    Get or create the global API client instance
+
+    Returns:
+        APIClient instance
+    """
+    global _api_client
+    if _api_client is None:
+        _api_client = APIClient()
+    return _api_client
diff --git a/CodeTranslation/api/services/pdf_service.py b/CodeTranslation/api/services/pdf_service.py
new file mode 100644
index 0000000000..abf857e9f5
--- /dev/null
+++ b/CodeTranslation/api/services/pdf_service.py
@@ -0,0 +1,128 @@
+"""
+PDF Code Extraction Service
+Extracts code snippets from PDF documents
+"""
+
+import logging
+import re
+from pathlib import Path
+from typing import List
+from pypdf import PdfReader
+
+logger = logging.getLogger(__name__)
+
+
+def extract_code_from_pdf(pdf_path: str) -> str:
+    """
+    Extract code content from a PDF file
+
+    Args:
+        pdf_path: Path to the PDF file
+
+    Returns:
+        Extracted code as string
+
+    Raises:
+        Exception if PDF cannot be processed
+    """
+    try:
+        logger.info(f"Extracting code from PDF: {pdf_path}")
+
+        with open(pdf_path, 'rb') as file:
+            pdf_reader = PdfReader(file)
+            num_pages = len(pdf_reader.pages)
+
+            logger.info(f"PDF has {num_pages} pages")
+
+            # Extract text from all pages
+            all_text = ""
+            for page_num in range(num_pages):
+                page = pdf_reader.pages[page_num]
+                text = page.extract_text()
+                all_text += text + "\n"
+
+            logger.info(f"Extracted {len(all_text)} characters from PDF")
+
+            # Try to identify and extract code blocks
+            # Look for common code patterns
+            code_content = extract_code_patterns(all_text)
+
+            if not code_content.strip():
+                # If no code patterns found, return all text
+                code_content = all_text
+
+            logger.info(f"Extracted code content: {len(code_content)} characters")
+
+            return code_content.strip()
+
+    except Exception as e:
+        logger.error(f"Error extracting code from PDF: {str(e)}", exc_info=True)
+        raise Exception(f"Failed to extract code from PDF: {str(e)}")
+
+
+def extract_code_patterns(text: str) -> str:
+    """
+    Extract code patterns from text
+
+    Args:
+        text: Text content to search
+
+    Returns:
+        Extracted code snippets
+    """
+    # Look for code between common delimiters
+    code_blocks = []
+
+    # Pattern 1: Code between ``` markers
+    markdown_code = re.findall(r'```[\w]*\n(.*?)\n```', text, re.DOTALL)
+    code_blocks.extend(markdown_code)
+
+    # Pattern 2: Indented code blocks (4+ spaces)
+    indented_code = re.findall(r'(?:^    .+$)+', text, re.MULTILINE)
+    code_blocks.extend(indented_code)
+
+    # Pattern 3: Code with common keywords (class, def, function, etc.)
+    keyword_patterns = [
+        r'(?:public|private|protected)?\s*class\s+\w+.*?\{.*?\}',  # Java/C++ classes
+        r'def\s+\w+\(.*?\):.*?(?=\n(?!\s))',  # Python functions
+        r'function\s+\w+\(.*?\)\s*\{.*?\}',  # JavaScript functions
+        r'fn\s+\w+\(.*?\)\s*\{.*?\}',  # Rust functions
+        r'func\s+\w+\(.*?\)\s*\{.*?\}',  # Go functions
+    ]
+
+    for pattern in keyword_patterns:
+        matches = re.findall(pattern, text, re.DOTALL | re.MULTILINE)
+        code_blocks.extend(matches)
+
+    if code_blocks:
+        return '\n\n'.join(code_blocks)
+
+    # If no patterns match, return original text
+    return text
+
+
+def validate_pdf_file(filename: str, file_size: int, max_size: int) -> None:
+    """
+    Validate uploaded PDF file
+
+    Args:
+        filename: Name of the file
+        file_size: Size of the file in bytes
+        max_size: Maximum allowed file size in bytes
+
+    Raises:
+        ValueError if validation fails
+    """
+    # Check file extension
+    if not filename.lower().endswith('.pdf'):
+        raise ValueError("Only PDF files are allowed")
+
+    # Check file size
+    if file_size > max_size:
+        max_size_mb = max_size / (1024 * 1024)
+        raise ValueError(f"File too large. Maximum size is {max_size_mb}MB")
+
+    if file_size == 0:
+        raise ValueError("Empty file uploaded")
+
+    logger.info(f"PDF file validation passed: {filename} ({file_size / 1024:.2f} KB)")
\ No newline at end of file
diff --git a/CodeTranslation/docker-compose.yaml b/CodeTranslation/docker-compose.yaml
new file mode 100644
index 0000000000..b2c08940aa
--- /dev/null
+++ b/CodeTranslation/docker-compose.yaml
@@ -0,0 +1,48 @@
+version: '3.8'
+
+services:
+  backend:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+    container_name: code-trans-backend
+    ports:
+      - "5001:5001"
+    env_file:
+      - .env
+    environment:
+      - BASE_URL=${BASE_URL}
+      - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID}
+      - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}
+      - INFERENCE_MODEL_ENDPOINT=${INFERENCE_MODEL_ENDPOINT}
+      - INFERENCE_MODEL_NAME=${INFERENCE_MODEL_NAME}
+      - LLM_TEMPERATURE=${LLM_TEMPERATURE:-0.2}
+      - LLM_MAX_TOKENS=${LLM_MAX_TOKENS:-4096}
+      - MAX_CODE_LENGTH=${MAX_CODE_LENGTH:-10000}
+      - MAX_FILE_SIZE=${MAX_FILE_SIZE:-10485760}
+    networks:
+      - code-trans-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  frontend:
+    build:
+      context: ./ui
+      dockerfile: Dockerfile
+    container_name: code-trans-frontend
+    ports:
+      - "3000:80"
+    depends_on:
+      - backend
+    networks:
+      - code-trans-network
+    restart: unless-stopped
+
+networks:
+  code-trans-network:
+    driver: bridge
diff --git a/CodeTranslation/images/ui.png b/CodeTranslation/images/ui.png
new file mode 100644
index 0000000000..ab4ed77e9e
Binary files /dev/null and b/CodeTranslation/images/ui.png differ
diff --git a/CodeTranslation/ui/.dockerignore b/CodeTranslation/ui/.dockerignore
new file mode 100644
index 0000000000..bd3f4adad9
--- /dev/null
+++ b/CodeTranslation/ui/.dockerignore
@@ -0,0 +1,12 @@
+node_modules
+npm-debug.log
+.git
+.gitignore
+.DS_Store
+.env
+.env.local
+.env.production
+dist
+build
+coverage
+*.log
diff --git a/CodeTranslation/ui/Dockerfile b/CodeTranslation/ui/Dockerfile
new file mode 100644
index 0000000000..efb238bbae
--- /dev/null
+++ b/CodeTranslation/ui/Dockerfile
@@ -0,0 +1,29 @@
+# Build stage
+FROM node:18-alpine as build
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy application code
+COPY . .
+
+# Build the application
+RUN npm run build
+
+# Production stage
+FROM nginx:alpine
+
+# Copy built assets from build stage
+COPY --from=build /app/dist /usr/share/nginx/html
+
+# Copy nginx configuration
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]
diff --git a/CodeTranslation/ui/index.html b/CodeTranslation/ui/index.html
new file mode 100644
index 0000000000..7b4a4f671a
--- /dev/null
+++ b/CodeTranslation/ui/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Code Translation - AI-Powered Code Converter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
diff --git a/CodeTranslation/ui/nginx.conf b/CodeTranslation/ui/nginx.conf
new file mode 100644
index 0000000000..8b576ede27
--- /dev/null
+++ b/CodeTranslation/ui/nginx.conf
@@ -0,0 +1,23 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        rewrite ^/api/(.*)$ /$1 break;
+        proxy_pass http://backend:5001;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
diff --git a/CodeTranslation/ui/package.json b/CodeTranslation/ui/package.json
new file mode 100644
index 0000000000..310f586320
--- /dev/null
+++ b/CodeTranslation/ui/package.json
@@ -0,0 +1,31 @@
+{
+  "name": "code-trans-ui",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "axios": "^1.6.0",
+    "lucide-react": "^0.294.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.3.6",
+    "vite": "^5.0.8"
+  }
+}
diff --git a/CodeTranslation/ui/postcss.config.js b/CodeTranslation/ui/postcss.config.js
new file mode 100644
index 0000000000..2e7af2b7f1
--- /dev/null
+++ b/CodeTranslation/ui/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
diff --git a/CodeTranslation/ui/src/App.jsx b/CodeTranslation/ui/src/App.jsx
new file mode 100644
index 0000000000..185fdf9fbc
--- /dev/null
+++ b/CodeTranslation/ui/src/App.jsx
@@ -0,0 +1,76 @@
+import { useState } from 'react'
+import CodeTranslator from './components/CodeTranslator'
+import PDFUploader from './components/PDFUploader'
+import Header from './components/Header'
+import StatusBar from './components/StatusBar'
+
+function App() {
+  const [translationStatus, setTranslationStatus] = useState('idle') // idle, translating, success, error
+  const [sourceLanguage, setSourceLanguage] = useState('python')
+  const [targetLanguage, setTargetLanguage] = useState('java')
+  const [pdfExtractedCode, setPdfExtractedCode] = useState('')
+  const [isUploading, setIsUploading] = useState(false)
+
+  const handleTranslationStart = () => {
+    setTranslationStatus('translating')
+  }
+
+  const handleTranslationSuccess = () => {
+    setTranslationStatus('success')
+    setTimeout(() => setTranslationStatus('idle'), 3000)
+  }
+
+  const handleTranslationError = () => {
+    setTranslationStatus('error')
+    setTimeout(() => setTranslationStatus('idle'), 3000)
+  }
+
+  const handlePDFUploadSuccess = (extractedCode) => {
+    setPdfExtractedCode(extractedCode)
+    setIsUploading(false)
+  }
+
+  const handlePDFUploadStart = () => {
+    setIsUploading(true)
+  }
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 via-white to-purple-50">
+      <Header />
+
+      <main className="container mx-auto px-4 py-8 max-w-7xl">
+        {/* Status Bar */}
+        <StatusBar
+          translationStatus={translationStatus}
+          isUploading={isUploading}
+          sourceLanguage={sourceLanguage}
+          targetLanguage={targetLanguage}
+        />
+
+        {/* Main Code Translator - Side by Side */}
+        <div className="mt-6">
+          <CodeTranslator
+            onTranslationStart={handleTranslationStart}
+            onTranslationSuccess={handleTranslationSuccess}
+            onTranslationError={handleTranslationError}
+            pdfExtractedCode={pdfExtractedCode}
+            sourceLanguage={sourceLanguage}
+            targetLanguage={targetLanguage}
+            onSourceLanguageChange={setSourceLanguage}
+            onTargetLanguageChange={setTargetLanguage}
+          />
+        </div>
+
+        {/* PDF Uploader at Bottom */}
+        <div className="mt-6">
+          <PDFUploader
+            onUploadSuccess={handlePDFUploadSuccess}
+            onUploadStart={handlePDFUploadStart}
+          />
+        </div>
+      </main>
+    </div>
+  )
+}
+
+export default App
diff --git a/CodeTranslation/ui/src/components/CodeTranslator.jsx b/CodeTranslation/ui/src/components/CodeTranslator.jsx
new file mode 100644
index 0000000000..b646d6f734
--- /dev/null
+++ b/CodeTranslation/ui/src/components/CodeTranslator.jsx
@@ -0,0 +1,212 @@
+import { useState, useEffect } from 'react'
+import { ArrowRight, Code, Copy, Check } from 'lucide-react'
+import axios from 'axios'
+
+const LANGUAGES = ['java', 'c', 'cpp', 'python', 'rust', 'go']
+
+const LANGUAGE_LABELS = {
+  'java': 'JAVA',
+  'c': 'C',
+  'cpp': 'C++',
+  'python': 'PYTHON',
+  'rust': 'RUST',
+  'go': 'GO'
+}
+
+const API_URL = import.meta.env.VITE_API_URL || '/api'
+
+export default function CodeTranslator({
+  onTranslationStart,
+  onTranslationSuccess,
+  onTranslationError,
+  pdfExtractedCode,
+  sourceLanguage,
+  targetLanguage,
+  onSourceLanguageChange,
+  onTargetLanguageChange
+}) {
+  const [sourceCode, setSourceCode] = useState('')
+  const [translatedCode, setTranslatedCode] = useState('')
+  const [isTranslating, setIsTranslating] = useState(false)
+  const [copied, setCopied] = useState(false)
+
+  // When PDF code is extracted, set it as source code
+  useEffect(() => {
+    if (pdfExtractedCode) {
+      setSourceCode(pdfExtractedCode)
+    }
+  }, [pdfExtractedCode])
+
+  const handleTranslate = async () => {
+    if (!sourceCode.trim()) {
+      alert('Please enter code to translate')
+      return
+    }
+
+    if (sourceLanguage === targetLanguage) {
+      alert('Source and target languages must be different')
+      return
+    }
+
+    setIsTranslating(true)
+    onTranslationStart()
+
+    try {
+      const response = await axios.post(`${API_URL}/translate`, {
+        source_code: sourceCode,
+        source_language: sourceLanguage,
+        target_language: targetLanguage
+      })
+
+      setTranslatedCode(response.data.translated_code)
+      onTranslationSuccess()
+    } catch (error) {
+      console.error('Translation error:', error)
+      onTranslationError()
+      alert(error.response?.data?.detail || 'Translation failed')
+    } finally {
+      setIsTranslating(false)
+    }
+  }
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(translatedCode)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+      <div className="flex items-center space-x-2 mb-4">
+        <Code className="w-5 h-5 text-blue-600" />
+        <h2 className="text-lg font-semibold text-gray-800">Code Translator</h2>
+      </div>
+
+      {/* Language Selection */}
+      <div className="flex items-center space-x-3 mb-4">
+        <div className="flex-1">
+          <label className="block text-sm font-medium text-gray-700 mb-1">Source Language</label>
+          <select
+            value={sourceLanguage}
+            onChange={(e) => onSourceLanguageChange(e.target.value)}
+            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+          >
+            {LANGUAGES.map(lang => (
+              <option key={lang} value={lang}>
+                {LANGUAGE_LABELS[lang]}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        <div className="pt-6">
+          <ArrowRight className="w-5 h-5 text-gray-400" />
+        </div>
+
+        <div className="flex-1">
+          <label className="block text-sm font-medium text-gray-700 mb-1">Target Language</label>
+          <select
+            value={targetLanguage}
+            onChange={(e) => onTargetLanguageChange(e.target.value)}
+            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent"
+          >
+            {LANGUAGES.map(lang => (
+              <option key={lang} value={lang}>
+                {LANGUAGE_LABELS[lang]}
+              </option>
+            ))}
+          </select>
+        </div>
+      </div>
+
+      {/* Side by Side Code Boxes */}
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-4 mb-4">
+        {/* Source Code Input */}
+        <div>
+          <div className="flex items-center justify-between mb-1">
+            <label className="block text-sm font-medium text-gray-700">
+              Source Code ({LANGUAGE_LABELS[sourceLanguage]})
+            </label>
+            <span className={`text-xs ${sourceCode.length > 10000 ? 'text-red-600 font-semibold' : 'text-gray-500'}`}>
+              {sourceCode.length.toLocaleString()} / 10,000 characters
+            </span>
+          </div>
+          <textarea
+            value={sourceCode}
+            onChange={(e) => setSourceCode(e.target.value)}
+            placeholder={`Enter your ${sourceLanguage} code here...`}
+            className={`w-full h-96 px-3 py-2 border rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent font-mono text-sm resize-none ${
+              sourceCode.length > 10000 ? 'border-red-500' : 'border-gray-300'
+            }`}
+          />
+          {sourceCode.length > 10000 && (
+            <p className="text-xs text-red-600 mt-1">
+              Code exceeds maximum length. Please reduce to 10,000 characters or less.
+            </p>
+          )}
+        </div>
+
+        {/* Translated Code Output */}
+        <div>
+          <div className="flex items-center justify-between mb-1">
+            <label className="block text-sm font-medium text-gray-700">
+              Translated Code ({LANGUAGE_LABELS[targetLanguage]})
+            </label>
+            {translatedCode && (
+              <button
+                onClick={handleCopy}
+                className="flex items-center space-x-1 text-sm text-blue-600 hover:text-blue-700"
+              >
+                {copied ? (
+                  <>
+                    <Check className="w-4 h-4" />
+                    <span>Copied!</span>
+                  </>
+                ) : (
+                  <>
+                    <Copy className="w-4 h-4" />
+                    <span>Copy</span>
+                  </>
+                )}
+              </button>
+            )}
+          </div>
+          <textarea
+            value={translatedCode}
+            readOnly
+            placeholder="Translated code will appear here..."
+            className="w-full h-96 px-3 py-2 border border-gray-300 bg-gray-50 rounded-lg font-mono text-sm resize-none"
+          />
+        </div>
+      </div>
+
+      {/* Translate Button */}
+      <button
+        onClick={handleTranslate}
+        disabled={isTranslating || !sourceCode.trim() || sourceCode.length > 10000}
+        className="w-full bg-gradient-to-r from-blue-500 to-purple-600 text-white py-3 rounded-lg font-medium hover:from-blue-600 hover:to-purple-700 transition-all disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center space-x-2"
+      >
+        {isTranslating ? (
+          <>
+            <div className="w-5 h-5 border-2 border-white border-t-transparent rounded-full animate-spin"></div>
+            <span>Translating...</span>
+          </>
+        ) : (
+          <>
+            <ArrowRight className="w-5 h-5" />
+            <span>Translate Code</span>
+          </>
+        )}
+      </button>
+
+      {/* Info Note */}
+      <div className="mt-4 p-3 bg-blue-50 border border-blue-200 rounded-lg">
+        <p className="text-xs text-gray-600">
+          <span className="font-semibold">Note:</span> The 10,000 character limit is due to CodeLlama-34b's
+          context window (16K tokens). This ensures optimal translation quality and prevents timeouts.
+          For larger files, consider breaking them into smaller modules.
+        </p>
+      </div>
+    </div>
+  )
+}
diff --git a/CodeTranslation/ui/src/components/Header.jsx b/CodeTranslation/ui/src/components/Header.jsx
new file mode 100644
index 0000000000..cbd1bd51e1
--- /dev/null
+++ b/CodeTranslation/ui/src/components/Header.jsx
@@ -0,0 +1,28 @@
+import { Code2, Sparkles } from 'lucide-react'
+
+export default function Header() {
+  return (
+    <header className="bg-white border-b border-gray-200 shadow-sm">
+      <div className="container mx-auto px-4 py-4 max-w-6xl">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center space-x-3">
+            <div className="bg-gradient-to-br from-blue-500 to-purple-600 p-2 rounded-lg">
+              <Code2 className="w-6 h-6 text-white" />
+            </div>
+            <div>
+              <h1 className="text-2xl font-bold bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
+                Code Translation
+              </h1>
+              <p className="text-sm text-gray-500">Translate code between programming languages</p>
+            </div>
+          </div>
+
+          <div className="flex items-center space-x-2 text-sm text-gray-500">
+            <Sparkles className="w-4 h-4" />
+            <span>Powered by CodeLlama-34b</span>
+          </div>
+        </div>
+      </div>
+    </header>
+  )
+}
diff --git a/CodeTranslation/ui/src/components/PDFUploader.jsx b/CodeTranslation/ui/src/components/PDFUploader.jsx
new file mode 100644
index 0000000000..9426199d23
--- /dev/null
+++ b/CodeTranslation/ui/src/components/PDFUploader.jsx
@@ -0,0 +1,139 @@
+import { useState } from 'react'
+import { Upload, FileText, AlertCircle } from 'lucide-react'
+import axios from 'axios'
+
+const API_URL = import.meta.env.VITE_API_URL || '/api'
+
+export default function PDFUploader({ onUploadSuccess, onUploadStart }) {
+  const [isDragging, setIsDragging] = useState(false)
+  const [isUploading, setIsUploading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleDragOver = (e) => {
+    e.preventDefault()
+    setIsDragging(true)
+  }
+
+  const handleDragLeave = () => {
+    setIsDragging(false)
+  }
+
+  const handleDrop = (e) => {
+    e.preventDefault()
+    setIsDragging(false)
+
+    const file = e.dataTransfer.files[0]
+    if (file) {
+      handleFileUpload(file)
+    }
+  }
+
+  const handleFileSelect = (e) => {
+    const file = e.target.files[0]
+    if (file) {
+      handleFileUpload(file)
+    }
+  }
+
+  const handleFileUpload = async (file) => {
+    // Validate file type
+    if (!file.name.toLowerCase().endsWith('.pdf')) {
+      setError('Only PDF files are allowed')
+      return
+    }
+
+    // Validate file size (10MB)
+    if (file.size > 10 * 1024 * 1024) {
+      setError('File too large. Maximum size is 10MB')
+      return
+    }
+
+    setError('')
+    setIsUploading(true)
+    onUploadStart()
+
+    try {
+      const formData = new FormData()
+      formData.append('file', file)
+
+      const response = await axios.post(`${API_URL}/upload-pdf`, formData, {
+        headers: {
+          'Content-Type': 'multipart/form-data'
+        }
+      })
+
+      onUploadSuccess(response.data.extracted_code)
+    } catch (error) {
+      console.error('Upload error:', error)
+      setError(error.response?.data?.detail || 'Failed to extract code from PDF')
+    } finally {
+      setIsUploading(false)
+    }
+  }
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+      <div className="flex items-start justify-between mb-3">
+        <div className="flex items-center space-x-2">
+          <FileText className="w-5 h-5 text-blue-600" />
+          <h3 className="text-lg font-semibold text-gray-800">Alternative: Upload PDF</h3>
+        </div>
+      </div>
+
+      <p className="text-sm text-gray-600 mb-4">
+        Don't have code ready? Upload a PDF containing code and it will be automatically extracted
+        and placed in the source code box for translation.
+      </p>
+
+      <div className="flex items-center gap-4">
+        {/* Compact Upload Area */}
+        <div
+          onDragOver={handleDragOver}
+          onDragLeave={handleDragLeave}
+          onDrop={handleDrop}
+          className={`flex-1 border-2 border-dashed rounded-lg p-4 text-center transition-colors ${
+            isDragging
+              ? 'border-blue-500 bg-blue-50'
+              : 'border-gray-300 hover:border-gray-400'
+          }`}
+        >
+          {isUploading ? (
+            <div className="flex items-center justify-center space-x-3">
+              <div className="w-6 h-6 border-4 border-blue-500 border-t-transparent rounded-full animate-spin"></div>
+              <p className="text-sm text-gray-600">Extracting code from PDF...</p>
+            </div>
+          ) : (
+            <div className="flex items-center justify-center space-x-4">
+              <Upload className={`w-8 h-8 ${isDragging ? 'text-blue-500' : 'text-gray-400'}`} />
+              <div className="text-left">
+                <p className="text-sm text-gray-700 mb-1">
+                  Drag and drop your PDF here, or{' '}
+                  <label className="text-blue-600 hover:text-blue-700 cursor-pointer font-medium">
+                    browse
+                    <input
+                      type="file"
+                      accept=".pdf"
+                      onChange={handleFileSelect}
+                      className="hidden"
+                    />
+                  </label>
+                </p>
+                <p className="text-xs text-gray-500">
+                  Max 10MB • Supports Java, C, C++, Python, Rust, Go
+                </p>
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Error Message */}
+        {error && (
+          <div className="flex-shrink-0 w-64 p-3 bg-red-50 border border-red-200 rounded-lg flex items-start space-x-2">
+            <AlertCircle className="w-5 h-5 text-red-500 flex-shrink-0 mt-0.5" />
+            <p className="text-sm text-red-700">{error}</p>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/CodeTranslation/ui/src/components/StatusBar.jsx b/CodeTranslation/ui/src/components/StatusBar.jsx
new file mode 100644
index 0000000000..272803f734
--- /dev/null
+++ b/CodeTranslation/ui/src/components/StatusBar.jsx
@@ -0,0 +1,51 @@
+import { CheckCircle, AlertCircle, Loader, ArrowRight } from 'lucide-react'
+
+export default function StatusBar({ translationStatus, isUploading, sourceLanguage, targetLanguage }) {
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-4">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-3">
+          {isUploading && (
+            <>
+              <Loader className="w-5 h-5 text-blue-500 animate-spin" />
+              <p className="text-sm font-medium text-gray-700">Extracting code from PDF...</p>
+            </>
+          )}
+
+          {!isUploading && translationStatus === 'translating' && (
+            <>
+              <Loader className="w-5 h-5 text-blue-500 animate-spin" />
+              <div className="flex items-center space-x-2">
+                <p className="text-sm font-medium text-gray-700">Translating</p>
+                <span className="text-xs bg-blue-100 text-blue-700 px-2 py-0.5 rounded">{sourceLanguage}</span>
+                <ArrowRight className="w-4 h-4 text-gray-400" />
+                <span className="text-xs bg-purple-100 text-purple-700 px-2 py-0.5 rounded">{targetLanguage}</span>
+              </div>
+            </>
+          )}
+
+          {!isUploading && translationStatus === 'success' && (
+            <>
+              <CheckCircle className="w-5 h-5 text-green-500" />
+              <p className="text-sm font-medium text-gray-700">Translation completed successfully</p>
+            </>
+          )}
+
+          {!isUploading && translationStatus === 'error' && (
+            <>
+              <AlertCircle className="w-5 h-5 text-red-500" />
+              <p className="text-sm font-medium text-gray-700">Translation failed</p>
+            </>
+          )}
+
+          {!isUploading && translationStatus === 'idle' && (
+            <>
+              <AlertCircle className="w-5 h-5 text-amber-500" />
+              <p className="text-sm font-medium text-gray-700">Ready to translate code</p>
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/CodeTranslation/ui/src/index.css b/CodeTranslation/ui/src/index.css
new file mode 100644
index 0000000000..867782feea
--- /dev/null
+++ b/CodeTranslation/ui/src/index.css
@@ -0,0 +1,16 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+  font-family: 'Courier New', Courier, monospace;
+}
diff --git a/CodeTranslation/ui/src/main.jsx b/CodeTranslation/ui/src/main.jsx
new file mode 100644
index 0000000000..54b39dd1d9
--- /dev/null
+++ b/CodeTranslation/ui/src/main.jsx
@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
diff --git a/CodeTranslation/ui/tailwind.config.js b/CodeTranslation/ui/tailwind.config.js
new file mode 100644
index 0000000000..dca8ba02d3
--- /dev/null
+++ b/CodeTranslation/ui/tailwind.config.js
@@ -0,0 +1,11 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
diff --git a/CodeTranslation/ui/vite.config.js b/CodeTranslation/ui/vite.config.js
new file mode 100644
index 0000000000..417e887ec1
--- /dev/null
+++ b/CodeTranslation/ui/vite.config.js
@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    host: '0.0.0.0',
+    proxy: {
+      '/api': {
+        target: 'http://localhost:5001',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+    },
+  },
+})
diff --git a/DocSummarization/.gitignore b/DocSummarization/.gitignore
new file mode 100644
index 0000000000..409de7af9c
--- /dev/null
+++ b/DocSummarization/.gitignore
@@ -0,0 +1,58 @@
+# Environment variables and secrets
+.env
+.env.local
+.env.*.local
+*.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+*.log
+logs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node modules
+node_modules/
+
+# Docker
+*.pid
+
+# Temporary files
+*.tmp
+*.bak
+nul
diff --git a/DocSummarization/README.MD b/DocSummarization/README.MD
new file mode 100644
index 0000000000..f9486ddcbf
--- /dev/null
+++ b/DocSummarization/README.MD
@@ -0,0 +1,262 @@
+## Document Summarization
+
+A full-stack document summarization application that processes text and document files to generate concise summaries.
+The system integrates a FastAPI backend with enterprise inference endpoints, alongside a modern React + Vite + Tailwind CSS frontend for an intuitive user experience.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick Start Deployment](#quick-start-deployment)
+- [User Interface](#user-interface)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Overview
+
+The **Document Summarization** application processes multiple content formats to generate concise summaries. Users can paste text or upload documents (PDF, DOCX). The backend uses enterprise inference endpoints via Keycloak authentication for all text summarization.
+
+---
+
+## Features
+
+**Backend**
+
+- Multiple input format support (text, PDF, DOCX)
+- PDF text extraction with OCR support for image-based PDFs
+- DOCX document processing
+- Enterprise inference endpoints for text summarization via Keycloak
+- File validation and size limits (PDF/DOCX: 50 MB)
+- CORS enabled for web integration
+- Comprehensive error handling and logging
+- Health check endpoints
+- Modular architecture (routes + services)
+
+**Frontend**
+
+- Clean, intuitive interface with tab-based input selection
+- Drag-and-drop file upload
+- Real-time summary display
+- Mobile-responsive design with Tailwind CSS
+- Built with Vite for fast development
+
+---
+
+## Architecture
+
+Below is the architecture showing how user input is processed through document extraction, then summarized using the enterprise inference endpoint.
+
+```mermaid
+graph TB
+    A[React Web UI<br/>Port 5173] -->|User Input| B[FastAPI Backend<br/>Port 8000]
+
+    B --> C{Input Type}
+    C -->|Text| D[LLM Service]
+    C -->|PDF/DOCX| E[PDF Service]
+
+    E -->|Extracted Text| D
+
+    D -->|Get Token| F[API Client]
+    F -->|Authenticate| G[Keycloak]
+    G -->|Access Token| F
+    F -->|Token| D
+    D -->|API Call with Token| H[Enterprise Inference<br/>Llama-3.1-8B-Instruct]
+    H -->|Summary| B
+    B -->|JSON Response| A
+
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style D fill:#ffe1f5
+    style E fill:#ffe1f5
+    style F fill:#fffacd
+    style G fill:#ffcccc
+    style H fill:#e1ffe1
+```
+
+**Service Components:**
+
+1. **React Web UI (Port 5173)** - Provides intuitive interface with drag-and-drop file upload, tab-based input selection, and real-time summary display
+
+2. **FastAPI Backend (Port 8000)** - Orchestrates document processing, handles authentication, and routes requests to appropriate processing services
+
+**Typical Flow:**
+
+1. User inputs text or uploads a document (PDF/DOCX) through the web UI.
+2. The backend processes the input:
+   - Text: Sent directly to LLM service
+   - PDF/DOCX: Extracted using PDF service with OCR support
+3. The LLM service requests a token from API Client.
+4. API Client authenticates with Keycloak and obtains an access token.
+5. LLM service uses the token to call the enterprise inference endpoint.
+6. The model generates a summary using Llama-3.1-8B-Instruct.
+7. The summary is returned and displayed to the user via the UI.
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+Before you begin, ensure you have the following installed:
+
+- **Docker and Docker Compose**
+- **Enterprise inference endpoint access** (Keycloak authentication)
+
+### Verify Docker Installation
+
+```bash
+# Check Docker version
+docker --version
+
+# Check Docker Compose version
+docker compose version
+
+# Verify Docker is running
+docker ps
+```
+
+---
+
+## Quick Start Deployment
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/opea-project/GenAIExamples.git
+cd GenAIExamples/DocSummarization
+```
+
+### Set up the Environment
+
+This application requires an `.env` file in the `backend` directory for proper configuration. Create it with the commands below:
+
+```bash
+# Create the .env file in the backend directory
+mkdir -p backend
+cat > backend/.env << EOF
+# Enterprise/Keycloak Configuration (REQUIRED)
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Model Configuration (Enterprise Inference)
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+
+# LLM Configuration
+LLM_TEMPERATURE=0.7
+LLM_MAX_TOKENS=2000
+
+# Service Configuration
+SERVICE_PORT=8000
+LOG_LEVEL=INFO
+
+# CORS Settings
+CORS_ORIGINS=*
+EOF
+```
+
+Or manually create `backend/.env` with:
+
+```bash
+# Enterprise/Keycloak Configuration (REQUIRED)
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Model Configuration (Enterprise Inference)
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+
+# LLM Configuration
+LLM_TEMPERATURE=0.7
+LLM_MAX_TOKENS=2000
+
+# Service Configuration
+SERVICE_PORT=8000
+LOG_LEVEL=INFO
+
+# CORS Settings
+CORS_ORIGINS=*
+```
+
+
+### Running the Application
+
+Start both API and UI services together with Docker Compose:
+
+```bash
+# From the DocSummarization directory
+docker compose up --build
+
+# Or run in detached mode (background)
+docker compose up -d --build
+```
+
+The Backend will be available at: `http://localhost:8000`
+The UI will be available at: `http://localhost:5173`
+
+**View logs**:
+
+```bash
+# All services
+docker compose logs -f
+
+# Backend only
+docker compose logs -f backend
+
+# Frontend only
+docker compose logs -f frontend
+```
+
+**Verify the services are running**:
+
+```bash
+# Check API health
+curl http://localhost:8000/health
+
+# Check if containers are running
+docker compose ps
+```
+
+---
+
+
+## User Interface
+
+**Using the Application**
+
+Make sure you are at the localhost:5173 url
+
+You will be directed to the main page which has each feature
+
+![Home Page - Hero Section](./assets/img/homepage.png)
+
+![Home Page - Hero Section](./assets/img/ui.png)
+
+
+
+**UI Configuration**
+
+When running with Docker Compose, the UI automatically connects to the backend API. The frontend is available at `http://localhost:5173` and the API at `http://localhost:8000`.
+
+
+### Stopping the Application
+
+```bash
+docker compose down
+```
+
+---
+
+## Troubleshooting
+
+For comprehensive troubleshooting guidance, common issues, and solutions, refer to:
+
+[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+
diff --git a/DocSummarization/TROUBLESHOOTING.md b/DocSummarization/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..789e18dfe0
--- /dev/null
+++ b/DocSummarization/TROUBLESHOOTING.md
@@ -0,0 +1,320 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### 1. Containers Not Starting
+
+**Symptom**: Containers fail to start or exit immediately
+
+**Check container status:**
+```bash
+docker compose ps
+```
+
+**View error logs:**
+```bash
+docker compose logs backend
+docker compose logs frontend
+```
+
+**Solution:**
+```bash
+# Rebuild containers
+docker compose down
+docker compose up -d --build
+```
+
+### 2. Backend Connection Errors
+
+**Symptom**: Frontend shows "Failed to connect" or network errors
+
+**Check backend health:**
+```bash
+curl http://localhost:8000/health
+```
+
+**Expected response:**
+```json
+{"status":"healthy","service":"Document Summarization Service","version":"2.0.0","llm_provider":"Enterprise Inference (Keycloak)"}
+```
+
+**Solution:**
+- Verify backend container is running: `docker compose ps`
+- Check backend logs: `docker compose logs backend -f`
+- Restart backend: `docker compose restart backend`
+
+### 3. Keycloak Authentication Errors
+
+**Symptom**: Text/PDF summarization fails with authentication errors
+
+**Error**: `Authentication error` or `Failed to resolve 'api.example.com'`
+
+**Solution:**
+- Check Keycloak credentials in `backend/.env`:
+  - `BASE_URL` (enterprise inference endpoint)
+  - `KEYCLOAK_REALM`
+  - `KEYCLOAK_CLIENT_ID`
+  - `KEYCLOAK_CLIENT_SECRET`
+- Verify enterprise inference endpoint is accessible
+- Test authentication:
+```bash
+curl -X POST https://your-api.example.com/token \
+  -d "grant_type=client_credentials" \
+  -d "client_id=your-client-id" \
+  -d "client_secret=your-client-secret"
+```
+
+**Error**: `Connection timeout`
+
+**Solution:**
+- Verify `BASE_URL` is correct in `backend/.env`
+- Check network connectivity to enterprise endpoint
+- Verify firewall settings allow HTTPS connections
+
+### 4. PDF Processing Errors
+
+**Symptom**: PDF upload fails or returns empty text
+
+**Error**: `Failed to extract text from PDF`
+
+**Causes:**
+- Scanned PDF without text layer (image-only PDF)
+- Password-protected PDF
+- Corrupted PDF file
+- PDF with complex formatting
+
+**Solution:**
+- For scanned PDFs, ensure OCR was run during scanning
+- Remove password protection before uploading
+- Try re-saving PDF with Adobe Reader or similar tool
+- Check backend logs for specific error details
+- Maximum PDF size: 50MB
+
+### 5. Frontend Not Loading
+
+**Symptom**: Browser shows blank page or cannot connect to localhost:5173
+
+**Check frontend status:**
+```bash
+docker compose ps frontend
+```
+
+**Check frontend logs:**
+```bash
+docker compose logs frontend -f
+```
+
+**Solution:**
+- Clear browser cache and hard refresh (Ctrl+F5)
+- Verify port 5173 is not in use: `netstat -ano | findstr :5173` (Windows)
+- Kill conflicting process if port is occupied
+- Restart frontend: `docker compose restart frontend`
+- Check firewall settings allow localhost:5173
+
+### 6. Port Already in Use
+
+**Error**: `Port 5173 is already allocated` or `Port 8000 is already allocated`
+
+**Find process using port:**
+```bash
+# Windows
+netstat -ano | findstr :5173
+netstat -ano | findstr :8000
+
+# Linux/Mac
+lsof -i :5173
+lsof -i :8000
+```
+
+**Solution:**
+- Stop the conflicting process
+- Or change ports in `docker-compose.yml`:
+  ```yaml
+  ports:
+    - "8001:8000"  # Change 8000 to 8001
+    - "5174:80"    # Change 5173 to 5174
+  ```
+
+### 7. Out of Memory Errors
+
+**Symptom**: Container crashes or backend becomes unresponsive
+
+**Check logs:**
+```bash
+docker compose logs backend | grep -i "memory\|killed"
+```
+
+**Solution:**
+- Reduce file sizes (use smaller PDFs)
+- Reduce `max_tokens` in LLM requests
+- Increase Docker memory limit in Docker Desktop settings (minimum 4GB recommended)
+- Process one file at a time instead of multiple concurrent requests
+
+### 8. Backend Service Unavailable
+
+**Symptom**: 502 Bad Gateway or 503 Service Unavailable
+
+**Check backend:**
+```bash
+docker compose logs backend --tail=50
+```
+
+**Common causes:**
+- Backend still starting (wait 30-60 seconds after start)
+- Configuration error in `.env` file
+- Enterprise inference endpoint unreachable
+- Keycloak authentication failing
+- Python dependency issues
+
+**Solution:**
+```bash
+# Restart backend
+docker compose restart backend
+
+# If issues persist, rebuild
+docker compose down
+docker compose up -d --build backend
+```
+
+## Configuration Issues
+
+### Invalid .env Configuration
+
+**Symptom**: Backend fails to start with configuration errors
+
+**Check required variables in `backend/.env`:**
+
+**For text/PDF/DOCX summarization:**
+```bash
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+```
+
+**Common mistakes:**
+- Missing required Keycloak variables
+- Extra spaces in variable names
+- Wrong endpoint format (missing https://)
+- Quotes around values (not needed in .env files)
+- Using placeholder values like "api.example.com" or "your_client_secret"
+
+### File Size Limits
+
+**Maximum file sizes:**
+- PDF/DOCX documents: 50 MB
+
+**Configured in `backend/config.py`:**
+```python
+MAX_PDF_SIZE = 52428800  # 50MB in bytes
+```
+
+## Advanced Troubleshooting
+
+### Enable Debug Logging
+
+Edit `backend/.env`:
+```bash
+LOG_LEVEL=DEBUG
+```
+
+Restart backend:
+```bash
+docker compose restart backend
+docker compose logs backend -f
+```
+
+### Test Backend Directly
+
+**Test text summarization:**
+```bash
+curl -X POST http://localhost:8000/v1/docsum \
+  -F "type=text" \
+  -F "messages=This is a test document about artificial intelligence and machine learning." \
+  -F "max_tokens=100" \
+  -F "stream=false"
+```
+
+**Test PDF summarization:**
+```bash
+curl -X POST http://localhost:8000/v1/docsum \
+  -F "type=text" \
+  -F "files=@test.pdf" \
+  -F "max_tokens=100" \
+  -F "stream=false"
+```
+
+
+### Inspect Container
+
+**Access backend container shell:**
+```bash
+docker compose exec backend /bin/bash
+```
+
+**Check Python environment:**
+```bash
+docker compose exec backend pip list
+docker compose exec backend python -c "import pypdf; print('pypdf installed')"
+```
+
+**Verify environment variables:**
+```bash
+docker compose exec backend env | grep -E "BASE_URL|KEYCLOAK"
+```
+
+### Clean Docker Environment
+
+If issues persist, clean Docker completely:
+
+```bash
+# Stop and remove containers
+docker compose down -v
+
+# Remove unused images
+docker system prune -a
+
+# Rebuild from scratch
+docker compose up -d --build
+```
+
+## Architecture-Specific Issues
+
+### Enterprise Inference Connection
+
+**Symptom**: All summarization fails (text, PDF)
+
+**Required for**: ALL summarization operations
+
+**Check configuration:**
+1. Verify `BASE_URL` points to your enterprise inference endpoint
+2. Confirm Keycloak credentials are correct
+3. Test Keycloak authentication separately
+4. Verify network access to enterprise endpoint
+5. Check if model name matches available models
+
+## Getting Help
+
+If issues persist after following this guide:
+
+1. **Collect Information:**
+   - Docker logs: `docker compose logs > logs.txt`
+   - Docker status: `docker compose ps`
+   - Environment check: `docker compose config`
+
+2. **Check Configuration:**
+   - Review `backend/.env` file (remove sensitive data before sharing)
+   - Verify Keycloak credentials with your admin
+
+3. **Try Minimal Setup:**
+   - Start with text summarization (simple, no files)
+   - Then test PDF processing
+   - This helps isolate which component is failing
+
+4. **System Information:**
+   - Docker version: `docker --version`
+   - Docker Compose version: `docker compose version`
+   - Operating system and version
+   - Available memory and disk space
diff --git a/DocSummarization/assets/img/docsum-homepage1.png b/DocSummarization/assets/img/docsum-homepage1.png
new file mode 100644
index 0000000000..af95b1a30a
Binary files /dev/null and b/DocSummarization/assets/img/docsum-homepage1.png differ
diff --git a/DocSummarization/assets/img/docsum-homepage2.png b/DocSummarization/assets/img/docsum-homepage2.png
new file mode 100644
index 0000000000..f556397dbc
Binary files /dev/null and b/DocSummarization/assets/img/docsum-homepage2.png differ
diff --git a/DocSummarization/assets/img/homepage.png b/DocSummarization/assets/img/homepage.png
new file mode 100644
index 0000000000..b2c8c07c6f
Binary files /dev/null and b/DocSummarization/assets/img/homepage.png differ
diff --git a/DocSummarization/assets/img/ui.png b/DocSummarization/assets/img/ui.png
new file mode 100644
index 0000000000..39da31a1d4
Binary files /dev/null and b/DocSummarization/assets/img/ui.png differ
diff --git a/DocSummarization/backend/.env.example b/DocSummarization/backend/.env.example
new file mode 100644
index 0000000000..e09ae8a97c
--- /dev/null
+++ b/DocSummarization/backend/.env.example
@@ -0,0 +1,25 @@
+# Enterprise/Keycloak Configuration (REQUIRED)
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Model Configuration (Enterprise Inference)
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+
+# LLM Configuration
+LLM_TEMPERATURE=0.7
+LLM_MAX_TOKENS=2000
+
+# Service Configuration
+SERVICE_PORT=8000
+LOG_LEVEL=INFO
+
+# File Upload Limits
+MAX_FILE_SIZE=524288000
+MAX_PDF_SIZE=52428800
+MAX_PDF_PAGES=100
+
+# CORS Settings
+CORS_ORIGINS=*
diff --git a/DocSummarization/backend/Dockerfile b/DocSummarization/backend/Dockerfile
new file mode 100644
index 0000000000..bb7151c8ba
--- /dev/null
+++ b/DocSummarization/backend/Dockerfile
@@ -0,0 +1,35 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Create a non-root user and group
+RUN groupadd --system app && useradd --system --gid app app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    tesseract-ocr \
+    tesseract-ocr-eng \
+    poppler-utils \
+    --no-install-recommends \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better layer caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY --chown=app:app . .
+
+# Switch to the non-root user
+USER app
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f "http://localhost:8000/health" || exit 1
+
+# Run the application
+CMD ["python", "server.py"]
diff --git a/DocSummarization/backend/api/__init__.py b/DocSummarization/backend/api/__init__.py
new file mode 100644
index 0000000000..8b32ea0b6c
--- /dev/null
+++ b/DocSummarization/backend/api/__init__.py
@@ -0,0 +1,5 @@
+"""API module - HTTP endpoints"""
+
+from .routes import router
+
+__all__ = ["router"]
diff --git a/DocSummarization/backend/api/routes.py b/DocSummarization/backend/api/routes.py
new file mode 100644
index 0000000000..fabbad2056
--- /dev/null
+++ b/DocSummarization/backend/api/routes.py
@@ -0,0 +1,201 @@
+"""
+API Routes for Doc-Sum Application
+Handles all HTTP endpoints
+"""
+
+from fastapi import APIRouter, Form, File, UploadFile, HTTPException
+from fastapi.responses import StreamingResponse
+from typing import Optional
+import os
+import logging
+import json
+
+from services import pdf_service, llm_service
+import config
+from models import HealthResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Health check endpoint - dynamically checks service configuration"""
+    response = {
+        "status": "healthy",
+        "service": config.APP_TITLE,
+        "version": config.APP_VERSION
+    }
+
+    # Only show llm_provider if Keycloak is actually configured
+    if config.BASE_URL and config.KEYCLOAK_CLIENT_SECRET:
+        response["llm_provider"] = "Enterprise Inference (Keycloak)"
+
+    return response
+
+
+@router.post("/v1/docsum")
+async def summarize_document(
+    type: str = Form(...),
+    messages: str = Form(""),
+    max_tokens: int = Form(1024),
+    language: str = Form("en"),
+    summary_type: str = Form("auto"),
+    stream: str = Form("false"),
+    files: Optional[UploadFile] = File(None)
+):
+    """
+    Summarize text or PDF document content
+
+    Args:
+        type: Input type (text, pdf)
+        messages: Text content (for type='text')
+        max_tokens: Maximum summary length
+        language: Language code
+        summary_type: Type of summary
+        stream: Enable streaming response
+        files: Uploaded file (for pdf documents)
+
+    Returns:
+        Summary response with text
+    """
+    try:
+        stream_bool = stream.lower() == "true"
+
+        logger.info(f"Request received - type: {type}, has_file: {files is not None}, messages_len: {len(messages)}")
+
+        # ========== Text Input ==========
+        if type == "text" and messages.strip():
+            logger.info("Processing text input")
+            summary = llm_service.summarize(
+                text=messages,
+                max_tokens=max_tokens,
+                stream=stream_bool
+            )
+
+            if stream_bool:
+                return StreamingResponse(
+                    _format_stream(summary),
+                    media_type="text/event-stream"
+                )
+            else:
+                return {
+                    "text": summary,
+                    "summary": summary,
+                    "word_count": len(summary.split()),
+                    "char_count": len(summary)
+                }
+
+        # ========== File Upload (Documents) ==========
+        if files:
+            # Save file temporarily
+            temp_path = f"/tmp/{files.filename}"
+            filename_lower = files.filename.lower()
+            logger.info(f"Saving uploaded file: {files.filename}, type={type}")
+
+            with open(temp_path, "wb") as buffer:
+                content = await files.read()
+                buffer.write(content)
+
+            try:
+                # ===== Document Processing (PDF/DOC/DOCX/TXT) =====
+                # Check file extension to determine how to extract text
+                if filename_lower.endswith(('.pdf', '.docx', '.doc')):
+                    file_type = "PDF" if filename_lower.endswith('.pdf') else "DOCX"
+                    logger.info(f"Extracting text from {file_type} file")
+                    text_content = pdf_service.extract_text(temp_path)
+                    os.remove(temp_path)
+
+                    if not text_content.strip():
+                        raise HTTPException(status_code=400, detail=f"No text found in {file_type}")
+
+                    logger.info(f"Extracted {len(text_content)} characters, generating summary")
+                    summary = llm_service.summarize(
+                        text=text_content,
+                        max_tokens=max_tokens,
+                        stream=stream_bool
+                    )
+
+                    if stream_bool:
+                        return StreamingResponse(
+                            _format_stream(summary),
+                            media_type="text/event-stream"
+                        )
+                    else:
+                        return {
+                            "text": summary,
+                            "summary": summary,
+                            "word_count": len(summary.split()),
+                            "char_count": len(summary)
+                        }
+
+                elif filename_lower.endswith('.txt'):
+                    logger.info("Reading text from TXT file")
+                    with open(temp_path, "r", encoding="utf-8") as f:
+                        text_content = f.read()
+                    os.remove(temp_path)
+
+                    if not text_content.strip():
+                        raise HTTPException(status_code=400, detail="No text found in file")
+
+                    logger.info(f"Read {len(text_content)} characters, generating summary")
+                    summary = llm_service.summarize(
+                        text=text_content,
+                        max_tokens=max_tokens,
+                        stream=stream_bool
+                    )
+
+                    if stream_bool:
+                        return StreamingResponse(
+                            _format_stream(summary),
+                            media_type="text/event-stream"
+                        )
+                    else:
+                        return {
+                            "text": summary,
+                            "summary": summary,
+                            "word_count": len(summary.split()),
+                            "char_count": len(summary)
+                        }
+
+                else:
+                    logger.error(f"Unsupported file type: {files.filename}")
+                    os.remove(temp_path)
+                    raise HTTPException(status_code=400, detail=f"Unsupported file type. Please upload PDF, DOCX, or TXT files.")
+
+            except Exception as e:
+                # Clean up file on error
+                if os.path.exists(temp_path):
+                    os.remove(temp_path)
+                raise
+
+        # ========== Invalid Request ==========
+        raise HTTPException(
+            status_code=400,
+            detail="Either text message or file is required"
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Summarization error: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Summarization error: {str(e)}")
+
+
+def _format_stream(generator):
+    """
+    Format streaming response for SSE
+
+    Args:
+        generator: Text chunk generator
+
+    Yields:
+        Formatted SSE data chunks
+    """
+    try:
+        for chunk in generator:
+            yield f"data: {json.dumps({'text': chunk})}\n\n"
+        yield "data: [DONE]\n\n"
+    except Exception as e:
+        yield f"data: {json.dumps({'error': str(e)})}\n\n"
diff --git a/DocSummarization/backend/api_client.py b/DocSummarization/backend/api_client.py
new file mode 100644
index 0000000000..1744915ecd
--- /dev/null
+++ b/DocSummarization/backend/api_client.py
@@ -0,0 +1,68 @@
+import requests
+import httpx
+import logging
+from openai import OpenAI
+import config
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+    def __init__(self):
+        self.base_url = config.BASE_URL
+        self.token = None
+        self.http_client = None
+
+        if self.base_url and config.KEYCLOAK_CLIENT_SECRET:
+            self._authenticate()
+
+    def _authenticate(self) -> None:
+        """Authenticate and obtain access token from Keycloak"""
+        try:
+            token_url = f"{self.base_url}/token"
+            logger.info(f"Authenticating with Keycloak at {token_url}")
+
+            payload = {
+                "grant_type": "client_credentials",
+                "client_id": config.KEYCLOAK_CLIENT_ID,
+                "client_secret": config.KEYCLOAK_CLIENT_SECRET,
+            }
+
+            response = requests.post(token_url, data=payload, verify=False)
+
+            if response.status_code == 200:
+                self.token = response.json().get("access_token")
+                self.http_client = httpx.Client(verify=False)
+                logger.info("Authentication successful")
+            else:
+                raise Exception(f"Authentication failed: {response.status_code} - {response.text}")
+
+        except Exception as e:
+            logger.error(f"Authentication error: {str(e)}")
+            raise
+
+    def get_inference_client(self):
+        """Get OpenAI-style client for inference/completions"""
+        if not self.token or not self.http_client:
+            raise ValueError("API client not authenticated")
+
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{config.INFERENCE_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+
+    def is_authenticated(self) -> bool:
+        """Check if client is authenticated"""
+        return self.token is not None and self.http_client is not None
+
+
+# Global instance
+api_client = None
+
+def get_api_client():
+    """Get or create global API client instance"""
+    global api_client
+    if api_client is None:
+        api_client = APIClient()
+    return api_client
diff --git a/DocSummarization/backend/config.py b/DocSummarization/backend/config.py
new file mode 100644
index 0000000000..3e3350efaf
--- /dev/null
+++ b/DocSummarization/backend/config.py
@@ -0,0 +1,49 @@
+"""
+Configuration settings for Doc-Sum Application
+"""
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Enterprise/Keycloak Configuration (Required for LLM)
+BASE_URL = os.getenv("BASE_URL")
+KEYCLOAK_REALM = os.getenv("KEYCLOAK_REALM", "master")
+KEYCLOAK_CLIENT_ID = os.getenv("KEYCLOAK_CLIENT_ID", "api")
+KEYCLOAK_CLIENT_SECRET = os.getenv("KEYCLOAK_CLIENT_SECRET")
+
+# Model Configuration (Enterprise Inference)
+INFERENCE_MODEL_ENDPOINT = os.getenv("INFERENCE_MODEL_ENDPOINT", "Llama-3.1-8B-Instruct")
+INFERENCE_MODEL_NAME = os.getenv("INFERENCE_MODEL_NAME", "meta-llama/Llama-3.1-8B-Instruct")
+
+# LLM Configuration
+LLM_TEMPERATURE = float(os.getenv("LLM_TEMPERATURE", "0.7"))
+LLM_MAX_TOKENS = int(os.getenv("LLM_MAX_TOKENS", "2000"))
+
+# Validate configuration (checked at runtime, not on import)
+# KEYCLOAK_CLIENT_SECRET is required for text summarization
+
+# Application Settings
+APP_TITLE = "Document Summarization Service"
+APP_DESCRIPTION = "AI-powered document summarization with enterprise inference integration"
+APP_VERSION = "2.0.0"
+
+# Service Configuration
+SERVICE_PORT = int(os.getenv("SERVICE_PORT", "8000"))
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
+
+# File Upload Settings
+MAX_FILE_SIZE = int(os.getenv("MAX_FILE_SIZE", str(500 * 1024 * 1024)))  # 500MB
+MAX_PDF_SIZE = int(os.getenv("MAX_PDF_SIZE", str(50 * 1024 * 1024)))  # 50MB
+
+# File Processing Limits
+MAX_PDF_PAGES = int(os.getenv("MAX_PDF_PAGES", "100"))  # Maximum pages to process from PDF
+WARN_PDF_PAGES = 50  # Warn user if PDF has more than this many pages
+
+# CORS Settings
+CORS_ORIGINS = os.getenv("CORS_ORIGINS", "*")
+CORS_ALLOW_CREDENTIALS = True
+CORS_ALLOW_METHODS = ["*"]
+CORS_ALLOW_HEADERS = ["*"]
diff --git a/DocSummarization/backend/core/__init__.py b/DocSummarization/backend/core/__init__.py
new file mode 100644
index 0000000000..60f3099bf3
--- /dev/null
+++ b/DocSummarization/backend/core/__init__.py
@@ -0,0 +1,5 @@
+"""Core module - Configuration and models"""
+
+from .config import settings
+
+__all__ = ["settings"]
diff --git a/DocSummarization/backend/core/config.py.old b/DocSummarization/backend/core/config.py.old
new file mode 100644
index 0000000000..54fb92bd68
--- /dev/null
+++ b/DocSummarization/backend/core/config.py.old
@@ -0,0 +1,107 @@
+"""
+Configuration Management for Doc-Sum Application
+Supports swapping between different LLM and Audio providers
+"""
+
+from pydantic_settings import BaseSettings
+from typing import Optional, Literal
+
+
+class Settings(BaseSettings):
+    """Application Settings - Swap endpoints here for different deployments"""
+
+    # ==================== Service Info ====================
+    SERVICE_NAME: str = "Document Summarization Service"
+    SERVICE_VERSION: str = "1.0.0"
+    SERVICE_PORT: int = 8000
+
+    # ==================== LLM Provider Configuration ====================
+    # Supported: "openai", "groq", "ollama", "vllm", "tgi"
+    LLM_PROVIDER: Literal["openai", "groq", "ollama", "vllm", "tgi"] = "openai"
+
+    # LLM Endpoint URLs (swap based on deployment)
+    LLM_ENDPOINT: str = "https://api.openai.com/v1"  # Change for local models
+    LLM_API_KEY: Optional[str] = None
+    LLM_MODEL: str = "gpt-4o-mini"
+
+    # LLM Generation Parameters
+    LLM_TEMPERATURE: float = 0.7
+    LLM_MAX_TOKENS: int = 2000
+    LLM_MAX_RETRIES: int = 3
+
+    # ==================== Audio Provider Configuration ====================
+    # Supported: "openai", "whisper-local", "faster-whisper"
+    AUDIO_PROVIDER: Literal["openai", "whisper-local", "faster-whisper"] = "openai"
+
+    # Audio Endpoint (for OpenAI Whisper API)
+    AUDIO_ENDPOINT: str = "https://api.openai.com/v1"
+    AUDIO_API_KEY: Optional[str] = None
+    AUDIO_MODEL: str = "whisper-1"
+
+    # ==================== PDF Processing ====================
+    MAX_PDF_SIZE_MB: int = 50
+    PDF_EXTRACT_IMAGES: bool = False  # OCR support (future)
+
+    # ==================== File Upload Limits ====================
+    MAX_FILE_SIZE_MB: int = 100
+    ALLOWED_AUDIO_FORMATS: list = [".mp3", ".wav", ".m4a", ".flac", ".ogg"]
+    ALLOWED_VIDEO_FORMATS: list = [".mp4", ".avi", ".mov", ".mkv"]
+    ALLOWED_PDF_FORMATS: list = [".pdf"]
+
+    # ==================== CORS Configuration ====================
+    CORS_ORIGINS: str = "*"  # Comma-separated list or "*" for all origins
+
+    # ==================== Logging ====================
+    LOG_LEVEL: str = "INFO"
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+    # ==================== Deployment Presets ====================
+
+    @classmethod
+    def for_openai(cls):
+        """Preset for OpenAI deployment"""
+        return cls(
+            LLM_PROVIDER="openai",
+            LLM_ENDPOINT="https://api.openai.com/v1",
+            AUDIO_PROVIDER="openai",
+            AUDIO_ENDPOINT="https://api.openai.com/v1"
+        )
+
+    @classmethod
+    def for_groq(cls):
+        """Preset for Groq deployment"""
+        return cls(
+            LLM_PROVIDER="groq",
+            LLM_ENDPOINT="https://api.groq.com/openai/v1",
+            AUDIO_PROVIDER="openai",  # Groq doesn't have audio, use OpenAI
+            AUDIO_ENDPOINT="https://api.openai.com/v1"
+        )
+
+    @classmethod
+    def for_local_ollama(cls):
+        """Preset for local Ollama deployment"""
+        return cls(
+            LLM_PROVIDER="ollama",
+            LLM_ENDPOINT="http://localhost:11434",
+            LLM_MODEL="llama3.2",
+            AUDIO_PROVIDER="whisper-local",
+            AUDIO_ENDPOINT="http://localhost:8000"
+        )
+
+    @classmethod
+    def for_local_vllm(cls):
+        """Preset for local vLLM deployment (AMD/NVIDIA GPUs)"""
+        return cls(
+            LLM_PROVIDER="vllm",
+            LLM_ENDPOINT="http://localhost:8000/v1",
+            LLM_MODEL="meta-llama/Llama-3.2-3B-Instruct",
+            AUDIO_PROVIDER="faster-whisper",
+            AUDIO_ENDPOINT="http://localhost:8001"
+        )
+
+
+# Global settings instance
+settings = Settings()
diff --git a/DocSummarization/backend/core/models.py b/DocSummarization/backend/core/models.py
new file mode 100644
index 0000000000..40179c5001
--- /dev/null
+++ b/DocSummarization/backend/core/models.py
@@ -0,0 +1,33 @@
+"""
+Data Models for Doc-Sum API
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional, Literal
+
+
+class SummarizeRequest(BaseModel):
+    """Request model for summarization"""
+    type: Literal["text", "pdf", "audio", "video"]
+    messages: Optional[str] = ""
+    max_tokens: int = Field(default=1024, ge=100, le=4000)
+    language: str = "en"
+    summary_type: str = "auto"
+    stream: bool = False
+
+
+class SummarizeResponse(BaseModel):
+    """Response model for summarization"""
+    text: str
+    summary: str  # Kept for backward compatibility
+    word_count: Optional[int] = None
+    char_count: Optional[int] = None
+
+
+class HealthResponse(BaseModel):
+    """Health check response"""
+    status: str
+    service: str
+    version: str
+    llm_provider: str
+    audio_provider: str
diff --git a/DocSummarization/backend/models.py b/DocSummarization/backend/models.py
new file mode 100644
index 0000000000..db833bd8b3
--- /dev/null
+++ b/DocSummarization/backend/models.py
@@ -0,0 +1,32 @@
+"""
+Data Models for Doc-Sum API
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional, Literal
+
+
+class SummarizeRequest(BaseModel):
+    """Request model for summarization"""
+    type: Literal["text", "pdf"]
+    messages: Optional[str] = ""
+    max_tokens: int = Field(default=1024, ge=100, le=4000)
+    language: str = "en"
+    summary_type: str = "auto"
+    stream: bool = False
+
+
+class SummarizeResponse(BaseModel):
+    """Response model for summarization"""
+    text: str
+    summary: str  # Kept for backward compatibility
+    word_count: Optional[int] = None
+    char_count: Optional[int] = None
+
+
+class HealthResponse(BaseModel):
+    """Health check response"""
+    status: str
+    service: str
+    version: str
+    llm_provider: Optional[str] = None
diff --git a/DocSummarization/backend/requirements.txt b/DocSummarization/backend/requirements.txt
new file mode 100644
index 0000000000..854f811011
--- /dev/null
+++ b/DocSummarization/backend/requirements.txt
@@ -0,0 +1,23 @@
+# Core Web Framework
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+python-multipart==0.0.6
+
+# LLM & AI APIs
+httpx==0.27.2
+requests==2.31.0
+openai==1.54.0  # Required for OpenAI-compatible API interface to Enterprise Inference
+
+# Document Processing
+pypdf==6.1.1
+python-docx==1.1.0
+pdf2image==1.16.3
+pytesseract==0.3.10
+Pillow==10.2.0
+
+# Configuration Management
+python-dotenv==1.0.0
+pydantic==2.5.3
+
+# Utilities
+aiofiles==23.2.1
\ No newline at end of file
diff --git a/DocSummarization/backend/server.py b/DocSummarization/backend/server.py
new file mode 100644
index 0000000000..388b39f193
--- /dev/null
+++ b/DocSummarization/backend/server.py
@@ -0,0 +1,98 @@
+"""
+FastAPI server for Doc-Sum Application
+"""
+
+import logging
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+import uvicorn
+
+import config
+from models import HealthResponse
+from api.routes import router
+
+# Configure logging
+logging.basicConfig(
+    level=getattr(logging, config.LOG_LEVEL),
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Initialize FastAPI app
+app = FastAPI(
+    title=config.APP_TITLE,
+    description=config.APP_DESCRIPTION,
+    version=config.APP_VERSION
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.CORS_ORIGINS.split(",") if config.CORS_ORIGINS != "*" else ["*"],
+    allow_credentials=config.CORS_ALLOW_CREDENTIALS,
+    allow_methods=config.CORS_ALLOW_METHODS,
+    allow_headers=config.CORS_ALLOW_HEADERS,
+)
+
+# Include API routes
+app.include_router(router)
+
+# Root endpoint
+@app.get("/")
+def root():
+    """Root endpoint with service info"""
+    response = {
+        "message": "Document Summarization Service is running",
+        "version": config.APP_VERSION,
+        "status": "healthy",
+        "docs": "/docs",
+        "health": "/health"
+    }
+
+    # Only show config if services are actually configured
+    if config.BASE_URL and config.KEYCLOAK_CLIENT_SECRET:
+        response["config"] = {
+            "llm_provider": "Enterprise Inference (Keycloak)",
+            "llm_model": config.INFERENCE_MODEL_NAME
+        }
+
+    return response
+
+# Health check endpoint
+@app.get("/health", response_model=HealthResponse)
+def health_check():
+    """Detailed health check - dynamically checks service configuration"""
+    response_data = {
+        "status": "healthy",
+        "service": config.APP_TITLE,
+        "version": config.APP_VERSION
+    }
+
+    # Only show llm_provider if Keycloak is actually configured
+    if config.BASE_URL and config.KEYCLOAK_CLIENT_SECRET:
+        response_data["llm_provider"] = "Enterprise Inference (Keycloak)"
+
+    return HealthResponse(**response_data)
+
+# Startup event
+@app.on_event("startup")
+async def startup_event():
+    """Log configuration on startup"""
+    logger.info("=" * 60)
+    logger.info(f"Starting {config.APP_TITLE} v{config.APP_VERSION}")
+    logger.info("=" * 60)
+    logger.info("LLM Provider: Enterprise Inference (Keycloak)")
+    logger.info(f"Base URL: {config.BASE_URL}")
+    logger.info(f"Keycloak Configured: {bool(config.KEYCLOAK_CLIENT_SECRET)}")
+    logger.info(f"Model: {config.INFERENCE_MODEL_NAME}")
+    logger.info(f"Port: {config.SERVICE_PORT}")
+    logger.info("=" * 60)
+
+# Entry point for running with uvicorn
+if __name__ == "__main__":
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=config.SERVICE_PORT,
+        timeout_keep_alive=300
+    )
diff --git a/DocSummarization/backend/services/__init__.py b/DocSummarization/backend/services/__init__.py
new file mode 100644
index 0000000000..b790f73d82
--- /dev/null
+++ b/DocSummarization/backend/services/__init__.py
@@ -0,0 +1,6 @@
+"""Services module - Business logic layer"""
+
+from .pdf_service import pdf_service
+from .llm_service import llm_service
+
+__all__ = ["pdf_service", "llm_service"]
diff --git a/DocSummarization/backend/services/llm_service.py b/DocSummarization/backend/services/llm_service.py
new file mode 100644
index 0000000000..82fdadf76f
--- /dev/null
+++ b/DocSummarization/backend/services/llm_service.py
@@ -0,0 +1,205 @@
+"""
+LLM Service for Document Summarization
+Uses Enterprise Inference API via Keycloak authentication
+"""
+
+from typing import Iterator, Dict, Any
+import logging
+import re
+import config
+from api_client import get_api_client
+
+logger = logging.getLogger(__name__)
+
+
+def clean_markdown_formatting(text: str) -> str:
+    """
+    Remove markdown formatting symbols from text
+
+    Args:
+        text: Text that may contain markdown formatting
+
+    Returns:
+        Clean text without markdown symbols
+    """
+    # Remove bold (**text** or __text__)
+    text = re.sub(r'\*\*(.+?)\*\*', r'\1', text)
+    text = re.sub(r'__(.+?)__', r'\1', text)
+
+    # Remove italic (*text* or _text_)
+    text = re.sub(r'\*(.+?)\*', r'\1', text)
+    text = re.sub(r'_(.+?)_', r'\1', text)
+
+    # Remove code blocks (```text```)
+    text = re.sub(r'```.*?```', '', text, flags=re.DOTALL)
+
+    # Remove inline code (`text`)
+    text = re.sub(r'`(.+?)`', r'\1', text)
+
+    # Remove headers (# text)
+    text = re.sub(r'^#+\s+', '', text, flags=re.MULTILINE)
+
+    # Remove bullet points and list markers
+    text = re.sub(r'^\s*[-*+]\s+', '', text, flags=re.MULTILINE)
+    text = re.sub(r'^\s*\d+\.\s+', '', text, flags=re.MULTILINE)
+
+    return text.strip()
+
+
+class LLMService:
+    """
+    LLM service for document summarization using enterprise inference
+    """
+
+    def __init__(self):
+        """Initialize LLM service (authenticates on first use)"""
+        self.client = None
+        self.model = config.INFERENCE_MODEL_NAME
+        self._authenticated = False
+
+    def _ensure_authenticated(self):
+        """Authenticate with enterprise API (lazy initialization)"""
+        if self._authenticated:
+            return
+
+        if not config.KEYCLOAK_CLIENT_SECRET:
+            raise ValueError("KEYCLOAK_CLIENT_SECRET must be set in environment variables for text summarization")
+
+        logger.info("Initializing LLM Service with Enterprise API")
+        logger.info(f"Base URL: {config.BASE_URL}")
+        logger.info(f"Model: {config.INFERENCE_MODEL_NAME}")
+
+        # Use enterprise API client
+        api_client = get_api_client()
+        if not api_client.is_authenticated():
+            raise ValueError("Enterprise API authentication failed - check Keycloak credentials")
+
+        self.client = api_client.get_inference_client()
+        self._authenticated = True
+        logger.info("Enterprise API client initialized successfully")
+
+    def summarize(
+        self,
+        text: str,
+        max_tokens: int = None,
+        temperature: float = None,
+        stream: bool = False
+    ) -> str | Iterator[str]:
+        """
+        Summarize text using enterprise LLM
+
+        Args:
+            text: Text to summarize
+            max_tokens: Maximum tokens in summary
+            temperature: Generation temperature
+            stream: Whether to stream response
+
+        Returns:
+            Summary text or iterator of chunks if streaming
+        """
+        # Ensure we're authenticated before making API calls
+        self._ensure_authenticated()
+
+        max_tokens = max_tokens or config.LLM_MAX_TOKENS
+        temperature = temperature or config.LLM_TEMPERATURE
+
+        system_prompt = """You are a professional document summarizer.
+Your task is to create clear, concise, and accurate summaries of the provided text.
+Focus on the main points and key information while maintaining the original meaning.
+
+IMPORTANT: Provide the summary in plain text format only. Do not use any markdown formatting symbols like **, *, _, or other special characters for formatting. Write in a clean, readable paragraph format."""
+
+        user_prompt = f"""Please provide a comprehensive summary of the following text:
+
+{text}
+
+Summary:"""
+
+        try:
+            logger.info(f"Generating summary with {self.model} (stream={stream})")
+
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ],
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=stream
+            )
+
+            if stream:
+                return self._stream_response(response)
+            else:
+                summary = response.choices[0].message.content
+                # Clean any markdown formatting from the response
+                summary = clean_markdown_formatting(summary)
+                logger.info(f"Generated summary: {len(summary)} characters")
+                return summary
+
+        except Exception as e:
+            logger.error(f"LLM summarization error: {str(e)}")
+            raise Exception(f"Failed to generate summary: {str(e)}")
+
+    def _stream_response(self, response) -> Iterator[str]:
+        """Stream LLM response chunks (with markdown cleaning)"""
+        accumulated = ""
+        for chunk in response:
+            if chunk.choices[0].delta.content:
+                accumulated += chunk.choices[0].delta.content
+                # Only yield when we have a complete sentence or paragraph
+                if accumulated.endswith(('.', '!', '?', '\n')):
+                    cleaned = clean_markdown_formatting(accumulated)
+                    yield cleaned
+                    accumulated = ""
+
+        # Yield any remaining content
+        if accumulated:
+            cleaned = clean_markdown_formatting(accumulated)
+            yield cleaned
+
+    def health_check(self) -> Dict[str, Any]:
+        """
+        Check if LLM service is healthy
+
+        Returns:
+            Health status dictionary
+        """
+        try:
+            # Check if Keycloak is configured
+            if not config.KEYCLOAK_CLIENT_SECRET:
+                return {
+                    "status": "not_configured",
+                    "provider": "Enterprise Inference (Keycloak)",
+                    "message": "Keycloak credentials not configured"
+                }
+
+            # Ensure authenticated
+            self._ensure_authenticated()
+
+            # Try a simple completion
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": "Say 'OK'"}],
+                max_tokens=10
+            )
+
+            return {
+                "status": "healthy",
+                "provider": "Enterprise Inference (Keycloak)",
+                "model": self.model,
+                "base_url": config.BASE_URL
+            }
+
+        except Exception as e:
+            logger.error(f"Health check failed: {str(e)}")
+            return {
+                "status": "unhealthy",
+                "provider": "Enterprise Inference (Keycloak)",
+                "error": str(e)
+            }
+
+
+# Global LLM service instance
+llm_service = LLMService()
diff --git a/DocSummarization/backend/services/pdf_service.py b/DocSummarization/backend/services/pdf_service.py
new file mode 100644
index 0000000000..d3e245f29d
--- /dev/null
+++ b/DocSummarization/backend/services/pdf_service.py
@@ -0,0 +1,202 @@
+"""
+Document Extraction Service
+Handles PDF and DOCX text extraction with OCR support for image-based PDFs
+"""
+
+from pypdf import PdfReader
+from docx import Document
+from pdf2image import convert_from_path
+import pytesseract
+from typing import Optional
+import logging
+import os
+import config
+
+logger = logging.getLogger(__name__)
+
+
+class PDFService:
+    """Service for extracting text from PDF and DOCX files"""
+
+    def __init__(self):
+        """Initialize document extraction service"""
+        logger.info("Document Extraction Service initialized")
+
+    def extract_text(self, file_path: str) -> str:
+        """
+        Extract text from PDF or DOCX file
+
+        Args:
+            file_path: Path to document file
+
+        Returns:
+            Extracted text content
+
+        Raises:
+            Exception: If document extraction fails
+        """
+        try:
+            filename_lower = file_path.lower()
+
+            if filename_lower.endswith('.pdf'):
+                return self._extract_from_pdf(file_path)
+            elif filename_lower.endswith(('.docx', '.doc')):
+                return self._extract_from_docx(file_path)
+            else:
+                raise Exception(f"Unsupported file type: {file_path}")
+
+        except Exception as e:
+            logger.error(f"Document extraction error: {str(e)}")
+            raise Exception(f"Failed to extract text from document: {str(e)}")
+
+    def _extract_from_pdf(self, pdf_path: str) -> str:
+        """
+        Extract text from PDF file with automatic OCR fallback for image-based PDFs
+        Implements page limit to prevent processing extremely large PDFs
+
+        Args:
+            pdf_path: Path to PDF file
+
+        Returns:
+            Extracted text content
+        """
+        logger.info(f"Extracting text from PDF: {pdf_path}")
+
+        text_content = ""
+
+        # First, try standard text extraction
+        with open(pdf_path, "rb") as file:
+            pdf_reader = PdfReader(file)
+            num_pages = len(pdf_reader.pages)
+
+            logger.info(f"PDF has {num_pages} pages")
+
+            # Apply page limit
+            max_pages = config.MAX_PDF_PAGES
+            pages_to_process = min(num_pages, max_pages)
+
+            if num_pages > max_pages:
+                logger.warning(f"PDF has {num_pages} pages. Processing only first {max_pages} pages to prevent timeout.")
+                text_content += f"[Note: This PDF has {num_pages} pages. Processing first {max_pages} pages only.]\n\n"
+
+            for page_num, page in enumerate(pdf_reader.pages[:pages_to_process], 1):
+                page_text = page.extract_text()
+                text_content += page_text + "\n"
+                logger.debug(f"Extracted {len(page_text)} characters from page {page_num}")
+
+        extracted_length = len(text_content.strip())
+        logger.info(f"Extracted {extracted_length} characters from PDF")
+
+        # If no text was extracted, the PDF is likely image-based - use OCR
+        if extracted_length < 50:  # Threshold for considering PDF as image-based
+            logger.info("PDF appears to be image-based or has minimal text. Using OCR...")
+            text_content = self._extract_with_ocr(pdf_path, max_pages=pages_to_process)
+            extracted_length = len(text_content.strip())
+            logger.info(f"OCR extracted {extracted_length} characters from PDF")
+
+        return text_content.strip()
+
+    def _extract_with_ocr(self, pdf_path: str, max_pages: Optional[int] = None) -> str:
+        """
+        Extract text from PDF using OCR (for image-based PDFs)
+
+        Args:
+            pdf_path: Path to PDF file
+            max_pages: Maximum number of pages to process (None = all pages)
+
+        Returns:
+            Extracted text using OCR
+        """
+        try:
+            logger.info(f"Starting OCR extraction for: {pdf_path}")
+
+            # Convert PDF pages to images
+            images = convert_from_path(pdf_path, dpi=300)
+            total_pages = len(images)
+            logger.info(f"Converted PDF to {total_pages} images")
+
+            # Apply page limit if specified
+            if max_pages and total_pages > max_pages:
+                logger.warning(f"OCR: Processing only first {max_pages} of {total_pages} pages")
+                images = images[:max_pages]
+
+            text_content = ""
+            pages_to_process = len(images)
+
+            # Perform OCR on each page
+            for page_num, image in enumerate(images, 1):
+                logger.info(f"Running OCR on page {page_num}/{pages_to_process}")
+                page_text = pytesseract.image_to_string(image)
+                text_content += page_text + "\n"
+                logger.debug(f"OCR extracted {len(page_text)} characters from page {page_num}")
+
+            extracted_length = len(text_content.strip())
+            logger.info(f"OCR successfully extracted {extracted_length} characters")
+
+            return text_content.strip()
+
+        except Exception as e:
+            logger.error(f"OCR extraction failed: {str(e)}")
+            raise Exception(f"Failed to extract text using OCR: {str(e)}")
+
+    def _extract_from_docx(self, docx_path: str) -> str:
+        """
+        Extract text from DOCX file
+
+        Args:
+            docx_path: Path to DOCX file
+
+        Returns:
+            Extracted text content
+        """
+        logger.info(f"Extracting text from DOCX: {docx_path}")
+
+        text_content = ""
+
+        doc = Document(docx_path)
+
+        # Extract text from all paragraphs
+        for paragraph in doc.paragraphs:
+            text_content += paragraph.text + "\n"
+
+        # Extract text from tables if present
+        for table in doc.tables:
+            for row in table.rows:
+                for cell in row.cells:
+                    text_content += cell.text + " "
+                text_content += "\n"
+
+        extracted_length = len(text_content.strip())
+        logger.info(f"Successfully extracted {extracted_length} characters from DOCX")
+
+        return text_content.strip()
+
+    def get_pdf_metadata(self, pdf_path: str) -> dict:
+        """
+        Get PDF metadata (title, author, pages, etc.)
+
+        Args:
+            pdf_path: Path to PDF file
+
+        Returns:
+            Dictionary with PDF metadata
+        """
+        try:
+            with open(pdf_path, "rb") as file:
+                pdf_reader = PdfReader(file)
+
+                metadata = {
+                    "num_pages": len(pdf_reader.pages),
+                    "title": pdf_reader.metadata.get("/Title", "Unknown") if pdf_reader.metadata else "Unknown",
+                    "author": pdf_reader.metadata.get("/Author", "Unknown") if pdf_reader.metadata else "Unknown",
+                }
+
+                return metadata
+
+        except Exception as e:
+            logger.error(f"Error getting PDF metadata: {str(e)}")
+            return {}
+
+
+# Global PDF service instance
+pdf_service = PDFService()
diff --git a/DocSummarization/docker-compose.yml b/DocSummarization/docker-compose.yml
new file mode 100644
index 0000000000..65eff240ae
--- /dev/null
+++ b/DocSummarization/docker-compose.yml
@@ -0,0 +1,56 @@
+services:
+  # Backend Gateway (Python)
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: backend
+    ports:
+      - "8000:8000"
+    env_file:
+      - ./backend/.env
+    volumes:
+      - ./backend:/app
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  # Frontend (React)
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    container_name: frontend
+    ports:
+      - "5173:80"
+    depends_on:
+      - backend
+    networks:
+      - app_network
+    restart: unless-stopped
+
+networks:
+  app_network:
+    driver: bridge
+
+# =============================================================================
+# Usage Instructions:
+# =============================================================================
+#
+# 1. Copy backend/.env.example to backend/.env and configure your Keycloak credentials
+#
+# 2. Start the application:
+#    docker-compose up -d
+#
+# 3. Access the application:
+#    - Frontend: http://localhost:5173
+#    - Backend API: http://localhost:8000
+#    - API Docs: http://localhost:8000/docs
+#
+# 4. View logs:
+#    docker-compose logs -f
+#
+# 5. Stop the application:
+#    docker-compose down
+#
+# =============================================================================
diff --git a/DocSummarization/frontend/.dockerignore b/DocSummarization/frontend/.dockerignore
new file mode 100644
index 0000000000..cd2b1a1eb1
--- /dev/null
+++ b/DocSummarization/frontend/.dockerignore
@@ -0,0 +1,6 @@
+node_modules
+dist
+.git
+.env
+.DS_Store
+npm-debug.log
diff --git a/DocSummarization/frontend/Dockerfile b/DocSummarization/frontend/Dockerfile
new file mode 100644
index 0000000000..a2cffd1f1d
--- /dev/null
+++ b/DocSummarization/frontend/Dockerfile
@@ -0,0 +1,58 @@
+# Build stage
+FROM node:18-alpine AS build
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM nginx:alpine
+
+COPY --from=build /app/dist /usr/share/nginx/html
+
+# Create nginx config with increased file upload limit and no-cache headers
+RUN echo 'server { \
+    listen 80; \
+    server_name localhost; \
+    client_max_body_size 500M; \
+    \
+    location / { \
+        root /usr/share/nginx/html; \
+        index index.html; \
+        try_files $uri $uri/ /index.html; \
+        \
+        # Disable cache for HTML \
+        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0"; \
+        add_header Pragma "no-cache"; \
+        add_header Expires "0"; \
+    } \
+    \
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { \
+        root /usr/share/nginx/html; \
+        expires -1; \
+        add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0"; \
+    } \
+    \
+    location /v1/ { \
+        proxy_pass http://backend:8000; \
+        proxy_http_version 1.1; \
+        proxy_set_header Upgrade $http_upgrade; \
+        proxy_set_header Connection "upgrade"; \
+        proxy_set_header Host $host; \
+        proxy_set_header X-Real-IP $remote_addr; \
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; \
+        proxy_set_header X-Forwarded-Proto $scheme; \
+        client_max_body_size 500M; \
+        proxy_read_timeout 600s; \
+        proxy_connect_timeout 600s; \
+        proxy_send_timeout 600s; \
+    } \
+}' > /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]
diff --git a/DocSummarization/frontend/index.html b/DocSummarization/frontend/index.html
new file mode 100644
index 0000000000..6e33b1c5cb
--- /dev/null
+++ b/DocSummarization/frontend/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/cloud2labs-logo.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Document Summarization - Cloud2Labs</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
diff --git a/DocSummarization/frontend/package.json b/DocSummarization/frontend/package.json
new file mode 100644
index 0000000000..4edece2b37
--- /dev/null
+++ b/DocSummarization/frontend/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "docsum-react-ui",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.20.0",
+    "lucide-react": "^0.294.0",
+    "react-hot-toast": "^2.4.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.2.0",
+    "vite": "^5.0.0",
+    "tailwindcss": "^3.3.5",
+    "autoprefixer": "^10.4.16",
+    "postcss": "^8.4.32"
+  }
+}
diff --git a/DocSummarization/frontend/postcss.config.js b/DocSummarization/frontend/postcss.config.js
new file mode 100644
index 0000000000..2e7af2b7f1
--- /dev/null
+++ b/DocSummarization/frontend/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
diff --git a/DocSummarization/frontend/public/assets/img/docsum-generate-page.png b/DocSummarization/frontend/public/assets/img/docsum-generate-page.png
new file mode 100644
index 0000000000..839c68379b
Binary files /dev/null and b/DocSummarization/frontend/public/assets/img/docsum-generate-page.png differ
diff --git a/DocSummarization/frontend/public/assets/img/docsum-homepage1.png b/DocSummarization/frontend/public/assets/img/docsum-homepage1.png
new file mode 100644
index 0000000000..af95b1a30a
Binary files /dev/null and b/DocSummarization/frontend/public/assets/img/docsum-homepage1.png differ
diff --git a/DocSummarization/frontend/public/assets/img/docsum-homepage2.png b/DocSummarization/frontend/public/assets/img/docsum-homepage2.png
new file mode 100644
index 0000000000..f556397dbc
Binary files /dev/null and b/DocSummarization/frontend/public/assets/img/docsum-homepage2.png differ
diff --git a/DocSummarization/frontend/public/assets/img/ui-result-page.png b/DocSummarization/frontend/public/assets/img/ui-result-page.png
new file mode 100644
index 0000000000..513ce033f6
Binary files /dev/null and b/DocSummarization/frontend/public/assets/img/ui-result-page.png differ
diff --git a/DocSummarization/frontend/public/cloud2labs-logo.png b/DocSummarization/frontend/public/cloud2labs-logo.png
new file mode 100644
index 0000000000..2a0ef60222
Binary files /dev/null and b/DocSummarization/frontend/public/cloud2labs-logo.png differ
diff --git a/DocSummarization/frontend/src/App.jsx b/DocSummarization/frontend/src/App.jsx
new file mode 100644
index 0000000000..8f5ee87aea
--- /dev/null
+++ b/DocSummarization/frontend/src/App.jsx
@@ -0,0 +1,43 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { Toaster } from 'react-hot-toast';
+import Layout from './components/layout/Layout';
+import Home from './pages/Home';
+import Generate from './pages/Generate';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Toaster
+        position="top-right"
+        toastOptions={{
+          duration: 4000,
+          style: {
+            background: '#fff',
+            color: '#374151',
+            boxShadow: '0 10px 15px -3px rgba(0, 0, 0, 0.1)',
+          },
+          success: {
+            iconTheme: {
+              primary: '#22c55e',
+              secondary: '#fff',
+            },
+          },
+          error: {
+            iconTheme: {
+              primary: '#ef4444',
+              secondary: '#fff',
+            },
+          },
+        }}
+      />
+      <Routes>
+        <Route path="/" element={<Layout />}>
+          <Route index element={<Home />} />
+          <Route path="generate" element={<Generate />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+
+export default App;
diff --git a/DocSummarization/frontend/src/components/FileUpload.jsx b/DocSummarization/frontend/src/components/FileUpload.jsx
new file mode 100644
index 0000000000..f524ba8469
--- /dev/null
+++ b/DocSummarization/frontend/src/components/FileUpload.jsx
@@ -0,0 +1,137 @@
+import { useState } from 'react';
+import { Upload, FileText, X } from 'lucide-react';
+
+const FileUpload = ({ onSubmit, isLoading, acceptedTypes, fileType, title, maxFileSize }) => {
+  const [dragActive, setDragActive] = useState(false);
+  const [file, setFile] = useState(null);
+
+  const handleDrag = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.type === "dragenter" || e.type === "dragover") {
+      setDragActive(true);
+    } else if (e.type === "dragleave") {
+      setDragActive(false);
+    }
+  };
+
+  const handleDrop = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragActive(false);
+
+    if (e.dataTransfer.files && e.dataTransfer.files[0]) {
+      const droppedFile = e.dataTransfer.files[0];
+      const fileExtension = '.' + droppedFile.name.split('.').pop().toLowerCase();
+
+      if (acceptedTypes.includes(fileExtension)) {
+        setFile(droppedFile);
+      }
+    }
+  };
+
+  const handleChange = (e) => {
+    e.preventDefault();
+    if (e.target.files && e.target.files[0]) {
+      setFile(e.target.files[0]);
+    }
+  };
+
+  const handleRemoveFile = () => {
+    setFile(null);
+  };
+
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    if (!file) return;
+
+    const formData = new FormData();
+    formData.append('type', fileType);
+    formData.append('messages', '');
+    formData.append('files', file);
+    formData.append('max_tokens', 1024);
+    formData.append('language', 'en');
+    formData.append('summary_type', 'auto');
+    formData.append('stream', 'false');
+
+    onSubmit(formData, false);
+  };
+
+  return (
+    <div className="card animate-fadeIn">
+      <div className="flex items-center mb-4">
+        <Upload className="h-6 w-6 text-primary-600 mr-2" />
+        <h2 className="text-xl font-semibold text-gray-800">{title}</h2>
+      </div>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div
+          className={`file-drop-zone ${dragActive ? 'file-drop-zone-active' : 'file-drop-zone-inactive'}`}
+          onDragEnter={handleDrag}
+          onDragLeave={handleDrag}
+          onDragOver={handleDrag}
+          onDrop={handleDrop}
+        >
+          {!file ? (
+            <>
+              <Upload className="mx-auto h-16 w-16 text-gray-400 mb-4" />
+              <p className="text-lg font-medium text-gray-700 mb-2">
+                Drop your file here or click to browse
+              </p>
+              <p className="text-sm text-gray-500 mb-2">
+                Supported formats: {acceptedTypes.join(', ')}
+              </p>
+              <p className="text-xs text-gray-400 mb-4">
+                Maximum file size: {maxFileSize || '50 MB'}
+              </p>
+              <input
+                type="file"
+                id="file-upload"
+                className="hidden"
+                accept={acceptedTypes.join(',')}
+                onChange={handleChange}
+                disabled={isLoading}
+              />
+              <label
+                htmlFor="file-upload"
+                className="btn-secondary cursor-pointer inline-block"
+              >
+                Browse Files
+              </label>
+            </>
+          ) : (
+            <div className="flex items-center justify-between bg-white p-4 rounded-lg border border-gray-200">
+              <div className="flex items-center space-x-3">
+                <FileText className="h-8 w-8 text-primary-600" />
+                <div>
+                  <p className="font-medium text-gray-800">{file.name}</p>
+                  <p className="text-sm text-gray-500">
+                    {(file.size / 1024 / 1024).toFixed(2)} MB
+                  </p>
+                </div>
+              </div>
+              <button
+                type="button"
+                onClick={handleRemoveFile}
+                className="text-gray-400 hover:text-red-500 transition-colors"
+                disabled={isLoading}
+              >
+                <X className="h-5 w-5" />
+              </button>
+            </div>
+          )}
+        </div>
+
+        <button
+          type="submit"
+          disabled={!file || isLoading}
+          className="btn-primary w-full"
+        >
+          {isLoading ? 'Generating Summary...' : 'Generate Summary'}
+        </button>
+      </form>
+    </div>
+  );
+};
+
+export default FileUpload;
diff --git a/DocSummarization/frontend/src/components/TextInput.jsx b/DocSummarization/frontend/src/components/TextInput.jsx
new file mode 100644
index 0000000000..065db85312
--- /dev/null
+++ b/DocSummarization/frontend/src/components/TextInput.jsx
@@ -0,0 +1,56 @@
+import { useState } from 'react';
+import { FileText } from 'lucide-react';
+
+const TextInput = ({ onSubmit, isLoading }) => {
+  const [text, setText] = useState('');
+
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    if (!text.trim()) return;
+
+    const formData = new FormData();
+    formData.append('type', 'text');
+    formData.append('messages', text);
+    formData.append('max_tokens', 1024);
+    formData.append('language', 'en');
+    formData.append('summary_type', 'auto');
+    formData.append('stream', 'false');
+
+    onSubmit(formData, false);
+  };
+
+  return (
+    <div className="card animate-fadeIn">
+      <div className="flex items-center mb-4">
+        <FileText className="h-6 w-6 text-primary-600 mr-2" />
+        <h2 className="text-xl font-semibold text-gray-800">Paste Text</h2>
+      </div>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label className="block text-sm font-medium text-gray-700 mb-2">
+            Enter text to summarize
+          </label>
+          <textarea
+            value={text}
+            onChange={(e) => setText(e.target.value)}
+            className="w-full px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-primary-500 focus:border-transparent resize-none"
+            rows="8"
+            placeholder="Paste your text here..."
+            disabled={isLoading}
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={!text.trim() || isLoading}
+          className="btn-primary w-full"
+        >
+          {isLoading ? 'Generating Summary...' : 'Generate Summary'}
+        </button>
+      </form>
+    </div>
+  );
+};
+
+export default TextInput;
diff --git a/DocSummarization/frontend/src/components/layout/Footer.jsx b/DocSummarization/frontend/src/components/layout/Footer.jsx
new file mode 100644
index 0000000000..e532cb20f7
--- /dev/null
+++ b/DocSummarization/frontend/src/components/layout/Footer.jsx
@@ -0,0 +1,23 @@
+export const Footer = () => {
+  return (
+    <footer className="bg-white border-t border-gray-200 py-6 mt-12">
+      <div className="container mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex flex-col items-center justify-center space-y-3">
+          <div className="flex items-center space-x-2">
+            <img
+              src="/cloud2labs-logo.png"
+              alt="Cloud2Labs"
+              className="h-8 object-contain"
+            />
+            <span className="text-sm font-medium text-gray-700">Cloud2Labs</span>
+          </div>
+          <p className="text-xs text-gray-500">
+            © 2025 Cloud2Labs. All rights reserved.
+          </p>
+        </div>
+      </div>
+    </footer>
+  );
+};
+
+export default Footer;
diff --git a/DocSummarization/frontend/src/components/layout/Header.jsx b/DocSummarization/frontend/src/components/layout/Header.jsx
new file mode 100644
index 0000000000..5d2772ae16
--- /dev/null
+++ b/DocSummarization/frontend/src/components/layout/Header.jsx
@@ -0,0 +1,77 @@
+import { Link } from 'react-router-dom';
+import { Menu, X } from 'lucide-react';
+import { useState } from 'react';
+
+export const Header = () => {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+
+  const navigation = [
+    { name: 'Home', href: '/' },
+    { name: 'Generate', href: '/generate' },
+  ];
+
+  return (
+    <header className="bg-white border-b border-gray-200 sticky top-0 z-40 shadow-sm">
+      <nav className="container mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex justify-between items-center h-16">
+          {/* Logo */}
+          <Link to="/" className="flex items-center gap-3 hover:opacity-80 transition-opacity">
+            <img
+              src="/cloud2labs-logo.png"
+              alt="Cloud2Labs"
+              className="h-10 w-10 object-contain"
+            />
+            <span className="text-xl font-bold text-gray-900">
+              Document Summarization
+            </span>
+          </Link>
+
+          {/* Desktop Navigation */}
+          <div className="hidden md:flex items-center gap-6">
+            {navigation.map((item) => (
+              <Link
+                key={item.name}
+                to={item.href}
+                className="text-gray-700 hover:text-primary-600 font-medium transition-colors"
+              >
+                {item.name}
+              </Link>
+            ))}
+          </div>
+
+          {/* Mobile menu button */}
+          <button
+            onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+            className="md:hidden p-2 rounded-lg hover:bg-gray-100"
+          >
+            {mobileMenuOpen ? (
+              <X className="w-6 h-6" />
+            ) : (
+              <Menu className="w-6 h-6" />
+            )}
+          </button>
+        </div>
+
+        {/* Mobile Navigation */}
+        <div
+          className={`md:hidden overflow-hidden transition-all duration-300 ${
+            mobileMenuOpen ? 'max-h-64 pb-4' : 'max-h-0'
+          }`}
+        >
+          {navigation.map((item) => (
+            <Link
+              key={item.name}
+              to={item.href}
+              className="block py-2 text-gray-700 hover:text-primary-600 font-medium"
+              onClick={() => setMobileMenuOpen(false)}
+            >
+              {item.name}
+            </Link>
+          ))}
+        </div>
+      </nav>
+    </header>
+  );
+};
+
+export default Header;
diff --git a/DocSummarization/frontend/src/components/layout/Layout.jsx b/DocSummarization/frontend/src/components/layout/Layout.jsx
new file mode 100644
index 0000000000..55e0fe0cef
--- /dev/null
+++ b/DocSummarization/frontend/src/components/layout/Layout.jsx
@@ -0,0 +1,17 @@
+import { Outlet } from 'react-router-dom';
+import Header from './Header';
+import Footer from './Footer';
+
+export const Layout = () => {
+  return (
+    <div className="flex flex-col min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
+      <Header />
+      <main className="flex-1 container mx-auto px-4 sm:px-6 lg:px-8 py-8">
+        <Outlet />
+      </main>
+      <Footer />
+    </div>
+  );
+};
+
+export default Layout;
diff --git a/DocSummarization/frontend/src/index.css b/DocSummarization/frontend/src/index.css
new file mode 100644
index 0000000000..d13d1c908c
--- /dev/null
+++ b/DocSummarization/frontend/src/index.css
@@ -0,0 +1,87 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-text-size-adjust: 100%;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+}
+
+#root {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: #f1f1f1;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #888;
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #555;
+}
+
+@layer components {
+  .card {
+    @apply bg-white rounded-xl p-6 shadow-lg hover:shadow-xl transition-shadow;
+  }
+
+  .btn-primary {
+    @apply bg-primary-600 hover:bg-primary-700 text-white font-medium px-6 py-2.5 rounded-lg transition-colors duration-200 disabled:opacity-50 disabled:cursor-not-allowed;
+  }
+
+  .btn-secondary {
+    @apply bg-gray-100 hover:bg-gray-200 text-gray-700 font-medium px-6 py-2.5 rounded-lg transition-colors duration-200 disabled:opacity-50 disabled:cursor-not-allowed;
+  }
+
+  .tab {
+    @apply px-4 py-2 font-medium text-gray-600 border-b-2 border-transparent hover:text-primary-600 hover:border-primary-500 transition-colors duration-200 cursor-pointer;
+  }
+
+  .tab-active {
+    @apply text-primary-600 border-primary-600;
+  }
+
+  .file-drop-zone {
+    @apply border-2 border-dashed rounded-lg p-12 text-center transition-colors duration-200;
+  }
+
+  .file-drop-zone-active {
+    @apply border-primary-500 bg-primary-50;
+  }
+
+  .file-drop-zone-inactive {
+    @apply border-gray-300 bg-gray-50;
+  }
+}
diff --git a/DocSummarization/frontend/src/main.jsx b/DocSummarization/frontend/src/main.jsx
new file mode 100644
index 0000000000..54b39dd1d9
--- /dev/null
+++ b/DocSummarization/frontend/src/main.jsx
@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
diff --git a/DocSummarization/frontend/src/pages/Generate.jsx b/DocSummarization/frontend/src/pages/Generate.jsx
new file mode 100644
index 0000000000..a757d25a45
--- /dev/null
+++ b/DocSummarization/frontend/src/pages/Generate.jsx
@@ -0,0 +1,125 @@
+import { useState } from 'react';
+import { toast } from 'react-hot-toast';
+import TextInput from '../components/TextInput';
+import FileUpload from '../components/FileUpload';
+import { generateSummary, generateSummaryStreaming } from '../services/api';
+
+export const Generate = () => {
+  const [activeTab, setActiveTab] = useState('text');
+  const [summary, setSummary] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+
+  const tabs = [
+    { id: 'text', label: 'Paste Text' },
+    { id: 'file', label: 'Upload File' },
+  ];
+
+  const handleSubmit = async (formData, isStreaming) => {
+    setIsLoading(true);
+    setSummary('');
+
+    try {
+      if (isStreaming) {
+        await generateSummaryStreaming(formData, (chunk) => {
+          setSummary((prev) => prev + chunk);
+        });
+        toast.success('Summary generated successfully!');
+      } else {
+        const result = await generateSummary(formData);
+        setSummary(result);
+        toast.success('Summary generated successfully!');
+      }
+    } catch (error) {
+      console.error('Error:', error);
+      toast.error('Failed to generate summary. Please try again.');
+      setSummary('');
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold text-gray-900 mb-2">
+          Generate Summary
+        </h1>
+        <p className="text-gray-600">
+          Choose your input method and generate concise summaries
+        </p>
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <div className="space-y-6">
+          <div className="card animate-slide-up">
+            <div className="flex border-b border-gray-200 mb-6">
+              {tabs.map((tab) => (
+                <button
+                  key={tab.id}
+                  onClick={() => setActiveTab(tab.id)}
+                  className={`tab ${activeTab === tab.id ? 'tab-active' : ''}`}
+                  disabled={isLoading}
+                >
+                  {tab.label}
+                </button>
+              ))}
+            </div>
+
+            {activeTab === 'text' && (
+              <TextInput onSubmit={handleSubmit} isLoading={isLoading} />
+            )}
+
+            {activeTab === 'file' && (
+              <FileUpload
+                onSubmit={handleSubmit}
+                isLoading={isLoading}
+                acceptedTypes={['.pdf', '.doc', '.docx']}
+                fileType="text"
+                title="Upload Document"
+                maxFileSize="50 MB"
+              />
+            )}
+          </div>
+        </div>
+
+        <div className="space-y-6">
+          <div className="card animate-slide-up">
+            <h2 className="text-xl font-semibold text-gray-800 mb-4">
+              Summary Output
+            </h2>
+
+            {isLoading && !summary && (
+              <div className="flex items-center justify-center py-12">
+                <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary-600"></div>
+              </div>
+            )}
+
+            {summary && (
+              <div className="bg-gradient-to-br from-blue-50 to-indigo-50 rounded-lg p-6 min-h-[400px] max-h-[600px] overflow-y-auto border border-primary-100">
+                <p className="text-gray-800 whitespace-pre-wrap leading-relaxed">
+                  {summary}
+                </p>
+              </div>
+            )}
+
+            {!isLoading && !summary && (
+              <div className="text-center py-12">
+                <div className="bg-primary-100 w-16 h-16 rounded-full flex items-center justify-center mx-auto mb-4">
+                  <svg className="w-8 h-8 text-primary-600" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+                  </svg>
+                </div>
+                <p className="text-gray-500">
+                  Your summary will appear here once generated
+                </p>
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+
+    </div>
+  );
+};
+
+export default Generate;
diff --git a/DocSummarization/frontend/src/pages/Home.jsx b/DocSummarization/frontend/src/pages/Home.jsx
new file mode 100644
index 0000000000..bb4df2d295
--- /dev/null
+++ b/DocSummarization/frontend/src/pages/Home.jsx
@@ -0,0 +1,147 @@
+import { Link } from 'react-router-dom';
+import { FileText, ArrowRight, Sparkles, Zap, Settings } from 'lucide-react';
+
+export const Home = () => {
+  const features = [
+    {
+      icon: FileText,
+      title: 'Multiple Input Formats',
+      description: 'Supports text, PDF, and DOC/DOCX document files',
+    },
+    {
+      icon: Sparkles,
+      title: 'AI-Powered Summarization',
+      description: 'Advanced AI creates concise, accurate summaries of your content',
+    },
+    {
+      icon: Settings,
+      title: 'Smart Processing',
+      description: 'Automatically optimizes summarization for your content type',
+    },
+    {
+      icon: Zap,
+      title: 'Fast & Efficient',
+      description: 'Get instant summaries with real-time streaming support',
+    },
+  ];
+
+  const steps = [
+    {
+      number: 1,
+      title: 'Choose Input Type',
+      description: 'Select from text or document upload',
+    },
+    {
+      number: 2,
+      title: 'Upload or Paste',
+      description: 'Upload your file or paste text content',
+    },
+    {
+      number: 3,
+      title: 'Get Summary',
+      description: 'Receive your AI-generated summary instantly',
+    },
+  ];
+
+  return (
+    <div className="space-y-16">
+      {/* Hero Section */}
+      <section className="text-center space-y-6 py-12">
+        <div className="inline-block">
+          <img
+            src="/cloud2labs-logo.png"
+            alt="Cloud2Labs"
+            className="w-32 h-32 object-contain mx-auto mb-6"
+          />
+        </div>
+
+        <h1 className="text-5xl md:text-6xl font-bold text-gray-900 leading-tight">
+          Intelligent Document
+          <br />
+          <span className="bg-gradient-to-r from-primary-600 to-secondary-600 bg-clip-text text-transparent">
+            Summarization
+          </span>
+        </h1>
+
+        <p className="text-xl text-gray-600 max-w-2xl mx-auto">
+          Transform any text or document into concise, meaningful summaries
+          powered by advanced AI. Perfect for research, content analysis, and information extraction.
+        </p>
+
+        <div className="flex flex-col sm:flex-row gap-4 justify-center pt-4">
+          <Link to="/generate">
+            <button className="btn-primary flex items-center gap-2 px-8 py-3 text-lg">
+              Get Started
+              <ArrowRight className="w-5 h-5" />
+            </button>
+          </Link>
+        </div>
+      </section>
+
+      {/* Features */}
+      <section>
+        <h2 className="text-3xl font-bold text-center text-gray-900 mb-12">
+          Why Choose Document Summarization?
+        </h2>
+        <div className="grid md:grid-cols-2 lg:grid-cols-4 gap-8">
+          {features.map((feature, index) => (
+            <div
+              key={index}
+              className="bg-white rounded-xl p-6 shadow-lg hover:shadow-xl transition-shadow"
+            >
+              <div className="bg-primary-100 w-12 h-12 rounded-lg flex items-center justify-center mb-4">
+                <feature.icon className="w-6 h-6 text-primary-600" />
+              </div>
+              <h3 className="text-xl font-semibold text-gray-900 mb-2">
+                {feature.title}
+              </h3>
+              <p className="text-gray-600">{feature.description}</p>
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* How It Works */}
+      <section>
+        <h2 className="text-3xl font-bold text-center text-gray-900 mb-12">
+          How It Works
+        </h2>
+        <div className="grid md:grid-cols-3 gap-8">
+          {steps.map((step, index) => (
+            <div key={index} className="relative">
+              <div className="flex flex-col items-center text-center">
+                <div className="w-16 h-16 bg-gradient-to-br from-primary-600 to-secondary-600 rounded-full flex items-center justify-center text-white text-2xl font-bold mb-4 shadow-lg">
+                  {step.number}
+                </div>
+                <h3 className="text-xl font-semibold text-gray-900 mb-2">
+                  {step.title}
+                </h3>
+                <p className="text-gray-600">{step.description}</p>
+              </div>
+              {index < steps.length - 1 && (
+                <div className="hidden md:block absolute top-8 left-1/2 w-full h-0.5 bg-gradient-to-r from-primary-600 to-secondary-600 opacity-30" />
+              )}
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* CTA */}
+      <section className="bg-gradient-to-r from-primary-600 to-secondary-600 rounded-2xl p-12 text-center text-white shadow-xl">
+        <h2 className="text-3xl font-bold mb-4">
+          Ready to Summarize Your Content?
+        </h2>
+        <p className="text-xl mb-8 opacity-90">
+          Get started in seconds. Process text and document files instantly.
+        </p>
+        <Link to="/generate">
+          <button className="bg-white text-primary-600 hover:bg-gray-100 font-medium px-8 py-3 rounded-lg transition-colors text-lg">
+            Start Summarizing Now
+          </button>
+        </Link>
+      </section>
+    </div>
+  );
+};
+
+export default Home;
diff --git a/DocSummarization/frontend/src/services/api.js b/DocSummarization/frontend/src/services/api.js
new file mode 100644
index 0000000000..af07076269
--- /dev/null
+++ b/DocSummarization/frontend/src/services/api.js
@@ -0,0 +1,206 @@
+const BACKEND_ENDPOINT = import.meta.env.VITE_BACKEND_ENDPOINT || '';
+
+// Helper function to decode Python string escape sequences
+const decodePythonString = (str) => {
+  // Unescape Python string literal - handle all Python escape sequences
+  return str
+    // First handle hex escapes (\xHH)
+    .replace(/\\x([0-9a-fA-F]{2})/g, (match, hex) => {
+      return String.fromCharCode(parseInt(hex, 16));
+    })
+    // Handle common escape sequences
+    .replace(/\\n/g, '\n')
+    .replace(/\\r/g, '\r')
+    .replace(/\\t/g, '\t')
+    .replace(/\\"/g, '"')
+    .replace(/\\'/g, "'")
+    // Handle escaped backslash - MUST BE LAST
+    .replace(/\\\\/g, '\\');
+};
+
+export const generateSummary = async (formData) => {
+  try {
+    const response = await fetch(`${BACKEND_ENDPOINT}/v1/docsum`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API Error: ${response.status} - ${errorText}`);
+    }
+
+    const responseText = await response.text();
+    console.log('Raw response received:', responseText.substring(0, 200) + '...');
+
+    // Handle streaming format: data: b'{"id":"...","text":"..."}'
+    if (responseText.includes('data:')) {
+      const lines = responseText.split('\n');
+      let extractedText = '';
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Skip [DONE] markers and empty lines
+        if (trimmed.includes('[DONE]') || trimmed === '' || trimmed === 'data:') {
+          continue;
+        }
+
+        if (trimmed.startsWith('data: ')) {
+          let dataContent = trimmed.substring(6).trim();
+          console.log('Processing line, data content:', dataContent.substring(0, 100));
+
+          // Remove b' prefix and trailing ' if present (Python bytes string format)
+          if (dataContent.startsWith("b'") && dataContent.endsWith("'")) {
+            dataContent = dataContent.substring(2, dataContent.length - 1);
+            console.log('After removing b prefix:', dataContent.substring(0, 100));
+          }
+
+          // Remove b" prefix and trailing " if present (alternative format)
+          if (dataContent.startsWith('b"') && dataContent.endsWith('"')) {
+            dataContent = dataContent.substring(2, dataContent.length - 1);
+          }
+
+          // Try to parse as JSON FIRST (before decoding, since JSON.parse handles escapes)
+          try {
+            const jsonData = JSON.parse(dataContent);
+            console.log('Parsed JSON successfully, text field present:', !!jsonData.text);
+
+            if (jsonData.text) {
+              extractedText += jsonData.text;
+              console.log('Extracted text:', jsonData.text.substring(0, 100));
+            }
+          } catch (parseError) {
+            console.error('JSON parse failed, trying decode then parse');
+
+            // If direct JSON parse fails, decode Python escapes then try again
+            try {
+              const decodedContent = decodePythonString(dataContent);
+              const jsonData = JSON.parse(decodedContent);
+
+              if (jsonData.text) {
+                extractedText += jsonData.text;
+                console.log('Extracted text after decode:', jsonData.text.substring(0, 100));
+              }
+            } catch (secondError) {
+              console.error('Both parsing attempts failed, trying regex extraction');
+
+              // Last resort: regex extraction
+              try {
+                const textMatch = dataContent.match(/"text":"([^"]*(?:\\.[^"]*)*)"/);
+                if (textMatch && textMatch[1]) {
+                  const unescapedText = textMatch[1]
+                    .replace(/\\"/g, '"')
+                    .replace(/\\\\/g, '\\')
+                    .replace(/\\n/g, '\n');
+                  extractedText += unescapedText;
+                  console.log('Extracted via regex:', unescapedText.substring(0, 100));
+                }
+              } catch (regexError) {
+                console.error('All parsing methods failed:', regexError);
+              }
+            }
+          }
+        }
+      }
+
+      if (extractedText) {
+        console.log('Returning extracted text, length:', extractedText.length);
+        return extractedText;
+      } else {
+        console.warn('No text extracted from data lines');
+      }
+    }
+
+    // Try direct JSON parse as fallback
+    try {
+      const jsonData = JSON.parse(responseText);
+      if (jsonData.text) {
+        return jsonData.text;
+      }
+      if (jsonData.output_text) {
+        return jsonData.output_text;
+      }
+    } catch (e) {
+      console.error('Direct JSON parse failed:', e.message);
+    }
+
+    // Last resort - return response text but warn user
+    console.error('Could not extract text field, returning raw response');
+    return responseText;
+  } catch (error) {
+    console.error('Error generating summary:', error);
+    throw error;
+  }
+};
+
+export const generateSummaryStreaming = async (formData, onChunk) => {
+  try {
+    const response = await fetch(`${BACKEND_ENDPOINT}/v1/docsum`, {
+      method: 'POST',
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`API Error: ${response.status} - ${errorText}`);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Process complete lines
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Skip [DONE] markers and empty lines
+        if (trimmed.includes('[DONE]') || trimmed === '' || trimmed === 'data:') {
+          continue;
+        }
+
+        if (trimmed.startsWith('data: ')) {
+          let dataContent = trimmed.substring(6).trim();
+
+          // Remove b' prefix and trailing ' if present (Python bytes string format)
+          if (dataContent.startsWith("b'") && dataContent.endsWith("'")) {
+            dataContent = dataContent.substring(2, dataContent.length - 1);
+          }
+
+          // Remove b" prefix and trailing " if present (alternative format)
+          if (dataContent.startsWith('b"') && dataContent.endsWith('"')) {
+            dataContent = dataContent.substring(2, dataContent.length - 1);
+          }
+
+          // Try to parse as JSON first (JSON.parse handles escape sequences correctly)
+          try {
+            const data = JSON.parse(dataContent);
+            if (data.text) {
+              console.log('[STREAMING] JSON chunk:', data.text);
+              onChunk(data.text);
+            }
+          } catch (parseError) {
+            // Not JSON - this is a raw text token, decode then send
+            if (dataContent) {
+              const decodedText = decodePythonString(dataContent);
+              console.log('[STREAMING] Raw token:', decodedText);
+              onChunk(decodedText);
+            }
+          }
+        }
+      }
+    }
+  } catch (error) {
+    console.error('Error generating summary:', error);
+    throw error;
+  }
+};
diff --git a/DocSummarization/frontend/tailwind.config.js b/DocSummarization/frontend/tailwind.config.js
new file mode 100644
index 0000000000..1f804147c2
--- /dev/null
+++ b/DocSummarization/frontend/tailwind.config.js
@@ -0,0 +1,57 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: '#f0f9ff',
+          100: '#e0f2fe',
+          200: '#bae6fd',
+          300: '#7dd3fc',
+          400: '#38bdf8',
+          500: '#0ea5e9',
+          600: '#0284c7',
+          700: '#0369a1',
+          800: '#075985',
+          900: '#0c4a6e',
+        },
+        secondary: {
+          50: '#fdf4ff',
+          100: '#fae8ff',
+          200: '#f5d0fe',
+          300: '#f0abfc',
+          400: '#e879f9',
+          500: '#d946ef',
+          600: '#c026d3',
+          700: '#a21caf',
+          800: '#86198f',
+          900: '#701a75',
+        },
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.5s ease-in-out',
+        'slide-up': 'slideUp 0.5s ease-out',
+        'slide-down': 'slideDown 0.5s ease-out',
+      },
+      keyframes: {
+        fadeIn: {
+          '0%': { opacity: '0' },
+          '100%': { opacity: '1' },
+        },
+        slideUp: {
+          '0%': { transform: 'translateY(20px)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+        slideDown: {
+          '0%': { transform: 'translateY(-20px)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+      },
+    },
+  },
+  plugins: [],
+}
diff --git a/DocSummarization/frontend/vite.config.js b/DocSummarization/frontend/vite.config.js
new file mode 100644
index 0000000000..5bae3cb83b
--- /dev/null
+++ b/DocSummarization/frontend/vite.config.js
@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: '0.0.0.0',
+    port: 5174,
+    proxy: {
+      '/v1': {
+        target: process.env.BACKEND_SERVICE_ENDPOINT || 'http://localhost:8888',
+        changeOrigin: true
+      }
+    }
+  }
+})
diff --git a/DocuGenMicroagents/.gitignore b/DocuGenMicroagents/.gitignore
new file mode 100644
index 0000000000..df9559db20
--- /dev/null
+++ b/DocuGenMicroagents/.gitignore
@@ -0,0 +1,86 @@
+
+.env
+.env.local
+.env.*.local
+*.env
+
+
+
+# ============================================
+# PYTHON
+# ============================================
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# ============================================
+# NODE.JS / REACT
+# ============================================
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Production build
+build/
+dist/
+
+# React
+.env.development.local
+.env.test.local
+.env.production.local
+
+# ============================================
+# TEMPORARY & CACHE FILES
+# ============================================
+# Temporary cloned repositories
+api/tmp/
+api/temp/
+*/tmp/
+*/temp/
+tests/
+
+# Logs
+*.log
+logs/
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ============================================
+# LANGGRAPH & AI
+# ============================================
+# LangGraph checkpoints (SQLite databases)
+*.db
+*.sqlite
+*.sqlite3
+checkpoints/
+
+tmp/
diff --git a/DocuGenMicroagents/README.md b/DocuGenMicroagents/README.md
new file mode 100644
index 0000000000..e01c8ec80e
--- /dev/null
+++ b/DocuGenMicroagents/README.md
@@ -0,0 +1,441 @@
+## Documentation Generator
+
+AI-powered documentation generator that automatically creates comprehensive README files from code repositories. This application uses a micro-agent system with nine specialized agents orchestrated by LangGraph to analyze code, extract API endpoints, map call graphs, identify error patterns, parse configurations, and generate documentation with architecture diagrams.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Tool System](#tool-system)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [User Interface](#user-interface)
+- [Troubleshooting](#troubleshooting)
+- [Additional Info](#additional-info)
+
+---
+
+## Project Overview
+
+Documentation Generator is an autonomous system that transforms code repositories into professional README documentation using a specialized micro-agent architecture. The application employs nine specialized AI agents built on LangChain and orchestrated by LangGraph. Six section-writer agents analyze specific aspects of the codebase (project overview, API endpoints, architecture patterns, error handling, environment configuration, and dependencies), while three coordination agents handle planning, diagram generation, and quality validation. The system clones repositories, performs intelligent analysis with strategic file sampling, and generates structured documentation including project descriptions, installation instructions, usage guides, and Mermaid architecture diagrams. Each agent operates with a limited tool set and context budget optimized for efficiency. The system supports both single-project repositories and monorepos with intelligent project detection and user selection capabilities.
+
+---
+
+## Features
+
+- Micro-agent system with nine specialized AI agents optimized for small language models: Code Explorer, API Reference, Call Graph, Error Analysis, Environment Config, Dependency Analyzer, Planner, Mermaid Generator, and QA Validator
+- 11 custom repository analysis tools built with LangChain distributed across agents for autonomous code exploration, API extraction, and syntax validation
+- Strategic file sampling with three reading strategies: full, smart, and pattern_window (context-aware extraction around routes, errors, and entry points)
+- Autonomous repository analysis using ReAct pattern (Thought → Action → Observation) for transparent decision-making
+- Intelligent monorepo detection with automatic project discovery and user selection interface
+- Subfolder-specific documentation generation via URL targeting (e.g., `https://github.com/owner/repo/tree/main/backend`)
+- Support for GitHub public and private repositories with token-based authentication
+- Automated pull request creation using Model Context Protocol (MCP) with official GitHub MCP server integration
+- Real-time progress tracking via Server-Sent Events (SSE) for live agent activity monitoring
+- Mermaid 8.14.0 compatible diagram generation with semantic validation and render-safe checks
+- Built on LangChain framework for tool infrastructure and LangGraph for multi-agent workflow orchestration with state persistence
+- Evidence-based documentation generation with filesystem verification and agent output aggregation
+- Comprehensive metrics tracking including token usage, tool calls, LLM calls, TPS (tokens per second), and execution duration
+- Modern React web interface with job history, status monitoring, and documentation preview
+- Flexible LLM backend supporting Qwen/Qwen3-4B-Instruct-2507 optimized for Intel Xeon processors
+- RESTful API with JSON-based communication for integration capabilities
+- Configurable analysis limits via .env (10GB max repo size, 500 files max, 1MB per file, adjustable line budget)
+
+---
+
+## Architecture
+
+This application uses a micro-agent architecture with nine specialized AI agents built on LangChain and orchestrated by LangGraph. The React frontend communicates with a FastAPI backend that orchestrates the workflow. Nine agents operate sequentially within a LangGraph StateGraph workflow: six section-writer agents (Code Explorer, API Reference, Call Graph, Error Analysis, Environment Config, Dependency Analyzer) analyze specific aspects of the codebase and write documentation sections directly, followed by three coordination agents (Planner decides which sections to include, Mermaid Generator creates architecture diagrams with semantic validation, and QA Validator performs evidence-based quality checks). An Evidence Aggregator node consolidates filesystem data and agent outputs before planning. All agents use strategic file sampling with pattern_window mode to extract high-value code regions (routes, error handlers, entry points) within limited context budgets. The system tracks comprehensive metrics including token usage, tool calls, and execution duration. Each agent operates with 3-8 specialized tools and implements the ReAct pattern for autonomous decision-making.
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        A[React Web UI<br/>Port 3000]
+    end
+
+    subgraph "API Layer"
+        B[FastAPI Server<br/>Port 5001<br/>REST API + SSE]
+    end
+
+    subgraph "Section Writer Agents"
+        C[Code Explorer<br/>Overview + Features]
+        D[API Reference<br/>Endpoint Extractor]
+        E[Call Graph<br/>Architecture Writer]
+        F[Error Analysis<br/>Troubleshooting Writer]
+        G[Env Config<br/>Configuration Writer]
+        H[Dependency Analyzer<br/>Prerequisites Writer]
+    end
+
+    subgraph "Coordination Agents"
+        I[Planner<br/>Section Selector]
+        J[Mermaid Generator<br/>Diagram + Validation]
+        K[QA Validator<br/>Evidence Checks]
+    end
+
+    subgraph "GitHub Integration"
+        L[PR Agent<br/>MCP Tools]
+        M[GitHub MCP Server<br/>Docker Container]
+    end
+
+    subgraph "External Services"
+        N[LLM Backend<br/>Qwen3-4B-Instruct]
+    end
+
+    A -->|POST /generate-docs| B
+    A -->|SSE /logs| B
+    B -->|Clone & Detect| C
+    C --> D
+    D --> E
+    E --> F
+    F --> G
+    G --> H
+    H -->|Evidence Aggregation| I
+    I --> J
+    J --> K
+    K -->|Assembly| B
+    B -->|JSON Response| A
+    A -->|POST /create-pr| B
+    B --> L
+    L --> M
+    M -->|Branch, Commit, PR| GitHub
+    C --> N
+    D --> N
+    E --> N
+    F --> N
+    G --> N
+    H --> N
+    I --> N
+    J --> N
+    K --> N
+    L --> N
+
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#ffe1f5
+    style D fill:#ffe1f5
+    style E fill:#ffe1f5
+    style F fill:#ffe1f5
+    style G fill:#ffe1f5
+    style H fill:#ffe1f5
+    style I fill:#d4f1d4
+    style J fill:#d4f1d4
+    style K fill:#d4f1d4
+    style L fill:#ffd4d4
+    style M fill:#e1ffe1
+    style N fill:#ffe1e1
+```
+
+**Strategic File Sampling:**
+
+The system implements three intelligent file reading strategies to optimize context usage with small language models. All strategies work within a configurable line budget (default: 500 lines, set via MAX_LINES_PER_FILE):
+
+- **full** - Reads first N lines within budget. Simple and deterministic for small files.
+- **smart** - Extracts top + function/class signatures + bottom sections. Preserves file structure overview while staying within line budget.
+- **pattern_window** - Context-aware extraction that detects high-value code patterns (FastAPI/Flask routes, error handlers, entry points, main functions) and extracts ±6 lines around matches. Falls back to smart strategy if no patterns found. This is the default mode for all agents, enabling efficient analysis of large codebases.
+
+All agents use `pattern_window` by default to maximize information density within the 8K context budget optimized for Qwen3-4B. The line budget is configurable via `.env` file to balance context usage and file coverage.
+
+**Core Components:**
+
+1. **React Web UI (Port 3000)** - Vite development server hosting the React frontend. Handles repository URL input with subfolder support, displays real-time generation progress via SSE streaming, provides project selection interface for monorepos, and offers documentation preview with download functionality.
+
+2. **FastAPI Server (Port 5001)** - Manages LangGraph workflow orchestration with state persistence, maintains job state in memory, handles repository cloning with branch detection, performs monorepo project detection, tracks comprehensive metrics (tokens, tool calls, TPS, duration), and coordinates GitHub PR creation via MCP protocol.
+
+3. **Code Explorer Agent** - Writes Project Overview and Features sections. Uses 5 tools: `list_directory`, `read_file`, `detect_languages`, `extract_dependencies`, `analyze_code_structure`. Extracts concrete technical details including project purpose, user-facing capabilities, dependencies, and architecture patterns.
+
+4. **API Reference Agent** - Extracts API endpoints and returns structured JSON. Uses 3 tools: `list_directory`, `read_file`, `find_api_routes`. Identifies REST API routes, HTTP methods, and endpoint purposes from FastAPI, Flask, Express, and Spring frameworks.
+
+5. **Call Graph Agent** - Writes Architecture section describing component relationships and data flow. Uses 5 tools including `find_entry_points` to identify main application files and `analyze_code_structure` to map dependencies.
+
+6. **Error Analysis Agent** - Writes Troubleshooting section by identifying error patterns, exception handlers, and common failure modes. Uses `read_file` with pattern_window to extract try-except blocks and error handling logic.
+
+7. **Environment Config Agent** - Writes Configuration section by analyzing .env.example files and configuration modules. Extracts environment variables, API keys, and deployment settings with their purposes.
+
+8. **Dependency Analyzer Agent** - Writes Prerequisites and Quick Start Deployment sections. Analyzes requirements.txt, package.json, Dockerfile, and docker-compose.yml to generate installation instructions and deployment guides.
+
+9. **Planner Agent** - Determines which sections to include in the final README based on project type (web app, API service, library, CLI tool). Uses 8 tools including `find_ui_files`, `find_docker_files`, `find_config_files` for project detection.
+
+10. **Mermaid Generator Agent** - Creates architecture diagrams with semantic validation. Validates diagrams against evidence packet to ensure accuracy (no endpoint nodes, includes backend/frontend/database based on detected components). Uses `validate_mermaid_syntax` for Mermaid 8.14.0 render-safe checks.
+
+11. **QA Validator Agent** - Performs evidence-based quality validation comparing README sections against filesystem evidence. Checks for hallucinations, missing sections, and factual accuracy before final assembly.
+
+12. **PR Agent** - Autonomous AI agent activated via `/api/create-pr/{job_id}` endpoint after documentation generation. Uses GitHub MCP server tools via Model Context Protocol stdio interface. Executes four-step workflow: checks existing README.md, creates feature branch, commits documentation with conventional commit message, creates pull request with descriptive body.
+
+---
+
+## Tool System
+
+The system includes 11 specialized repository analysis tools implemented in `api/tools/repo_tools.py` using LangChain's `@tool` decorator. These tools enable the nine LangGraph agents to autonomously analyze repositories. Each agent receives a curated subset of tools based on its specific responsibilities. The PR Agent uses a separate set of GitHub tools provided by the GitHub MCP server. All tools are invoked by agents using the ReAct pattern - agents autonomously decide when to call tools, interpret results, and act on observations.
+
+### Tool Distribution Across Agents
+
+| Agent                    | Tool Count | Tools Available                                       |
+|--------------------------|------------|-------------------------------------------------------|
+| **Code Explorer**        | 5          | Core analysis tools for repository exploration        |
+| **API Reference**        | 3          | Directory listing, file reading, API route detection  |
+| **Call Graph**           | 5          | Core analysis tools + entry point detection           |
+| **Error Analysis**       | 3          | File reading, directory listing, code structure       |
+| **Env Config**           | 3          | File reading, config file detection, directory listing|
+| **Dependency Analyzer**  | 5          | Core analysis tools + dependency extraction           |
+| **Planner**              | 8          | Core tools + project detection tools                  |
+| **Mermaid Generator**    | 7          | Selective tools + validation tools                    |
+| **QA Validator**         | 0          | No tools (operates on README sections + evidence)     |
+| **PR Agent**             | 4          | GitHub MCP tools (via Model Context Protocol)         |
+
+### Core Analysis Tools (5 tools)
+
+**Framework: LangChain (@tool decorator)**
+**Used by: Code Explorer, Call Graph, Dependency Analyzer**
+
+1. **`list_directory`** - Browses directory structure with automatic filtering of common ignore patterns (.git, node_modules, __pycache__, venv, dist, build)
+2. **`read_file`** - Reads source code and configuration files with strategic sampling (supports full, smart, pattern_window modes). Default: pattern_window for context-aware extraction. Limits: 1MB max file size, configurable line budget (default 500 via MAX_LINES_PER_FILE).
+3. **`detect_languages`** - Identifies programming languages by file extensions (supports 16 languages including Python, JavaScript, TypeScript, Go, Rust, Java, C++)
+4. **`extract_dependencies`** - Recursively scans subdirectories and parses dependency files (requirements.txt, package.json, go.mod, Cargo.toml). Returns first 20 dependencies per ecosystem.
+5. **`analyze_code_structure`** - Extracts functions, classes, and imports using AST parsing (Python) or basic line count metrics (other languages)
+
+### Project Detection Tools (3 tools)
+
+**Framework: LangChain (@tool decorator)**
+**Used by: Planner (in addition to core tools)**
+
+6. **`find_ui_files`** - Detects frontend components and frameworks (React, Vue.js, Angular, Next.js, Svelte)
+7. **`find_docker_files`** - Checks for Docker and containerization configuration files
+8. **`find_config_files`** - Locates environment and configuration files in repository root
+
+### Diagram Generation Tools (2 tools)
+
+**Framework: LangChain (@tool decorator)**
+**Used by: Diagram Generator (in addition to selective core tools)**
+
+9. **`find_entry_points`** - Locates main entry point files (main.py, server.py, index.js, etc.) across languages
+10. **`find_api_routes`** - Extracts API routes/endpoints using regex for Flask, FastAPI, Express, Spring frameworks
+
+### Validation Tool (1 tool)
+
+**Framework: LangChain (@tool decorator)**
+**Used by: Diagram Generator for self-critique**
+
+11. **`validate_mermaid_syntax`** - Validates Mermaid 8.14.0 syntax with automatic error detection and repair suggestions
+
+### GitHub MCP Tools (4 tools)
+
+**Framework: Model Context Protocol (MCP)**
+**Used by: PR Agent**
+
+1. **`get_file_contents`** - Retrieves file content and SHA from GitHub repository
+2. **`create_branch`** - Creates new feature branch with timestamp-based naming
+3. **`create_or_update_file`** - Commits README.md to branch with conventional commit message
+4. **`create_pull_request`** - Opens PR with AI-generated title, description, and labels
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+Before you begin, ensure you have the following installed:
+
+- **Python 3.9+** - Required for FastAPI backend and LangGraph workflow execution
+- **Node.js 16+** and **npm** - Required for React frontend with Vite build tooling
+- **Git** - Required for repository cloning operations and version control
+
+### Verify Installation
+
+```bash
+# Check Python version
+python --version
+
+# Check Node.js version
+node --version
+
+# Check npm version
+npm --version
+
+# Verify Git installation
+git --version
+```
+
+### Required API Keys
+
+**GenAI Gateway API Key:**
+- Required for accessing LLM models through the enterprise GenAI Gateway
+- Key format starts with `sk-` followed by alphanumeric string
+- Supports Qwen/Qwen3-4B-Instruct-2507 optimized for Intel Xeon processors
+- Used for all nine AI agents (Code Explorer, API Reference, Call Graph, Error Analysis, Env Config, Dependency Analyzer, Planner, Mermaid Generator, QA Validator) plus PR Agent
+
+**GitHub Personal Access Token (Optional):**
+- Required only for automatic pull request creation via PR Agent
+- Generate classic token at https://github.com/settings/tokens
+- Required scopes: `repo` (full control of private repositories)
+- Used by PR Agent via GitHub MCP server to create branch, commit, and pull request
+- Token format: `ghp_` followed by 36 alphanumeric characters
+
+---
+
+## Quick Start
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/opea-project/GenAIExamples.git
+cd GenAIExamples/DocuGenMicroagents
+```
+
+### Docker Deployment (Recommended)
+
+The fastest way to run DocuGen is using Docker Compose:
+
+**1. Configure Environment Variables:**
+
+```bash
+cp api/.env.example api/.env
+```
+
+Edit `api/.env` and configure your API keys:
+
+```bash
+# Auth mode: genai_gateway | keycloak
+AUTH_MODE=genai_gateway
+
+# GenAI Gateway Configuration
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your_genai_gateway_api_key_here
+
+# GitHub token (optional, required for PR creation)
+GITHUB_TOKEN=your_github_personal_access_token_here
+
+# AI models (all agents use Qwen3-4B optimized for Intel Xeon)
+CODE_EXPLORER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+API_REFERENCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+CALL_GRAPH_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ERROR_ANALYSIS_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ENV_CONFIG_MODEL=Qwen/Qwen3-4B-Instruct-2507
+DEPENDENCY_ANALYZER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+PLANNER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+MERMAID_MODEL=Qwen/Qwen3-4B-Instruct-2507
+QA_VALIDATOR_MODEL=Qwen/Qwen3-4B-Instruct-2507
+WRITER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+```
+
+**2. Start Services:**
+
+```bash
+docker-compose up -d
+```
+
+This command will:
+- Build and start the backend container on port 5001
+- Build and start the frontend container on port 3000
+- Set up networking between containers
+- Enable health checks for both services
+
+**3. Verify Services:**
+
+```bash
+docker-compose ps
+```
+
+Expected output:
+```
+NAME               STATUS
+docugen-backend    Up (healthy)
+docugen-frontend   Up (healthy)
+```
+
+**4. View Logs:**
+
+```bash
+# View all logs
+docker-compose logs -f
+
+# View specific service logs
+docker-compose logs -f backend
+docker-compose logs -f frontend
+```
+
+**5. Stop Services:**
+
+```bash
+docker-compose down
+```
+
+### Access the Application
+
+Open your browser and navigate to:
+
+```
+http://localhost:3000
+```
+
+---
+
+## User Interface
+
+### Homepage
+Enter any GitHub repository URL to start documentation generation. Supports full repositories, specific branches, and subfolder paths for monorepos.
+
+![Homepage](./docs/images/01-homepage-input.png)
+
+### Agent Workflow
+Watch the nine AI agents work sequentially in real-time. Each agent displays its reasoning process using the ReAct pattern (Thought → Action → Observation). Progress through six section-writer agents, followed by planning, diagram generation, and quality validation.
+
+![Agent Workflow](./docs/images/02-agent-workflow.png)
+
+### Progress Tracking
+Monitor live progress with detailed logs from each agent. Server-Sent Events (SSE) provide real-time updates on tool executions, decisions, and analysis results.
+
+![Progress Tracking](./docs/images/03-progress-tracking.png)
+
+### Generated Documentation
+Review the complete README with architecture diagrams, installation instructions, and usage guides. Download or create a pull request directly from the interface.
+
+![Generated README](./docs/images/04-generated-readme.png)
+
+### PR Agent Execution
+Activate the PR Agent to autonomously create a GitHub pull request. Watch as it checks for existing files, creates a branch, commits changes, and opens a PR with AI-generated descriptions.
+
+![PR Agent Logs](./docs/images/05-pr-agent-execution.png)
+
+### Pull Request Created
+PR Agent successfully creates the pull request with conventional commit messages and links it back to the UI for immediate access.
+
+![PR Created](./docs/images/06-pr-created.png)
+
+---
+
+## Troubleshooting
+
+For detailed troubleshooting guidance and solutions to common issues, refer to:
+
+[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+
+---
+
+## Additional Info
+
+### Model Compatibility
+
+| Model Name | Deployment Platform | Notes |
+|------------|---------------------|-------|
+| Qwen/Qwen3-4B-Instruct-2507 | Xeon | Optimized SLM with 8K context window for efficient documentation generation across all nine micro-agents. |
+
+### Performance Metrics
+
+The system tracks comprehensive performance metrics for each agent execution, providing visibility into token usage, processing speed, and resource consumption. Metrics are calculated and displayed in real-time during workflow execution:
+
+**Metrics Tracked:**
+- **Token Usage** - Input and output tokens per agent, aggregated for total workflow cost
+- **Tokens Per Second (TPS)** - Model generation speed measured at two levels:
+  - **Per-Agent TPS**: `output_tokens / agent_duration_seconds` - True model inference speed for each agent
+  - **Workflow Average TPS**: `total_output_tokens / workflow_duration_seconds` - Overall throughput including inter-agent overhead (typically lower due to I/O and state management gaps)
+- **Execution Duration** - Wall-clock time for each agent and total workflow duration
+- **LLM Calls** - Number of model inference requests per agent
+- **Tool Calls** - Number of repository analysis tool invocations per agent
+
+**TPS Interpretation**: Per-Agent TPS measures effective throughput (output tokens / total agent duration) which includes LLM inference time plus tool execution overhead. This represents real-world agent performance. Workflow Average TPS is typically lower because it also includes gaps between agent executions (state updates, inter-agent I/O). Both metrics provide complete visibility into system performance.
+
+![Performance Metrics Dashboard](./docs/images/07-metrics.png)
+
+Metrics are displayed in the agent logs panel upon completion with the format: `AgentName: total=X (out=Y), Zms, outTPS=W` showing total tokens, output tokens, duration, and output tokens per second for each agent, plus workflow-level averages.
+
diff --git a/DocuGenMicroagents/TROUBLESHOOTING.md b/DocuGenMicroagents/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..4e8ab5b92d
--- /dev/null
+++ b/DocuGenMicroagents/TROUBLESHOOTING.md
@@ -0,0 +1,517 @@
+# Troubleshooting Guide
+
+This guide covers common issues and solutions for the Documentation Generator Micro-Agents application.
+
+---
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [Configuration Errors](#configuration-errors)
+- [Runtime Errors](#runtime-errors)
+- [Agent Failures](#agent-failures)
+- [Performance Issues](#performance-issues)
+- [Docker Issues](#docker-issues)
+- [Network and API Errors](#network-and-api-errors)
+
+---
+
+## Installation Issues
+
+### Docker Container Build Fails
+
+**Error:** `ERROR [internal] load build context`
+
+**Cause:** Docker daemon not running or insufficient permissions.
+
+**Solution:**
+```bash
+# Start Docker daemon (Linux/Mac)
+sudo systemctl start docker
+
+# On Windows, start Docker Desktop application
+
+# Verify Docker is running
+docker ps
+```
+
+### Port Already in Use
+
+**Error:** `Error starting userland proxy: listen tcp 0.0.0.0:5001: bind: address already in use`
+
+**Cause:** Another service is using port 5001 (backend) or 3000 (frontend).
+
+**Solution:**
+```bash
+# Find process using the port
+# On Linux/Mac:
+lsof -i :5001
+lsof -i :3000
+
+# On Windows:
+netstat -ano | findstr :5001
+netstat -ano | findstr :3000
+
+# Kill the process or change ports in docker-compose.yml
+```
+
+---
+
+## Configuration Errors
+
+### Missing GenAI Gateway API Key
+
+**Error:** `ValueError: GENAI_GATEWAY_API_KEY not configured`
+
+**Cause:** API key not set in `.env` file.
+
+**Solution:**
+```bash
+# Copy environment template
+cp api/.env.example api/.env
+
+# Edit api/.env and add your API key
+GENAI_GATEWAY_API_KEY=your_actual_api_key_here
+```
+
+### Invalid GitHub Token
+
+**Error:** `401 Unauthorized` when creating pull requests
+
+**Cause:** GitHub token missing, expired, or has insufficient permissions.
+
+**Solution:**
+1. Generate a new Personal Access Token at https://github.com/settings/tokens
+2. Select `repo` scope (full control of repositories)
+3. Update `GITHUB_TOKEN` in `api/.env`
+4. Token format should be: `ghp_` followed by 36 alphanumeric characters
+
+### Authentication Mode Mismatch
+
+**Error:** `KeyError: 'KEYCLOAK_CLIENT_SECRET'` or connection refused
+
+**Cause:** AUTH_MODE set to keycloak but credentials not configured.
+
+**Solution:**
+```bash
+# For GenAI Gateway (recommended):
+AUTH_MODE=genai_gateway
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your_key_here
+
+# For Keycloak:
+AUTH_MODE=keycloak
+BASE_URL=https://your-inference-endpoint.com
+KEYCLOAK_CLIENT_SECRET=your_secret_here
+```
+
+---
+
+## Runtime Errors
+
+### Repository Clone Fails
+
+**Error:** `fatal: repository not found` or `Permission denied (publickey)`
+
+**Cause:** Invalid repository URL or insufficient permissions.
+
+**Solution:**
+1. Verify the GitHub URL is correct and accessible
+2. For private repositories, ensure:
+   - Repository exists and you have access
+   - Authentication is configured correctly
+   - Organization SSO is authorized if applicable
+
+### Repository Too Large
+
+**Error:** `Repository exceeds maximum size of 10GB`
+
+**Cause:** Repository size exceeds MAX_REPO_SIZE limit.
+
+**Solution:**
+```bash
+# Option 1: Increase limit in api/.env
+MAX_REPO_SIZE=21474836480  # 20GB in bytes
+
+# Option 2: Use subfolder targeting
+# Instead of: https://github.com/org/repo
+# Use: https://github.com/org/repo/tree/main/backend
+```
+
+### File Size Limit Exceeded
+
+**Error:** `File too large (X bytes). Maximum is 1.0MB`
+
+**Cause:** Individual file exceeds MAX_FILE_SIZE limit.
+
+**Solution:**
+```bash
+# Increase file size limit in api/.env
+MAX_FILE_SIZE=2000000  # 2MB in bytes
+
+# Or exclude large files by using subfolder targeting
+```
+
+### Too Many Files in Repository
+
+**Error:** `Repository has X files, maximum is 500`
+
+**Cause:** Repository exceeds MAX_FILES_TO_SCAN limit.
+
+**Solution:**
+```bash
+# Increase file scan limit in api/.env
+MAX_FILES_TO_SCAN=1000
+
+# Or use subfolder targeting for specific directories
+```
+
+---
+
+## Agent Failures
+
+### Agent Timeout
+
+**Error:** `Agent execution timed out after 300 seconds`
+
+**Cause:** Agent taking too long to complete analysis.
+
+**Solution:**
+```bash
+# Increase timeout in api/.env
+AGENT_TIMEOUT=600  # 10 minutes
+
+# Or reduce repository size using subfolder targeting
+```
+
+### Code Explorer Agent Fails
+
+**Error:** `CodeExplorer failed: No code files found`
+
+**Cause:** Repository contains no recognized programming language files.
+
+**Solution:**
+- Verify repository contains source code files (.py, .js, .ts, .go, .rs, etc.)
+- Check if files are in subdirectories (agents scan recursively)
+- Ensure repository cloning completed successfully
+
+### API Reference Agent Returns Empty Results
+
+**Error:** `No API endpoints extracted`
+
+**Cause:** Repository doesn't contain API route definitions, or patterns not recognized.
+
+**Solution:**
+- This is normal for non-API projects (libraries, CLI tools)
+- For API projects, ensure route definitions use standard patterns:
+  - FastAPI: `@router.get("/endpoint")`, `@app.post("/endpoint")`
+  - Flask: `@app.route("/endpoint")`
+  - Express: `app.get("/endpoint")`
+  - Spring: `@GetMapping("/endpoint")`
+
+### Mermaid Diagram Validation Fails
+
+**Error:** `Diagram has semantic issues: missing Backend node`
+
+**Cause:** Generated diagram doesn't match detected project structure.
+
+**Solution:**
+- This is a warning, not a failure - diagram is still generated
+- The system validates diagrams against detected components (backend, frontend, database)
+- Check agent logs to see what was detected in Evidence Aggregator
+- Diagram may need manual refinement if complex architecture
+
+### QA Validator Detects Issues
+
+**Error:** `QA validation failed: Low quality score`
+
+**Cause:** README sections don't match detected evidence or contain hallucinations.
+
+**Solution:**
+- Review the QA validation output in agent logs
+- Check if correct sections were generated by section-writer agents
+- Verify Evidence Aggregator detected files correctly
+- This doesn't block README generation - final output is still produced
+
+---
+
+## Performance Issues
+
+### Slow Documentation Generation
+
+**Symptom:** Workflow takes longer than 5 minutes
+
+**Causes and Solutions:**
+
+1. **Large repository**
+   ```bash
+   # Reduce scan limits in api/.env
+   MAX_FILES_TO_SCAN=300
+   MAX_LINES_PER_FILE=300
+   ```
+
+2. **High token usage**
+   - Check metrics summary in agent logs
+   - Typical usage: 20K-40K tokens per repository
+   - If much higher, repository may have very large files
+
+3. **Network latency to LLM backend**
+   - Ensure low latency network connection to GenAI Gateway
+   - Check GENAI_GATEWAY_URL is accessible
+
+### High Token Usage
+
+**Symptom:** Metrics show >60K tokens for small repository
+
+**Cause:** Strategic sampling not working efficiently or very verbose files.
+
+**Solution:**
+```bash
+# Reduce lines per file in api/.env
+MAX_LINES_PER_FILE=300
+
+# Agents automatically use pattern_window mode to minimize context
+# This is the default and most efficient strategy
+```
+
+---
+
+## Docker Issues
+
+### Backend Container Won't Start
+
+**Error:** `backend exited with code 1`
+
+**Solution:**
+```bash
+# Check backend logs for specific error
+docker-compose logs backend
+
+# Common causes:
+# 1. Missing .env file - solution above in Configuration Errors
+# 2. Invalid Python dependencies - rebuild:
+docker-compose build --no-cache backend
+docker-compose up -d
+
+# 3. Port conflict - solution above in Installation Issues
+```
+
+### Frontend Container Build Fails
+
+**Error:** `npm install failed` or `Cannot find module`
+
+**Solution:**
+```bash
+# Rebuild frontend with clean cache
+docker-compose build --no-cache frontend
+docker-compose up -d frontend
+
+# Verify Node.js version in Dockerfile is compatible (16+)
+```
+
+### Container Memory Issues
+
+**Error:** `Killed` or `Out of memory`
+
+**Solution:**
+```bash
+# Increase Docker memory limit in Docker Desktop settings
+# Recommended: 4GB minimum, 8GB preferred
+
+# Or reduce repository analysis limits:
+MAX_FILES_TO_SCAN=200
+MAX_LINES_PER_FILE=300
+```
+
+### Cannot Connect to Backend from Frontend
+
+**Error:** `Network error` or `Connection refused` in browser console
+
+**Cause:** Docker network misconfiguration or CORS issue.
+
+**Solution:**
+```bash
+# Verify both containers are running
+docker-compose ps
+
+# Check backend is accessible
+curl http://localhost:5001/api/health
+
+# Verify CORS_ORIGINS in api/.env includes frontend URL
+CORS_ORIGINS=["http://localhost:3000"]
+
+# Restart services
+docker-compose restart
+```
+
+---
+
+## Network and API Errors
+
+### GenAI Gateway Connection Refused
+
+**Error:** `ConnectionRefusedError: [Errno 111] Connection refused`
+
+**Cause:** GenAI Gateway URL incorrect or service unavailable.
+
+**Solution:**
+```bash
+# Verify GENAI_GATEWAY_URL is correct in api/.env
+# Test connectivity:
+curl https://your-gateway-url.com/health
+
+# Check firewall/proxy settings allow outbound HTTPS
+```
+
+### LLM Request Timeout
+
+**Error:** `Timeout waiting for LLM response`
+
+**Cause:** LLM backend overloaded or network latency.
+
+**Solution:**
+```bash
+# Increase agent timeout in api/.env
+AGENT_TIMEOUT=600
+
+# Check LLM backend status
+# Contact infrastructure team if persistent
+```
+
+### Rate Limit Exceeded
+
+**Error:** `429 Too Many Requests` or `Rate limit exceeded`
+
+**Cause:** Too many concurrent requests to LLM backend.
+
+**Solution:**
+- Wait a few minutes before retrying
+- Reduce concurrent documentation generation jobs
+- Contact infrastructure team to increase rate limits
+- The system processes agents sequentially to minimize rate limit issues
+
+### GitHub API Rate Limit (PR Creation)
+
+**Error:** `403 API rate limit exceeded`
+
+**Cause:** Too many GitHub API calls within rate limit window.
+
+**Solution:**
+- Wait 1 hour for rate limit reset
+- Authenticated requests have higher limits (5000/hour vs 60/hour)
+- Ensure GITHUB_TOKEN is configured correctly
+- Check rate limit status:
+  ```bash
+  curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit
+  ```
+
+---
+
+## Advanced Troubleshooting
+
+### Enable Debug Logging
+
+To get more detailed logs for debugging:
+
+```bash
+# Add to api/.env
+LOG_LEVEL=DEBUG
+
+# Restart backend
+docker-compose restart backend
+
+# View detailed logs
+docker-compose logs -f backend
+```
+
+### Check Agent Execution Metrics
+
+Metrics are displayed in the agent logs panel after workflow completion:
+
+```
+📊 Workflow Metrics Summary
+├─ Total Agents: 9
+├─ Successful: 9
+├─ Failed: 0
+├─ Total Duration: 155.59s
+├─ Total Tokens: 33,135
+│  ├─ Input: 30,728
+│  └─ Output: 2,407
+├─ Total Tool Calls: 23
+├─ Total LLM Calls: 31
+└─ Average TPS: 15.47 tokens/sec
+```
+
+**Analysis:**
+- **Failed agents**: Should be 0 for successful runs
+- **Total tokens**: Typical range 20K-40K for medium repositories
+- **Average TPS**: Depends on LLM backend performance
+- **Tool calls**: Indicates how many tool invocations agents made
+
+### Manual Repository Cleanup
+
+If cloned repositories aren't cleaned up automatically:
+
+```bash
+# Clean tmp directory
+rm -rf api/tmp/repos/*
+
+# Or within Docker:
+docker-compose exec backend rm -rf /app/tmp/repos/*
+```
+
+### Reset Application State
+
+To completely reset the application:
+
+```bash
+# Stop and remove containers
+docker-compose down -v
+
+# Remove temporary files
+rm -rf api/tmp/*
+
+# Rebuild and restart
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+---
+
+## Getting Help
+
+If you continue to experience issues:
+
+1. **Check Logs:** Review backend logs with `docker-compose logs backend -f`
+2. **Verify Configuration:** Ensure all required environment variables are set in `api/.env`
+3. **Test Connectivity:** Verify network access to GenAI Gateway and GitHub
+4. **Metrics Analysis:** Check workflow metrics for anomalies (token usage, duration, failed agents)
+5. **Report Issues:** If the problem persists, collect:
+   - Error messages from logs
+   - Workflow metrics summary
+   - Repository URL (if not sensitive)
+   - Configuration (redact sensitive values)
+
+---
+
+## Common Success Indicators
+
+A successful run should show:
+
+```
+✅ Repository cloned successfully
+✅ Overview & Features sections completed
+✅ Extracted X API endpoints
+✅ Architecture section completed
+✅ Troubleshooting section completed
+✅ Configuration section completed
+✅ Prerequisites & Deployment sections completed
+✅ Evidence aggregated: X Python deps, Y Node deps
+✅ Planner completed - Z sections planned
+✅ Mermaid Generator completed
+✅ QA Validator completed (Score: XX)
+✅ Documentation generation complete!
+📊 Workflow Metrics Summary
+```
+
+All agents should complete successfully with metrics showing reasonable token usage and no failed agents.
diff --git a/DocuGenMicroagents/api/.dockerignore b/DocuGenMicroagents/api/.dockerignore
new file mode 100644
index 0000000000..2c7d29581b
--- /dev/null
+++ b/DocuGenMicroagents/api/.dockerignore
@@ -0,0 +1,47 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+
+venv/
+env/
+ENV/
+.venv
+
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+
+tmp/
+*.log
+logs/
+
+.env
+.env.local
+.env.*.local
+
+.git/
+.gitignore
+
+README.md
+TROUBLESHOOTING.md
+*.md
+
+Dockerfile
+.dockerignore
+docker-compose.yml
+
+.DS_Store
+Thumbs.db
diff --git a/DocuGenMicroagents/api/.env.example b/DocuGenMicroagents/api/.env.example
new file mode 100644
index 0000000000..6172a67697
--- /dev/null
+++ b/DocuGenMicroagents/api/.env.example
@@ -0,0 +1,70 @@
+# ==========================================
+# Authentication Configuration
+# ==========================================
+# Auth mode: genai_gateway | keycloak
+AUTH_MODE=genai_gateway
+
+# GenAI Gateway Configuration
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your_genai_gateway_api_key_here
+
+# Keycloak Configuration (Enterprise Authentication)
+# Uncomment and configure if using AUTH_MODE=keycloak
+# BASE_URL=https://your-inference-endpoint.company.com
+# KEYCLOAK_REALM=master
+# KEYCLOAK_CLIENT_ID=api
+# KEYCLOAK_CLIENT_SECRET=your_client_secret_here
+
+# ==========================================
+# Micro-Agent Model Configuration
+# ==========================================
+# All agents use Qwen3-4B-Instruct (optimized SLM for code analysis)
+# You can customize individual agent models if needed
+
+CODE_EXPLORER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+API_REFERENCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+CALL_GRAPH_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ERROR_ANALYSIS_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ENV_CONFIG_MODEL=Qwen/Qwen3-4B-Instruct-2507
+DEPENDENCY_ANALYZER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+PLANNER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+MERMAID_MODEL=Qwen/Qwen3-4B-Instruct-2507
+QA_VALIDATOR_MODEL=Qwen/Qwen3-4B-Instruct-2507
+WRITER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+
+# ==========================================
+# Repository Analysis Limits
+# ==========================================
+# All limits are configurable to suit your needs
+TEMP_REPO_DIR=./tmp/repos
+MAX_REPO_SIZE=10737418240    # 10GB in bytes
+MAX_FILE_SIZE=1000000         # 1MB in bytes
+MAX_FILES_TO_SCAN=500         # Maximum number of files to analyze
+MAX_LINES_PER_FILE=500        # Line budget per file (pattern_window strategy extracts ~150-300 lines focusing on key patterns)
+
+# ==========================================
+# Agent Execution Settings
+# ==========================================
+AGENT_TEMPERATURE=0.7         # Model temperature (0.0-1.0)
+AGENT_MAX_TOKENS=1000         # Maximum tokens per agent response
+AGENT_TIMEOUT=300             # Agent timeout in seconds (5 minutes)
+
+# ==========================================
+# GitHub Integration (MCP)
+# ==========================================
+# Required for automatic PR creation
+# Generate token at: https://github.com/settings/tokens
+# Required scopes: repo (full access to repositories)
+GITHUB_TOKEN=your_github_personal_access_token_here
+
+# ==========================================
+# Server Configuration
+# ==========================================
+API_PORT=5001
+HOST=0.0.0.0
+
+# ==========================================
+# CORS Settings
+# ==========================================
+# Add your frontend URL if different from defaults
+CORS_ORIGINS=["http://localhost:3000", "http://localhost:3001", "http://localhost:5173"]
diff --git a/DocuGenMicroagents/api/Dockerfile b/DocuGenMicroagents/api/Dockerfile
new file mode 100644
index 0000000000..75c627d7c3
--- /dev/null
+++ b/DocuGenMicroagents/api/Dockerfile
@@ -0,0 +1,46 @@
+# Multi-stage build for DocuGen AI Backend
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies including git, curl, and Docker CLI for MCP
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    build-essential \
+    ca-certificates \
+    gnupg \
+    lsb-release \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends docker-ce-cli \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create temp directory for repo cloning
+RUN mkdir -p /app/tmp/repos
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Expose port
+EXPOSE 5001
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD curl -f http://localhost:5001/health || exit 1
+
+# Run the application
+# Disable reload to prevent server restart when cloning repos into tmp/
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "5001"]
diff --git a/DocuGenMicroagents/api/agents/__init__.py b/DocuGenMicroagents/api/agents/__init__.py
new file mode 100644
index 0000000000..f2db88afac
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/__init__.py
@@ -0,0 +1,35 @@
+"""
+LangChain Agents for DocuGen AI
+Each agent is autonomous with its own tools and reasoning capabilities
+"""
+
+# 10-agent simplified system (optimized for 8K context)
+from .code_explorer_agent import run_code_explorer_agent
+from .api_reference_agent import run_api_reference_agent
+from .call_graph_agent import run_call_graph_agent
+from .error_analysis_agent import run_error_analysis_agent
+from .env_config_agent import run_env_config_agent
+from .dependency_analyzer_agent import run_dependency_analyzer_agent
+from .planner_agent import run_planner_agent
+from .writer_agent_sectioned import run_writer_agent_sectioned
+from .mermaid_agent import run_mermaid_agent
+from .qa_validator_agent import run_qa_validator_agent
+
+# PR Agent for MCP
+from .pr_agent_mcp import create_pr_with_mcp
+
+__all__ = [
+    # Simplified micro-agents
+    "run_code_explorer_agent",
+    "run_api_reference_agent",
+    "run_call_graph_agent",
+    "run_error_analysis_agent",
+    "run_env_config_agent",
+    "run_dependency_analyzer_agent",
+    "run_planner_agent",
+    "run_writer_agent_sectioned",
+    "run_mermaid_agent",
+    "run_qa_validator_agent",
+    # MCP PR agent
+    "create_pr_with_mcp"
+]
diff --git a/DocuGenMicroagents/api/agents/api_reference_agent.py b/DocuGenMicroagents/api/agents/api_reference_agent.py
new file mode 100644
index 0000000000..9e5ce35c2b
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/api_reference_agent.py
@@ -0,0 +1,154 @@
+"""
+API Reference Agent - SIMPLIFIED for 8K context models
+
+Extracts API endpoints, HTTP methods, parameters, and response models from FastAPI/Flask codebases.
+
+Follows CodeExplorer proven pattern:
+- ≤3 tools (minimal schema overhead)
+- pattern_window strategy by default (detects @app.get, @router.post)
+- Minimal prompt (~200 tokens)
+- No inline metrics
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# Data Extraction Prompt - outputs JSON data for Mermaid agent, NOT markdown sections
+API_REFERENCE_PROMPT = """You are the API Endpoint Data Extractor. Extract API endpoint information for diagram generation.
+
+**YOUR JOB:**
+Use tools to find actual API endpoints and extract their data. DO NOT write markdown sections.
+
+**TOOLS:**
+- find_entry_points() - find main server files (server.py, main.py, app.py)
+- read_file(file_path) - read files (detects @app.get, @router.post, @app.route)
+- list_directory(relative_path) - list files
+
+**WORKFLOW:**
+1. find_entry_points() to locate server files
+2. read_file() on server files to find route decorators
+3. Extract: HTTP method, path, description from code
+
+**CRITICAL RULES:**
+1. ONLY extract endpoints you actually find in code
+2. DO NOT write markdown sections - only return structured data
+3. DO NOT invent example endpoints
+4. Use actual paths/methods from code
+
+**OUTPUT FORMAT (JSON data structure):**
+```json
+{
+  "endpoints": [
+    {
+      "method": "GET",
+      "path": "/",
+      "description": "Health check endpoint"
+    },
+    {
+      "method": "POST",
+      "path": "/upload",
+      "description": "Upload file for processing"
+    }
+  ],
+  "endpoint_count": 2
+}
+```
+
+If NO endpoints found:
+```json
+{
+  "endpoints": [],
+  "endpoint_count": 0
+}
+```
+
+Return ONLY the JSON object, nothing else. No markdown, no explanations.
+
+**Limit:** 20 tool calls."""
+
+
+async def run_api_reference_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Simplified API Reference Agent - minimal context usage
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 tools only)
+        @tool
+        def list_directory(relative_path: str = ".") -> str:
+            """List directory. Args: relative_path (str)"""
+            from tools.repo_tools import list_directory_tool
+            return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read file with strategic sampling. Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use pattern_window strategy to detect FastAPI routes (@app.get, @router.post)
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="pattern_window")
+
+        @tool
+        def find_entry_points() -> str:
+            """Find main entry point files (main.py, server.py, app.py). No args."""
+            from tools.repo_tools import find_entry_points_tool
+            return find_entry_points_tool.func(repo_path=repo_path)
+
+        tools = [list_directory, read_file, find_entry_points]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="APIReference")
+
+        # Execute with callback
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", API_REFERENCE_PROMPT),
+                ("user", "Extract API endpoint data as JSON. Start with find_entry_points().")
+            ]},
+            config={
+                "recursion_limit": 20,
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output
+        messages = result.get("messages", [])
+        final_output = messages[-1].content if messages else ""
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "APIReference",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"APIReference failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "APIReference"
+        }
diff --git a/DocuGenMicroagents/api/agents/call_graph_agent.py b/DocuGenMicroagents/api/agents/call_graph_agent.py
new file mode 100644
index 0000000000..3fb9589cc5
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/call_graph_agent.py
@@ -0,0 +1,158 @@
+"""
+Call Graph Agent - Architecture Section Writer
+
+Writes the complete "## Architecture" section for README.
+
+Section writer pattern:
+- ≤3 tools
+- smart strategy (extracts function signatures, not full bodies)
+- Outputs complete markdown section
+- Also outputs structured call_graph data for Mermaid agent
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# Section Writer Prompt - outputs complete "## Architecture" section with explanation
+CALL_GRAPH_PROMPT = """You are the Architecture Section Writer. Write the complete "## Architecture" README section with clear explanation.
+
+**YOUR JOB:**
+Use tools to analyze code structure and function relationships, then write a clear Architecture section explaining how components work together.
+
+**TOOLS:**
+- list_directory(relative_path) - list files
+- read_file(file_path) - read file (uses smart strategy for signatures)
+- analyze_code_structure(file_path) - get function/class list from Python files
+
+**WORKFLOW:**
+1. list_directory() to find main code files
+2. analyze_code_structure() to get quick overview of key files
+3. read_file() on important files to understand flow
+4. Identify: components, layers, data flow, key modules
+5. Write the section with explanation + note about diagram
+
+**CRITICAL RULES:**
+1. ONLY describe architecture you can see in the code
+2. Start with 2-3 sentences explaining the overall architecture
+3. Describe how components interact and data flows
+4. Add note: "The architecture diagram below visualizes component relationships and data flow."
+5. If minimal code found → output: "## Architecture\n\nMinimal codebase. Refer to source files for structure."
+6. DO NOT invent components or layers not found in code
+
+**OUTPUT FORMAT (complete markdown section):**
+```
+## Architecture
+
+[2-3 sentences explaining the overall architecture pattern, e.g., "The application follows a client-server architecture with a FastAPI backend and React frontend. The backend handles data processing and API endpoints, while the frontend provides the user interface. Data flows from user input through the API to backend services and back to the UI."]
+
+### Components
+
+**[Component Name]** (`path/to/file.py`)
+- Purpose: [What it does based on code]
+- Key functions: [Actual functions found]
+
+**[Another Component]** (`path/to/file.py`)
+- Purpose: [What it does based on code]
+- Key functions: [Actual functions found]
+
+### Data Flow
+
+1. User → [Entry point] receives [input]
+2. [Entry point] → [Module/Service] processes data
+3. [Service] → [Database/API] stores/retrieves information
+4. Response flows back through the stack to user
+
+The architecture diagram below visualizes these component relationships and data flow.
+```
+
+Start your output with "## Architecture" heading. Include the diagram note at the end.
+
+**Limit:** 25 tool calls."""
+
+
+async def run_call_graph_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Simplified Call Graph Agent
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 tools only)
+        @tool
+        def list_directory(relative_path: str = ".") -> str:
+            """List directory. Args: relative_path (str)"""
+            from tools.repo_tools import list_directory_tool
+            return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read file with smart sampling (signatures only). Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use smart strategy: top + signatures + bottom (good for call graph)
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="smart")
+
+        @tool
+        def analyze_code_structure(file_path: str) -> str:
+            """Analyze Python file structure (functions, classes). Args: file_path (str)"""
+            from tools.repo_tools import analyze_code_structure_tool
+            return analyze_code_structure_tool.func(repo_path=repo_path, file_path=file_path)
+
+        tools = [list_directory, read_file, analyze_code_structure]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="CallGraph")
+
+
+        # Execute
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", CALL_GRAPH_PROMPT),
+                ("user", "Write the Architecture section. Start with list_directory().")
+            ]},
+            config={
+                "recursion_limit": 40,
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output
+        messages = result.get("messages", [])
+        final_output = messages[-1].content if messages else ""
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "CallGraph",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"CallGraph failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "CallGraph"
+        }
diff --git a/DocuGenMicroagents/api/agents/code_explorer_agent.py b/DocuGenMicroagents/api/agents/code_explorer_agent.py
new file mode 100644
index 0000000000..c86ceda044
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/code_explorer_agent.py
@@ -0,0 +1,194 @@
+"""
+Code Explorer Agent - Overview & Features Section Writer
+
+Writes the complete "## Project Overview" and "## Features" sections for README.
+
+Section writer pattern:
+- ≤3 tools
+- pattern_window strategy for quick file analysis
+- Outputs TWO complete markdown sections
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# Section Writer Prompt - outputs THREE complete sections
+EXPLORER_PROMPT = """You are the Overview, Features & User Interface Section Writer. Write THREE complete README sections.
+
+**YOUR JOB:**
+Use tools to understand the project structure and purpose, then write Project Overview, Features, and User Interface sections.
+
+**TOOLS:**
+- list_directory(relative_path) - list files in directories
+- read_file(file_path) - read file with pattern detection
+- detect_languages() - get programming languages used
+
+**WORKFLOW:**
+1. list_directory('.') to see project structure
+2. detect_languages() to understand tech stack
+3. read_file() on key files (README.md if exists, main files) to understand purpose
+4. Identify user-facing capabilities (not technical implementation)
+5. Check for frontend directories (ui/, frontend/, client/, web/, src/)
+6. Write ALL THREE sections
+
+**CRITICAL RULES - Project Overview:**
+1. 1-3 sentences ONLY
+2. Explain WHAT the project does and WHY it exists
+3. NO tech stack lists, NO "Repository Information", NO "Primary Language"
+4. Focus on user value, not implementation details
+
+**CRITICAL RULES - Features:**
+1. ONLY list user-facing capabilities you can confirm from code
+2. NO API endpoints (POST /, GET /), NO routes, NO technical implementation
+3. Features = what users CAN DO, not how it's built
+4. Group by Backend/Frontend if applicable
+5. If minimal code → output: "Basic [project type] structure."
+
+**CRITICAL RULES - User Interface:**
+1. ONLY write if frontend directory exists (ui/, frontend/, client/, web/)
+2. Describe frontend technology used (React, Vue, Angular, vanilla JS)
+3. Key UI components or pages found
+4. User workflow/experience
+5. If NO frontend found → output: "No dedicated user interface. This is a backend/API project."
+
+**OUTPUT FORMAT (THREE complete markdown sections):**
+```
+## Project Overview
+
+[1-3 sentences describing what this project does and why it's useful]
+
+## Features
+
+**Backend:**
+- Feature 1: [Backend capability based on code found]
+- Feature 2: [Another backend capability]
+
+**Frontend:**
+- Feature 3: [User interface capability]
+- Feature 4: [Another UI capability]
+
+## User Interface
+
+The frontend is built with [React/Vue/Angular/etc.] providing [description of UI].
+
+Key interface elements:
+- [Component/page 1] - [Purpose]
+- [Component/page 2] - [Purpose]
+
+User workflow:
+1. [Step 1 in user journey]
+2. [Step 2 in user journey]
+```
+
+If NO frontend found:
+```
+## User Interface
+
+No dedicated user interface. This is a backend/API project. Interact with the application through API endpoints or CLI commands.
+```
+
+If minimal/empty repo:
+```
+## Project Overview
+
+Minimal repository with basic project structure.
+
+## Features
+
+Basic project scaffolding. Refer to source files for details.
+
+## User Interface
+
+No user interface implemented yet.
+```
+
+Start with "## Project Overview", then "## Features", then "## User Interface".
+
+**Limit:** 25 tool calls."""
+
+
+async def run_code_explorer_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Simplified Code Explorer - minimal context usage
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 tools only)
+        @tool
+        def list_directory(relative_path: str = ".") -> str:
+            """List directory. Args: relative_path (str)"""
+            from tools.repo_tools import list_directory_tool
+            return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read file with strategic sampling. Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use pattern_window strategy to detect FastAPI routes, error handlers, etc.
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="pattern_window")
+
+        @tool
+        def detect_languages() -> str:
+            """Detect languages. No args."""
+            from tools.repo_tools import detect_languages_tool
+            return detect_languages_tool.func(repo_path=repo_path)
+
+        tools = [list_directory, read_file, detect_languages]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger for ReAct visibility
+        event_logger = create_agent_logger(job_id=job_id, agent_name="CodeExplorer")
+
+        # Execute with callback
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", EXPLORER_PROMPT),
+                ("user", "Write the Project Overview, Features, and User Interface sections. Start with list_directory(relative_path='.').")
+            ]},
+            config={
+                "recursion_limit": 25,
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output
+        messages = result.get("messages", [])
+        final_output = messages[-1].content if messages else ""
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "CodeExplorer",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"CodeExplorer failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "CodeExplorer"
+        }
diff --git a/DocuGenMicroagents/api/agents/dependency_analyzer_agent.py b/DocuGenMicroagents/api/agents/dependency_analyzer_agent.py
new file mode 100644
index 0000000000..3a23523836
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/dependency_analyzer_agent.py
@@ -0,0 +1,181 @@
+"""
+Dependency Analyzer Agent - Prerequisites & Deployment Section Writer
+
+Writes the complete "## Prerequisites" and "## Quick Start Deployment" sections for README.
+
+Section writer pattern:
+- ≤3 tools
+- full strategy for package files (they're small)
+- Outputs TWO complete markdown sections
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+
+def _get_final_assistant_text(messages) -> str:
+    """
+    Extract the last non-empty AIMessage content from LangGraph result.
+
+    FIX: messages[-1] is not guaranteed to be the final assistant answer.
+    """
+    for m in reversed(messages or []):
+        if isinstance(m, AIMessage) and isinstance(getattr(m, "content", None), str):
+            txt = m.content.strip()
+            if txt:
+                return txt
+    return (messages[-1].content or "").strip() if messages else ""
+
+# SIMPLIFIED Prompt for SLMs - NO templates, just instructions
+def _build_dependency_prompt(repo_url: str) -> str:
+    """Build prompt with actual repository URL"""
+    return f"""You write Prerequisites and Deployment sections for README files.
+
+**REPOSITORY URL:** {repo_url}
+
+**YOUR TASK:**
+1. First, call extract_dependencies() and list_directory(".") to see what's in the repo
+2. Based on what you find, write TWO sections
+
+**SECTION 1: ## Prerequisites**
+- List what needs to be installed (Python, Node.js, Docker)
+- Only list if you found the files (requirements.txt = Python, package.json = Node, docker-compose.yml = Docker)
+- Keep it short
+
+**SECTION 2: ## Quick Start Deployment**
+This section has TWO subsections (use ### for subsections!):
+
+**Subsection A: ### Installation**
+- Show how to clone the repository using the ACTUAL URL above
+- Tell how to install dependencies you found
+- Use actual paths (if found api/requirements.txt, write "cd api && pip install -r requirements.txt")
+
+**Subsection B: ### Running the Application**
+- If docker-compose.yml exists, show docker command
+- Otherwise, show how to run the entry point you find (server.py, app.py, main.py, etc.)
+
+**CRITICAL FORMATTING:**
+- Main sections use ## (two hashtags)
+- Subsections use ### (three hashtags)
+- Installation and Running are SUBSECTIONS (use ###, NOT ##)
+- Use the ACTUAL repository URL provided above, not placeholders
+
+**EXAMPLE STRUCTURE (not the content, just the heading pattern):**
+## Prerequisites
+...content...
+
+## Quick Start Deployment
+### Installation
+Clone the repository:
+```bash
+git clone {repo_url}
+cd repo-name
+```
+...other steps...
+### Running the Application
+...commands...
+
+Now analyze the repo and write these sections."""
+
+
+async def run_dependency_analyzer_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str,
+    repo_url: str = None
+) -> Dict[str, Any]:
+    """
+    Simplified Dependency Analyzer Agent
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+        repo_url: Repository URL (for clone instructions)
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Use placeholder if repo_url not provided
+        if not repo_url:
+            repo_url = "https://github.com/yourusername/your-repo.git"
+
+        # Create tool set with project structure analysis capabilities
+        @tool
+        def list_directory(relative_path: str = ".") -> str:
+            """List files and folders in a directory. Args: relative_path (str)"""
+            from tools.repo_tools import list_directory_tool
+            return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+        @tool
+        def find_dependency_files() -> str:
+            """Find dependency files (requirements.txt, package.json, etc.). No args."""
+            from tools.repo_tools import find_dependency_files_tool
+            return find_dependency_files_tool.func(repo_path=repo_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read file with full content. Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use full strategy: package files are small
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="full")
+
+        @tool
+        def extract_dependencies() -> str:
+            """Extract all dependencies from common package files. No args."""
+            from tools.repo_tools import extract_dependencies_tool
+            return extract_dependencies_tool.func(repo_path=repo_path)
+
+        tools = [list_directory, find_dependency_files, read_file, extract_dependencies]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="DependencyAnalyzer")
+
+        # Build prompt with actual repo URL
+        prompt = _build_dependency_prompt(repo_url)
+
+        # Execute with simplified user message
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", prompt),
+                ("user", "Write the sections. Start: call extract_dependencies()")
+            ]},
+            config={
+                "recursion_limit": 12,  # Reduced for SLMs: 2-3 tools + reasoning + output
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output - FIX: Use helper to get last AIMessage
+        messages = result.get("messages", [])
+        final_output = _get_final_assistant_text(messages)
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "DependencyAnalyzer",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"DependencyAnalyzer failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "DependencyAnalyzer"
+        }
diff --git a/DocuGenMicroagents/api/agents/env_config_agent.py b/DocuGenMicroagents/api/agents/env_config_agent.py
new file mode 100644
index 0000000000..f90551fa1d
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/env_config_agent.py
@@ -0,0 +1,150 @@
+"""
+Environment Config Agent - Configuration Section Writer
+
+Writes the complete "## Configuration" section for README.
+
+Section writer pattern:
+- ≤3 tools
+- full strategy (config files are small)
+- Outputs complete markdown section
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+
+def _get_final_assistant_text(messages) -> str:
+    """
+    Extract the last non-empty AIMessage content from LangGraph result.
+
+    FIX: messages[-1] is not guaranteed to be the final assistant answer.
+    """
+    for m in reversed(messages or []):
+        if isinstance(m, AIMessage) and isinstance(getattr(m, "content", None), str):
+            txt = m.content.strip()
+            if txt:
+                return txt
+    return (messages[-1].content or "").strip() if messages else ""
+
+# SIMPLIFIED for SLMs - No templates
+ENV_CONFIG_PROMPT = """You write Configuration sections for README files.
+
+**YOUR TASK:**
+1. Call find_config_files() to find .env or config files
+2. If found, call read_file() on the config file to see variable names
+3. Write "## Configuration" section documenting the variables
+
+**WHAT TO WRITE:**
+- Start with heading: ## Configuration
+- If you found config files, list the environment variables
+- Group variables by category (Database, API, Server, etc.)
+- Use actual variable names from the files
+- Use placeholder values like <value> or your_key_here
+- If NO config files found, write: "## Configuration\n\nNo environment configuration files found."
+
+**HEADING FORMAT:**
+- Use ## for main section: ## Configuration
+- Use ### for subsection: ### Environment Variables
+
+**STRUCTURE EXAMPLE:**
+## Configuration
+### Environment Variables
+Create a .env file:
+```bash
+DATABASE_URL=<value>
+API_KEY=<value>
+```
+**Required:**
+- DATABASE_URL - Database connection
+- API_KEY - API authentication
+
+Only document variables you actually find. Keep it simple."""
+
+
+async def run_env_config_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Simplified Env Config Agent
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 tools only)
+        @tool
+        def list_directory(relative_path: str = ".") -> str:
+            """List directory. Args: relative_path (str)"""
+            from tools.repo_tools import list_directory_tool
+            return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read config file. Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use full strategy: config files are small, read everything
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="full")
+
+        @tool
+        def find_config_files() -> str:
+            """Find configuration files (.env, config files). No args."""
+            from tools.repo_tools import find_config_files_tool
+            return find_config_files_tool.func(repo_path=repo_path)
+
+        tools = [list_directory, read_file, find_config_files]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="EnvConfig")
+
+
+        # Execute with simplified message
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", ENV_CONFIG_PROMPT),
+                ("user", "Write the Configuration section. Call find_config_files()")
+            ]},
+            config={
+                "recursion_limit": 8,
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output - FIX: Use helper to get last AIMessage
+        messages = result.get("messages", [])
+        final_output = _get_final_assistant_text(messages)
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "EnvConfig",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"EnvConfig failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "EnvConfig"
+        }
diff --git a/DocuGenMicroagents/api/agents/error_analysis_agent.py b/DocuGenMicroagents/api/agents/error_analysis_agent.py
new file mode 100644
index 0000000000..ae75e66f8a
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/error_analysis_agent.py
@@ -0,0 +1,136 @@
+"""
+Error Analysis Agent - Troubleshooting Section Writer
+
+Writes the complete "## Troubleshooting" section for README.
+
+Section writer pattern:
+- ≤3 tools
+- pattern_window strategy (detects try:, except, raise)
+- Outputs complete markdown section
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# SIMPLIFIED for SLMs - Generic troubleshooting
+ERROR_ANALYSIS_PROMPT = """You write Troubleshooting sections for README files.
+
+**YOUR TASK:**
+1. Optionally call list_directory(".") to see project type
+2. Write "## Troubleshooting" section with GENERIC advice for common problems
+
+**WHAT TO WRITE:**
+Write general troubleshooting guidance for these categories:
+- Dependency Issues
+- Environment Variables
+- Server Errors
+- (File/Upload Errors if project handles files)
+
+**HEADING FORMAT:**
+- Main: ## Troubleshooting
+- Subsections: ### Dependency Issues, ### Environment Variables, etc.
+
+**RULES:**
+- Write GENERIC advice (not specific exception names)
+- Keep it user-friendly and practical
+- Include basic commands
+- Mention checking logs
+
+**STRUCTURE EXAMPLE:**
+## Troubleshooting
+### Dependency Issues
+...advice...
+### Environment Variables
+...advice...
+### Server Errors
+...advice...
+
+Do NOT copy this template. Write your own content based on project type."""
+
+
+async def run_error_analysis_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Simplified Error Analysis Agent
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 tools only)
+        @tool
+        def list_directory(relative_path: str = ".") -> str:
+            """List directory. Args: relative_path (str)"""
+            from tools.repo_tools import list_directory_tool
+            return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read file with pattern matching (finds try/except/raise). Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use pattern_window: detects try:, except, raise patterns
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="pattern_window")
+
+        @tool
+        def find_error_handlers() -> str:
+            """Find all try/except blocks across Python files. No args."""
+            from tools.new_analysis_tools import find_error_handlers_tool
+            return find_error_handlers_tool.func(repo_path=repo_path)
+
+        tools = [list_directory, read_file, find_error_handlers]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="ErrorAnalysis")
+
+
+        # Execute with simplified message
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", ERROR_ANALYSIS_PROMPT),
+                ("user", "Write the Troubleshooting section with generic advice.")
+            ]},
+            config={
+                "recursion_limit": 10,  # Reduced for SLMs
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output
+        messages = result.get("messages", [])
+        final_output = messages[-1].content if messages else ""
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "ErrorAnalysis",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"ErrorAnalysis failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "ErrorAnalysis"
+        }
diff --git a/DocuGenMicroagents/api/agents/mermaid_agent.py b/DocuGenMicroagents/api/agents/mermaid_agent.py
new file mode 100644
index 0000000000..de35d8e7e1
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/mermaid_agent.py
@@ -0,0 +1,151 @@
+"""
+Mermaid Diagram Agent - SIMPLIFIED for 8K context models
+
+Generates Mermaid diagrams for architecture visualization.
+
+Follows proven pattern:
+- ≤3 tools
+- Includes validate_mermaid_syntax for self-correction
+- Minimal prompt
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# MINIMAL system prompt
+MERMAID_PROMPT = """You are a Mermaid Diagram Generator. Create architecture diagrams.
+
+**Output:** 1-2 Mermaid diagrams:
+1. System Architecture (components and connections)
+2. Optional: Data Flow or Sequence Diagram
+
+**Tools:**
+- find_entry_points() - find main files
+- read_file(path) - read file (smart strategy for structure)
+- validate_mermaid_syntax(code) - validate diagram
+
+**Mermaid Rules (CRITICAL):**
+- Node IDs: alphanumeric + underscore only (no spaces, slashes)
+- Node labels: use quotes for multi-word: NodeID["Label Text"]
+- Edge labels: avoid special chars (/, :, `, ")
+- Start with: graph TD or flowchart TD
+
+**Example:**
+```mermaid
+graph TD
+    User["User"]
+    API["API Server"]
+    DB["Database"]
+    User -->|Request| API
+    API -->|Query| DB
+```
+
+**Process:**
+1. Find entry points
+2. Read key files
+3. Generate diagram
+4. VALIDATE with validate_mermaid_syntax()
+5. Fix errors if validation fails
+
+**Limit:** 12 tool calls."""
+
+
+async def run_mermaid_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str,
+    api_endpoints: list = None
+) -> Dict[str, Any]:
+    """
+    Simplified Mermaid Agent
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+        api_endpoints: Optional list of API endpoints extracted by API Reference agent
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 tools)
+        @tool
+        def find_entry_points() -> str:
+            """Find main entry point files. No args."""
+            from tools.repo_tools import find_entry_points_tool
+            return find_entry_points_tool.func(repo_path=repo_path)
+
+        @tool
+        def read_file(file_path: str) -> str:
+            """Read file with smart sampling. Args: file_path (str)"""
+            from tools.repo_tools import read_file_tool
+            # Use smart strategy: signatures only (good for architecture)
+            return read_file_tool.func(repo_path=repo_path, file_path=file_path, strategy="smart")
+
+        @tool
+        def validate_mermaid_syntax(mermaid_code: str) -> str:
+            """Validate Mermaid diagram syntax. Args: mermaid_code (str)"""
+            from tools.repo_tools import validate_mermaid_syntax_tool
+            return validate_mermaid_syntax_tool.func(mermaid_code=mermaid_code)
+
+        tools = [find_entry_points, read_file, validate_mermaid_syntax]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="Mermaid")
+
+
+        # Build user message with optional API endpoints
+        user_message = "Generate Mermaid architecture diagram. Start with find_entry_points()."
+
+        if api_endpoints and len(api_endpoints) > 0:
+            user_message += f"\n\nAPI Endpoints available (include these in diagram if relevant):\n"
+            for ep in api_endpoints[:10]:  # Limit to 10 to avoid context overflow
+                method = ep.get("method", "GET")
+                path = ep.get("path", "/")
+                desc = ep.get("description", "")
+                user_message += f"- {method} {path}: {desc}\n"
+
+        # Execute
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", MERMAID_PROMPT),
+                ("user", user_message)
+            ]},
+            config={
+                "recursion_limit": 15,
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output
+        messages = result.get("messages", [])
+        final_output = messages[-1].content if messages else ""
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "Mermaid",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"Mermaid failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "Mermaid"
+        }
diff --git a/DocuGenMicroagents/api/agents/planner_agent.py b/DocuGenMicroagents/api/agents/planner_agent.py
new file mode 100644
index 0000000000..f85475a718
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/planner_agent.py
@@ -0,0 +1,151 @@
+"""
+Planner Agent - SIMPLIFIED for 8K context models
+
+Analyzes project type and plans documentation sections.
+
+Follows proven pattern:
+- ≤3 tools
+- full strategy for package files (they're small)
+- Minimal prompt
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# MINIMAL system prompt - MATCHES DOCUGEN TEMPLATE
+PLANNER_PROMPT = """You are a Documentation Planner. Determine project type and plan sections.
+
+**Task:** Analyze project and output recommended README sections.
+
+**Tools:**
+- detect_languages() - get language breakdown
+- extract_dependencies() - get dependencies
+- find_ui_files() - check for frontend
+
+**SECTION TEMPLATE (from DocuGen):**
+Always include base sections: "Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "Troubleshooting"
+Add conditionally:
+- "User Interface" - if find_ui_files() returns has_ui=true
+- "Configuration" - if project has .env or config files
+
+**Output:** JSON with:
+```json
+{
+  "project_type": "fastapi-backend" (or "web app", "CLI tool", etc.),
+  "sections": ["Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "User Interface", "Configuration", "Troubleshooting"]
+}
+```
+
+**Limit:** 8 tool calls."""
+
+
+async def run_planner_agent(
+    llm: BaseChatModel,
+    repo_path: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Simplified Planner Agent
+
+    Args:
+        llm: Language model
+        repo_path: Repository path
+        job_id: Job ID
+
+    Returns:
+        Results dict with success flag and output
+    """
+    try:
+        # Create minimal tool set (3 core tools + 2 optional)
+        @tool
+        def detect_languages() -> str:
+            """Detect programming languages. No args."""
+            from tools.repo_tools import detect_languages_tool
+            return detect_languages_tool.func(repo_path=repo_path)
+
+        @tool
+        def extract_dependencies() -> str:
+            """Extract dependencies from package files. No args."""
+            from tools.repo_tools import extract_dependencies_tool
+            return extract_dependencies_tool.func(repo_path=repo_path)
+
+        @tool
+        def find_ui_files() -> str:
+            """Check if project has UI/frontend. No args."""
+            from tools.repo_tools import find_ui_files_tool
+            return find_ui_files_tool.func(repo_path=repo_path)
+
+        tools = [detect_languages, extract_dependencies, find_ui_files]
+
+        # Create agent
+        agent = create_react_agent(model=llm, tools=tools)
+
+        # Create callback logger
+        event_logger = create_agent_logger(job_id=job_id, agent_name="Planner")
+
+
+        # Execute
+        result = await agent.ainvoke(
+            {"messages": [
+                ("system", PLANNER_PROMPT),
+                ("user", "Analyze project type and plan README sections using DocuGen template. Start with detect_languages().")
+            ]},
+            config={
+                "recursion_limit": 8,
+                "callbacks": [event_logger]
+            }
+        )
+
+        # Extract output
+        messages = result.get("messages", [])
+        final_output = messages[-1].content if messages else ""
+
+        # Parse and validate output has correct section names
+        import json
+        try:
+            # Try to extract JSON
+            content = final_output.strip()
+            if '```json' in content:
+                content = content.split('```json')[1].split('```')[0]
+            elif '```' in content:
+                content = content.split('```')[1].split('```')[0]
+
+            plan = json.loads(content.strip())
+
+            # Ensure sections match DocuGen template
+            if "sections" not in plan or not plan["sections"]:
+                plan["sections"] = ["Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "Troubleshooting"]
+
+            final_output = json.dumps(plan, indent=2)
+        except:
+            # Fallback to default DocuGen sections
+            plan = {
+                "project_type": "Unknown",
+                "sections": ["Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "Troubleshooting"]
+            }
+            final_output = json.dumps(plan, indent=2)
+
+        # Extract metrics from messages
+        metrics = extract_agent_metrics(messages)
+
+        return {
+            "success": True,
+            "output": final_output,
+            "agent": "Planner",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"Planner failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "Planner"
+        }
diff --git a/DocuGenMicroagents/api/agents/pr_agent_mcp.py b/DocuGenMicroagents/api/agents/pr_agent_mcp.py
new file mode 100644
index 0000000000..5f868b3005
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/pr_agent_mcp.py
@@ -0,0 +1,386 @@
+"""
+PR Agent with TRUE MCP Integration
+Uses official GitHub MCP server via MCP protocol (not direct API calls)
+With full ReAct-style logging (Thought → Action → Observation)
+"""
+
+import logging
+import re
+import json
+from typing import Dict, Any
+from datetime import datetime
+
+from models import get_log_manager, LogType
+from mcp_client import get_github_mcp_client
+
+logger = logging.getLogger(__name__)
+
+
+async def create_pr_with_mcp(
+    repo_full_name: str,
+    readme_content: str,
+    project_name: str,
+    base_branch: str,
+    github_token: str,
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Create GitHub PR using TRUE MCP protocol with ReAct logging
+
+    This function:
+    1. Connects to GitHub MCP server (Docker)
+    2. Discovers available tools via MCP
+    3. Calls tools to create branch, commit, and PR
+    4. Uses stdio protocol (not direct API)
+    5. Logs full ReAct cycle (Thought → Action → Observation)
+
+    Args:
+        repo_full_name: Repository "owner/repo"
+        readme_content: Generated README content
+        project_name: Project name for PR title
+        base_branch: Base branch to create PR against (e.g., "main" or "dev")
+        github_token: GitHub Personal Access Token
+        job_id: Job ID for logging
+
+    Returns:
+        Dict with success status, PR URL, and details
+    """
+    log_manager = get_log_manager()
+
+    try:
+        # Log start
+        await log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.AGENT_START,
+            message="PR Agent initialized with MCP protocol",
+            agent_name="PR Agent (MCP)"
+        )
+
+        # 💭 Thought: Planning to connect
+        await log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.AGENT_THINKING,
+            message=f"💭 Thought: I need to connect to GitHub MCP server for {repo_full_name}",
+            agent_name="PR Agent (MCP)"
+        )
+
+        # Get MCP client
+        mcp_client = get_github_mcp_client(github_token)
+
+        # Connect to GitHub MCP server (Docker container via stdio)
+        async with mcp_client.connect() as session:
+            # 💭 Thought: Discovering tools
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_THINKING,
+                message="💭 Thought: Connected to MCP server. I need to discover available GitHub tools",
+                agent_name="PR Agent (MCP)"
+            )
+
+            # List available tools
+            tools = await mcp_client.list_available_tools()
+            logger.info(f"Available MCP tools: {tools}")
+
+            # 📊 Observation: Tools discovered
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_OBSERVATION,
+                message=f"📊 Observation: Found {len(tools)} GitHub MCP tools including: {', '.join(tools[:5])}...",
+                agent_name="PR Agent (MCP)",
+                metadata={"tools_count": len(tools), "tools": tools}
+            )
+
+            # Generate unique branch name with project name
+            timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+            # Create slug from project name (lowercase, replace spaces/special chars with hyphens)
+            project_slug = re.sub(r'[^a-z0-9]+', '-', project_name.lower()).strip('-')
+            branch_name = f"docs/{project_slug}-readme-{timestamp}"
+
+            # Parse repo owner and name
+            owner, repo = repo_full_name.split("/")
+
+            # Extract actual project name from README title (H1 or H2)
+            readme_title = project_name  # fallback to provided name
+            lines = readme_content.split('\n')
+            for line in lines[:15]:  # Check first 15 lines for title
+                # Look for H1 (# Title) or H2 (## Title)
+                if line.startswith('# ') and not line.startswith('## '):
+                    readme_title = line[2:].strip()
+                    break
+                elif line.startswith('## '):
+                    # H2 title found - extract it
+                    readme_title = line[3:].strip()
+                    break
+
+            # === STEP 1: Create Branch ===
+
+            # 💭 Thought: Need to create branch
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_THINKING,
+                message=f"💭 Thought: I need to create a new branch '{branch_name}' from {base_branch}",
+                agent_name="PR Agent (MCP)"
+            )
+
+            # 🔧 Action: Create branch
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_ACTION,
+                message=f"🔧 Action: create_branch(owner={owner}, repo={repo}, branch={branch_name}, from_branch={base_branch})",
+                agent_name="PR Agent (MCP)",
+                metadata={"tool": "create_branch", "params": {"owner": owner, "repo": repo, "branch": branch_name, "from_branch": base_branch}}
+            )
+
+            try:
+                branch_result = await mcp_client.call_tool(
+                    "create_branch",
+                    {
+                        "owner": owner,
+                        "repo": repo,
+                        "branch": branch_name,
+                        "from_branch": base_branch
+                    }
+                )
+                logger.info(f"Branch creation result: {branch_result}")
+
+                # 📊 Observation: Branch created
+                await log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.AGENT_OBSERVATION,
+                    message=f"📊 Observation: Branch '{branch_name}' created successfully from {base_branch}",
+                    agent_name="PR Agent (MCP)",
+                    metadata={"branch_created": True, "branch_name": branch_name}
+                )
+            except Exception as e:
+                logger.warning(f"Branch creation via MCP failed: {e}")
+                # 📊 Observation: Branch might exist
+                await log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.AGENT_OBSERVATION,
+                    message=f"📊 Observation: Branch creation failed ({str(e)}). Branch may already exist - continuing anyway",
+                    agent_name="PR Agent (MCP)",
+                    metadata={"branch_created": False, "error": str(e)}
+                )
+
+            # === STEP 2: Commit README.md using push_files (FOOLPROOF - No SHA needed) ===
+
+            # 💭 Thought: Need to commit README
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_THINKING,
+                message=f"💭 Thought: I need to commit README.md to branch '{branch_name}' using push_files (no SHA required)",
+                agent_name="PR Agent (MCP)"
+            )
+
+            # Use push_files tool (more reliable, no SHA needed)
+            push_params = {
+                "owner": owner,
+                "repo": repo,
+                "branch": branch_name,
+                "files": [
+                    {
+                        "path": "README.md",
+                        "content": readme_content
+                    }
+                ],
+                "message": f"docs: Updated README for {readme_title}"
+            }
+
+            logger.info(f"Using push_files to commit README.md to branch '{branch_name}'")
+
+            # 🔧 Action: Commit file using push_files
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_ACTION,
+                message=f"🔧 Action: push_files(owner={owner}, repo={repo}, branch={branch_name}, files=[README.md])",
+                agent_name="PR Agent (MCP)",
+                metadata={"tool": "push_files", "params": push_params, "content_length": len(readme_content)}
+            )
+
+            commit_success = False
+            try:
+                commit_result = await mcp_client.call_tool(
+                    "push_files",
+                    push_params
+                )
+                logger.info(f"Commit result: {commit_result}")
+
+                # Check if commit was successful
+                if commit_result and not (hasattr(commit_result, 'isError') and commit_result.isError):
+                    commit_success = True
+                    # 📊 Observation: File committed
+                    await log_manager.log_async(
+                        job_id=job_id,
+                        log_type=LogType.AGENT_OBSERVATION,
+                        message=f"📊 Observation: README.md committed successfully to branch '{branch_name}'",
+                        agent_name="PR Agent (MCP)",
+                        metadata={"file_committed": True}
+                    )
+                else:
+                    error_text = str(commit_result.content[0].text if hasattr(commit_result, 'content') else commit_result)
+                    logger.error(f"File commit returned error: {error_text}")
+                    await log_manager.log_async(
+                        job_id=job_id,
+                        log_type=LogType.AGENT_OBSERVATION,
+                        message=f"📊 Observation: Failed to commit README.md - {error_text[:200]}",
+                        agent_name="PR Agent (MCP)",
+                        metadata={"file_committed": False, "error": error_text}
+                    )
+                    raise Exception(f"push_files failed: {error_text}")
+
+            except Exception as e:
+                logger.error(f"File commit failed: {e}")
+                # 📊 Observation: Commit failed
+                await log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.AGENT_OBSERVATION,
+                    message=f"📊 Observation: Failed to commit README.md - {str(e)}",
+                    agent_name="PR Agent (MCP)",
+                    metadata={"file_committed": False, "error": str(e)}
+                )
+                raise
+
+            # === STEP 3: Create Pull Request ===
+
+            # 💭 Thought: Ready to create PR
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_THINKING,
+                message=f"💭 Thought: README.md is committed. Now I need to create a pull request from '{branch_name}' to '{base_branch}'",
+                agent_name="PR Agent (MCP)"
+            )
+
+            pr_body = f"""## Summary
+This PR adds comprehensive AI-generated documentation for **{readme_title}**.
+
+## What's Included
+- **Project Overview** - High-level description and key features
+- **Architecture** - System design with Mermaid diagrams
+- **Installation Guide** - Step-by-step setup instructions with actual repository URLs
+- **Configuration** - Environment variables and settings documentation
+- **Deployment** - Quick start guide with Docker/manual deployment options
+- **Troubleshooting** - Common issues and solutions
+- **API Documentation** - Endpoints and usage examples (if applicable)
+
+## About This Documentation
+This README was automatically generated by **DocuGen Micro-Agents**, an advanced AI system that uses specialized agents to analyze your repository:
+
+---
+*Generated by DocuGen Micro-Agents AI-powered documentation with specialized micro-agent system*
+- Agents Used: Code Explorer, API Reference, Call Graph Analyzer, Environment Config, Dependency Analyzer, Error Analysis, Planner, Mermaid Generator, QA Validator
+- Integration: Model Context Protocol (MCP) for GitHub"""
+
+            # 🔧 Action: Create PR
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_ACTION,
+                message=f"🔧 Action: create_pull_request(owner={owner}, repo={repo}, title='docs: Updated README for {readme_title}', head={branch_name}, base={base_branch})",
+                agent_name="PR Agent (MCP)",
+                metadata={"tool": "create_pull_request", "params": {"owner": owner, "repo": repo, "head": branch_name, "base": base_branch}}
+            )
+
+            pr_url = None
+            try:
+                pr_result = await mcp_client.call_tool(
+                    "create_pull_request",
+                    {
+                        "owner": owner,
+                        "repo": repo,
+                        "title": f"docs: Updated README for {readme_title}",
+                        "body": pr_body,
+                        "head": branch_name,
+                        "base": base_branch
+                    }
+                )
+
+                logger.info(f"PR creation result: {pr_result}")
+                logger.info(f"PR result type: {type(pr_result)}")
+
+                # Check if PR creation failed
+                if hasattr(pr_result, 'isError') and pr_result.isError:
+                    error_text = str(pr_result.content[0].text if hasattr(pr_result, 'content') else pr_result)
+                    logger.error(f"PR creation returned error: {error_text}")
+                    raise Exception(f"create_pull_request failed: {error_text}")
+
+                # Extract PR URL from result
+                if hasattr(pr_result, 'content') and pr_result.content:
+                    if isinstance(pr_result.content, list) and len(pr_result.content) > 0:
+                        result_text = str(pr_result.content[0].text if hasattr(pr_result.content[0], 'text') else pr_result.content[0])
+                        logger.info(f"Extracted result_text: {result_text[:500]}")
+                    else:
+                        result_text = str(pr_result.content)
+                        logger.info(f"Result content (non-list): {result_text[:500]}")
+
+                    # Try multiple methods to extract URL
+                    # Method 1: Parse as JSON
+                    try:
+                        data = json.loads(result_text)
+                        pr_url = data.get("html_url")
+                        logger.info(f"Extracted PR URL from JSON: {pr_url}")
+                    except:
+                        logger.info("Could not parse result as JSON, trying regex")
+                        # Method 2: Regex search for GitHub PR URL
+                        url_match = re.search(r'https://github\.com/[^\s"\'<>]+/pull/\d+', result_text)
+                        if url_match:
+                            pr_url = url_match.group(0)
+                            logger.info(f"Extracted PR URL from regex: {pr_url}")
+                        else:
+                            # Method 3: Construct URL from owner/repo if PR number is available
+                            pr_number_match = re.search(r'"number":\s*(\d+)', result_text)
+                            if pr_number_match:
+                                pr_number = pr_number_match.group(1)
+                                pr_url = f"https://github.com/{owner}/{repo}/pull/{pr_number}"
+                                logger.info(f"Constructed PR URL from number: {pr_url}")
+
+                # 📊 Observation: PR created
+                await log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.AGENT_OBSERVATION,
+                    message=f"📊 Observation: Pull request created successfully! URL: {pr_url or 'Check GitHub'}",
+                    agent_name="PR Agent (MCP)",
+                    metadata={"pr_created": True, "pr_url": pr_url}
+                )
+
+            except Exception as e:
+                logger.error(f"PR creation failed: {e}")
+                # 📊 Observation: PR creation failed
+                await log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.AGENT_OBSERVATION,
+                    message=f"📊 Observation: Failed to create pull request - {str(e)}",
+                    agent_name="PR Agent (MCP)",
+                    metadata={"pr_created": False, "error": str(e)}
+                )
+                raise
+
+            # Log completion
+            await log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.AGENT_COMPLETE,
+                message=f"PR workflow complete! PR created at: {pr_url or 'Check GitHub'}",
+                agent_name="PR Agent (MCP)",
+                metadata={"pr_url": pr_url, "branch": branch_name}
+            )
+
+            return {
+                "success": True,
+                "pr_url": pr_url,
+                "branch_name": branch_name,
+                "output": f"Successfully created PR via MCP protocol: {pr_url or 'See GitHub'}"
+            }
+
+    except Exception as e:
+        logger.error(f"MCP PR creation failed: {e}", exc_info=True)
+        await log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.ERROR,
+            message=f"MCP PR Agent error: {str(e)}",
+            agent_name="PR Agent (MCP)"
+        )
+
+        return {
+            "success": False,
+            "pr_url": None,
+            "branch_name": None,
+            "output": f"Failed to create PR via MCP: {str(e)}"
+        }
diff --git a/DocuGenMicroagents/api/agents/qa_validator_agent.py b/DocuGenMicroagents/api/agents/qa_validator_agent.py
new file mode 100644
index 0000000000..a6d0bb9a02
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/qa_validator_agent.py
@@ -0,0 +1,222 @@
+"""
+QA Validator Agent - SIMPLIFIED for 8K context models
+
+Validates README quality, completeness, and structure.
+
+KEY DIFFERENCE: QA Validator does NOT have file reading tools.
+It receives the final_readme from state and validates it.
+
+Follows proven pattern:
+- NO file reading tools (works from final_readme input)
+- Minimal prompt
+- Validates output quality
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.prebuilt import create_react_agent
+from langchain_core.language_models import BaseChatModel
+from langchain.tools import tool
+from core.agent_event_logger import create_agent_logger
+from utils.metrics_extractor import extract_agent_metrics
+
+logger = logging.getLogger(__name__)
+
+# MINIMAL system prompt
+QA_VALIDATOR_PROMPT = """You are a README Quality Validator. Validate documentation quality.
+
+**Input:** You'll receive a generated README markdown.
+
+**Task:** Evaluate the README on these criteria:
+1. **Completeness** - Are all expected sections present? (Overview, Installation, Usage, etc.)
+2. **Clarity** - Is the content clear and well-written?
+3. **Structure** - Proper markdown formatting, headings hierarchy
+4. **Code Examples** - Are code blocks properly formatted?
+5. **Mermaid Diagrams** - If present, are they valid?
+
+**Output:** JSON validation report:
+```json
+{
+  "qa_score": 85,
+  "qa_passed": true,
+  "issues": [
+    {"severity": "warning", "message": "Installation section is brief"},
+    {"severity": "error", "message": "No usage examples provided"}
+  ],
+  "recommendations": ["Add more usage examples", "Include configuration details"]
+}
+```
+
+**Tools:**
+- validate_readme_structure(readme) - check structure and completeness
+- validate_mermaid_diagrams(readme) - extract and validate Mermaid diagrams
+
+**Scoring:**
+- 90-100: Excellent
+- 75-89: Good
+- 60-74: Acceptable (needs minor improvements)
+- <60: Poor (needs major improvements)
+
+**Pass Threshold:** 60
+
+**Limit:** 5 tool calls."""
+
+
+async def run_qa_validator_agent(
+    llm: BaseChatModel,
+    readme_sections: dict,
+    job_id: str,
+    evidence_packet=None
+) -> Dict[str, Any]:
+    """
+    Enhanced QA Validator - Validates sections with evidence-based guardrails
+
+    Checks if expected sections are present, non-empty, AND don't contain
+    forbidden phrases without evidence.
+
+    Args:
+        llm: Language model (not used in fast mode)
+        readme_sections: Dict of section name -> content
+        job_id: Job ID
+        evidence_packet: EvidencePacket for checking forbidden phrases
+
+    Returns:
+        Results dict with success flag and validation report
+    """
+    try:
+        import json
+
+        # Expected sections
+        EXPECTED_SECTIONS = [
+            "Project Overview",
+            "Features",
+            "Architecture",
+            "Prerequisites",
+            "Quick Start Deployment",
+            "Configuration",
+            "Troubleshooting"
+        ]
+
+        issues = []
+        score = 100
+        missing_sections = []
+        empty_sections = []
+        forbidden_violations = []
+
+        # Check for missing sections
+        for section in EXPECTED_SECTIONS:
+            if section not in readme_sections:
+                missing_sections.append(section)
+                issues.append({"severity": "warning", "message": f"Missing section: {section}"})
+                score -= 5
+            elif len(readme_sections[section].strip()) < 50:
+                empty_sections.append(section)
+                issues.append({"severity": "error", "message": f"Section too short or empty: {section}"})
+                score -= 10
+
+        # Check for code blocks in deployment section
+        if "Quick Start Deployment" in readme_sections:
+            if '```' not in readme_sections["Quick Start Deployment"]:
+                issues.append({"severity": "warning", "message": "Quick Start Deployment lacks code examples"})
+                score -= 5
+
+        # Check for architecture diagram mention
+        if "Architecture" in readme_sections:
+            if "diagram" not in readme_sections["Architecture"].lower():
+                issues.append({"severity": "info", "message": "Architecture section should mention diagram"})
+
+        # === NEW: Evidence-Based Forbidden Phrase Checks (FIX 3 applied) ===
+        if evidence_packet:
+            # Combine all section content for checking
+            full_content = "\n".join(readme_sections.values())
+
+            # Define forbidden checks (removed weak port checks per FIX 3)
+            forbidden_checks = [
+                {
+                    "phrase": "npm",
+                    "evidence_required": lambda e: len(e.node_deps) > 0,
+                    "message": "Claims 'npm' commands but no package.json found"
+                },
+                {
+                    "phrase": "docker-compose",
+                    "evidence_required": lambda e: e.has_docker and "docker-compose.yml" in e.docker_files,
+                    "message": "Claims 'docker-compose' but no docker-compose.yml found"
+                },
+                {
+                    "phrase": "Dockerfile",
+                    "evidence_required": lambda e: e.has_docker and "Dockerfile" in e.docker_files,
+                    "message": "Claims 'Dockerfile' but no Dockerfile found"
+                },
+                {
+                    "phrase": "Whisper",
+                    "evidence_required": lambda e: any("whisper" in dep.lower() for dep in e.python_deps),
+                    "message": "Claims 'Whisper' without dependency evidence"
+                },
+                {
+                    "phrase": "Keycloak",
+                    "evidence_required": lambda e: any("keycloak" in dep.lower() for dep in (e.python_deps + e.node_deps)),
+                    "message": "Claims 'Keycloak' without dependency evidence"
+                },
+                {
+                    "phrase": "React",
+                    "evidence_required": lambda e: "react" in [d.lower() for d in e.node_deps] or e.frontend_framework == "React",
+                    "message": "Claims 'React' without evidence"
+                },
+                {
+                    "phrase": "Vue",
+                    "evidence_required": lambda e: "vue" in [d.lower() for d in e.node_deps] or e.frontend_framework == "Vue",
+                    "message": "Claims 'Vue' without evidence"
+                }
+            ]
+
+            # Check each forbidden phrase
+            for check in forbidden_checks:
+                phrase = check["phrase"]
+                if phrase in full_content:
+                    # Check if evidence exists
+                    if not check["evidence_required"](evidence_packet):
+                        forbidden_violations.append(check["message"])
+                        issues.append({
+                            "severity": "error",
+                            "message": f"HALLUCINATION: {check['message']}"
+                        })
+                        score -= 15  # Heavy penalty for hallucinations
+
+            if forbidden_violations:
+                logger.warning(f"[QA] Found {len(forbidden_violations)} forbidden phrase violations")
+
+        # Build validation report
+        qa_report = {
+            "qa_score": max(score, 0),  # Allow scores below 60 to show severity
+            "qa_passed": score >= 60,
+            "missing_sections": missing_sections,
+            "empty_sections": empty_sections,
+            "forbidden_violations": forbidden_violations,
+            "issues": issues,
+            "recommendations": [] if score >= 90 else [
+                "Ensure all sections have meaningful content",
+                "Add code examples to deployment instructions",
+                "Remove hallucinated commands/technologies without evidence"
+            ]
+        }
+
+        output_json = json.dumps(qa_report, indent=2)
+
+        # Note: QA Validator doesn't use LangGraph messages, so metrics will be empty
+        # But we include the call for consistency with other agents
+        metrics = extract_agent_metrics([])
+
+        return {
+            "success": True,
+            "output": output_json,
+            "agent": "QAValidator",
+            **metrics
+        }
+
+    except Exception as e:
+        logger.error(f"QAValidator failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "QAValidator"
+        }
diff --git a/DocuGenMicroagents/api/agents/writer_agent_sectioned.py b/DocuGenMicroagents/api/agents/writer_agent_sectioned.py
new file mode 100644
index 0000000000..8b19c7b70b
--- /dev/null
+++ b/DocuGenMicroagents/api/agents/writer_agent_sectioned.py
@@ -0,0 +1,296 @@
+"""
+Sectioned Writer Agent - TIMEOUT-RESISTANT DESIGN
+
+Generates README in multiple small calls instead of one large call.
+
+Architecture:
+1. Generate outline (fast)
+2. Generate sections one-by-one (small, bounded calls)
+3. Stitch sections together
+
+This prevents 504 Gateway Timeouts by keeping each LLM call small and fast.
+"""
+
+import logging
+import json
+from typing import Dict, Any, List
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import SystemMessage, HumanMessage
+
+logger = logging.getLogger(__name__)
+
+
+def build_structured_evidence(state: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Convert raw agent outputs into compact structured evidence.
+
+    This dramatically reduces tokens vs raw text concatenation.
+    """
+
+    # Parse code summary into bullets
+    code_summary = state.get("code_summary", "")
+    code_bullets = _extract_bullets(code_summary, max_bullets=10)
+
+    # Parse API documentation
+    api_docs = state.get("api_documentation", "")
+    api_bullets = _extract_bullets(api_docs, max_bullets=8)
+
+    # Parse dependencies
+    dependency_report = state.get("dependency_report", {})
+    if isinstance(dependency_report, dict):
+        dep_output = dependency_report.get("output", "")
+    else:
+        dep_output = str(dependency_report)
+    dep_bullets = _extract_bullets(dep_output, max_bullets=6)
+
+    # Parse env config
+    env_config = state.get("env_config_output", "")
+    env_bullets = _extract_bullets(env_config, max_bullets=5)
+
+    # Parse call graph (already dict)
+    call_graph = state.get("call_graph", {})
+    if isinstance(call_graph, dict) and "output" in call_graph:
+        call_graph_text = str(call_graph["output"])[:500]  # Truncate
+    else:
+        call_graph_text = str(call_graph)[:500]
+
+    # Parse error analysis
+    error_analysis = state.get("error_analysis", {})
+    if isinstance(error_analysis, dict):
+        error_output = error_analysis.get("output", "")
+    else:
+        error_output = str(error_analysis)
+    error_bullets = _extract_bullets(error_output, max_bullets=5)
+
+    # Project metadata
+    project_type = state.get("project_type", "Unknown")
+    repo_name = state.get("repo_name", "Project")
+
+    # Build compact structured evidence
+    structured = {
+        "project_name": repo_name,
+        "project_type": project_type,
+        "overview": code_bullets[:3] if code_bullets else ["No overview available"],
+        "architecture": code_bullets[3:8] if len(code_bullets) > 3 else [],
+        "api_endpoints": api_bullets,
+        "dependencies": dep_bullets,
+        "environment": env_bullets,
+        "call_graph_summary": call_graph_text,
+        "error_handling": error_bullets
+    }
+
+    return structured
+
+
+def _extract_bullets(text: str, max_bullets: int = 10) -> List[str]:
+    """Extract bullet points or key sentences from text"""
+    if not text:
+        return []
+
+    bullets = []
+
+    # Try to find existing bullets (lines starting with -, *, •, or numbers)
+    lines = text.split('\n')
+    for line in lines:
+        line = line.strip()
+        if line and (line.startswith('-') or line.startswith('*') or
+                     line.startswith('•') or (len(line) > 2 and line[0].isdigit() and line[1] in '.)')):
+            # Remove bullet marker
+            clean = line.lstrip('-*•0123456789.) ').strip()
+            if clean:
+                bullets.append(clean)
+                if len(bullets) >= max_bullets:
+                    break
+
+    # If no bullets found, extract first N sentences
+    if not bullets:
+        sentences = text.replace('\n', ' ').split('. ')
+        for sentence in sentences[:max_bullets]:
+            sentence = sentence.strip()
+            if sentence:
+                bullets.append(sentence)
+
+    return bullets[:max_bullets]
+
+
+async def run_writer_agent_sectioned(
+    llm: BaseChatModel,
+    state: Dict[str, Any],
+    job_id: str
+) -> Dict[str, Any]:
+    """
+    Sectioned Writer Agent - generates README in multiple small calls.
+    Uses planner's section list instead of generating own outline.
+
+    Args:
+        llm: Language model
+        state: Full workflow state (we'll extract structured evidence)
+        job_id: Job ID
+
+    Returns:
+        Results dict with sections dict (not a single readme string)
+    """
+    try:
+        # Step 1: Build structured evidence (compact)
+        print(f"[Writer] Building structured evidence...")
+        evidence = build_structured_evidence(state)
+        evidence_json = json.dumps(evidence, indent=2)
+
+        print(f"[Writer] Structured evidence: {len(evidence_json)} chars")
+        logger.info(f"[Writer] Structured evidence: {len(evidence_json)} chars")
+
+        # Step 2: Get sections from planner (NO outline generation!)
+        planned_sections = state.get("documentation_sections", ["Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "Troubleshooting"])
+        print(f"[Writer] Using planner sections: {planned_sections}")
+        logger.info(f"[Writer] Using planner sections: {planned_sections}")
+
+        # Step 3: Generate sections one-by-one (small, fast calls)
+        sections_dict = {}
+        for section_name in planned_sections:
+            logger.info(f"[Writer] Generating section: {section_name}")
+            section_content = await _generate_section(llm, section_name, evidence)
+            # Store with ## heading included
+            sections_dict[section_name] = f"## {section_name}\n\n{section_content}"
+
+        logger.info(f"[Writer] Generated {len(sections_dict)} sections")
+
+        # Return sections dict (NOT a single assembled readme)
+        # Assembly will happen in assembly_node
+        return {
+            "success": True,
+            "output": sections_dict,  # Dict of section_name: content
+            "agent": "Writer"
+        }
+
+    except Exception as e:
+        logger.error(f"Writer failed: {e}")
+        return {
+            "success": False,
+            "error": str(e),
+            "agent": "Writer"
+        }
+
+
+async def _generate_section(
+    llm: BaseChatModel,
+    section_name: str,
+    evidence: Dict[str, Any]
+) -> str:
+    """
+    Generate a single README section (small, fast call).
+
+    Returns: Markdown content for this section
+    """
+
+    # Build section-specific evidence (only relevant data)
+    # Map DocuGen section names to evidence
+    if section_name == "Project Overview":
+        context = f"""
+Project: {evidence.get('project_name')}
+Type: {evidence.get('project_type')}
+Overview: {json.dumps(evidence.get('overview', []))}
+Architecture: {json.dumps(evidence.get('architecture', [])[:3])}
+"""
+
+    elif section_name == "Features":
+        context = f"""
+Architecture: {json.dumps(evidence.get('architecture', []))}
+Key capabilities: {json.dumps(evidence.get('overview', []))}
+API Endpoints: {json.dumps(evidence.get('api_endpoints', [])[:5])}
+"""
+
+    elif section_name == "Prerequisites":
+        context = f"""
+Dependencies: {json.dumps(evidence.get('dependencies', []))}
+Project type: {evidence.get('project_type')}
+"""
+
+    elif section_name == "Quick Start Deployment":
+        context = f"""
+Dependencies: {json.dumps(evidence.get('dependencies', []))}
+Environment variables: {json.dumps(evidence.get('environment', [])[:5])}
+Project type: {evidence.get('project_type')}
+"""
+
+    elif section_name == "Configuration":
+        context = f"""
+Environment variables: {json.dumps(evidence.get('environment', []))}
+"""
+
+    elif section_name == "User Interface":
+        context = f"""
+Project type: {evidence.get('project_type')}
+Overview: {json.dumps(evidence.get('overview', []))}
+"""
+
+    elif section_name == "Architecture":
+        context = f"""
+Architecture: {json.dumps(evidence.get('architecture', []))}
+Call graph: {evidence.get('call_graph_summary', '')}
+API Endpoints: {json.dumps(evidence.get('api_endpoints', [])[:3])}
+"""
+
+    elif section_name == "Troubleshooting":
+        context = f"""
+Error handling: {json.dumps(evidence.get('error_handling', []))}
+Common issues: {json.dumps(evidence.get('overview', []))}
+"""
+
+    else:
+        # Fallback for any other section names
+        context = json.dumps(evidence, indent=2)[:1000]
+
+    # Section-specific requirements
+    if section_name == "Prerequisites":
+        requirements = """List ONLY the actual dependencies and requirements found in the context.
+Format as:
+- Runtime/language versions (e.g., Python 3.8+, Node.js 16+)
+- Required tools (Docker, npm, pip, etc.)
+- System requirements
+If no specific prerequisites found, state: "Standard development environment for [project_type]."
+"""
+    elif section_name == "Quick Start Deployment":
+        requirements = """Provide deployment instructions based ONLY on evidence:
+1. Installation steps (based on actual dependencies found)
+2. Configuration steps (based on actual env variables found)
+3. How to run the application (based on project type and entry points)
+4. Docker commands if Docker files were found
+If insufficient information, provide minimal: "Refer to dependency files and configuration for setup details."
+"""
+    elif section_name == "Configuration":
+        requirements = """List ONLY the actual environment variables found. Format as:
+- Variable name: Brief purpose
+If no variables found, state: "No environment configuration required."
+"""
+    else:
+        requirements = "Write based on the evidence provided. Be factual and concise."
+
+    prompt = f"""Write the "{section_name}" section for a README based STRICTLY on the provided evidence.
+
+**CRITICAL RULES:**
+1. ONLY use information from the Context below
+2. If Context is empty or says "No X available", write a minimal 1-2 sentence section acknowledging what's missing
+3. DO NOT invent features, files, commands, or technical details that aren't in the Context
+4. DO NOT add placeholder examples or generic instructions
+5. Be factual and concise - accuracy over completeness
+
+**Section-Specific Requirements:**
+{requirements}
+
+Context:
+{context}
+
+Write clear, concise markdown using ONLY the facts above.
+If the context indicates the project is minimal/empty, reflect that accurately.
+Keep it under 300 words.
+
+Section content:"""
+
+    messages = [
+        SystemMessage(content="You are a technical writer who ONLY writes based on provided evidence. Never invent or assume information. Be factual and concise."),
+        HumanMessage(content=prompt)
+    ]
+
+    response = await llm.ainvoke(messages)
+
+    return response.content.strip()
diff --git a/DocuGenMicroagents/api/config.py b/DocuGenMicroagents/api/config.py
new file mode 100644
index 0000000000..a5dfbeaa1e
--- /dev/null
+++ b/DocuGenMicroagents/api/config.py
@@ -0,0 +1,83 @@
+"""
+Configuration management for DocuGen AI
+Supports GenAI Gateway and Keycloak authentication
+"""
+
+import os
+from enum import Enum
+from typing import Optional
+from pydantic_settings import BaseSettings
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class AuthMode(str, Enum):
+    """Authentication mode enumeration"""
+    GENAI_GATEWAY = "genai_gateway"
+    KEYCLOAK = "keycloak"
+
+
+class Settings(BaseSettings):
+    """Application settings with multi-auth support"""
+
+    # Application Info
+    APP_TITLE: str = "DocuGen Micro-Agents"
+    APP_DESCRIPTION: str = "AI-powered documentation generation with specialized micro-agent system"
+    APP_VERSION: str = "1.0.0"
+
+    # Server Configuration
+    API_PORT: int = 5001
+    HOST: str = "0.0.0.0"
+
+    # CORS Settings
+    CORS_ORIGINS: list = ["http://localhost:3000", "http://localhost:3001", "http://localhost:5173"]
+
+    # Authentication Mode
+    AUTH_MODE: AuthMode = AuthMode.GENAI_GATEWAY
+
+    # GenAI Gateway Configuration
+    GENAI_GATEWAY_URL: Optional[str] = None
+    GENAI_GATEWAY_API_KEY: Optional[str] = None
+
+    # Keycloak Configuration (Enterprise)
+    BASE_URL: Optional[str] = None
+    KEYCLOAK_REALM: str = "master"  # Keycloak realm (typically "master")
+    KEYCLOAK_CLIENT_ID: str = "api"  # Client ID for service account
+    KEYCLOAK_CLIENT_SECRET: Optional[str] = None  # Client secret for authentication
+
+    # Micro-Agent Model Configuration (Using SLM - Qwen3-4B)
+    CODE_EXPLORER_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    API_REFERENCE_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    CALL_GRAPH_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    ERROR_ANALYSIS_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    ENV_CONFIG_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    DEPENDENCY_ANALYZER_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    PLANNER_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    MERMAID_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    QA_VALIDATOR_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+    WRITER_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+
+
+    # Repository Settings
+    TEMP_REPO_DIR: str = "./tmp/repos"
+    MAX_REPO_SIZE: int = 10737418240  # 10GB in bytes
+    MAX_FILE_SIZE: int = 1000000  # 1MB
+    MAX_FILES_TO_SCAN: int = 500
+    MAX_LINES_PER_FILE: int = 500  # Line budget per file (pattern_window extracts ~150-300 lines)
+
+    # GitHub Integration (for MCP PR creation)
+    GITHUB_TOKEN: Optional[str] = None
+
+    # Agent Settings
+    AGENT_TEMPERATURE: float = 0.7
+    AGENT_MAX_TOKENS: int = 1000
+    AGENT_TIMEOUT: int = 300  # 5 minutes
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+
+# Global settings instance
+settings = Settings()
diff --git a/DocuGenMicroagents/api/core/__init__.py b/DocuGenMicroagents/api/core/__init__.py
new file mode 100644
index 0000000000..49192fbc96
--- /dev/null
+++ b/DocuGenMicroagents/api/core/__init__.py
@@ -0,0 +1,13 @@
+"""
+Core infrastructure for docugen-microagents
+Provides metrics tracking and agent event logging
+"""
+
+from .metrics_collector import MetricsCollector, AgentMetrics
+from .agent_event_logger import create_agent_logger
+
+__all__ = [
+    'MetricsCollector',
+    'AgentMetrics',
+    'create_agent_logger'
+]
diff --git a/DocuGenMicroagents/api/core/agent_event_logger.py b/DocuGenMicroagents/api/core/agent_event_logger.py
new file mode 100644
index 0000000000..e2ce019152
--- /dev/null
+++ b/DocuGenMicroagents/api/core/agent_event_logger.py
@@ -0,0 +1,309 @@
+"""
+Shared Agent Event Logger - Callback Handler for ReAct Pattern Visibility
+
+Captures tool calls and LLM events from LangChain agents and streams them
+to the UI via SSE for real-time "Thinking → Action → Observation" display.
+
+Works with both LangChain and LangGraph agents.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+from langchain_core.callbacks.base import AsyncCallbackHandler
+from models import get_log_manager, LogType
+
+logger = logging.getLogger(__name__)
+
+
+class AgentEventLogger(AsyncCallbackHandler):
+    """
+    Callback handler that captures agent events and streams them to UI.
+
+    Captures:
+    - Tool calls (Actions)
+    - Tool outputs (Observations)
+    - LLM starts (Thinking)
+
+    Usage:
+        logger = AgentEventLogger(job_id="job_123", agent_name="CodeExplorer")
+        result = await agent.ainvoke(..., config={"callbacks": [logger]})
+    """
+
+    def __init__(self, job_id: str, agent_name: str):
+        """
+        Initialize the event logger
+
+        Args:
+            job_id: Job ID for streaming logs
+            agent_name: Name of the agent (e.g., "CodeExplorer", "Writer")
+        """
+        super().__init__()
+        self.job_id = job_id
+        self.agent_name = agent_name
+        self.log_manager = get_log_manager()
+        self.cycle_count = 0
+        self.tool_call_count = 0
+        self.current_tool = None
+
+        # Debouncing flags to prevent duplicate logs
+        self._agent_started = False
+        self._agent_completed = False
+
+        # Tool-specific thinking messages (context-aware)
+        self.thinking_templates = {
+            "list_directory": "📂 Examining directory structure...",
+            "read_file": "📖 Reading file to extract information...",
+            "detect_languages": "🔍 Analyzing programming languages...",
+            "extract_dependencies": "📦 Extracting project dependencies...",
+            "analyze_code_structure": "🏗️ Analyzing code structure and patterns...",
+            "find_entry_points": "🎯 Locating application entry points...",
+            "find_api_routes": "🌐 Discovering API routes and endpoints...",
+            "find_config_files": "⚙️ Finding configuration files...",
+            "validate_mermaid_syntax": "✅ Validating diagram syntax...",
+            "validate_readme_structure": "📋 Checking README structure...",
+            "default": "💭 Analyzing repository and planning next step..."
+        }
+
+    async def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when a tool starts executing (Action step)
+
+        Args:
+            serialized: Tool metadata
+            input_str: Tool input arguments
+        """
+        self.cycle_count += 1
+        self.tool_call_count += 1
+
+        # Extract tool name
+        tool_name = serialized.get("name", "unknown_tool")
+        self.current_tool = tool_name
+
+        # Log thinking step before action
+        thinking_msg = self.thinking_templates.get(tool_name, self.thinking_templates["default"])
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.AGENT_THINKING,
+            message=f"💭 Thinking (Cycle {self.cycle_count}): {thinking_msg}",
+            agent_name=self.agent_name,
+            metadata={
+                "cycle": self.cycle_count,
+                "type": "thinking",
+                "next_tool": tool_name
+            }
+        )
+
+        # Format tool arguments for display
+        try:
+            # Try to parse input_str as it might be JSON or formatted string
+            args_display = input_str[:200] if input_str else "(no args)"
+            if len(input_str) > 200:
+                args_display += "..."
+        except:
+            args_display = "(args)"
+
+        # Log action step
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.AGENT_ACTION,
+            message=f"🔧 Action (Cycle {self.cycle_count}): {tool_name}({args_display})",
+            agent_name=self.agent_name,
+            metadata={
+                "cycle": self.cycle_count,
+                "type": "action",
+                "tool": tool_name,
+                "input": input_str,
+                "call_number": self.tool_call_count
+            }
+        )
+
+    async def on_tool_end(
+        self,
+        output: str,
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when a tool finishes (Observation step)
+
+        Args:
+            output: Tool output/result
+        """
+        tool_name = self.current_tool or "unknown"
+
+        # Create intelligent summary of output
+        output_str = str(output)
+        output_lines = output_str.count('\n') + 1
+
+        # Smart truncation
+        if len(output_str) > 300:
+            output_preview = output_str[:300] + f"... [{len(output_str)} chars total, {output_lines} lines]"
+        else:
+            output_preview = output_str
+
+        # Log observation step
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.AGENT_OBSERVATION,
+            message=f"📊 Observation (Cycle {self.cycle_count}): {tool_name} returned:\n{output_preview}",
+            agent_name=self.agent_name,
+            metadata={
+                "cycle": self.cycle_count,
+                "type": "observation",
+                "tool": tool_name,
+                "output_length": len(output_str),
+                "line_count": output_lines
+            }
+        )
+
+    async def on_tool_error(
+        self,
+        error: Exception,
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when a tool encounters an error
+
+        Args:
+            error: The exception that occurred
+        """
+        tool_name = self.current_tool or "unknown"
+
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.ERROR,
+            message=f"❌ Error (Cycle {self.cycle_count}): {tool_name} failed - {str(error)}",
+            agent_name=self.agent_name,
+            metadata={
+                "cycle": self.cycle_count,
+                "type": "error",
+                "tool": tool_name,
+                "error": str(error)
+            }
+        )
+
+    async def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when LLM starts generating (optional - for detailed logging)
+
+        Args:
+            serialized: LLM metadata
+            prompts: Input prompts
+        """
+        # Optional: Log LLM reasoning start
+        # Only log if we want very detailed visibility
+        pass
+
+    async def on_llm_end(
+        self,
+        response: Any,
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when LLM finishes generating
+
+        Args:
+            response: LLM response
+        """
+        # Optional: Log LLM completion
+        pass
+
+    async def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when agent chain starts
+        """
+        # Debounce: Only log the first chain start
+        if self._agent_started:
+            return
+
+        self._agent_started = True
+
+        # Log agent start
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.AGENT_START,
+            message=f"🚀 Starting {self.agent_name} agent...",
+            agent_name=self.agent_name,
+            metadata={"type": "agent_start"}
+        )
+
+    async def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when agent chain completes
+        """
+        # Debounce: Only log the first chain end
+        if self._agent_completed:
+            return
+
+        self._agent_completed = True
+
+        # Log completion summary
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.INFO,
+            message=f"✅ Completed {self.cycle_count} ReAct cycle(s) with {self.tool_call_count} tool call(s)",
+            agent_name=self.agent_name,
+            metadata={
+                "type": "agent_complete",
+                "total_cycles": self.cycle_count,
+                "total_tool_calls": self.tool_call_count
+            }
+        )
+
+    async def on_chain_error(
+        self,
+        error: Exception,
+        **kwargs: Any
+    ) -> None:
+        """
+        Called when agent chain encounters an error
+
+        Args:
+            error: The exception that occurred
+        """
+        await self.log_manager.log_async(
+            job_id=self.job_id,
+            log_type=LogType.ERROR,
+            message=f"❌ {self.agent_name} agent failed: {str(error)}",
+            agent_name=self.agent_name,
+            metadata={
+                "type": "agent_error",
+                "error": str(error)
+            }
+        )
+
+
+def create_agent_logger(job_id: str, agent_name: str) -> AgentEventLogger:
+    """
+    Factory function to create an AgentEventLogger
+
+    Args:
+        job_id: Job ID for log streaming
+        agent_name: Name of the agent
+
+    Returns:
+        Configured AgentEventLogger instance
+
+    Example:
+        logger = create_agent_logger("job_123", "CodeExplorer")
+        result = await agent.ainvoke(..., config={"callbacks": [logger]})
+    """
+    return AgentEventLogger(job_id=job_id, agent_name=agent_name)
diff --git a/DocuGenMicroagents/api/core/metrics_collector.py b/DocuGenMicroagents/api/core/metrics_collector.py
new file mode 100644
index 0000000000..f887d37303
--- /dev/null
+++ b/DocuGenMicroagents/api/core/metrics_collector.py
@@ -0,0 +1,220 @@
+"""
+Metrics Collection for Workflow Execution
+
+Tracks real metrics from execution:
+- Token usage per agent
+- Time to first token (TTFT)
+- Tokens per second (TPS)
+- Tool calls per agent
+- Workflow-level aggregated metrics
+
+Key principle: Measure everything, estimate nothing
+"""
+
+import time
+import logging
+from typing import Dict, Optional, Any
+from dataclasses import dataclass, asdict
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentMetrics:
+    """Metrics for a single agent execution"""
+    agent_name: str
+    job_id: str
+
+    # Execution metrics
+    start_time_ms: float = 0
+    end_time_ms: float = 0
+    duration_ms: float = 0
+
+    # Token usage
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+
+    # Tool calling
+    llm_calls: int = 0
+    tool_calls: int = 0
+
+    # Status
+    success: bool = False
+    error_message: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary"""
+        return asdict(self)
+
+    def calculate_cost(self, cost_per_million_tokens: float = 0.15) -> float:
+        """
+        Calculate estimated cost in USD
+
+        Args:
+            cost_per_million_tokens: Cost per 1M tokens (default: $0.15 for Qwen3-4B estimate)
+
+        Returns:
+            Estimated cost in USD
+        """
+        return (self.total_tokens / 1_000_000) * cost_per_million_tokens
+
+    def calculate_tps(self) -> float:
+        """
+        Calculate tokens per second (TPS)
+
+        Returns:
+            Tokens per second
+        """
+        if self.duration_ms == 0:
+            return 0.0
+        duration_seconds = self.duration_ms / 1000
+        return self.output_tokens / duration_seconds if duration_seconds > 0 else 0.0
+
+
+class MetricsCollector:
+    """
+    Centralized metrics collection for all agents
+
+    Tracks real execution metrics for workflow analysis
+    """
+
+    def __init__(self, job_id: str):
+        """
+        Initialize MetricsCollector
+
+        Args:
+            job_id: Unique job identifier
+        """
+        self.job_id = job_id
+        self.agents: Dict[str, AgentMetrics] = {}
+        self.workflow_start_time = time.time() * 1000  # Convert to ms
+        self.workflow_end_time: Optional[float] = None
+
+        logger.info(f"[{job_id}] MetricsCollector initialized")
+
+    def start_agent(self, agent_name: str) -> AgentMetrics:
+        """
+        Start tracking an agent
+
+        Args:
+            agent_name: Name of agent
+
+        Returns:
+            AgentMetrics instance for this agent
+        """
+        if agent_name in self.agents:
+            logger.warning(f"[{self.job_id}] Agent {agent_name} already started, resetting")
+
+        metrics = AgentMetrics(
+            agent_name=agent_name,
+            job_id=self.job_id,
+            start_time_ms=time.time() * 1000
+        )
+
+        self.agents[agent_name] = metrics
+        logger.debug(f"[{self.job_id}] Started tracking: {agent_name}")
+
+        return metrics
+
+    def end_agent(
+        self,
+        agent_name: str,
+        success: bool = True,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        llm_calls: int = 0,
+        tool_calls: int = 0,
+        error_message: Optional[str] = None
+    ):
+        """
+        End tracking an agent
+
+        Args:
+            agent_name: Name of agent
+            success: Whether agent succeeded
+            input_tokens: Input tokens used
+            output_tokens: Output tokens generated
+            llm_calls: Number of LLM calls
+            tool_calls: Number of tool calls
+            error_message: Error message if failed
+        """
+        if agent_name not in self.agents:
+            logger.error(f"[{self.job_id}] Agent {agent_name} not started")
+            return
+
+        metrics = self.agents[agent_name]
+        metrics.end_time_ms = time.time() * 1000
+        metrics.duration_ms = metrics.end_time_ms - metrics.start_time_ms
+        metrics.success = success
+        metrics.input_tokens = input_tokens
+        metrics.output_tokens = output_tokens
+        metrics.total_tokens = input_tokens + output_tokens
+        metrics.llm_calls = llm_calls
+        metrics.tool_calls = tool_calls
+        metrics.error_message = error_message
+
+        tps = metrics.calculate_tps()
+
+        logger.info(
+            f"[{self.job_id}] {agent_name} completed: "
+            f"success={success}, tokens={metrics.total_tokens}, "
+            f"duration={metrics.duration_ms:.0f}ms, TPS={tps:.2f}"
+        )
+
+    def finalize_workflow(self):
+        """Mark workflow as complete and calculate final metrics"""
+        self.workflow_end_time = time.time() * 1000
+        workflow_duration = self.workflow_end_time - self.workflow_start_time
+
+        logger.info(
+            f"[{self.job_id}] Workflow completed in {workflow_duration:.0f}ms "
+            f"({len(self.agents)} agents)"
+        )
+
+    def get_summary(self) -> Dict[str, Any]:
+        """
+        Get comprehensive metrics summary
+
+        Returns:
+            Dictionary with all metrics
+        """
+        if not self.workflow_end_time:
+            self.finalize_workflow()
+
+        # Calculate totals
+        total_tokens = sum(m.total_tokens for m in self.agents.values())
+        total_input_tokens = sum(m.input_tokens for m in self.agents.values())
+        total_output_tokens = sum(m.output_tokens for m in self.agents.values())
+        total_tool_calls = sum(m.tool_calls for m in self.agents.values())
+        total_llm_calls = sum(m.llm_calls for m in self.agents.values())
+        workflow_duration_ms = self.workflow_end_time - self.workflow_start_time
+
+        # Agent-level metrics
+        agent_metrics = [m.to_dict() for m in self.agents.values()]
+
+        # Calculate workflow-level TPS
+        workflow_duration_seconds = workflow_duration_ms / 1000
+        workflow_tps = total_output_tokens / workflow_duration_seconds if workflow_duration_seconds > 0 else 0.0
+
+        # Count failed agents
+        failed_agents = [m for m in self.agents.values() if not m.success]
+
+        return {
+            "job_id": self.job_id,
+            "workflow": {
+                "total_agents": len(self.agents),
+                "successful_agents": len([m for m in self.agents.values() if m.success]),
+                "failed_agents": len(failed_agents),
+                "total_duration_ms": workflow_duration_ms,
+                "total_duration_seconds": round(workflow_duration_seconds, 2),
+                "total_tokens": total_tokens,
+                "total_input_tokens": total_input_tokens,
+                "total_output_tokens": total_output_tokens,
+                "total_tool_calls": total_tool_calls,
+                "total_llm_calls": total_llm_calls,
+                "average_tps": round(workflow_tps, 2)
+            },
+            "agents": agent_metrics,
+            "failed_agent_names": [m.agent_name for m in failed_agents]
+        }
diff --git a/DocuGenMicroagents/api/mcp_client/__init__.py b/DocuGenMicroagents/api/mcp_client/__init__.py
new file mode 100644
index 0000000000..15cca45fec
--- /dev/null
+++ b/DocuGenMicroagents/api/mcp_client/__init__.py
@@ -0,0 +1,8 @@
+"""
+MCP Client Module
+Provides connections to MCP servers (Model Context Protocol)
+"""
+
+from .github_mcp_client import GitHubMCPClient, get_github_mcp_client
+
+__all__ = ['GitHubMCPClient', 'get_github_mcp_client']
diff --git a/DocuGenMicroagents/api/mcp_client/github_mcp_client.py b/DocuGenMicroagents/api/mcp_client/github_mcp_client.py
new file mode 100644
index 0000000000..cf235d3fe8
--- /dev/null
+++ b/DocuGenMicroagents/api/mcp_client/github_mcp_client.py
@@ -0,0 +1,131 @@
+"""
+GitHub MCP Client - Connects to official GitHub MCP server
+Uses MCP protocol (stdio) to communicate with Docker container
+"""
+
+import os
+import asyncio
+import logging
+from typing import Dict, Any, List, Optional
+from contextlib import asynccontextmanager
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+logger = logging.getLogger(__name__)
+
+
+class GitHubMCPClient:
+    """Client for GitHub MCP Server"""
+
+    def __init__(self, github_token: str):
+        """
+        Initialize GitHub MCP client
+
+        Args:
+            github_token: GitHub Personal Access Token
+        """
+        self.github_token = github_token
+        self.session: Optional[ClientSession] = None
+        self._client_context = None
+
+    @asynccontextmanager
+    async def connect(self):
+        """
+        Connect to GitHub MCP server running in Docker
+
+        Yields:
+            ClientSession for making tool calls
+        """
+        # Define server parameters - run GitHub MCP server via Docker
+        server_params = StdioServerParameters(
+            command="docker",
+            args=[
+                "run",
+                "-i",
+                "--rm",
+                "-e", f"GITHUB_PERSONAL_ACCESS_TOKEN={self.github_token}",
+                "ghcr.io/github/github-mcp-server:latest"
+            ],
+            env=None
+        )
+
+        logger.info("Starting GitHub MCP server via Docker...")
+
+        async with stdio_client(server_params) as (read, write):
+            async with ClientSession(read, write) as session:
+                self.session = session
+
+                # Initialize session
+                await session.initialize()
+
+                # List available tools
+                tools = await session.list_tools()
+                logger.info(f"Connected to GitHub MCP server. Available tools: {[t.name for t in tools.tools]}")
+
+                yield session
+
+        logger.info("Disconnected from GitHub MCP server")
+        self.session = None
+
+    async def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        """
+        Call a tool on the GitHub MCP server
+
+        Args:
+            tool_name: Name of the tool to call
+            arguments: Tool arguments
+
+        Returns:
+            Tool result
+        """
+        if not self.session:
+            raise RuntimeError("Not connected to MCP server. Use 'async with client.connect():'")
+
+        logger.debug(f"Calling MCP tool: {tool_name} with args: {arguments}")
+
+        result = await self.session.call_tool(tool_name, arguments=arguments)
+
+        logger.debug(f"MCP tool {tool_name} result: {result}")
+
+        return result
+
+    async def list_available_tools(self) -> List[str]:
+        """
+        Get list of available tools from GitHub MCP server
+
+        Returns:
+            List of tool names
+        """
+        if not self.session:
+            raise RuntimeError("Not connected to MCP server")
+
+        tools = await self.session.list_tools()
+        return [tool.name for tool in tools.tools]
+
+
+# Singleton instance
+_github_mcp_client: Optional[GitHubMCPClient] = None
+
+
+def get_github_mcp_client(github_token: Optional[str] = None) -> GitHubMCPClient:
+    """
+    Get or create GitHub MCP client instance
+
+    Args:
+        github_token: GitHub PAT (uses env var if not provided)
+
+    Returns:
+        GitHubMCPClient instance
+    """
+    global _github_mcp_client
+
+    if _github_mcp_client is None:
+        token = github_token or os.getenv("GITHUB_TOKEN")
+        if not token:
+            raise ValueError("GitHub token required. Set GITHUB_TOKEN env var or pass token parameter.")
+
+        _github_mcp_client = GitHubMCPClient(token)
+        logger.info("GitHub MCP client created")
+
+    return _github_mcp_client
diff --git a/DocuGenMicroagents/api/models/__init__.py b/DocuGenMicroagents/api/models/__init__.py
new file mode 100644
index 0000000000..84e3590591
--- /dev/null
+++ b/DocuGenMicroagents/api/models/__init__.py
@@ -0,0 +1,28 @@
+"""
+Data models for DocuGen AI
+"""
+
+from .state import DocGenState
+from .schemas import (
+    GenerateDocsRequest,
+    GenerateDocsResponse,
+    JobStatusResponse,
+    ProjectSelectionRequest,
+    ProjectSelectionResponse,
+    AgentLog,
+    LogType
+)
+from .log_manager import LogManager, get_log_manager
+
+__all__ = [
+    "DocGenState",
+    "GenerateDocsRequest",
+    "GenerateDocsResponse",
+    "JobStatusResponse",
+    "ProjectSelectionRequest",
+    "ProjectSelectionResponse",
+    "AgentLog",
+    "LogType",
+    "LogManager",
+    "get_log_manager"
+]
diff --git a/DocuGenMicroagents/api/models/evidence.py b/DocuGenMicroagents/api/models/evidence.py
new file mode 100644
index 0000000000..b8818d1072
--- /dev/null
+++ b/DocuGenMicroagents/api/models/evidence.py
@@ -0,0 +1,126 @@
+"""
+Evidence Packet - Central Evidence Store for README Generation
+
+This module defines the schema for storing all repository evidence
+with provenance tracking to prevent hallucinations.
+
+Key Principles:
+- Single source of truth for all README content
+- Every evidence item includes source_files for traceability
+- Deterministic derivation (no LLM-generated values)
+- Supports both file-based and structured agent outputs
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any
+
+
+@dataclass
+class EvidenceItem:
+    """Single piece of evidence with provenance."""
+    category: str  # "dependency", "config", "route", "tool", etc.
+    key: str  # Identifier (e.g., "fastapi", "PORT", "/upload")
+    value: str  # The evidence value
+    source_files: List[str] = field(default_factory=list)  # Where it was found
+    confidence: str = "high"  # "high", "medium", "low"
+
+
+@dataclass
+class EvidencePacket:
+    """
+    Central evidence store for README generation.
+
+    Contains all factual information extracted from repository
+    with provenance tracking.
+    """
+
+    # Repository metadata (deterministic)
+    repo_name: str = ""
+    repo_path: str = ""
+
+    # Language detection
+    languages: Dict[str, int] = field(default_factory=dict)  # {language: file_count}
+
+    # Dependencies (from package files)
+    python_deps: List[str] = field(default_factory=list)  # From requirements.txt
+    node_deps: List[str] = field(default_factory=list)  # From package.json
+
+    # Technology flags
+    has_docker: bool = False
+    has_frontend: bool = False
+    has_backend: bool = False
+
+    # Configuration
+    env_files: List[str] = field(default_factory=list)  # [".env.example", ".env"]
+    env_vars: Dict[str, str] = field(default_factory=dict)  # {VAR: description}
+
+    # Docker evidence
+    docker_files: List[str] = field(default_factory=list)  # ["Dockerfile", "docker-compose.yml"]
+
+    # API endpoints (if backend detected)
+    api_endpoints: List[Dict[str, str]] = field(default_factory=list)  # [{method, path, file}]
+
+    # Entry points
+    entry_points: List[str] = field(default_factory=list)  # ["server.py", "main.py"]
+
+    # Frontend info
+    frontend_framework: str = ""  # "React", "Vue", "Angular", ""
+    frontend_files: List[str] = field(default_factory=list)
+
+    # Raw evidence items
+    items: List[EvidenceItem] = field(default_factory=list)
+
+    def add_evidence(self, item: EvidenceItem) -> None:
+        """Add evidence item with deduplication."""
+        # Avoid duplicate evidence
+        for existing in self.items:
+            if existing.key == item.key and existing.category == item.category:
+                return
+        self.items.append(item)
+
+    def has_evidence_for(self, key: str, category: str = None) -> bool:
+        """Check if evidence exists for a key."""
+        for item in self.items:
+            if item.key == key:
+                if category is None or item.category == category:
+                    return True
+        return False
+
+    def get_evidence(self, key: str, category: str = None) -> List[EvidenceItem]:
+        """Get all evidence items matching key and optional category."""
+        results = []
+        for item in self.items:
+            if item.key == key:
+                if category is None or item.category == category:
+                    results.append(item)
+        return results
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "repo_name": self.repo_name,
+            "repo_path": self.repo_path,
+            "languages": self.languages,
+            "python_deps": self.python_deps,
+            "node_deps": self.node_deps,
+            "has_docker": self.has_docker,
+            "has_frontend": self.has_frontend,
+            "has_backend": self.has_backend,
+            "env_files": self.env_files,
+            "env_vars": self.env_vars,
+            "docker_files": self.docker_files,
+            "api_endpoints": self.api_endpoints,
+            "entry_points": self.entry_points,
+            "frontend_framework": self.frontend_framework,
+            "frontend_files": self.frontend_files,
+            "items": [
+                {
+                    "category": item.category,
+                    "key": item.key,
+                    "value": item.value,
+                    "source_files": item.source_files,
+                    "confidence": item.confidence
+                }
+                for item in self.items
+            ]
+        }
diff --git a/DocuGenMicroagents/api/models/log_manager.py b/DocuGenMicroagents/api/models/log_manager.py
new file mode 100644
index 0000000000..45d3ec15fa
--- /dev/null
+++ b/DocuGenMicroagents/api/models/log_manager.py
@@ -0,0 +1,208 @@
+"""
+Log Manager for storing and streaming agent activity logs
+Supports Server-Sent Events (SSE) for real-time streaming
+"""
+
+import asyncio
+import logging
+from collections import defaultdict
+from typing import Dict, List, Optional
+from datetime import datetime
+from .schemas import AgentLog, LogType
+
+logger = logging.getLogger(__name__)
+
+
+class LogManager:
+    """
+    Manages agent activity logs with SSE streaming support.
+    Stores logs per job_id and provides async iteration for SSE.
+    """
+
+    def __init__(self, max_logs_per_job: int = 1000):
+        """
+        Initialize log manager
+
+        Args:
+            max_logs_per_job: Maximum logs to keep per job (circular buffer)
+        """
+        self.max_logs_per_job = max_logs_per_job
+        self._logs: Dict[str, List[AgentLog]] = defaultdict(list)
+        self._subscribers: Dict[str, List[asyncio.Queue]] = defaultdict(list)
+        self._lock = asyncio.Lock()
+
+    async def add_log(self, log: AgentLog) -> None:
+        """
+        Add a log entry and notify all subscribers
+
+        Args:
+            log: Agent log entry
+        """
+        async with self._lock:
+            # Add to storage
+            job_logs = self._logs[log.job_id]
+            job_logs.append(log)
+
+            # Maintain circular buffer
+            if len(job_logs) > self.max_logs_per_job:
+                job_logs.pop(0)
+
+            # Notify all subscribers for this job
+            dead_queues = []
+            for queue in self._subscribers[log.job_id]:
+                try:
+                    await asyncio.wait_for(queue.put(log), timeout=1.0)
+                except (asyncio.TimeoutError, asyncio.QueueFull):
+                    dead_queues.append(queue)
+                    logger.warning(f"Queue full or timeout for job {log.job_id}")
+
+            # Clean up dead queues
+            for queue in dead_queues:
+                self._subscribers[log.job_id].remove(queue)
+
+            # Log to console for debugging
+            logger.info(f"[{log.job_id}] {log.log_type.value}: {log.message}")
+
+    def log_sync(
+        self,
+        job_id: str,
+        log_type: LogType,
+        message: str,
+        agent_name: Optional[str] = None,
+        metadata: Optional[Dict] = None
+    ) -> None:
+        """
+        Synchronous logging helper (for use in sync code)
+
+        Args:
+            job_id: Job identifier
+            log_type: Type of log
+            message: Log message
+            agent_name: Name of the agent (if applicable)
+            metadata: Additional metadata
+        """
+        log = AgentLog(
+            job_id=job_id,
+            log_type=log_type,
+            message=message,
+            agent_name=agent_name,
+            metadata=metadata
+        )
+        # Schedule the async add_log in the event loop
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                asyncio.create_task(self.add_log(log))
+            else:
+                loop.run_until_complete(self.add_log(log))
+        except RuntimeError:
+            # No event loop, just log to console
+            logger.info(f"[{job_id}] {log_type.value}: {message}")
+
+    async def log_async(
+        self,
+        job_id: str,
+        log_type: LogType,
+        message: str,
+        agent_name: Optional[str] = None,
+        metadata: Optional[Dict] = None
+    ) -> None:
+        """
+        Asynchronous logging helper
+
+        Args:
+            job_id: Job identifier
+            log_type: Type of log
+            message: Log message
+            agent_name: Name of the agent (if applicable)
+            metadata: Additional metadata
+        """
+        log = AgentLog(
+            job_id=job_id,
+            log_type=log_type,
+            message=message,
+            agent_name=agent_name,
+            metadata=metadata
+        )
+        await self.add_log(log)
+
+    def get_logs(self, job_id: str, limit: Optional[int] = None) -> List[AgentLog]:
+        """
+        Get all logs for a job
+
+        Args:
+            job_id: Job identifier
+            limit: Maximum number of logs to return (most recent)
+
+        Returns:
+            List of logs
+        """
+        logs = self._logs.get(job_id, [])
+        if limit:
+            return logs[-limit:]
+        return logs
+
+    async def subscribe(self, job_id: str) -> asyncio.Queue:
+        """
+        Subscribe to real-time logs for a job (for SSE)
+
+        Args:
+            job_id: Job identifier
+
+        Returns:
+            Queue that will receive new logs
+        """
+        queue: asyncio.Queue = asyncio.Queue(maxsize=100)
+        async with self._lock:
+            self._subscribers[job_id].append(queue)
+
+            # Send existing logs immediately
+            for log in self._logs.get(job_id, []):
+                try:
+                    await queue.put(log)
+                except asyncio.QueueFull:
+                    logger.warning(f"Initial logs queue full for job {job_id}")
+                    break
+
+        return queue
+
+    async def unsubscribe(self, job_id: str, queue: asyncio.Queue) -> None:
+        """
+        Unsubscribe from logs
+
+        Args:
+            job_id: Job identifier
+            queue: Queue to remove
+        """
+        async with self._lock:
+            if queue in self._subscribers[job_id]:
+                self._subscribers[job_id].remove(queue)
+
+    def clear_job_logs(self, job_id: str) -> None:
+        """
+        Clear all logs for a job
+
+        Args:
+            job_id: Job identifier
+        """
+        if job_id in self._logs:
+            del self._logs[job_id]
+        if job_id in self._subscribers:
+            del self._subscribers[job_id]
+
+
+# Global log manager instance
+_log_manager: Optional[LogManager] = None
+
+
+def get_log_manager() -> LogManager:
+    """
+    Get or create the global log manager instance
+
+    Returns:
+        LogManager instance
+    """
+    global _log_manager
+    if _log_manager is None:
+        _log_manager = LogManager()
+    return _log_manager
diff --git a/DocuGenMicroagents/api/models/schemas.py b/DocuGenMicroagents/api/models/schemas.py
new file mode 100644
index 0000000000..7668e567e4
--- /dev/null
+++ b/DocuGenMicroagents/api/models/schemas.py
@@ -0,0 +1,75 @@
+"""
+Pydantic schemas for API requests and responses
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, HttpUrl, Field
+
+
+class GenerateDocsRequest(BaseModel):
+    """Request to generate documentation"""
+    repo_url: HttpUrl = Field(..., description="GitHub repository URL")
+
+
+class GenerateDocsResponse(BaseModel):
+    """Response with job ID for tracking"""
+    job_id: str
+    status: str
+    message: str
+
+
+class JobStatusResponse(BaseModel):
+    """Job status information"""
+    job_id: str
+    status: str
+    progress_percentage: int
+    current_agent: Optional[str] = None
+    error_message: Optional[str] = None
+    readme_preview: Optional[str] = None
+    awaiting_project_selection: Optional[bool] = False
+    detected_projects: Optional[List[Dict[str, Any]]] = None
+    skipped_folders: Optional[List[Dict[str, Any]]] = None
+
+
+class ProjectSelectionRequest(BaseModel):
+    """User's project selection"""
+    selected_project_paths: List[str] = Field(..., description="List of selected project paths")
+
+
+class ProjectSelectionResponse(BaseModel):
+    """Response after project selection"""
+    status: str
+    message: str
+
+
+class LogType(str, Enum):
+    """Types of log entries"""
+    AGENT_START = "agent_start"
+    AGENT_THINKING = "agent_thinking"
+    AGENT_ACTION = "agent_action"  # Agent calling a tool (ReAct Action step)
+    AGENT_OBSERVATION = "agent_observation"  # Agent receiving tool result (ReAct Observation step)
+    AGENT_TOOL_USE = "agent_tool_use"
+    AGENT_DECISION = "agent_decision"
+    AGENT_COMPLETE = "agent_complete"
+    WORKFLOW_PROGRESS = "workflow_progress"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    SUCCESS = "success"
+
+
+class AgentLog(BaseModel):
+    """Agent activity log entry"""
+    timestamp: datetime = Field(default_factory=datetime.now)
+    job_id: str
+    log_type: LogType
+    agent_name: Optional[str] = None
+    message: str
+    metadata: Optional[Dict[str, Any]] = None
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
diff --git a/DocuGenMicroagents/api/models/state.py b/DocuGenMicroagents/api/models/state.py
new file mode 100644
index 0000000000..b114478175
--- /dev/null
+++ b/DocuGenMicroagents/api/models/state.py
@@ -0,0 +1,98 @@
+"""
+LangGraph State Definition for DocuGen Micro-Agents
+Enhanced with agent messaging, evidence packs, and metrics tracking
+"""
+
+from typing import TypedDict, Dict, List, Any, Optional
+from models.evidence import EvidencePacket
+
+
+class DocGenState(TypedDict):
+    """
+    Shared state for the micro-agent documentation generation workflow.
+    Each agent reads from and writes to this state.
+    """
+
+    # Job Information
+    job_id: str
+    repo_url: str
+
+    # Repository Data (populated by clone step)
+    repo_path: Optional[str]
+    repo_name: Optional[str]
+    default_branch: Optional[str]
+    is_subfolder_target: Optional[bool]
+
+    # Project Detection (populated by project detector)
+    is_monorepo: Optional[bool]
+    detected_projects: Optional[List[Dict[str, Any]]]
+    skipped_folders: Optional[List[Dict[str, Any]]]
+    selected_projects: Optional[List[str]]
+    awaiting_project_selection: Optional[bool]
+
+    # Evidence-Based Architecture
+    evidence_packet: Optional[EvidencePacket]  # Central evidence store
+
+    # Analysis Agent Outputs
+    file_structure: Optional[str]
+    languages: Optional[Dict[str, int]]
+    key_files: Optional[List[str]]
+    code_summary: Optional[str]
+
+    # Dependency Analysis (NEW - from DependencyAnalyzer)
+    dependency_report: Optional[Dict[str, Any]]  # Full dependency analysis
+    security_warnings: Optional[List[Dict[str, str]]]  # Vulnerability warnings
+
+    # Environment Config (NEW - from EnvConfigParser)
+    env_variables: Optional[List[Dict[str, Any]]]  # Extracted env vars
+    config_files_found: Optional[List[str]]
+
+    # Code Analysis Agent Outputs
+    # API Reference (NEW - from APIReferenceAgent)
+    api_endpoints: Optional[List[Dict[str, Any]]]  # Detected endpoints
+    api_documentation: Optional[str]
+
+    # Call Graph (NEW - from CallGraphAgent)
+    call_graph: Optional[Dict[str, Any]]  # Function call relationships
+
+    # Error Analysis (NEW - from ErrorAnalysisAgent)
+    error_handlers: Optional[List[Dict[str, Any]]]  # Exception handlers found
+    error_analysis: Optional[Dict[str, Any]]
+
+    # Planning
+    project_type: Optional[str]
+    documentation_sections: Optional[List[str]]
+    section_instructions: Optional[Dict[str, str]]
+
+    # Content Generation
+    readme_sections: Optional[Dict[str, str]]
+
+    # Visualization
+    mermaid_diagrams: Optional[Dict[str, str]]
+
+    # Quality Assurance
+    qa_validation_result: Optional[Dict[str, Any]]  # QA validator output
+    qa_score: Optional[int]
+    qa_passed: Optional[bool]
+
+    # Final Output
+    final_readme: Optional[str]
+
+    # Agent-to-Agent Communication (NEW)
+    agent_messages: Optional[List[Dict[str, Any]]]  # Messages between agents
+    # Format: [{"from": "APIReference", "to": "Mermaid", "type": "data", "content": {...}}]
+
+    # Performance Metrics (NEW)
+    agent_metrics: Optional[Dict[str, Dict[str, Any]]]  # Per-agent metrics
+    blast_radius_report: Optional[Dict[str, Any]]  # Blast radius calculation
+    total_tokens_used: Optional[int]
+    total_duration_ms: Optional[float]
+
+    # Error Handling
+    error: Optional[str]
+    retry_count: int
+    failed_agents: Optional[List[str]]  # List of agents that failed
+
+    # Metadata
+    workflow_status: str  # pending, in_progress, completed, failed
+    current_agent: Optional[str]
diff --git a/DocuGenMicroagents/api/requirements.txt b/DocuGenMicroagents/api/requirements.txt
new file mode 100644
index 0000000000..0839d7c5a3
--- /dev/null
+++ b/DocuGenMicroagents/api/requirements.txt
@@ -0,0 +1,38 @@
+# Web Framework
+fastapi>=0.109.0
+uvicorn[standard]>=0.27.0
+python-multipart>=0.0.6
+sse-starlette>=1.6.5
+
+# Environment & Config
+python-dotenv>=1.0.0
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+
+# LangChain & LangGraph (Agentic Framework)
+langchain>=0.1.0
+langchain-openai>=0.0.5
+langgraph>=0.0.20
+langgraph-checkpoint-sqlite>=1.0.0
+langchain-community>=0.0.20
+
+# LLM APIs
+openai>=1.10.0
+httpx>=0.24.0
+requests>=2.31.0
+
+# Git Operations
+gitpython>=3.1.40
+
+# GitHub Integration
+PyGithub>=2.1.1
+
+# MCP (Model Context Protocol)
+mcp>=0.9.0
+
+# Code Analysis
+astroid>=3.0.0
+
+# Utilities
+aiofiles>=23.0.0
+aiosqlite>=0.20.0
diff --git a/DocuGenMicroagents/api/server.py b/DocuGenMicroagents/api/server.py
new file mode 100644
index 0000000000..c330743353
--- /dev/null
+++ b/DocuGenMicroagents/api/server.py
@@ -0,0 +1,563 @@
+"""
+FastAPI Server for DocuGen AI
+Provides REST API and SSE streaming for real-time agent visibility
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import uuid
+from contextlib import asynccontextmanager
+from typing import Dict, List
+
+# Disable output buffering for real-time log streaming
+sys.stdout.reconfigure(line_buffering=True)
+sys.stderr.reconfigure(line_buffering=True)
+
+from fastapi import FastAPI, BackgroundTasks, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from sse_starlette.sse import EventSourceResponse
+
+from config import settings
+from models import (
+    GenerateDocsRequest,
+    GenerateDocsResponse,
+    JobStatusResponse,
+    ProjectSelectionRequest,
+    ProjectSelectionResponse,
+    LogType,
+    get_log_manager
+)
+from workflow import get_workflow
+from agents.pr_agent_mcp import create_pr_with_mcp
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Job storage 
+job_storage: Dict[str, Dict] = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context for startup/shutdown"""
+    logger.info("DocuGen AI starting up...")
+    logger.info(f"Authentication mode: {settings.AUTH_MODE}")
+
+    # Check if GitHub token is configured for MCP PR creation
+    github_token = settings.GITHUB_TOKEN
+    if github_token:
+        logger.info("GitHub token configured - MCP PR creation enabled")
+    else:
+        logger.warning("GITHUB_TOKEN not configured - PR creation will be disabled")
+
+    yield
+    logger.info("DocuGen AI shutting down...")
+
+
+# Initialize FastAPI
+app = FastAPI(
+    title=settings.APP_TITLE,
+    description=settings.APP_DESCRIPTION,
+    version=settings.APP_VERSION,
+    lifespan=lifespan
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/")
+def root():
+    """Root endpoint"""
+    return {
+        "name": settings.APP_TITLE,
+        "version": settings.APP_VERSION,
+        "status": "running"
+    }
+
+
+@app.get("/health")
+def health_check():
+    """Health check"""
+    return {
+        "status": "healthy",
+        "auth_mode": settings.AUTH_MODE.value
+    }
+
+
+@app.post("/api/generate-docs", response_model=GenerateDocsResponse)
+async def generate_documentation(request: GenerateDocsRequest, background_tasks: BackgroundTasks):
+    """
+    Start documentation generation workflow
+
+    Returns job_id for tracking and SSE streaming
+    """
+    try:
+        job_id = str(uuid.uuid4())
+
+        # Initialize job
+        job_storage[job_id] = {
+            "repo_url": str(request.repo_url),
+            "status": "pending",
+            "workflow_paused": False,
+            "current_agent": None,
+            "final_readme": None,
+            "error": None,
+            "awaiting_project_selection": False,
+            "detected_projects": None
+        }
+
+        # Start workflow in background
+        background_tasks.add_task(run_workflow, job_id, str(request.repo_url))
+
+        logger.info(f"Documentation generation started: {job_id}")
+
+        return GenerateDocsResponse(
+            job_id=job_id,
+            status="started",
+            message="Documentation generation workflow started. Connect to SSE stream to monitor progress."
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to start workflow: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+async def run_workflow(job_id: str, repo_url: str):
+    """
+    Run the documentation workflow
+    Executes with human-in-the-loop interrupts
+    """
+    try:
+        workflow = await get_workflow()
+
+        # Initial state
+        initial_state = {
+            "job_id": job_id,
+            "repo_url": repo_url,
+            "repo_path": None,
+            "repo_name": None,
+            "default_branch": None,
+            "is_monorepo": None,
+            "detected_projects": None,
+            "skipped_folders": None,  # List of skipped folders with reasons
+            "selected_projects": None,
+            "awaiting_project_selection": None,
+            "is_subfolder_target": None,  # NEW: Track if user provided subfolder URL
+            "file_structure": None,
+            "languages": None,
+            "dependencies": None,
+            "key_files": None,
+            "code_summary": None,
+            "project_type": None,
+            "documentation_sections": None,
+            "section_instructions": None,
+            "readme_sections": None,
+            "mermaid_diagrams": None,
+            "final_readme": None,
+            "error": None,
+            "retry_count": 0,
+            "workflow_status": "pending",
+            "current_agent": None
+        }
+
+        # Run workflow (will interrupt after each agent)
+        config = {"configurable": {"thread_id": job_id}}
+
+        # Execute workflow - it will pause at interrupt points
+        async for event in workflow.graph.astream(initial_state, config):
+            logger.info(f"Workflow event: {event}")
+
+            # Update job storage with latest state
+            for node_name, node_state in event.items():
+                if isinstance(node_state, dict):
+                    # Always update status from workflow_status
+                    workflow_status = node_state.get("workflow_status", "in_progress")
+                    job_storage[job_id]["status"] = workflow_status
+                    job_storage[job_id]["current_agent"] = node_state.get("current_agent")
+
+                    # Store repo_name for PR creation
+                    if node_state.get("repo_name"):
+                        job_storage[job_id]["repo_name"] = node_state["repo_name"]
+
+                    # CRITICAL: Update final_readme whenever present
+                    if node_state.get("final_readme"):
+                        job_storage[job_id]["final_readme"] = node_state["final_readme"]
+                        logger.info(f"✅ Updated job_storage[{job_id}]['final_readme'] = {len(node_state['final_readme'])} chars (workflow_status={workflow_status})")
+
+                    if node_state.get("error"):
+                        job_storage[job_id]["error"] = node_state["error"]
+
+                    # Handle project selection
+                    if node_state.get("awaiting_project_selection"):
+                        job_storage[job_id]["awaiting_project_selection"] = True
+                        job_storage[job_id]["detected_projects"] = node_state.get("detected_projects")
+                        job_storage[job_id]["skipped_folders"] = node_state.get("skipped_folders", [])
+
+                        # DEBUG: Log what we're storing
+                        logger.info(f"DEBUG server.py: Storing skipped_folders: {job_storage[job_id]['skipped_folders']}")
+                        logger.info(f"DEBUG server.py: Number of skipped folders: {len(job_storage[job_id]['skipped_folders'])}")
+
+                        logger.info(f"Workflow paused for project selection: {job_id}")
+                        return  # Stop workflow execution until user selects projects
+
+        logger.info(f"Workflow completed for job: {job_id}")
+
+    except Exception as e:
+        logger.error(f"Workflow failed for job {job_id}: {e}", exc_info=True)
+        job_storage[job_id]["status"] = "failed"
+        job_storage[job_id]["error"] = str(e)
+
+
+@app.get("/api/status/{job_id}", response_model=JobStatusResponse)
+def get_job_status(job_id: str):
+    """Get current job status"""
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    job = job_storage[job_id]
+
+    # DEBUG: Log what we're returning
+    skipped = job.get("skipped_folders", [])
+    logger.info(f"DEBUG get_job_status: Returning skipped_folders with {len(skipped)} items")
+    logger.info(f"DEBUG get_job_status: skipped_folders = {skipped}")
+
+    return JobStatusResponse(
+        job_id=job_id,
+        status=job["status"],
+        progress_percentage=50,  # Simplified
+        current_agent=job.get("current_agent"),
+        error_message=job.get("error"),
+        readme_preview=job.get("final_readme", "")[:500] if job.get("final_readme") else None,
+        awaiting_project_selection=job.get("awaiting_project_selection", False),
+        detected_projects=job.get("detected_projects"),
+        skipped_folders=job.get("skipped_folders", [])
+    )
+
+
+@app.get("/api/logs/{job_id}")
+async def stream_logs(job_id: str):
+    """
+    Server-Sent Events (SSE) endpoint for streaming agent activity logs
+
+    Client usage:
+    ```javascript
+    const eventSource = new EventSource(`/api/logs/${jobId}`)
+    eventSource.onmessage = (event) => {
+        const log = JSON.parse(event.data)
+        console.log(log)
+    }
+    ```
+    """
+    log_manager = get_log_manager()
+
+    async def event_generator():
+        """Generate SSE events from log queue"""
+        # Subscribe to logs for this job
+        queue = await log_manager.subscribe(job_id)
+
+        try:
+            while True:
+                # Wait for new log
+                try:
+                    log = await asyncio.wait_for(queue.get(), timeout=30.0)
+
+                    # Convert log to JSON
+                    log_data = {
+                        "timestamp": log.timestamp.isoformat(),
+                        "log_type": log.log_type.value,
+                        "agent_name": log.agent_name,
+                        "message": log.message,
+                        "metadata": log.metadata
+                    }
+
+                    yield {
+                        "data": json.dumps(log_data)
+                    }
+
+                except asyncio.TimeoutError:
+                    # Send keep-alive ping
+                    yield {
+                        "data": json.dumps({"type": "keepalive"})
+                    }
+
+        except asyncio.CancelledError:
+            logger.info(f"SSE stream cancelled for job: {job_id}")
+        finally:
+            # Unsubscribe
+            await log_manager.unsubscribe(job_id, queue)
+
+    return EventSourceResponse(event_generator())
+
+
+@app.post("/api/approve/{job_id}")
+async def approve_agent_output(job_id: str):
+    """
+    Approve current agent's output and continue workflow
+    Used for human-in-the-loop control
+    """
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    # Resume workflow by invoking with continue command
+    workflow = await get_workflow()
+    config = {"configurable": {"thread_id": job_id}}
+
+    try:
+        # Continue workflow from last checkpoint
+        state = workflow.graph.get_state(config)
+
+        # Resume execution
+        async for event in workflow.graph.astream(None, config):
+            logger.info(f"Resumed workflow: {event}")
+
+        return {"status": "approved", "message": "Workflow continued"}
+
+    except Exception as e:
+        logger.error(f"Failed to continue workflow: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/reject/{job_id}")
+async def reject_agent_output(job_id: str, feedback: str = ""):
+    """
+    Reject current agent's output and provide feedback
+    Agent will retry with feedback
+    """
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    # Update state with feedback and retry
+    workflow = await get_workflow()
+    config = {"configurable": {"thread_id": job_id}}
+
+    try:
+        state = workflow.graph.get_state(config)
+
+        # Update state with feedback
+        # (Implementation depends on how you want to handle retries)
+
+        return {"status": "rejected", "message": "Agent will retry with feedback"}
+
+    except Exception as e:
+        logger.error(f"Failed to reject and retry: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/select-projects/{job_id}", response_model=ProjectSelectionResponse)
+async def select_projects(job_id: str, request: ProjectSelectionRequest, background_tasks: BackgroundTasks):
+    """
+    Submit user's project selection and resume workflow
+    """
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    job = job_storage[job_id]
+
+    if not job.get("awaiting_project_selection"):
+        raise HTTPException(status_code=400, detail="Job is not awaiting project selection")
+
+    # Validate: 1 project can be selected
+    if len(request.selected_project_paths) != 1:
+        project_word = "project" if len(request.selected_project_paths) == 1 else "projects"
+        raise HTTPException(
+            status_code=400,
+            detail=f" {len(request.selected_project_paths)} {project_word} are selected! Please select one project, as single-project documentation is supported."
+        )
+
+    try:
+        # Update job storage
+        job["awaiting_project_selection"] = False
+        job_storage[job_id] = job
+
+        logger.info(f"User selected {len(request.selected_project_paths)} projects for job {job_id}")
+
+        # Resume workflow with selected projects
+        background_tasks.add_task(resume_workflow, job_id, request.selected_project_paths)
+
+        return ProjectSelectionResponse(
+            status="accepted",
+            message=f"Selected {len(request.selected_project_paths)} project(s). Resuming documentation generation..."
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to process project selection: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+async def resume_workflow(job_id: str, selected_projects: List[str]):
+    """
+    Resume workflow after user selects projects
+    """
+    try:
+        workflow = await get_workflow()
+        config = {"configurable": {"thread_id": job_id}}
+
+        # Log selection
+        log_manager = get_log_manager()
+        await log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message=f"✅ User selected {len(selected_projects)} project(s). Continuing workflow..."
+        )
+
+        # DEBUG: Log the selected projects
+        logger.info(f"DEBUG: Updating state with selected_projects = {selected_projects}")
+
+        # Update the state directly in the graph
+        await workflow.graph.aupdate_state(
+            config,
+            {
+                "selected_projects": selected_projects,
+                "awaiting_project_selection": False
+            }
+        )
+
+        # Resume workflow from updated state
+        async for event in workflow.graph.astream(None, config):
+            logger.info(f"Resumed workflow event: {event}")
+
+            # Update job storage
+            for node_name, node_state in event.items():
+                if isinstance(node_state, dict):
+                    workflow_status = node_state.get("workflow_status", "in_progress")
+                    job_storage[job_id]["status"] = workflow_status
+                    job_storage[job_id]["current_agent"] = node_state.get("current_agent")
+
+                    # Store repo_name for PR creation
+                    if node_state.get("repo_name"):
+                        job_storage[job_id]["repo_name"] = node_state["repo_name"]
+
+                    # CRITICAL: Update final_readme whenever present
+                    if node_state.get("final_readme"):
+                        job_storage[job_id]["final_readme"] = node_state["final_readme"]
+                        logger.info(f"✅ [RESUME] Updated job_storage[{job_id}]['final_readme'] = {len(node_state['final_readme'])} chars (workflow_status={workflow_status})")
+
+                    if node_state.get("error"):
+                        job_storage[job_id]["error"] = node_state["error"]
+
+        logger.info(f"Workflow resumed and completed for job: {job_id}")
+        logger.info(f"✅ Final job_storage[{job_id}] has final_readme: {'final_readme' in job_storage[job_id]}")
+
+    except Exception as e:
+        logger.error(f"Failed to resume workflow: {e}", exc_info=True)
+        job_storage[job_id]["status"] = "failed"
+        job_storage[job_id]["error"] = str(e)
+
+
+@app.get("/api/download/{job_id}")
+def download_readme(job_id: str):
+    """Download generated README.md"""
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    job = job_storage[job_id]
+
+    if not job.get("final_readme"):
+        raise HTTPException(status_code=400, detail="README not ready yet")
+
+    from fastapi.responses import Response
+
+    return Response(
+        content=job["final_readme"],
+        media_type="text/markdown",
+        headers={
+            "Content-Disposition": "attachment; filename=README.md"
+        }
+    )
+
+
+@app.post("/api/create-pr/{job_id}")
+async def create_pull_request(job_id: str):
+    """
+    Create a GitHub Pull Request using TRUE MCP Protocol
+    Connects to official GitHub MCP server via stdio
+    """
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    job = job_storage[job_id]
+
+    if not job.get("final_readme"):
+        raise HTTPException(status_code=400, detail="README not ready yet")
+
+    # Check if GitHub token is configured
+    github_token = settings.GITHUB_TOKEN
+    if not github_token:
+        raise HTTPException(
+            status_code=503,
+            detail="GitHub integration not configured. Please set GITHUB_TOKEN in environment variables."
+        )
+
+    try:
+        # Extract repo info from URL
+        repo_url = job["repo_url"]
+
+        # Parse GitHub repo from URL
+        # Expected format: https://github.com/owner/repo or https://github.com/owner/repo/tree/branch/...
+        if "github.com" not in repo_url:
+            raise HTTPException(status_code=400, detail="Only GitHub repositories are supported for PR creation")
+
+        # Parse the full GitHub URL to extract owner, repo, and branch
+        from services.git_service import parse_github_url
+        parsed_url = parse_github_url(repo_url)
+
+        repo_full_name = f"{parsed_url['owner']}/{parsed_url['repo']}"
+        base_branch = parsed_url['branch']  # Extract branch from URL (e.g., "dev")
+
+        # Extract project name from workflow state (already set correctly)
+        # Use the actual repo_name from job storage which comes from workflow
+        project_name = job.get("repo_name", parsed_url['display_name'])
+
+        # Call MCP-based PR creation
+        result = await create_pr_with_mcp(
+            repo_full_name=repo_full_name,
+            readme_content=job["final_readme"],
+            project_name=project_name,
+            base_branch=base_branch,
+            github_token=github_token,
+            job_id=job_id
+        )
+
+        if result["success"]:
+            return {
+                "status": "success",
+                "message": "Pull request created successfully via MCP",
+                "pr_url": result["pr_url"],
+                "branch_name": result["branch_name"]
+            }
+        else:
+            return {
+                "status": "error",
+                "message": f"Failed to create PR via MCP: {result['output']}",
+                "details": result["output"]
+            }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to create PR via MCP: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to create PR via MCP: {str(e)}")
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        app,
+        host=settings.HOST,
+        port=settings.API_PORT,
+        log_level="info"
+    )
diff --git a/DocuGenMicroagents/api/services/__init__.py b/DocuGenMicroagents/api/services/__init__.py
new file mode 100644
index 0000000000..33f8d3b588
--- /dev/null
+++ b/DocuGenMicroagents/api/services/__init__.py
@@ -0,0 +1,11 @@
+"""
+Services for DocuGen AI
+"""
+
+from .llm_service import get_llm
+from .git_service import GitService
+
+__all__ = [
+    "get_llm",
+    "GitService"
+]
diff --git a/DocuGenMicroagents/api/services/git_service.py b/DocuGenMicroagents/api/services/git_service.py
new file mode 100644
index 0000000000..69abd38111
--- /dev/null
+++ b/DocuGenMicroagents/api/services/git_service.py
@@ -0,0 +1,288 @@
+"""
+Git Service - Handles repository cloning and cleanup
+"""
+
+import os
+import shutil
+import logging
+import re
+import requests
+from typing import Tuple, Dict, Optional, Callable
+from git import Repo, GitCommandError, RemoteProgress
+from config import settings
+import uuid
+
+logger = logging.getLogger(__name__)
+
+
+def parse_github_url(url: str) -> Dict[str, Optional[str]]:
+    """
+    Parse GitHub URL to extract components
+
+    Supports:
+    - Base repo: https://github.com/owner/repo
+    - Base repo with .git: https://github.com/owner/repo.git
+    - Tree URL: https://github.com/owner/repo/tree/branch
+    - Subfolder URL: https://github.com/owner/repo/tree/branch/path/to/folder
+
+    Args:
+        url: GitHub URL
+
+    Returns:
+        Dict with keys: owner, repo, branch, subfolder, clone_url, is_subfolder
+
+    Raises:
+        ValueError: If URL is invalid
+    """
+    # Remove trailing slashes
+    url = url.rstrip('/')
+
+    # Pattern: https://github.com/owner/repo[.git][/tree/branch[/path]]
+    pattern = r'^https?://github\.com/([^/]+)/([^/]+?)(?:\.git)?(?:/tree/([^/]+)(?:/(.*))?)?$'
+
+    match = re.match(pattern, url)
+
+    if not match:
+        raise ValueError(
+            f"Invalid GitHub URL format. Expected: https://github.com/owner/repo[/tree/branch[/path]]\n"
+            f"Got: {url}"
+        )
+
+    owner, repo, branch, subfolder = match.groups()
+
+    # Clean repo name (remove .git if present)
+    repo = repo.replace('.git', '')
+
+    result = {
+        "owner": owner,
+        "repo": repo,
+        "branch": branch or "main",  # Default to main if not specified
+        "subfolder": subfolder if subfolder else None,
+        "clone_url": f"https://github.com/{owner}/{repo}.git",
+        "is_subfolder": bool(subfolder),
+        "display_name": subfolder.split('/')[-1] if subfolder else repo
+    }
+
+    logger.info(f"Parsed URL: {url} -> {result}")
+
+    return result
+
+
+class CloneProgress(RemoteProgress):
+    """Progress reporter for git clone operations"""
+
+    def __init__(self, callback: Optional[Callable[[str], None]] = None):
+        super().__init__()
+        self.callback = callback
+        self._last_message = ""
+
+    def update(self, op_code, cur_count, max_count=None, message=''):
+        """Called by GitPython during clone operation"""
+        if self.callback:
+            # Parse operation
+            if op_code & self.COUNTING:
+                msg = f"📊 Counting objects: {cur_count}"
+            elif op_code & self.COMPRESSING:
+                msg = f"🗜️ Compressing objects: {cur_count}/{max_count}" if max_count else f"🗜️ Compressing objects: {cur_count}"
+            elif op_code & self.RECEIVING:
+                percentage = int((cur_count / max_count * 100)) if max_count else 0
+                msg = f"⬇️ Receiving objects: {cur_count}/{max_count} ({percentage}%)"
+            elif op_code & self.RESOLVING:
+                percentage = int((cur_count / max_count * 100)) if max_count else 0
+                msg = f"🔧 Resolving deltas: {cur_count}/{max_count} ({percentage}%)"
+            else:
+                msg = f"⏳ Cloning: {cur_count}"
+
+            # Only report if message changed (avoid spam)
+            if msg != self._last_message:
+                self._last_message = msg
+                self.callback(msg)
+
+
+class GitService:
+    """Service for Git operations"""
+
+    def __init__(self):
+        self.temp_dir = settings.TEMP_REPO_DIR
+        os.makedirs(self.temp_dir, exist_ok=True)
+
+    def clone_repository(
+        self,
+        repo_url: str,
+        branch: Optional[str] = None,
+        progress_callback: Optional[Callable[[str], None]] = None
+    ) -> Tuple[str, Dict[str, str]]:
+        """
+        Clone a Git repository to a temporary directory
+
+        Args:
+            repo_url: GitHub repository URL
+            branch: Optional branch name to checkout after cloning
+            progress_callback: Optional callback for progress updates
+
+        Returns:
+            Tuple of (repo_path, metadata_dict)
+        """
+        try:
+            # Generate unique directory name
+            repo_id = str(uuid.uuid4())
+            repo_path = os.path.join(self.temp_dir, repo_id)
+
+            logger.info(f"Cloning repository: {repo_url}")
+
+            # Check repository size before cloning
+            try:
+                # Extract owner and repo name from URL
+                # Format: https://github.com/owner/repo or https://github.com/owner/repo.git
+                parts = repo_url.rstrip('/').replace('.git', '').split('/')
+                if 'github.com' in repo_url and len(parts) >= 2:
+                    owner = parts[-2]
+                    repo_name = parts[-1]
+
+                    # Query GitHub API for repo info
+                    api_url = f"https://api.github.com/repos/{owner}/{repo_name}"
+                    headers = {}
+                    if settings.GITHUB_TOKEN:
+                        headers['Authorization'] = f'token {settings.GITHUB_TOKEN}'
+
+                    response = requests.get(api_url, headers=headers, timeout=10)
+                    if response.status_code == 200:
+                        repo_data = response.json()
+                        repo_size_kb = repo_data.get('size', 0)  # GitHub returns size in KB
+                        repo_size_bytes = repo_size_kb * 1024
+
+                        max_size_gb = settings.MAX_REPO_SIZE / (1024 ** 3)
+                        if repo_size_bytes > settings.MAX_REPO_SIZE:
+                            error_msg = f"Repository size ({repo_size_bytes / (1024 ** 3):.2f}GB) exceeds maximum allowed size ({max_size_gb:.0f}GB). Please try a smaller repository."
+                            logger.error(error_msg)
+                            if progress_callback:
+                                progress_callback(f"❌ {error_msg}")
+                            raise ValueError(error_msg)
+                        else:
+                            logger.info(f"Repository size check passed: {repo_size_bytes / (1024 ** 3):.2f}GB")
+                            if progress_callback:
+                                progress_callback(f"✅ Repository size: {repo_size_bytes / (1024 ** 3):.2f}GB")
+            except requests.RequestException as e:
+                # Don't fail if we can't check size, just log warning
+                logger.warning(f"Could not verify repository size: {e}")
+            except ValueError:
+                # Re-raise size limit errors
+                raise
+
+            if progress_callback:
+                progress_callback(f"🚀 Starting clone of {repo_url}")
+
+            # Clone the repository with progress tracking
+            progress = CloneProgress(callback=progress_callback)
+
+            # Add GitHub PAT authentication for private repos
+            clone_url = repo_url
+            if settings.GITHUB_TOKEN and 'github.com' in repo_url:
+                # Inject GitHub PAT into URL: https://TOKEN@github.com/owner/repo.git
+                clone_url = repo_url.replace('https://github.com/', f'https://{settings.GITHUB_TOKEN}@github.com/')
+                logger.info(f"Using authenticated clone for private repository")
+
+            repo = Repo.clone_from(clone_url, repo_path, progress=progress)
+
+            if progress_callback:
+                progress_callback(f"✅ Clone completed successfully")
+
+            # Checkout specified branch if provided
+            if branch:
+                try:
+                    current_branch = None
+                    try:
+                        current_branch = repo.active_branch.name
+                    except TypeError:
+                        # Detached HEAD state or no branches yet
+                        pass
+
+                    # Only checkout if not already on the requested branch
+                    if current_branch != branch:
+                        # Check if branch exists locally
+                        if branch in [ref.name for ref in repo.heads]:
+                            repo.git.checkout(branch)
+                        else:
+                            # Create local branch tracking remote branch
+                            repo.git.checkout('-b', branch, f'origin/{branch}')
+
+                        logger.info(f"Checked out branch: {branch}")
+                        if progress_callback:
+                            progress_callback(f"✅ Checked out branch: {branch}")
+                except Exception as e:
+                    logger.warning(f"Failed to checkout branch {branch}: {e}")
+                    if progress_callback:
+                        progress_callback(f"⚠️ Warning: Could not checkout branch {branch}, using default branch")
+
+            # Extract metadata
+            metadata = {
+                "repo_url": repo_url,
+                "repo_name": repo_url.split('/')[-1].replace('.git', ''),
+                "default_branch": repo.active_branch.name,
+                "repo_path": repo_path
+            }
+
+            logger.info(f"Repository cloned successfully to: {repo_path}")
+
+            return repo_path, metadata
+
+        except GitCommandError as e:
+            logger.error(f"Git clone failed: {e}")
+
+            # Parse git error and provide user-friendly message
+            error_message = str(e)
+            user_friendly_message = None
+
+            # Exit code 128: Repository not found or access denied
+            if "exit code(128)" in error_message:
+                if "not found" in error_message.lower() or "could not read" in error_message.lower():
+                    user_friendly_message = "Repository not found. Please check the URL and verify the repository exists."
+                elif "authentication" in error_message.lower() or "permission" in error_message.lower():
+                    user_friendly_message = "Access denied. This repository may be private or you may not have permission to access it."
+                else:
+                    user_friendly_message = "Repository not found or access denied. Please verify the URL and your permissions."
+
+            # Exit code 403: Rate limit or access forbidden
+            elif "403" in error_message:
+                user_friendly_message = "Access forbidden. You may have hit GitHub's rate limit or don't have permission to access this repository."
+
+            # Network errors
+            elif "connection" in error_message.lower() or "network" in error_message.lower():
+                user_friendly_message = "Network error. Please check your internet connection and try again."
+
+            # Use user-friendly message if detected, otherwise use generic message
+            final_message = user_friendly_message or f"Failed to clone repository: {str(e)}"
+
+            if progress_callback:
+                progress_callback(f"❌ {final_message}")
+
+            raise ValueError(final_message)
+
+        except Exception as e:
+            logger.error(f"Unexpected error cloning repository: {e}")
+            error_message = f"Unexpected error while cloning: {str(e)}"
+
+            if progress_callback:
+                progress_callback(f"❌ {error_message}")
+
+            raise ValueError(error_message)
+
+    def cleanup_repository(self, repo_path: str) -> bool:
+        """
+        Clean up cloned repository
+
+        Args:
+            repo_path: Path to the repository
+
+        Returns:
+            True if successful
+        """
+        try:
+            if os.path.exists(repo_path):
+                shutil.rmtree(repo_path, ignore_errors=True)
+                logger.info(f"Cleaned up repository: {repo_path}")
+                return True
+            return False
+        except Exception as e:
+            logger.warning(f"Failed to cleanup repository {repo_path}: {e}")
+            return False
diff --git a/DocuGenMicroagents/api/services/keycloak_client.py b/DocuGenMicroagents/api/services/keycloak_client.py
new file mode 100644
index 0000000000..83b612fea5
--- /dev/null
+++ b/DocuGenMicroagents/api/services/keycloak_client.py
@@ -0,0 +1,154 @@
+"""
+Keycloak Authentication Client for DocuGen
+Handles token acquisition and management for enterprise inference endpoints
+"""
+
+import logging
+import requests
+import httpx
+from typing import Optional
+from langchain_openai import ChatOpenAI
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class KeycloakClient:
+    """
+    Client for handling Keycloak authentication and creating LLM clients
+
+    Features:
+    - Persistent token storage
+    - Automatic token acquisition via client_credentials grant
+    - SSL verification bypass for internal endpoints
+    - httpx client management for API calls
+    """
+
+    def __init__(self):
+        """Initialize Keycloak client and authenticate"""
+        self.base_url = settings.BASE_URL
+        self.token = None
+        self.http_client = None
+
+        # Authenticate immediately
+        self._authenticate()
+
+    def _authenticate(self) -> None:
+        """
+        Authenticate with Keycloak and obtain access token
+
+        Token endpoint: {BASE_URL}/token
+        Grant type: client_credentials
+
+        Raises:
+            Exception: If authentication fails
+        """
+        if not self.base_url:
+            raise ValueError("BASE_URL is required for Keycloak authentication")
+
+        if not settings.KEYCLOAK_CLIENT_SECRET:
+            raise ValueError("KEYCLOAK_CLIENT_SECRET is required for Keycloak authentication")
+
+        token_url = f"{self.base_url}/token"
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": settings.KEYCLOAK_CLIENT_ID,
+            "client_secret": settings.KEYCLOAK_CLIENT_SECRET,
+        }
+
+        try:
+            logger.info(f"Authenticating with Keycloak at: {token_url}")
+
+            # Disable SSL verification for internal endpoints (like -k in curl)
+            response = requests.post(token_url, data=payload, verify=False)
+
+            if response.status_code == 200:
+                self.token = response.json().get("access_token")
+                if self.token:
+                    logger.info(f"✓ Access token obtained: {self.token[:20]}...")
+                else:
+                    logger.error("❌ No access token in response")
+                    raise Exception("Access token not found in response")
+
+                # Create httpx client with SSL verification disabled
+                self.http_client = httpx.Client(verify=False)
+                logger.info("✓ httpx client initialized")
+
+            else:
+                logger.error(f"❌ Authentication failed: {response.status_code} - {response.text}")
+                raise Exception(f"Authentication failed: {response.status_code}")
+
+        except Exception as e:
+            logger.error(f"❌ Error during Keycloak authentication: {str(e)}")
+            raise
+
+    def get_llm_client(self, model_name: str, temperature: float = 0.7, max_tokens: int = 2000) -> ChatOpenAI:
+        """
+        Get LangChain ChatOpenAI client configured with Keycloak token
+
+        Args:
+            model_name: Model name to use (e.g., "Qwen/Qwen2.5-32B-Instruct", "Llama-3.1-8B-Instruct")
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+
+        Returns:
+            ChatOpenAI instance configured for Keycloak endpoint
+
+        Raises:
+            ValueError: If not authenticated
+        """
+        if not self.is_authenticated():
+            raise ValueError("Keycloak client is not authenticated")
+
+        logger.info(f"Creating LLM client for model: {model_name}")
+
+        # Create ChatOpenAI with Keycloak token as API key
+        return ChatOpenAI(
+            model=model_name,
+            temperature=temperature,
+            openai_api_key=self.token,
+            openai_api_base=f"{self.base_url}/v1",
+            max_tokens=max_tokens,
+            http_client=self.http_client
+        )
+
+    def is_authenticated(self) -> bool:
+        """
+        Check if client is authenticated
+
+        Returns:
+            True if token and http_client are available
+        """
+        return self.token is not None and self.http_client is not None
+
+    def __del__(self):
+        """Cleanup: Close httpx client on deletion"""
+        if self.http_client:
+            try:
+                self.http_client.close()
+                logger.debug("httpx client closed")
+            except Exception as e:
+                logger.warning(f"Error closing httpx client: {e}")
+
+
+# Global Keycloak client instance (singleton pattern)
+_keycloak_client: Optional[KeycloakClient] = None
+
+
+def get_keycloak_client() -> KeycloakClient:
+    """
+    Get or create the global Keycloak client instance
+
+    Uses singleton pattern to reuse token across multiple LLM requests
+
+    Returns:
+        KeycloakClient instance
+
+    Raises:
+        Exception: If authentication fails
+    """
+    global _keycloak_client
+    if _keycloak_client is None:
+        logger.info("Initializing global Keycloak client")
+        _keycloak_client = KeycloakClient()
+    return _keycloak_client
diff --git a/DocuGenMicroagents/api/services/llm_service.py b/DocuGenMicroagents/api/services/llm_service.py
new file mode 100644
index 0000000000..282719f3e3
--- /dev/null
+++ b/DocuGenMicroagents/api/services/llm_service.py
@@ -0,0 +1,74 @@
+"""
+LLM Service - Handles LLM initialization based on authentication mode
+Supports GenAI Gateway and Keycloak authentication
+"""
+
+import logging
+from typing import Optional
+from langchain_openai import ChatOpenAI
+from config import settings, AuthMode
+
+logger = logging.getLogger(__name__)
+
+
+def get_llm(model_name: Optional[str] = None, temperature: float = 0.7) -> ChatOpenAI:
+    """
+    Get LLM instance based on authentication mode
+
+    Args:
+        model_name: Override model name (required - specify which agent model to use)
+        temperature: Temperature for generation
+
+    Returns:
+        ChatOpenAI instance configured for the auth mode
+    """
+    if model_name is None:
+        raise ValueError("model_name is required. Use settings.CODE_EXPLORER_MODEL, settings.PLANNER_MODEL, etc.")
+
+    model_name = model_name
+
+    if settings.AUTH_MODE == AuthMode.GENAI_GATEWAY:
+        # GenAI Gateway
+        if not settings.GENAI_GATEWAY_URL or not settings.GENAI_GATEWAY_API_KEY:
+            raise ValueError("GENAI_GATEWAY_URL and API_KEY are required for GenAI Gateway mode")
+
+        logger.info(f"Initializing GenAI Gateway LLM with model: {model_name}")
+
+        # Create httpx client with SSL verification disabled for self-signed certs
+        import httpx
+        http_client = httpx.Client(verify=False)
+        async_http_client = httpx.AsyncClient(verify=False)
+
+        return ChatOpenAI(
+            model=model_name,
+            temperature=temperature,
+            openai_api_key=settings.GENAI_GATEWAY_API_KEY,
+            openai_api_base=settings.GENAI_GATEWAY_URL,
+            max_tokens=settings.AGENT_MAX_TOKENS,
+            http_client=http_client,
+            http_async_client=async_http_client
+        )
+
+    elif settings.AUTH_MODE == AuthMode.KEYCLOAK:
+        # Keycloak Enterprise Inference (Robust implementation with persistent token)
+        if not all([settings.BASE_URL, settings.KEYCLOAK_CLIENT_ID, settings.KEYCLOAK_CLIENT_SECRET]):
+            raise ValueError("Keycloak configuration incomplete")
+
+        logger.info(f"Initializing Keycloak LLM with model: {model_name}")
+
+        # Use dedicated Keycloak client with token management
+        from services.keycloak_client import get_keycloak_client
+
+        try:
+            keycloak_client = get_keycloak_client()
+            return keycloak_client.get_llm_client(
+                model_name=model_name,
+                temperature=temperature,
+                max_tokens=settings.AGENT_MAX_TOKENS
+            )
+        except Exception as e:
+            logger.error(f"Failed to initialize Keycloak LLM client: {e}")
+            raise ValueError(f"Keycloak authentication failed: {str(e)}")
+
+    else:
+        raise ValueError(f"Unknown authentication mode: {settings.AUTH_MODE}")
diff --git a/DocuGenMicroagents/api/tools/__init__.py b/DocuGenMicroagents/api/tools/__init__.py
new file mode 100644
index 0000000000..d7897a096d
--- /dev/null
+++ b/DocuGenMicroagents/api/tools/__init__.py
@@ -0,0 +1,31 @@
+"""
+LangChain Tools for repository analysis
+These tools are used by agents to interact with code repositories
+"""
+
+from .repo_tools import (
+    list_directory_tool,
+    read_file_tool,
+    detect_languages_tool,
+    extract_dependencies_tool,
+    analyze_code_structure_tool
+)
+
+from .new_analysis_tools import (
+    analyze_call_graph_tool,
+    find_error_handlers_tool,
+    analyze_exceptions_tool,
+    extract_env_vars_tool
+)
+
+__all__ = [
+    "list_directory_tool",
+    "read_file_tool",
+    "detect_languages_tool",
+    "extract_dependencies_tool",
+    "analyze_code_structure_tool",
+    "analyze_call_graph_tool",
+    "find_error_handlers_tool",
+    "analyze_exceptions_tool",
+    "extract_env_vars_tool"
+]
diff --git a/DocuGenMicroagents/api/tools/new_analysis_tools.py b/DocuGenMicroagents/api/tools/new_analysis_tools.py
new file mode 100644
index 0000000000..c7fffbf0c3
--- /dev/null
+++ b/DocuGenMicroagents/api/tools/new_analysis_tools.py
@@ -0,0 +1,443 @@
+"""
+New Analysis Tools for Micro-Agent Architecture
+
+Four specialized tools for code analysis:
+1. analyze_call_graph - Python function call relationships
+2. find_error_handlers - Exception handling patterns
+3. analyze_exceptions - Error handling analysis
+4. extract_env_vars - Environment variable extraction
+
+All tools use RepoReadService for cached, bounded file reads
+"""
+
+import os
+import ast
+import re
+import json
+import logging
+from typing import Dict, List, Set, Optional
+from pathlib import Path
+from langchain.tools import tool
+
+logger = logging.getLogger(__name__)
+
+
+@tool
+def analyze_call_graph_tool(repo_path: str, entry_file: str) -> str:
+    """
+    Analyze Python function call relationships to build call graph.
+
+    Extracts which functions call which other functions, useful for
+    understanding code flow and dependencies.
+
+    Args:
+        repo_path: Absolute path to repository root
+        entry_file: Relative path to Python file to analyze
+
+    Returns:
+        JSON string with call graph data
+    """
+    try:
+        full_path = os.path.normpath(os.path.join(repo_path, entry_file))
+
+        # Security check
+        if not full_path.startswith(os.path.normpath(repo_path)):
+            return json.dumps({"error": "Access denied - path traversal detected"})
+
+        if not os.path.exists(full_path):
+            return json.dumps({"error": f"File not found: {entry_file}"})
+
+        if not entry_file.endswith('.py'):
+            return json.dumps({"error": "Only Python files supported for call graph analysis"})
+
+        # Read file (respects RepoReadService caps via shared config)
+        with open(full_path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+
+        # Parse AST
+        try:
+            tree = ast.parse(content)
+        except SyntaxError as e:
+            return json.dumps({
+                "error": f"Python syntax error: {str(e)}",
+                "file": entry_file
+            })
+
+        # Extract function definitions and calls
+        functions = {}
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                func_name = node.name
+                calls = []
+
+                # Find function calls within this function
+                for child in ast.walk(node):
+                    if isinstance(child, ast.Call):
+                        if isinstance(child.func, ast.Name):
+                            calls.append(child.func.id)
+                        elif isinstance(child.func, ast.Attribute):
+                            calls.append(f"{child.func.value.id if hasattr(child.func.value, 'id') else '?'}.{child.func.attr}")
+
+                functions[func_name] = {
+                    "calls": list(set(calls)),  # Deduplicate
+                    "call_count": len(calls),
+                    "line_number": node.lineno
+                }
+
+        # Build graph structure
+        edges = []
+        for func, data in functions.items():
+            for called_func in data["calls"]:
+                # Only include edges to other functions in this file
+                if called_func in functions:
+                    edges.append({"from": func, "to": called_func})
+
+        result = {
+            "file": entry_file,
+            "functions": functions,
+            "edges": edges,
+            "function_count": len(functions),
+            "edge_count": len(edges)
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error analyzing call graph for {entry_file}: {e}")
+        return json.dumps({"error": f"Analysis failed: {str(e)}"})
+
+
+@tool
+def find_error_handlers_tool(repo_path: str) -> str:
+    """
+    Find exception handlers (try/except blocks) across Python files.
+
+    Identifies error handling patterns and which exceptions are caught.
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        JSON string with error handler locations and types
+    """
+    try:
+        error_handlers = []
+        files_scanned = 0
+        max_files = 50  # Limit scan to prevent timeout
+
+        # Walk repository
+        for root, dirs, files in os.walk(repo_path):
+            # Filter ignored directories
+            dirs[:] = [d for d in dirs if d not in {
+                '.git', '__pycache__', 'node_modules', '.venv', 'venv',
+                'dist', 'build', 'target', 'coverage'
+            }]
+
+            for file in files:
+                if not file.endswith('.py'):
+                    continue
+
+                if files_scanned >= max_files:
+                    break
+
+                file_path = os.path.join(root, file)
+                rel_path = os.path.relpath(file_path, repo_path)
+
+                try:
+                    with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                        content = f.read()
+
+                    # Parse AST
+                    tree = ast.parse(content)
+
+                    # Find try/except blocks
+                    for node in ast.walk(tree):
+                        if isinstance(node, ast.Try):
+                            exceptions_caught = []
+
+                            for handler in node.handlers:
+                                if handler.type:
+                                    if isinstance(handler.type, ast.Name):
+                                        exceptions_caught.append(handler.type.id)
+                                    elif isinstance(handler.type, ast.Tuple):
+                                        for exc in handler.type.elts:
+                                            if isinstance(exc, ast.Name):
+                                                exceptions_caught.append(exc.id)
+                                else:
+                                    exceptions_caught.append("Exception")  # Bare except
+
+                            error_handlers.append({
+                                "file": rel_path,
+                                "line": node.lineno,
+                                "exceptions": exceptions_caught,
+                                "has_finally": len(node.finalbody) > 0,
+                                "has_else": len(node.orelse) > 0
+                            })
+
+                    files_scanned += 1
+
+                except Exception as e:
+                    logger.debug(f"Skipping {rel_path}: {e}")
+                    continue
+
+            if files_scanned >= max_files:
+                break
+
+        # Aggregate statistics
+        exception_types = {}
+        for handler in error_handlers:
+            for exc in handler["exceptions"]:
+                exception_types[exc] = exception_types.get(exc, 0) + 1
+
+        result = {
+            "error_handlers": error_handlers[:100],  # Limit output
+            "total_handlers": len(error_handlers),
+            "files_scanned": files_scanned,
+            "exception_types": dict(sorted(exception_types.items(), key=lambda x: x[1], reverse=True))
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding error handlers: {e}")
+        return json.dumps({"error": f"Scan failed: {str(e)}"})
+
+
+@tool
+def analyze_exceptions_tool(repo_path: str, file_path: str) -> str:
+    """
+    Analyze exception handling in a specific Python file.
+
+    Provides detailed analysis of try/except patterns, custom exceptions,
+    and error handling quality.
+
+    Args:
+        repo_path: Absolute path to repository root
+        file_path: Relative path to Python file
+
+    Returns:
+        JSON string with exception analysis
+    """
+    try:
+        full_path = os.path.normpath(os.path.join(repo_path, file_path))
+
+        # Security check
+        if not full_path.startswith(os.path.normpath(repo_path)):
+            return json.dumps({"error": "Access denied"})
+
+        if not os.path.exists(full_path):
+            return json.dumps({"error": f"File not found: {file_path}"})
+
+        # Read file
+        with open(full_path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+
+        # Parse AST
+        try:
+            tree = ast.parse(content)
+        except SyntaxError as e:
+            return json.dumps({"error": f"Syntax error: {str(e)}"})
+
+        # Find custom exception classes
+        custom_exceptions = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                # Check if it inherits from Exception
+                for base in node.bases:
+                    if isinstance(base, ast.Name) and 'Exception' in base.id:
+                        custom_exceptions.append({
+                            "name": node.name,
+                            "line": node.lineno
+                        })
+
+        # Analyze try/except blocks
+        exception_handlers = []
+        bare_excepts = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Try):
+                handler_info = {
+                    "line": node.lineno,
+                    "handlers": []
+                }
+
+                for handler in node.handlers:
+                    if handler.type is None:
+                        bare_excepts.append(node.lineno)
+                        handler_info["handlers"].append({"type": "bare_except", "warning": "Catches all exceptions"})
+                    elif isinstance(handler.type, ast.Name):
+                        handler_info["handlers"].append({"type": handler.type.id})
+                    elif isinstance(handler.type, ast.Tuple):
+                        types = [exc.id for exc in handler.type.elts if isinstance(exc, ast.Name)]
+                        handler_info["handlers"].append({"types": types})
+
+                exception_handlers.append(handler_info)
+
+        # Find raise statements
+        raises = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Raise):
+                if node.exc:
+                    if isinstance(node.exc, ast.Call) and isinstance(node.exc.func, ast.Name):
+                        raises.append({
+                            "line": node.lineno,
+                            "exception": node.exc.func.id
+                        })
+                    elif isinstance(node.exc, ast.Name):
+                        raises.append({
+                            "line": node.lineno,
+                            "exception": node.exc.id
+                        })
+
+        result = {
+            "file": file_path,
+            "custom_exceptions": custom_exceptions,
+            "exception_handlers": exception_handlers,
+            "bare_excepts_count": len(bare_excepts),
+            "bare_except_lines": bare_excepts,
+            "raises": raises,
+            "quality_notes": []
+        }
+
+        # Add quality notes
+        if len(bare_excepts) > 0:
+            result["quality_notes"].append(f"Found {len(bare_excepts)} bare except clauses (not recommended)")
+
+        if len(custom_exceptions) > 0:
+            result["quality_notes"].append(f"Defines {len(custom_exceptions)} custom exception classes")
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error analyzing exceptions in {file_path}: {e}")
+        return json.dumps({"error": f"Analysis failed: {str(e)}"})
+
+
+@tool
+def extract_env_vars_tool(repo_path: str) -> str:
+    """
+    Extract environment variables from .env example files.
+
+    Finds .env.example, .env.sample, .env.template files and extracts
+    variable names (not values, for security).
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        JSON string with environment variable names and descriptions
+    """
+    try:
+        env_vars = []
+        files_found = []
+
+        # Common env file patterns
+        env_file_patterns = [
+            '.env.example',
+            '.env.sample',
+            '.env.template',
+            'env.example',
+            'example.env'
+        ]
+
+        # Search for env files
+        for pattern in env_file_patterns:
+            file_path = os.path.join(repo_path, pattern)
+            if os.path.exists(file_path):
+                files_found.append(pattern)
+
+                try:
+                    with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+                        lines = f.readlines()
+
+                    for line_num, line in enumerate(lines, 1):
+                        line = line.strip()
+
+                        # Skip comments and empty lines
+                        if not line or line.startswith('#'):
+                            continue
+
+                        # Parse KEY=value format
+                        if '=' in line:
+                            key, value = line.split('=', 1)
+                            key = key.strip()
+                            value = value.strip()
+
+                            # Extract inline comment if present
+                            comment = ""
+                            if '#' in value:
+                                value, comment = value.split('#', 1)
+                                comment = comment.strip()
+
+                            # Check if value looks like a placeholder
+                            is_placeholder = bool(re.match(r'^(<.*?>|".*?"|\'.*?\'|\$\{.*?\}|your_.*|example_.*)', value, re.IGNORECASE))
+
+                            env_vars.append({
+                                "key": key,
+                                "file": pattern,
+                                "line": line_num,
+                                "has_default": len(value) > 0 and not is_placeholder,
+                                "description": comment if comment else None,
+                                "is_placeholder": is_placeholder
+                            })
+
+                except Exception as e:
+                    logger.warning(f"Error reading {pattern}: {e}")
+                    continue
+
+        # Also check for variables in README or docs
+        readme_vars = set()
+        for readme_name in ['README.md', 'readme.md', 'README']:
+            readme_path = os.path.join(repo_path, readme_name)
+            if os.path.exists(readme_path):
+                try:
+                    with open(readme_path, 'r', encoding='utf-8', errors='ignore') as f:
+                        content = f.read()
+
+                    # Look for environment variable mentions
+                    var_pattern = r'\b([A-Z_][A-Z0-9_]{2,})\b'
+                    matches = re.findall(var_pattern, content)
+                    readme_vars.update(matches)
+
+                except:
+                    pass
+
+        # Categorize variables
+        categories = {
+            "database": [],
+            "api_keys": [],
+            "urls": [],
+            "ports": [],
+            "auth": [],
+            "other": []
+        }
+
+        for var in env_vars:
+            key_lower = var["key"].lower()
+            if any(word in key_lower for word in ['db', 'database', 'postgres', 'mysql', 'mongo']):
+                categories["database"].append(var)
+            elif any(word in key_lower for word in ['key', 'token', 'secret', 'password']):
+                categories["api_keys"].append(var)
+            elif any(word in key_lower for word in ['url', 'endpoint', 'host', 'domain']):
+                categories["urls"].append(var)
+            elif 'port' in key_lower:
+                categories["ports"].append(var)
+            elif any(word in key_lower for word in ['auth', 'client_id', 'client_secret', 'oauth']):
+                categories["auth"].append(var)
+            else:
+                categories["other"].append(var)
+
+        result = {
+            "env_files_found": files_found,
+            "total_variables": len(env_vars),
+            "variables": env_vars,
+            "categorized": categories,
+            "readme_mentions": list(readme_vars)[:20]  # Limit to 20
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error extracting env vars: {e}")
+        return json.dumps({"error": f"Extraction failed: {str(e)}"})
diff --git a/DocuGenMicroagents/api/tools/repo_tools.py b/DocuGenMicroagents/api/tools/repo_tools.py
new file mode 100644
index 0000000000..300b0c111e
--- /dev/null
+++ b/DocuGenMicroagents/api/tools/repo_tools.py
@@ -0,0 +1,1287 @@
+"""
+LangChain tools for repository analysis
+Uses @tool decorator for automatic integration with agents
+
+FIXED VERSION: Strengthened Mermaid validation for render-safe diagrams
+ENHANCED: Strategic file reading with pattern_window mode
+"""
+
+import os
+import json
+import re
+from pathlib import Path
+from collections import Counter
+from typing import Dict, List, Literal
+from langchain.tools import tool
+import logging
+
+from config import settings
+
+logger = logging.getLogger(__name__)
+
+# Ignore patterns for directory listing
+IGNORE_DIRS = {
+    '.git', '__pycache__', 'node_modules', '.venv', 'venv',
+    'dist', 'build', '.next', '.nuxt', 'target', 'coverage',
+    '.idea', '.vscode', 'DS_Store'
+}
+
+# Language detection mapping
+LANGUAGE_MAP = {
+    '.py': 'Python',
+    '.js': 'JavaScript',
+    '.ts': 'TypeScript',
+    '.jsx': 'JavaScript (JSX)',
+    '.tsx': 'TypeScript (TSX)',
+    '.java': 'Java',
+    '.go': 'Go',
+    '.rs': 'Rust',
+    '.c': 'C',
+    '.cpp': 'C++',
+    '.cs': 'C#',
+    '.rb': 'Ruby',
+    '.php': 'PHP',
+    '.swift': 'Swift',
+    '.kt': 'Kotlin',
+    '.scala': 'Scala',
+}
+
+
+@tool
+def list_directory_tool(repo_path: str, relative_path: str = ".") -> str:
+    """
+    List contents of a directory in the repository.
+    Shows files and subdirectories with their types.
+
+    Args:
+        repo_path: Absolute path to the repository root
+        relative_path: Relative path from repo root (default: ".")
+
+    Returns:
+        Formatted string listing files and directories
+    """
+    try:
+        full_path = os.path.normpath(os.path.join(repo_path, relative_path))
+
+        # Security check
+        if not full_path.startswith(os.path.normpath(repo_path)):
+            return f"Error: Access denied - path traversal detected"
+
+        if not os.path.exists(full_path):
+            return f"Error: Directory not found: {relative_path}"
+
+        if not os.path.isdir(full_path):
+            return f"Error: Path is not a directory: {relative_path}"
+
+        items = []
+        for entry in os.listdir(full_path):
+            if entry in IGNORE_DIRS or entry.startswith('.'):
+                continue
+
+            entry_path = os.path.join(full_path, entry)
+            item_type = "DIR" if os.path.isdir(entry_path) else "FILE"
+            items.append(f"[{item_type}] {entry}")
+
+        if not items:
+            return f"Directory '{relative_path}' is empty or contains only ignored files"
+
+        return f"Contents of {relative_path}:\n" + "\n".join(sorted(items))
+
+    except Exception as e:
+        logger.error(f"Error listing directory {relative_path}: {e}")
+        return f"Error listing directory: {str(e)}"
+
+
+def _smart_sample_lines(lines: List[str], max_lines: int) -> tuple[list[str], bool]:
+    """
+    Smart sampling: top + function/class signatures + bottom
+
+    Args:
+        lines: All file lines
+        max_lines: Budget for total lines
+
+    Returns:
+        (selected_lines, was_truncated)
+    """
+    if len(lines) <= max_lines:
+        return lines, False
+
+    top_n = min(50, max_lines)
+    bottom_n = min(30, max_lines - top_n)
+    middle_budget = max(0, max_lines - top_n - bottom_n)
+
+    top = lines[:top_n]
+    bottom = lines[-bottom_n:] if bottom_n > 0 else []
+
+    # Extract function/class signatures
+    sigs = []
+    for ln in lines[top_n:len(lines) - bottom_n]:
+        s = ln.lstrip()
+        if s.startswith(("def ", "async def ", "class ")):
+            sigs.append(ln)
+            if len(sigs) >= middle_budget:
+                break
+
+    out = top + ["\n... [middle omitted] ...\n"] + sigs + ["\n... [end] ...\n"] + bottom
+    return out[:max_lines], True
+
+
+def _pattern_window_lines(lines: List[str], max_lines: int) -> tuple[list[str], bool]:
+    """
+    Pattern window sampling: detect high-value patterns, extract ±6 lines around matches
+
+    Patterns detected:
+    - FastAPI/Flask routes: @app.get, @router.post, APIRouter, include_router
+    - Error handling: try, except, raise
+    - Entry points: if __name__ == "__main__", uvicorn.run, def main
+
+    Args:
+        lines: All file lines
+        max_lines: Budget for total lines
+
+    Returns:
+        (selected_lines, was_truncated)
+    """
+    if len(lines) <= max_lines:
+        return lines, False
+
+    patterns = [
+        r"@app\.(get|post|put|delete)\b",
+        r"@router\.(get|post|put|delete)\b",
+        r"\bAPIRouter\b",
+        r"\binclude_router\b",
+        r"\btry:\b",
+        r"\bexcept\b",
+        r"\braise\b",
+        r'if __name__\s*==\s*[\'"]__main__[\'"]',
+        r"\buvicorn\.run\b",
+        r"\bdef main\(",
+    ]
+
+    top_n = min(40, max_lines)
+    bottom_n = min(25, max_lines - top_n)
+    budget = max_lines - top_n - bottom_n
+
+    # Find match line numbers
+    match_lines: list[int] = []
+    for i, ln in enumerate(lines):
+        for pat in patterns:
+            if re.search(pat, ln):
+                match_lines.append(i)
+                break
+
+    # Fallback to smart if no patterns found
+    if not match_lines:
+        logger.debug("No patterns found, falling back to smart strategy")
+        return _smart_sample_lines(lines, max_lines)
+
+    # Make windows ±6 lines around matches
+    windows: list[tuple[int, int]] = []
+    for i in match_lines[:50]:  # Cap matches
+        start = max(0, i - 6)
+        end = min(len(lines), i + 7)
+        windows.append((start, end))
+
+    # Merge overlapping windows
+    windows.sort()
+    merged: list[tuple[int, int]] = []
+    for s, e in windows:
+        if not merged or s > merged[-1][1]:
+            merged.append((s, e))
+        else:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], e))
+
+    # Emit lines within budget
+    out = lines[:top_n]
+    used = len(out)
+    last_end = top_n
+
+    for s, e in merged:
+        if used >= top_n + budget:
+            break
+        if e <= top_n or s >= len(lines) - bottom_n:
+            continue  # Already in top/bottom
+
+        if s > last_end:
+            out.append("\n... [omitted] ...\n")
+            used += 1
+
+        chunk = lines[s:e]
+        room = top_n + budget - used
+        if room <= 0:
+            break
+        out.extend(chunk[:room])
+        used = len(out)
+        last_end = e
+
+    out.append("\n... [end] ...\n")
+    out.extend(lines[-bottom_n:])
+
+    # Final clamp
+    out = out[:max_lines]
+    return out, True
+
+
+@tool
+def read_file_tool(
+    repo_path: str,
+    file_path: str,
+    max_lines: int = None,
+    strategy: Literal["full", "smart", "pattern_window"] = "full"
+) -> str:
+    """
+    Read contents of a file from the repository.
+
+    Args:
+        repo_path: Absolute path to the repository root
+        file_path: Relative path to the file from repo root
+        max_lines: Maximum lines to read (default: from settings.MAX_LINES_PER_FILE)
+        strategy: Reading strategy:
+          - "full": first N lines (default, backwards compatible)
+          - "smart": top + signatures + bottom
+          - "pattern_window": extract windows around high-value patterns (routes, errors, entrypoints)
+
+    Returns:
+        File contents as string
+    """
+    try:
+        # Use config setting if not specified
+        if max_lines is None:
+            max_lines = settings.MAX_LINES_PER_FILE
+
+        full_path = os.path.normpath(os.path.join(repo_path, file_path))
+
+        # Security check
+        if not full_path.startswith(os.path.normpath(repo_path)):
+            return "Error: Access denied - path traversal detected"
+
+        if not os.path.exists(full_path):
+            return f"Error: File not found: {file_path}"
+
+        if not os.path.isfile(full_path):
+            return f"Error: Path is not a file: {file_path}"
+
+        # Check file size using config setting
+        file_size = os.path.getsize(full_path)
+        max_file_size_mb = settings.MAX_FILE_SIZE / 1_000_000
+        if file_size > settings.MAX_FILE_SIZE:
+            return f"Error: File too large ({file_size} bytes). Maximum is {max_file_size_mb:.1f}MB."
+
+        # Read file
+        with open(full_path, "r", encoding="utf-8", errors="ignore") as f:
+            lines = f.readlines()
+
+        # Strategy dispatch
+        if strategy == "full":
+            selected = lines[:max_lines]
+            truncated = len(lines) > max_lines
+
+        elif strategy == "smart":
+            selected, truncated = _smart_sample_lines(lines, max_lines=max_lines)
+
+        elif strategy == "pattern_window":
+            selected, truncated = _pattern_window_lines(lines, max_lines=max_lines)
+
+        else:
+            selected = lines[:max_lines]
+            truncated = len(lines) > max_lines
+
+        content = "".join(selected)
+
+        # Deterministic header for verification
+        header = f"File: {file_path} | strategy: {strategy} | lines: {len(selected)}/{len(lines)}"
+        if truncated:
+            return f"{header}\n\n{content}\n\n[File truncated...]"
+        return f"{header}\n\n{content}"
+
+    except Exception as e:
+        logger.error(f"Error reading file {file_path}: {e}")
+        return f"Error reading file: {str(e)}"
+
+
+@tool
+def detect_languages_tool(repo_path: str) -> str:
+    """
+    Detect programming languages used in the repository.
+    Analyzes file extensions and provides statistics.
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with language statistics
+    """
+    try:
+        language_counter = Counter()
+        total_files = 0
+
+        for root, dirs, files in os.walk(repo_path):
+            # Filter out ignored directories
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.startswith('.')]
+
+            for file in files:
+                if file.startswith('.'):
+                    continue
+
+                ext = Path(file).suffix.lower()
+                if ext in LANGUAGE_MAP:
+                    language = LANGUAGE_MAP[ext]
+                    language_counter[language] += 1
+                    total_files += 1
+
+        if not language_counter:
+            return "No recognized programming languages detected"
+
+        # Format output
+        result = {
+            "total_files": total_files,
+            "languages": dict(language_counter.most_common()),
+            "primary_language": language_counter.most_common(1)[0][0] if language_counter else "Unknown"
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error detecting languages: {e}")
+        return f"Error detecting languages: {str(e)}"
+
+
+@tool
+def extract_dependencies_tool(repo_path: str) -> str:
+    """
+    Extract dependencies from common dependency files.
+    Recursively scans subdirectories for package.json, requirements.txt, go.mod, Cargo.toml, etc.
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with dependencies by ecosystem
+    """
+    try:
+        dependencies = {}
+        found_files = []
+
+        # Recursively walk directory tree to find dependency files
+        for root, dirs, files in os.walk(repo_path):
+            # Filter out ignored directories
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.startswith('.')]
+
+            # Python - requirements.txt
+            if 'requirements.txt' in files:
+                req_file = os.path.join(root, 'requirements.txt')
+                rel_path = os.path.relpath(req_file, repo_path)
+                try:
+                    with open(req_file, 'r') as f:
+                        deps = [line.strip().split('==')[0].split('>=')[0].split('[')[0]
+                                for line in f if line.strip() and not line.startswith('#')]
+                        if deps and "Python" not in dependencies:
+                            dependencies["Python"] = deps[:20]  # Limit to 20
+                            found_files.append(f"requirements.txt ({rel_path})")
+                except:
+                    pass
+
+            # Node.js - package.json
+            if 'package.json' in files:
+                pkg_file = os.path.join(root, 'package.json')
+                rel_path = os.path.relpath(pkg_file, repo_path)
+                try:
+                    with open(pkg_file, 'r') as f:
+                        pkg_data = json.load(f)
+                        deps = list(pkg_data.get("dependencies", {}).keys())
+                        if deps and "Node.js" not in dependencies:
+                            dependencies["Node.js"] = deps[:20]
+                            found_files.append(f"package.json ({rel_path})")
+                except:
+                    pass
+
+            # Go - go.mod
+            if 'go.mod' in files:
+                go_file = os.path.join(root, 'go.mod')
+                rel_path = os.path.relpath(go_file, repo_path)
+                try:
+                    with open(go_file, 'r') as f:
+                        deps = [line.split()[0] for line in f if line.strip().startswith('require')]
+                        if deps and "Go" not in dependencies:
+                            dependencies["Go"] = deps[:20]
+                            found_files.append(f"go.mod ({rel_path})")
+                except:
+                    pass
+
+            # Rust - Cargo.toml
+            if 'Cargo.toml' in files:
+                cargo_file = os.path.join(root, 'Cargo.toml')
+                rel_path = os.path.relpath(cargo_file, repo_path)
+                try:
+                    with open(cargo_file, 'r') as f:
+                        in_deps = False
+                        deps = []
+                        for line in f:
+                            if '[dependencies]' in line:
+                                in_deps = True
+                                continue
+                            if in_deps and line.strip() and line.startswith('['):
+                                break
+                            if in_deps and '=' in line:
+                                dep_name = line.split('=')[0].strip()
+                                deps.append(dep_name)
+                        if deps and "Rust" not in dependencies:
+                            dependencies["Rust"] = deps[:20]
+                            found_files.append(f"Cargo.toml ({rel_path})")
+                except:
+                    pass
+
+        if not dependencies:
+            return "No dependency files found"
+
+        result = {
+            "dependencies": dependencies,
+            "files_found": found_files
+        }
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error extracting dependencies: {e}")
+        return f"Error extracting dependencies: {str(e)}"
+
+
+@tool
+def analyze_code_structure_tool(repo_path: str, file_path: str) -> str:
+    """
+    Analyze code structure of a file (functions, classes, imports).
+    Uses AST parsing for Python, basic regex for others.
+
+    Args:
+        repo_path: Absolute path to the repository root
+        file_path: Relative path to the file from repo root
+
+    Returns:
+        JSON string with code structure analysis
+    """
+    try:
+        full_path = os.path.normpath(os.path.join(repo_path, file_path))
+
+        if not full_path.startswith(os.path.normpath(repo_path)):
+            return "Error: Access denied"
+
+        if not os.path.exists(full_path):
+            return "Error: File not found"
+
+        ext = Path(file_path).suffix.lower()
+
+        # Python AST analysis
+        if ext == '.py':
+            try:
+                import ast
+                with open(full_path, 'r', encoding='utf-8') as f:
+                    tree = ast.parse(f.read())
+
+                functions = [node.name for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)]
+                classes = [node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef)]
+                imports = [alias.name for node in ast.walk(tree) if isinstance(node, ast.Import) for alias in node.names]
+
+                result = {
+                    "language": "Python",
+                    "functions": functions[:20],
+                    "classes": classes[:20],
+                    "imports": imports[:20],
+                    "total_functions": len(functions),
+                    "total_classes": len(classes)
+                }
+                return json.dumps(result, indent=2)
+            except Exception as e:
+                return f"Error parsing Python file: {str(e)}"
+
+        # For other languages, provide basic info
+        with open(full_path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+            lines = content.split('\n')
+
+        result = {
+            "language": LANGUAGE_MAP.get(ext, "Unknown"),
+            "lines_of_code": len(lines),
+            "non_empty_lines": len([l for l in lines if l.strip()]),
+            "note": "Detailed analysis only available for Python files"
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error analyzing code structure: {e}")
+        return f"Error analyzing code structure: {str(e)}"
+
+
+# ============================================================================
+# SPECIALIZED TOOLS FOR PLANNER AGENT
+# ============================================================================
+
+@tool
+def find_ui_files_tool(repo_path: str) -> str:
+    """
+    Check if the project has a UI/frontend component.
+    Looks for frontend directories and files (React, Vue, Angular, HTML, etc.).
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with UI detection results
+    """
+    try:
+        ui_indicators = {
+            "directories": [],
+            "files": [],
+            "frameworks": []
+        }
+
+        # Check for common frontend directories
+        ui_dirs = ['frontend', 'ui', 'client', 'web', 'app', 'src/components', 'public']
+        for dir_name in ui_dirs:
+            dir_path = os.path.join(repo_path, dir_name)
+            if os.path.exists(dir_path) and os.path.isdir(dir_path):
+                ui_indicators["directories"].append(dir_name)
+
+        # Check for frontend files
+        ui_files = ['index.html', 'App.jsx', 'App.tsx', 'App.vue', 'index.jsx', 'index.tsx']
+        for root, dirs, files in os.walk(repo_path):
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
+            for file in files:
+                if file in ui_files:
+                    rel_path = os.path.relpath(os.path.join(root, file), repo_path)
+                    ui_indicators["files"].append(rel_path)
+
+        # Check package.json for frontend frameworks
+        pkg_file = os.path.join(repo_path, "package.json")
+        if os.path.exists(pkg_file):
+            with open(pkg_file, 'r') as f:
+                pkg_data = json.load(f)
+                deps = {**pkg_data.get("dependencies", {}), **pkg_data.get("devDependencies", {})}
+
+                if "react" in deps:
+                    ui_indicators["frameworks"].append("React")
+                if "vue" in deps:
+                    ui_indicators["frameworks"].append("Vue.js")
+                if "@angular/core" in deps:
+                    ui_indicators["frameworks"].append("Angular")
+                if "next" in deps:
+                    ui_indicators["frameworks"].append("Next.js")
+                if "svelte" in deps:
+                    ui_indicators["frameworks"].append("Svelte")
+
+        has_ui = bool(ui_indicators["directories"] or ui_indicators["files"] or ui_indicators["frameworks"])
+
+        result = {
+            "has_ui": has_ui,
+            "indicators": ui_indicators
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding UI files: {e}")
+        return f"Error finding UI files: {str(e)}"
+
+
+@tool
+def find_docker_files_tool(repo_path: str) -> str:
+    """
+    Check for Docker/container deployment files.
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with Docker file detection results
+    """
+    try:
+        docker_files = []
+
+        # Check for Docker files
+        docker_indicators = [
+            'Dockerfile',
+            'docker-compose.yml',
+            'docker-compose.yaml',
+            '.dockerignore',
+            'Dockerfile.prod',
+            'Dockerfile.dev'
+        ]
+
+        for file_name in docker_indicators:
+            file_path = os.path.join(repo_path, file_name)
+            if os.path.exists(file_path):
+                docker_files.append(file_name)
+
+        result = {
+            "has_docker": bool(docker_files),
+            "docker_files": docker_files
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding Docker files: {e}")
+        return f"Error finding Docker files: {str(e)}"
+
+
+@tool
+def find_config_files_tool(repo_path: str) -> str:
+    """
+    Find configuration files (.env, config files, etc.).
+    Recursively scans subdirectories.
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with configuration file detection results
+    """
+    try:
+        config_files = []
+
+        # Config file patterns to search for
+        config_indicators = [
+            '.env.example',
+            '.env.sample',
+            '.env.template',
+            'config.json',
+            'config.yaml',
+            'config.yml',
+            'settings.py',
+            'config.py',
+            'appsettings.json'
+        ]
+
+        # Recursively walk directory tree
+        for root, dirs, files in os.walk(repo_path):
+            # Filter out ignored directories
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.startswith('.')]
+
+            for file in files:
+                if file in config_indicators:
+                    full_path = os.path.join(root, file)
+                    rel_path = os.path.relpath(full_path, repo_path)
+                    config_files.append(rel_path)
+
+        result = {
+            "has_config": bool(config_files),
+            "config_files": config_files,
+            "count": len(config_files)
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding config files: {e}")
+        return f"Error finding config files: {str(e)}"
+
+
+@tool
+def find_dependency_files_tool(repo_path: str) -> str:
+    """
+    Find dependency/package files in the repository.
+    Recursively scans subdirectories for requirements.txt, package.json, go.mod, Cargo.toml, pom.xml, etc.
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with dependency file locations
+    """
+    try:
+        dependency_files = []
+
+        # Common dependency file patterns
+        dep_patterns = [
+            'requirements.txt',
+            'package.json',
+            'go.mod',
+            'Cargo.toml',
+            'pom.xml',
+            'build.gradle',
+            'Gemfile',
+            'composer.json',
+            'Pipfile',
+            'poetry.lock',
+            'yarn.lock',
+            'package-lock.json'
+        ]
+
+        # Recursively walk directory tree
+        for root, dirs, files in os.walk(repo_path):
+            # Filter out ignored directories
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.startswith('.')]
+
+            for file in files:
+                if file in dep_patterns:
+                    full_path = os.path.join(root, file)
+                    rel_path = os.path.relpath(full_path, repo_path)
+                    dependency_files.append(rel_path)
+
+        result = {
+            "dependency_files": dependency_files,
+            "count": len(dependency_files)
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding dependency files: {e}")
+        return f"Error finding dependency files: {str(e)}"
+
+
+# ============================================================================
+# SPECIALIZED TOOLS FOR DIAGRAM GENERATOR AGENT
+# ============================================================================
+
+@tool
+def find_entry_points_tool(repo_path: str) -> str:
+    """
+    Find main entry point files (main.py, server.py, index.js, etc.).
+
+    Args:
+        repo_path: Absolute path to the repository root
+
+    Returns:
+        JSON string with entry point file locations
+    """
+    try:
+        entry_points = []
+
+        # Common entry point patterns
+        entry_patterns = [
+            'main.py', 'app.py', 'server.py', '__main__.py',
+            'index.js', 'index.ts', 'server.js', 'app.js',
+            'main.go', 'main.rs', 'Main.java'
+        ]
+
+        for root, dirs, files in os.walk(repo_path):
+            dirs[:] = [d for d in dirs if d not in IGNORE_DIRS]
+
+            for file in files:
+                if file in entry_patterns:
+                    rel_path = os.path.relpath(os.path.join(root, file), repo_path)
+                    entry_points.append(rel_path)
+
+        result = {
+            "entry_points": entry_points,
+            "count": len(entry_points)
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding entry points: {e}")
+        return f"Error finding entry points: {str(e)}"
+
+
+@tool
+def find_api_routes_tool(repo_path: str, entry_file: str) -> str:
+    """
+    Analyze an entry file to find API routes/endpoints.
+    Looks for common patterns like @app.route, @router.get, etc.
+
+    Args:
+        repo_path: Absolute path to the repository root
+        entry_file: Relative path to entry file from repo root
+
+    Returns:
+        JSON string with discovered API routes
+    """
+    try:
+        full_path = os.path.normpath(os.path.join(repo_path, entry_file))
+
+        if not full_path.startswith(os.path.normpath(repo_path)):
+            return "Error: Access denied"
+
+        if not os.path.exists(full_path):
+            return "Error: File not found"
+
+        routes = []
+
+        with open(full_path, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+            lines = content.split('\n')
+
+        # Pattern matching for routes
+        route_patterns = [
+            r'@app\.route\(["\'](.+?)["\']\)',  # Flask
+            r'@router\.(get|post|put|delete)\(["\'](.+?)["\']\)',  # FastAPI
+            r'app\.(get|post|put|delete)\(["\'](.+?)["\']\)',  # Express
+            r'@(Get|Post|Put|Delete)Mapping\(["\'](.+?)["\']\)'  # Spring
+        ]
+
+        for line in lines:
+            for pattern in route_patterns:
+                matches = re.findall(pattern, line)
+                if matches:
+                    routes.extend([str(m) if isinstance(m, str) else m[-1] for m in matches])
+
+        result = {
+            "file": entry_file,
+            "routes": routes[:50],  # Limit to 50 routes
+            "route_count": len(routes)
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error finding API routes: {e}")
+        return f"Error finding API routes: {str(e)}"
+
+
+
+# ============================================================================
+# VALIDATION TOOLS FOR SELF-CRITIQUE LOOPS
+# ============================================================================
+
+@tool
+def validate_readme_structure_tool(readme_content: str) -> str:
+    """
+    Validate README structure and completeness.
+    Checks for expected sections, proper markdown formatting, code blocks.
+
+    Args:
+        readme_content: README markdown content to validate
+
+    Returns:
+        JSON string with validation results
+    """
+    try:
+        issues = []
+        sections_found = []
+
+        # Extract sections (markdown headers)
+        import re
+        header_pattern = r'^##\s+(.+)$'
+        sections = re.findall(header_pattern, readme_content, re.MULTILINE)
+        sections_found = sections
+
+        # Expected sections (at least some of these should be present)
+        expected_sections = ["Overview", "Features", "Installation", "Usage", "Configuration", "API"]
+        found_expected = [s for s in expected_sections if any(exp.lower() in s.lower() for exp in sections)]
+
+        if len(found_expected) < 3:
+            issues.append({
+                "severity": "warning",
+                "message": f"Only {len(found_expected)} standard sections found. Consider adding more."
+            })
+
+        # Check for code blocks
+        code_blocks = readme_content.count("```")
+        if code_blocks == 0:
+            issues.append({
+                "severity": "info",
+                "message": "No code examples found. Consider adding usage examples."
+            })
+        elif code_blocks % 2 != 0:
+            issues.append({
+                "severity": "error",
+                "message": "Unbalanced code blocks (missing closing ```)"
+            })
+
+        # Check for mermaid diagrams
+        has_mermaid = "```mermaid" in readme_content
+        if not has_mermaid:
+            issues.append({
+                "severity": "info",
+                "message": "No Mermaid diagrams found. Visual diagrams enhance documentation."
+            })
+
+        # Check minimum length
+        if len(readme_content) < 500:
+            issues.append({
+                "severity": "warning",
+                "message": "README is very short. Consider adding more detail."
+            })
+
+        result = {
+            "sections_found": sections_found,
+            "section_count": len(sections_found),
+            "code_blocks": code_blocks // 2 if code_blocks % 2 == 0 else 0,
+            "has_mermaid": has_mermaid,
+            "content_length": len(readme_content),
+            "issues": issues
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error validating README structure: {e}")
+        return json.dumps({
+            "error": str(e),
+            "issues": [{"severity": "error", "message": f"Validation failed: {str(e)}"}]
+        })
+
+
+@tool
+def validate_mermaid_syntax_tool(mermaid_code: str) -> str:
+    """
+    Validate Mermaid diagram syntax with STRICT Mermaid 8.14.0 render-safe checks.
+    Returns JSON string with validation results.
+
+    FIXED VERSION: Enforces render-safe patterns that prevent "Syntax error in graph"
+
+    Checks:
+    - Node IDs must be alphanumeric + underscore only
+    - Node labels must be quoted: ID["Label"]
+    - Edge labels must not contain: / ( ) : ` "
+    - Basic structure (brackets, arrows, diagram type)
+
+    Args:
+        mermaid_code: Mermaid diagram code to validate
+
+    Returns:
+        JSON: {"valid": bool, "errors": [...], "warnings": [...]}
+    """
+    try:
+        errors = []
+        warnings = []
+
+        # Basic checks
+        if not mermaid_code or not mermaid_code.strip():
+            errors.append("Empty diagram code")
+            return json.dumps({"valid": False, "errors": errors, "warnings": warnings})
+
+        code = mermaid_code.strip()
+
+        # Check for diagram type
+        diagram_types = [
+            "graph", "flowchart", "sequenceDiagram", "classDiagram",
+            "stateDiagram", "erDiagram", "journey", "gantt", "pie"
+        ]
+        has_type = any(code.startswith(dt) for dt in diagram_types)
+        if not has_type:
+            errors.append(f"Must start with diagram type: {diagram_types[:4]}...")
+
+        # Check for common syntax errors
+        open_brackets = code.count("[")
+        close_brackets = code.count("]")
+        if open_brackets != close_brackets:
+            errors.append(f"Unbalanced square brackets: {open_brackets} open vs {close_brackets} close")
+
+        open_parens = code.count("(")
+        close_parens = code.count(")")
+        if open_parens != close_parens:
+            errors.append(f"Unbalanced parentheses: {open_parens} open vs {close_parens} close")
+
+        open_braces = code.count("{")
+        close_braces = code.count("}")
+        if open_braces != close_braces:
+            errors.append(f"Unbalanced curly braces: {open_braces} open vs {close_braces} close")
+
+        # Check for arrow syntax (graph/flowchart)
+        if code.startswith(("graph", "flowchart")):
+            # Must have at least one arrow
+            has_arrow = ("-->" in code or "---" in code or "==>" in code or
+                        "-.->" in code or "-..->" in code)
+            if not has_arrow:
+                warnings.append("Graph/flowchart diagrams typically need arrows (-->, --->, etc.)")
+
+            # Check for node definitions
+            lines = code.split("\n")
+            node_lines = [l for l in lines if "-->" in l or "---" in l]
+            if len(node_lines) == 0:
+                errors.append("No connections found - graph needs edges like: A --> B")
+
+            # ===================================================================
+            # MERMAID 8.14.0 RENDER-SAFE VALIDATION (NEW)
+            # ===================================================================
+
+            # Check 1: Node IDs must be alphanumeric + underscore only
+            # Pattern: extract node IDs from lines like "NodeID[...]" or "NodeID --> OtherNode"
+            node_id_pattern = r'\b([A-Za-z][A-Za-z0-9_]*)\s*(?:\[|-->|---|\||$)'
+            node_ids = []
+            for line in lines[1:]:  # Skip first line (graph TD/LR)
+                if not line.strip() or line.strip().startswith('#'):
+                    continue
+                matches = re.findall(node_id_pattern, line)
+                node_ids.extend(matches)
+
+            # Check for invalid node IDs (contain special chars besides underscore)
+            invalid_node_pattern = r'\b([A-Za-z0-9_]*[^A-Za-z0-9_\s\[\](){}|>-]+[A-Za-z0-9_]*)\s*(?:\[|-->)'
+            for line in lines[1:]:
+                if not line.strip():
+                    continue
+                invalid_matches = re.findall(invalid_node_pattern, line)
+                for invalid_id in invalid_matches:
+                    if invalid_id and not invalid_id.isspace():
+                        errors.append(
+                            f"Invalid node ID '{invalid_id}' - must be alphanumeric + underscore only. "
+                            f"Use: {re.sub(r'[^A-Za-z0-9_]', '', invalid_id)}"
+                        )
+
+            # Check 2: Node labels must be quoted if they contain special characters
+            # Pattern: NodeID[unquoted text with spaces or special chars]
+            unquoted_label_pattern = r'([A-Za-z][A-Za-z0-9_]*)\[([^\]"]+[^"\]])\]'
+            for line in lines[1:]:
+                if not line.strip():
+                    continue
+                matches = re.findall(unquoted_label_pattern, line)
+                for node_id, label in matches:
+                    # Check if label has spaces or special chars and is not quoted
+                    if ' ' in label or '(' in label or ')' in label or '/' in label:
+                        if not (label.strip().startswith('"') and label.strip().endswith('"')):
+                            errors.append(
+                                f"Unquoted label in node '{node_id}[{label}]' - must use quotes: {node_id}[\"{label}\"]"
+                            )
+
+            # Check 3: Edge labels must not contain unsafe characters
+            # Pattern: |label text|
+            edge_label_pattern = r'\|([^|]+)\|'
+            unsafe_edge_chars = ['/', '(', ')', ':', '`', '"']
+            for line in lines[1:]:
+                if not line.strip():
+                    continue
+                edge_matches = re.findall(edge_label_pattern, line)
+                for edge_label in edge_matches:
+                    for unsafe_char in unsafe_edge_chars:
+                        if unsafe_char in edge_label:
+                            safe_label = edge_label
+                            for char in unsafe_edge_chars:
+                                safe_label = safe_label.replace(char, '')
+                            safe_label = safe_label.strip()
+                            errors.append(
+                                f"Unsafe edge label '|{edge_label}|' contains '{unsafe_char}'. "
+                                f"Use simple label: |{safe_label}| or create a separate node for complex paths."
+                            )
+                            break
+
+        # Check sequenceDiagram syntax
+        if code.startswith("sequenceDiagram"):
+            if "->" not in code and "->>" not in code:
+                errors.append("sequenceDiagram needs arrows like: Alice->>Bob: Hello")
+
+        # Warning for common mistakes
+        if "graph TD" in code and "TB" not in code:
+            pass  # TD (top-down) is valid
+        elif "graph TB" in code:
+            pass  # TB (top-bottom) is valid
+        elif "graph LR" in code:
+            pass  # LR (left-right) is valid
+        elif "graph RL" in code:
+            pass  # RL (right-left) is valid
+        elif "graph" in code and not any(d in code for d in ["TD", "TB", "LR", "RL", "BT"]):
+            warnings.append("graph should specify direction: graph TD, graph LR, etc.")
+
+        valid = len(errors) == 0
+
+        result = {
+            "valid": valid,
+            "errors": errors,
+            "warnings": warnings,
+            "diagram_type": next((dt for dt in diagram_types if code.startswith(dt)), "unknown")
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        logger.error(f"Error validating Mermaid syntax: {e}")
+        return json.dumps({
+            "valid": False,
+            "errors": [f"Validation error: {str(e)}"],
+            "warnings": []
+        })
+
+
+# ============================================================================
+# TOOL BINDING HELPERS - Bind repo_path to simplify LLM tool usage
+# ============================================================================
+
+def make_bound_tools_for_code_explorer(repo_path: str) -> List:
+    """
+    Create tools for Code Explorer with repo_path pre-bound.
+    This simplifies the tool signatures the LLM sees.
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        List of tool instances with bound repo_path
+    """
+    # Create wrapper functions with repo_path bound
+    @tool
+    def list_directory(relative_path: str = ".") -> str:
+        """List contents of a directory. Args: relative_path (str, default '.'): Path from repo root"""
+        return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+    @tool
+    def read_file(
+        file_path: str,
+        max_lines: int = None,
+        strategy: Literal["full", "smart", "pattern_window"] = "pattern_window"
+    ) -> str:
+        """Read a file. Args: file_path (str), max_lines (int, optional), strategy (full|smart|pattern_window, default: pattern_window)"""
+        return read_file_tool.func(
+            repo_path=repo_path,
+            file_path=file_path,
+            max_lines=max_lines,
+            strategy=strategy
+        )
+
+    @tool
+    def detect_languages() -> str:
+        """Detect programming languages in the repository. No arguments needed."""
+        return detect_languages_tool.func(repo_path=repo_path)
+
+    @tool
+    def extract_dependencies() -> str:
+        """Extract dependencies from package files (requirements.txt, package.json, etc.). No arguments needed."""
+        return extract_dependencies_tool.func(repo_path=repo_path)
+
+    @tool
+    def analyze_code_structure(file_path: str) -> str:
+        """Analyze code structure (functions, classes, imports). Args: file_path (str): Relative path from repo root"""
+        return analyze_code_structure_tool.func(repo_path=repo_path, file_path=file_path)
+
+    return [list_directory, read_file, detect_languages, extract_dependencies, analyze_code_structure]
+
+
+def make_bound_tools_for_planner(repo_path: str) -> List:
+    """
+    Create tools for Planner with repo_path pre-bound.
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        List of tool instances with bound repo_path
+    """
+    # Create wrapper functions with repo_path bound
+    @tool
+    def list_directory(relative_path: str = ".") -> str:
+        """List contents of a directory. Args: relative_path (str, default '.')"""
+        return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+    @tool
+    def read_file(
+        file_path: str,
+        max_lines: int = None,
+        strategy: Literal["full", "smart", "pattern_window"] = "pattern_window"
+    ) -> str:
+        """Read a file. Args: file_path (str), max_lines (int, optional), strategy (full|smart|pattern_window, default: pattern_window)"""
+        return read_file_tool.func(
+            repo_path=repo_path,
+            file_path=file_path,
+            max_lines=max_lines,
+            strategy=strategy
+        )
+
+    @tool
+    def detect_languages() -> str:
+        """Detect programming languages. No arguments."""
+        return detect_languages_tool.func(repo_path=repo_path)
+
+    @tool
+    def extract_dependencies() -> str:
+        """Extract dependencies from package files. No arguments."""
+        return extract_dependencies_tool.func(repo_path=repo_path)
+
+    @tool
+    def analyze_code_structure(file_path: str) -> str:
+        """Analyze code structure. Args: file_path (str)"""
+        return analyze_code_structure_tool.func(repo_path=repo_path, file_path=file_path)
+
+    @tool
+    def find_ui_files() -> str:
+        """Check if project has UI/frontend components. No arguments."""
+        return find_ui_files_tool.func(repo_path=repo_path)
+
+    @tool
+    def find_docker_files() -> str:
+        """Check for Docker deployment files. No arguments."""
+        return find_docker_files_tool.func(repo_path=repo_path)
+
+    @tool
+    def find_config_files() -> str:
+        """Find configuration files (.env, config files). No arguments."""
+        return find_config_files_tool.func(repo_path=repo_path)
+
+    return [list_directory, read_file, detect_languages, extract_dependencies, analyze_code_structure,
+            find_ui_files, find_docker_files, find_config_files]
+
+
+def make_bound_tools_for_writer(repo_path: str) -> List:
+    """
+    Create tools for Writer with repo_path pre-bound.
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        List of StructuredTool instances with bound repo_path
+    """
+    # Same as code explorer
+    return make_bound_tools_for_code_explorer(repo_path)
+
+
+def make_bound_tools_for_diagram_generator(repo_path: str) -> List:
+    """
+    Create tools for Diagram Generator with repo_path pre-bound.
+
+    FIXED: Adds validate_mermaid_syntax wrapper (without _tool suffix) to match prompt.
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        List of tool instances with bound repo_path
+    """
+    # Create wrapper functions with repo_path bound
+    @tool
+    def list_directory(relative_path: str = ".") -> str:
+        """List contents of a directory. Args: relative_path (str, default '.')"""
+        return list_directory_tool.func(repo_path=repo_path, relative_path=relative_path)
+
+    @tool
+    def read_file(
+        file_path: str,
+        max_lines: int = None,
+        strategy: Literal["full", "smart", "pattern_window"] = "pattern_window"
+    ) -> str:
+        """Read a file. Args: file_path (str), max_lines (int, optional), strategy (full|smart|pattern_window, default: pattern_window)"""
+        return read_file_tool.func(
+            repo_path=repo_path,
+            file_path=file_path,
+            max_lines=max_lines,
+            strategy=strategy
+        )
+
+    @tool
+    def detect_languages() -> str:
+        """Detect programming languages. No arguments."""
+        return detect_languages_tool.func(repo_path=repo_path)
+
+    @tool
+    def find_entry_points() -> str:
+        """Find main entry point files (main.py, server.py, index.js, etc.). No arguments."""
+        return find_entry_points_tool.func(repo_path=repo_path)
+
+    @tool
+    def find_api_routes(entry_file: str) -> str:
+        """Find API routes in an entry file. Args: entry_file (str): Relative path to entry file"""
+        return find_api_routes_tool.func(repo_path=repo_path, entry_file=entry_file)
+
+    @tool
+    def find_docker_files() -> str:
+        """Check for Docker files. No arguments."""
+        return find_docker_files_tool.func(repo_path=repo_path)
+
+    # FIXED: Add wrapper for validate_mermaid_syntax (without _tool suffix)
+    # This matches the tool name used in the diagram generator prompt
+    @tool
+    def validate_mermaid_syntax(mermaid_code: str) -> str:
+        """
+        Validate Mermaid diagram syntax with strict Mermaid 8.14.0 render-safe checks.
+
+        CRITICAL: Use this to validate EVERY diagram before finalizing output.
+
+        Args:
+            mermaid_code (str): The complete Mermaid diagram code to validate
+
+        Returns:
+            JSON with {"valid": bool, "errors": [...], "warnings": [...]}
+        """
+        return validate_mermaid_syntax_tool.func(mermaid_code=mermaid_code)
+
+    return [list_directory, read_file, detect_languages, find_entry_points, find_api_routes,
+            find_docker_files, validate_mermaid_syntax]
diff --git a/DocuGenMicroagents/api/utils/__init__.py b/DocuGenMicroagents/api/utils/__init__.py
new file mode 100644
index 0000000000..2b0e869f30
--- /dev/null
+++ b/DocuGenMicroagents/api/utils/__init__.py
@@ -0,0 +1,5 @@
+"""Utility functions for DocuGen AI"""
+
+from .project_detector import detect_projects, ProjectDetector
+
+__all__ = ["detect_projects", "ProjectDetector"]
diff --git a/DocuGenMicroagents/api/utils/metrics_extractor.py b/DocuGenMicroagents/api/utils/metrics_extractor.py
new file mode 100644
index 0000000000..3d5e70c087
--- /dev/null
+++ b/DocuGenMicroagents/api/utils/metrics_extractor.py
@@ -0,0 +1,56 @@
+"""
+Utility for extracting metrics from LangGraph agent execution results
+"""
+
+from typing import Dict, List, Any
+
+
+def extract_agent_metrics(messages: List[Any]) -> Dict[str, int]:
+    """
+    Extract token usage and call counts from LangGraph messages.
+
+    Args:
+        messages: List of messages from LangGraph agent execution
+
+    Returns:
+        Dict with input_tokens, output_tokens, tool_calls, llm_calls
+    """
+    input_tokens = 0
+    output_tokens = 0
+    tool_calls = 0
+    llm_calls = 0
+
+    for msg in messages:
+        # Count tool calls (messages with tool_calls attribute)
+        if hasattr(msg, 'tool_calls') and msg.tool_calls:
+            tool_calls += len(msg.tool_calls)
+
+        # Count LLM calls and extract token usage from AIMessage responses ONLY
+        # Check if this is an AIMessage by looking for response_metadata attribute
+        if hasattr(msg, 'response_metadata') and msg.__class__.__name__ == 'AIMessage':
+            llm_calls += 1
+            metadata = msg.response_metadata
+
+            # Try different token usage formats (different LLM providers use different keys)
+            if 'usage_metadata' in metadata:
+                # LangChain format
+                usage = metadata['usage_metadata']
+                input_tokens += usage.get('input_tokens', 0)
+                output_tokens += usage.get('output_tokens', 0)
+            elif 'token_usage' in metadata:
+                # OpenAI format
+                usage = metadata['token_usage']
+                input_tokens += usage.get('prompt_tokens', 0)
+                output_tokens += usage.get('completion_tokens', 0)
+            elif 'usage' in metadata:
+                # Alternative format
+                usage = metadata['usage']
+                input_tokens += usage.get('input_tokens', usage.get('prompt_tokens', 0))
+                output_tokens += usage.get('output_tokens', usage.get('completion_tokens', 0))
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "tool_calls": tool_calls,
+        "llm_calls": llm_calls
+    }
diff --git a/DocuGenMicroagents/api/utils/project_detector.py b/DocuGenMicroagents/api/utils/project_detector.py
new file mode 100644
index 0000000000..dd3c606589
--- /dev/null
+++ b/DocuGenMicroagents/api/utils/project_detector.py
@@ -0,0 +1,431 @@
+"""
+Smart Project Detector
+Analyzes repository structure and identifies individual projects within a monorepo
+Includes grouping logic to treat parent folders (with api/ui children) as single projects
+"""
+
+import os
+import logging
+import fnmatch
+from typing import List, Dict, Any
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Project indicators - files that typically mark a project root
+PROJECT_INDICATORS = {
+    "python": ["requirements.txt", "setup.py", "pyproject.toml", "Pipfile", "poetry.lock"],
+    "nodejs": ["package.json"],
+    "java": ["pom.xml", "build.gradle", "build.gradle.kts"],
+    "go": ["go.mod"],
+    "rust": ["Cargo.toml"],
+    "php": ["composer.json"],
+    "ruby": ["Gemfile"],
+    "dotnet": ["*.csproj", "*.sln", "*.fsproj", "*.vbproj"],
+    "cpp": ["CMakeLists.txt", "Makefile"],
+    "r": ["DESCRIPTION", "NAMESPACE"],
+}
+
+# Directories to ignore
+IGNORE_DIRS = {
+    "node_modules", ".git", "__pycache__", "venv", "env", ".venv",
+    "dist", "build", ".idea", ".vscode", "target", "out",
+    ".next", ".nuxt", "coverage", ".pytest_cache"
+}
+
+# Common subproject folder names (generic patterns, not hardcoded to specific names)
+SUBPROJECT_PATTERNS = ["api", "ui", "frontend", "backend", "web", "server", "client", "app", "service"]
+
+
+class ProjectDetector:
+    """Detects and analyzes projects within a repository"""
+
+    def __init__(self, repo_path: str, max_depth: int = 3, group_subprojects: bool = True):
+        """
+        Args:
+            repo_path: Path to repository root
+            max_depth: Maximum depth to scan
+            group_subprojects: If True, group api/ui siblings under parent project
+        """
+        self.repo_path = Path(repo_path)
+        self.max_depth = max_depth
+        self.group_subprojects = group_subprojects
+
+    def detect_projects(self) -> Dict[str, Any]:
+        """
+        Scan repository and detect individual projects
+
+        Returns:
+            Dict with:
+                - is_monorepo: bool
+                - project_count: int
+                - projects: List[Dict] with project metadata
+                - skipped_folders: List[Dict] with skipped folder info and reasons
+        """
+        projects = []
+        skipped_folders = []
+
+        # Check if root itself is a project
+        root_project = self._analyze_directory(self.repo_path, depth=0)
+        if root_project:
+            projects.append(root_project)
+
+        # Scan subdirectories
+        self._scan_recursive(self.repo_path, projects, depth=1, skipped=skipped_folders)
+
+        # Apply grouping logic if enabled
+        if self.group_subprojects:
+            projects = self._group_composite_projects(projects)
+
+        # Filter out nested skipped folders (children of other skipped folders)
+        skipped_folders = self._filter_nested_skipped_folders(skipped_folders)
+
+        # Filter out standalone media/asset folders when there's a doc folder
+        skipped_folders = self._filter_redundant_asset_folders(skipped_folders)
+
+        # Classify as monorepo or single project
+        is_monorepo = len(projects) > 1
+
+        logger.info(f"Detected {len(projects)} project(s) - Monorepo: {is_monorepo}")
+        if skipped_folders:
+            logger.info(f"Skipped {len(skipped_folders)} folder(s) without project indicators")
+
+        return {
+            "is_monorepo": is_monorepo,
+            "project_count": len(projects),
+            "projects": projects,
+            "skipped_folders": skipped_folders
+        }
+
+    def _scan_recursive(self, directory: Path, projects: List[Dict], depth: int, skipped: List[Dict] = None):
+        """Recursively scan directories for projects"""
+        if depth > self.max_depth:
+            return
+
+        if skipped is None:
+            skipped = []
+
+        try:
+            for item in directory.iterdir():
+                # Skip ignored directories
+                if not item.is_dir() or item.name in IGNORE_DIRS or item.name.startswith('.'):
+                    continue
+
+                # Check if this directory is a project
+                project_info = self._analyze_directory(item, depth)
+                if project_info:
+                    projects.append(project_info)
+                    # Don't scan deeper if we found a project (avoid nested projects)
+                    continue
+
+                # Directory has no project indicators - analyze why and track it
+                skip_reason = self._analyze_skipped_folder(item)
+                if skip_reason:
+                    rel_path = item.relative_to(self.repo_path)
+                    skipped.append({
+                        "name": item.name,
+                        "path": str(rel_path),
+                        "reason": skip_reason["reason"],
+                        "details": skip_reason["details"],
+                        "depth": depth
+                    })
+
+                # Continue scanning deeper
+                self._scan_recursive(item, projects, depth + 1, skipped)
+
+        except PermissionError:
+            logger.warning(f"Permission denied: {directory}")
+
+    def _analyze_skipped_folder(self, directory: Path) -> Dict[str, str]:
+        """
+        Analyze why a folder was skipped (no project indicators)
+
+        Returns:
+            Dict with 'reason' and 'details', or None if folder should be ignored
+        """
+        try:
+            items = list(directory.iterdir())
+            files = [f for f in items if f.is_file()]
+            subdirs = [d for d in items if d.is_dir() and d.name not in IGNORE_DIRS]
+
+            # Empty folder
+            if not files and not subdirs:
+                return {
+                    "reason": "Empty folder",
+                    "details": "Contains no files or subfolders"
+                }
+
+            # Analyze file types
+            doc_extensions = {'.md', '.txt', '.rst', '.adoc', '.pdf'}
+            image_extensions = {'.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp', '.bmp'}
+
+            doc_files = [f for f in files if f.suffix.lower() in doc_extensions]
+            image_files = [f for f in files if f.suffix.lower() in image_extensions]
+            other_files = [f for f in files if f.suffix.lower() not in doc_extensions | image_extensions]
+
+            # Documentation-only folder
+            if doc_files and not other_files and not image_files:
+                return {
+                    "reason": "Documentation only",
+                    "details": f"Contains only documentation files ({len(doc_files)} markdown/text files)"
+                }
+
+            # Images/media-only folder
+            if image_files and not other_files and not doc_files:
+                return {
+                    "reason": "Media only",
+                    "details": f"Contains only image files ({len(image_files)} images)"
+                }
+
+            # Mixed docs and images, no code
+            if (doc_files or image_files) and not other_files and len(files) < 5:
+                return {
+                    "reason": "Documentation and media",
+                    "details": f"Contains {len(doc_files)} docs, {len(image_files)} images, no code"
+                }
+
+            # Has files but no project indicators
+            if files and not subdirs:
+                return {
+                    "reason": "No project indicators",
+                    "details": f"Contains {len(files)} files but no package.json, requirements.txt, etc."
+                }
+
+            # Has subdirectories - likely being scanned recursively
+            # Don't report these as skipped since we'll scan their children
+            return None
+
+        except PermissionError:
+            return {
+                "reason": "Permission denied",
+                "details": "Cannot access folder contents"
+            }
+
+    def _analyze_directory(self, directory: Path, depth: int) -> Dict[str, Any]:
+        """
+        Analyze a directory to determine if it's a project
+
+        Returns:
+            Project metadata dict if project detected, None otherwise
+        """
+        try:
+            files = [f.name for f in directory.iterdir() if f.is_file()]
+        except PermissionError:
+            return None
+
+        # Check for project indicators (with glob pattern support)
+        detected_types = []
+        indicator_files = []
+
+        for proj_type, indicators in PROJECT_INDICATORS.items():
+            for indicator in indicators:
+                # Support glob patterns like *.csproj
+                if '*' in indicator or '?' in indicator:
+                    # Use fnmatch for glob patterns
+                    matches = [f for f in files if fnmatch.fnmatch(f, indicator)]
+                    if matches:
+                        detected_types.append(proj_type)
+                        indicator_files.extend(matches)
+                else:
+                    # Exact match
+                    if indicator in files:
+                        detected_types.append(proj_type)
+                        indicator_files.append(indicator)
+
+        # If we found project indicators, it's likely a project
+        if detected_types:
+            # Calculate relative path from repo root
+            rel_path = directory.relative_to(self.repo_path)
+
+            # Estimate project complexity
+            file_count = len(files)
+            dir_count = len([d for d in directory.iterdir() if d.is_dir() and d.name not in IGNORE_DIRS])
+
+            return {
+                "name": directory.name,
+                "path": str(rel_path) if str(rel_path) != "." else "/",
+                "full_path": str(directory),
+                "types": list(set(detected_types)),  # Remove duplicates
+                "indicators": indicator_files,
+                "depth": depth,
+                "file_count": file_count,
+                "dir_count": dir_count,
+                "is_root": depth == 0,
+                "is_composite": False  # Will be updated by grouping logic
+            }
+
+        return None
+
+    def _group_composite_projects(self, projects: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Group projects that are subprojects under a common parent.
+
+        Logic: If multiple sibling folders at the same depth are projects,
+        and they match common subproject patterns (api, ui, frontend, backend, etc.),
+        group them under their parent folder as a single composite project.
+
+        Example:
+            rag-chatbot/api    (project)
+            rag-chatbot/ui     (project)
+            → Groups into: rag-chatbot (composite project)
+
+        Returns:
+            New list with grouped projects
+        """
+        # Build a parent-to-children mapping
+        parent_map: Dict[str, List[Dict]] = {}
+
+        for project in projects:
+            project_path = Path(project["full_path"])
+            parent_path = str(project_path.parent)
+
+            if parent_path not in parent_map:
+                parent_map[parent_path] = []
+            parent_map[parent_path].append(project)
+
+        # Identify parents with multiple subproject children
+        grouped_projects = []
+        processed_projects = set()
+
+        for parent_path, children in parent_map.items():
+            # Skip root-level projects (no grouping needed)
+            if len(children) == 1:
+                if children[0]["path"] not in processed_projects:
+                    grouped_projects.append(children[0])
+                    processed_projects.add(children[0]["path"])
+                continue
+
+            # Check if these siblings look like subprojects (api, ui, etc.)
+            child_names = [child["name"].lower() for child in children]
+            subproject_count = sum(1 for name in child_names if any(pattern in name for pattern in SUBPROJECT_PATTERNS))
+
+            # If 2+ children match subproject patterns, group them under parent
+            if len(children) >= 2 and subproject_count >= 2:
+                parent_dir = Path(parent_path)
+                parent_name = parent_dir.name
+
+                # Skip if parent is the repo root
+                if str(parent_dir) == str(self.repo_path):
+                    # Don't group root-level subprojects, keep them separate
+                    for child in children:
+                        if child["path"] not in processed_projects:
+                            grouped_projects.append(child)
+                            processed_projects.add(child["path"])
+                    continue
+
+                # Create composite project for the parent
+                composite_project = {
+                    "name": parent_name,
+                    "path": str(parent_dir.relative_to(self.repo_path)),
+                    "full_path": str(parent_dir),
+                    "types": list(set([t for child in children for t in child["types"]])),
+                    "indicators": [f"{child['name']}/{ind}" for child in children for ind in child["indicators"]],
+                    "depth": children[0]["depth"] - 1,  # Parent is one level up
+                    "file_count": sum(child["file_count"] for child in children),
+                    "dir_count": len(children),
+                    "is_root": False,
+                    "is_composite": True,
+                    "subprojects": [child["name"] for child in children]
+                }
+
+                grouped_projects.append(composite_project)
+
+                # Mark children as processed
+                for child in children:
+                    processed_projects.add(child["path"])
+
+                logger.info(f"Grouped {len(children)} subprojects under '{parent_name}': {', '.join(child_names)}")
+
+            else:
+                # Not a composite project pattern, keep children separate
+                for child in children:
+                    if child["path"] not in processed_projects:
+                        grouped_projects.append(child)
+                        processed_projects.add(child["path"])
+
+        return grouped_projects
+
+    def _filter_nested_skipped_folders(self, skipped_folders: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Filter out skipped folders that are children of other skipped folders.
+        Only keep top-level skipped folders to avoid redundant information.
+
+        Example: If 'code-generation' is skipped, don't also show 'code-generation/src' and 'code-generation/img'
+        """
+        if not skipped_folders:
+            return []
+
+        # Sort by depth (shallowest first) and then by path
+        sorted_folders = sorted(skipped_folders, key=lambda x: (x['depth'], x['path']))
+
+        filtered = []
+        for folder in sorted_folders:
+            # Normalize path using Path to handle both / and \ correctly
+            folder_path = Path(folder['path'])
+
+            # Check if this folder is a child of any already-added skipped folder
+            is_nested = False
+            for parent in filtered:
+                parent_path = Path(parent['path'])
+                # Check if folder_path is a child of parent_path
+                try:
+                    folder_path.relative_to(parent_path)
+                    # If no exception, folder_path is under parent_path
+                    is_nested = True
+                    break
+                except ValueError:
+                    # Not a subpath, continue checking
+                    pass
+
+            # Only add if it's not nested under another skipped folder
+            if not is_nested:
+                filtered.append(folder)
+
+        logger.info(f"Filtered nested folders: {len(skipped_folders)} -> {len(filtered)}")
+        return filtered
+
+    def _filter_redundant_asset_folders(self, skipped_folders: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """
+        Filter out standalone asset folders (images, media) when there's a documentation folder.
+
+        Rationale: If a repo has both a 'docs' folder and an 'images' folder at the same level,
+        the images likely belong to the docs, so we only need to show the docs folder.
+        """
+        if not skipped_folders:
+            return []
+
+        # Check if there's at least one documentation folder
+        has_doc_folder = any(
+            folder['reason'] in ['Documentation only', 'Documentation and media']
+            for folder in skipped_folders
+        )
+
+        # If there's a doc folder, filter out standalone media folders
+        if has_doc_folder:
+            filtered = [
+                folder for folder in skipped_folders
+                if folder['reason'] != 'Media only'
+            ]
+            if len(filtered) < len(skipped_folders):
+                logger.info(f"Filtered asset folders: {len(skipped_folders)} -> {len(filtered)} (removed media-only folders)")
+            return filtered
+
+        # No doc folder, keep all skipped folders
+        return skipped_folders
+
+
+def detect_projects(repo_path: str) -> Dict[str, Any]:
+    """
+    Convenience function to detect projects in a repository
+
+    Args:
+        repo_path: Path to the cloned repository
+
+    Returns:
+        Dict with:
+            - is_monorepo: bool
+            - project_count: int
+            - projects: List[Dict] with project metadata
+    """
+    detector = ProjectDetector(repo_path, group_subprojects=True)
+    return detector.detect_projects()
diff --git a/DocuGenMicroagents/api/workflow.py b/DocuGenMicroagents/api/workflow.py
new file mode 100644
index 0000000000..a1ffc02a7e
--- /dev/null
+++ b/DocuGenMicroagents/api/workflow.py
@@ -0,0 +1,1322 @@
+"""
+Simplified LangGraph Workflow for 10 Micro-Agents
+Optimized for 8K context models with evidence-based architecture
+"""
+
+import logging
+from typing import Dict, Any
+from langgraph.graph import StateGraph, END
+from langgraph.checkpoint.memory import MemorySaver
+
+from models.state import DocGenState
+from models.evidence import EvidencePacket, EvidenceItem
+from models import get_log_manager, LogType
+from services import get_llm, GitService
+from services.git_service import parse_github_url
+from utils import detect_projects
+from config import settings
+from langchain_core.messages import AIMessage
+import os
+import json
+import re
+
+# Import all agents (6 section writers + planner + mermaid + QA)
+from agents.code_explorer_agent import run_code_explorer_agent
+from agents.api_reference_agent import run_api_reference_agent
+from agents.call_graph_agent import run_call_graph_agent
+from agents.error_analysis_agent import run_error_analysis_agent
+from agents.env_config_agent import run_env_config_agent
+from agents.dependency_analyzer_agent import run_dependency_analyzer_agent
+from agents.planner_agent import run_planner_agent
+from agents.mermaid_agent import run_mermaid_agent
+from agents.qa_validator_agent import run_qa_validator_agent
+from core.metrics_collector import MetricsCollector
+
+logger = logging.getLogger(__name__)
+
+
+class SimplifiedDocuGenWorkflow:
+    """
+    Simplified workflow with 9 micro-agents optimized for 8K context models.
+
+    Architecture:
+    - 6 Section Writer Agents (write sections directly)
+      - Code Explorer: Project Overview + Features
+      - API Reference: API Reference
+      - Call Graph: Architecture
+      - Error Analysis: Troubleshooting
+      - Env Config: Configuration
+      - Dependency Analyzer: Prerequisites + Quick Start Deployment
+    - 1 Planner Agent (decides which sections to include)
+    - 1 Mermaid Agent (generates architecture diagram)
+    - 1 QA Agent (validates quality)
+    """
+
+    def __init__(self):
+        self.git_service = GitService()
+        self.log_manager = get_log_manager()
+        self.graph = None
+        self.checkpointer = None
+        self.metrics_collectors = {}  # Store metrics collector per job_id
+
+    def _get_metrics_collector(self, job_id: str) -> MetricsCollector:
+        """Get or create metrics collector for a job"""
+        if job_id not in self.metrics_collectors:
+            self.metrics_collectors[job_id] = MetricsCollector(job_id)
+        return self.metrics_collectors[job_id]
+
+    def _get_target_path(self, state: DocGenState) -> str:
+        """
+        Get the target path for agent analysis.
+        If user selected specific projects, return path to that project.
+        Otherwise, return full repo path.
+        """
+        repo_path = state["repo_path"]
+        selected_projects = state.get("selected_projects")
+
+        if selected_projects and len(selected_projects) > 0:
+            import os
+            return os.path.join(repo_path, selected_projects[0])
+        return repo_path
+
+    def _get_final_assistant_text(self, messages) -> str:
+        """
+        Extract the last non-empty AIMessage content from LangGraph result.
+
+        FIX: messages[-1] is not guaranteed to be the final assistant answer.
+        It can be a ToolMessage, intermediate AIMessage, or truncated stub.
+        """
+        # Walk backwards and return the last assistant AIMessage with non-empty content
+        for m in reversed(messages or []):
+            if isinstance(m, AIMessage) and isinstance(getattr(m, "content", None), str):
+                txt = m.content.strip()
+                if txt:
+                    return txt
+        # Fallback
+        return (messages[-1].content or "").strip() if messages else ""
+
+    def _store_section(self, sections_dict: Dict[str, str], heading: str, section_md: str):
+        """
+        Store section with guard against overwriting good content with stubs.
+
+        FIX: Don't replace a complete section with an empty header-only stub.
+        """
+        new_md = (section_md or "").strip()
+        old_md = (sections_dict.get(heading) or "").strip()
+
+        # Don't overwrite a real section (>= 80 chars) with a stub (< 80 chars)
+        if len(new_md) < 80 and len(old_md) >= 80:
+            logger.warning(f"[Parser] Skipping stub overwrite for '{heading}': {len(new_md)} < {len(old_md)} chars")
+            return
+
+        sections_dict[heading] = new_md
+
+    def _parse_and_store_sections(self, output: str, sections_dict: Dict[str, str]):
+        """
+        Parse agent output to extract markdown sections with subsection handling.
+
+        FIX: Merges ### subsections back into their parent ## sections.
+
+        Logic:
+        - If we see "## Parent" followed by "### Child", merge them into one section
+        - If we see standalone "## Section" with content, store it as-is
+        """
+        # Split by ## headings but preserve them
+        lines = output.split('\n')
+        current_section = None
+        current_content = []
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+
+            # Check if this is a ## heading
+            if line.startswith('## '):
+                # Store previous section if exists
+                if current_section and current_content:
+                    full_content = '\n'.join(current_content).strip()
+                    self._store_section(sections_dict, current_section, full_content)
+
+                # Start new section
+                current_section = line.replace('##', '').strip()
+                current_content = [line]  # Include the heading itself
+
+            elif line.strip():  # Non-empty line
+                if current_section:
+                    current_content.append(line)
+            else:  # Empty line
+                if current_section:
+                    current_content.append(line)
+
+            i += 1
+
+        # Store last section
+        if current_section and current_content:
+            full_content = '\n'.join(current_content).strip()
+            self._store_section(sections_dict, current_section, full_content)
+
+    async def create_workflow(self) -> StateGraph:
+        """Build the simplified 10-agent workflow"""
+        workflow = StateGraph(DocGenState)
+
+        # Add nodes
+        workflow.add_node("clone_repository", self.clone_repository_node)
+        workflow.add_node("project_detection", self.project_detection_node)
+
+        # Section Writer Agents
+        workflow.add_node("code_explorer", self.code_explorer_node)
+        workflow.add_node("api_reference", self.api_reference_node)
+        workflow.add_node("call_graph", self.call_graph_node)
+        workflow.add_node("error_analysis", self.error_analysis_node)
+        workflow.add_node("env_config", self.env_config_node)
+        workflow.add_node("dependency_analyzer", self.dependency_analyzer_node)
+
+        # Evidence Aggregation
+        workflow.add_node("evidence_aggregator", self.evidence_aggregator_node)
+
+        # Planning
+        workflow.add_node("planner", self.planner_node)
+
+        # Mermaid Diagram Generation
+        workflow.add_node("mermaid", self.mermaid_node)
+
+        # QA Validation
+        workflow.add_node("qa_validator", self.qa_validator_node)
+
+        # Final assembly
+        workflow.add_node("assembly", self.assembly_node)
+
+        # Define workflow flow (NEW: analysis → evidence_aggregator → planner → mermaid → QA → assembly)
+        workflow.set_entry_point("clone_repository")
+        workflow.add_edge("clone_repository", "project_detection")
+        workflow.add_edge("project_detection", "code_explorer")
+        workflow.add_edge("code_explorer", "api_reference")
+        workflow.add_edge("api_reference", "call_graph")
+        workflow.add_edge("call_graph", "error_analysis")
+        workflow.add_edge("error_analysis", "env_config")
+        workflow.add_edge("env_config", "dependency_analyzer")
+        workflow.add_edge("dependency_analyzer", "evidence_aggregator")  # NEW: aggregate evidence after all analysis
+        workflow.add_edge("evidence_aggregator", "planner")  # Planner uses evidence for routing
+        workflow.add_edge("planner", "mermaid")
+        workflow.add_edge("mermaid", "qa_validator")
+        workflow.add_edge("qa_validator", "assembly")
+        workflow.add_edge("assembly", END)
+
+        # Use memory checkpointer (ephemeral)
+        checkpointer = MemorySaver()
+        compiled = workflow.compile(checkpointer=checkpointer)
+
+        self.graph = compiled
+        self.checkpointer = checkpointer
+        return compiled
+
+    async def clone_repository_node(self, state: DocGenState) -> DocGenState:
+        """Clone the GitHub repository (reuse existing implementation)"""
+        job_id = state["job_id"]
+        repo_url = state["repo_url"]
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message=f"📦 Cloning repository: {repo_url}"
+        )
+
+        try:
+            parsed_url = parse_github_url(repo_url)
+
+            def progress_callback(message: str):
+                import asyncio
+                try:
+                    loop = asyncio.get_event_loop()
+                    loop.create_task(self.log_manager.log_async(
+                        job_id=job_id,
+                        log_type=LogType.INFO,
+                        message=message
+                    ))
+                except RuntimeError:
+                    logger.info(message)
+
+            repo_path, metadata = self.git_service.clone_repository(
+                parsed_url["clone_url"],
+                branch=parsed_url["branch"],
+                progress_callback=progress_callback
+            )
+
+            if parsed_url["is_subfolder"]:
+                import os
+                target_path = os.path.join(repo_path, parsed_url["subfolder"])
+                if not os.path.exists(target_path):
+                    raise ValueError(f"Subfolder '{parsed_url['subfolder']}' not found")
+                state["repo_path"] = target_path
+                state["repo_name"] = parsed_url["display_name"]
+                state["is_subfolder_target"] = True
+            else:
+                state["repo_path"] = repo_path
+                state["repo_name"] = parsed_url["repo"]
+                state["is_subfolder_target"] = False
+
+            state["default_branch"] = metadata["default_branch"]
+            state["workflow_status"] = "detecting"
+
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Repository cloned successfully"
+            )
+
+            return state
+
+        except Exception as e:
+            logger.error(f"Clone failed: {e}")
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.ERROR,
+                message=f"❌ Clone failed: {str(e)}"
+            )
+            state["error"] = str(e)
+            state["workflow_status"] = "failed"
+            raise
+
+    async def project_detection_node(self, state: DocGenState) -> DocGenState:
+        """Detect projects in repository (reuse existing implementation)"""
+        job_id = state["job_id"]
+        repo_path = state["repo_path"]
+        is_subfolder = state.get("is_subfolder_target", False)
+
+        if is_subfolder:
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message=f"🎯 Targeting subfolder: {state['repo_name']}"
+            )
+            state["awaiting_project_selection"] = False
+            state["selected_projects"] = None
+            state["is_monorepo"] = False
+            state["detected_projects"] = []
+            state["workflow_status"] = "analyzing"
+            return state
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="🔍 Detecting projects..."
+        )
+
+        try:
+            detection_result = detect_projects(repo_path)
+            state["is_monorepo"] = detection_result["is_monorepo"]
+            state["detected_projects"] = detection_result["projects"]
+            state["skipped_folders"] = detection_result.get("skipped_folders", [])
+
+            if detection_result["project_count"] <= 1:
+                state["awaiting_project_selection"] = False
+                state["selected_projects"] = None
+                state["workflow_status"] = "analyzing"
+            else:
+                # Multiple projects - need selection (handled by server)
+                state["awaiting_project_selection"] = True
+                state["workflow_status"] = "awaiting_selection"
+
+            return state
+
+        except Exception as e:
+            logger.error(f"Detection failed: {e}")
+            state["awaiting_project_selection"] = False
+            state["selected_projects"] = None
+            state["workflow_status"] = "analyzing"
+            return state
+
+    # Section Writer Agents
+    async def code_explorer_node(self, state: DocGenState) -> DocGenState:
+        """Run Code Explorer agent - writes Overview + Features sections"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("CodeExplorer")
+
+        # CRITICAL: Update repo_name to selected project name if project was selected
+        selected_projects = state.get("selected_projects")
+        if selected_projects and len(selected_projects) > 0:
+            # Update repo_name to the selected project folder name
+            state["repo_name"] = selected_projects[0]
+            logger.info(f"[CodeExplorer] Updated repo_name to selected project: {state['repo_name']}")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message=f"🔍 Running Overview & Features Writer (1/7) for {state['repo_name']}...",
+            agent_name="CodeExplorer"
+        )
+
+        llm = get_llm(model_name=settings.CODE_EXPLORER_MODEL, temperature=0.7)
+        result = await run_code_explorer_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            # Parse output to extract two sections: Project Overview and Features
+            output = result.get("output", "")
+            sections_dict = state.get("readme_sections") or {}
+
+            # Extract sections from output (they're in format: ## Section Name\n\nContent...)
+            self._parse_and_store_sections(output, sections_dict)
+            state["readme_sections"] = sections_dict
+
+            logger.info(f"[CodeExplorer] Stored sections: {list(sections_dict.keys())}")
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Overview & Features sections completed",
+                agent_name="CodeExplorer"
+            )
+
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "CodeExplorer",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"CodeExplorer failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("CodeExplorer", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "CodeExplorer"
+        return state
+
+    async def api_reference_node(self, state: DocGenState) -> DocGenState:
+        """Run API Reference agent - extracts endpoint data (no markdown sections)"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("APIReference")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="📡 Running API Endpoint Extractor (2/7)...",
+            agent_name="APIReference"
+        )
+
+        llm = get_llm(model_name=settings.API_REFERENCE_MODEL, temperature=0.7)
+        result = await run_api_reference_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            output = result.get("output", "")
+            # Parse JSON output to extract endpoint data
+            import json
+            import re
+            try:
+                # Try to find JSON in output (might be wrapped in markdown code block)
+                json_match = re.search(r'```json\s*(\{.*?\})\s*```', output, re.DOTALL)
+                if json_match:
+                    json_str = json_match.group(1)
+                else:
+                    # Try to find raw JSON object
+                    json_match = re.search(r'\{.*\}', output, re.DOTALL)
+                    if json_match:
+                        json_str = json_match.group(0)
+                    else:
+                        json_str = output
+
+                endpoint_data = json.loads(json_str)
+                state["api_endpoints"] = endpoint_data.get("endpoints", [])
+                logger.info(f"[APIReference] Extracted {len(state['api_endpoints'])} endpoints")
+
+                await self.log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.SUCCESS,
+                    message=f"✅ Extracted {len(state['api_endpoints'])} API endpoints",
+                    agent_name="APIReference"
+                )
+                # End metrics tracking (success)
+                metrics.end_agent(
+                    "APIReference",
+                    success=True,
+                    input_tokens=result.get("input_tokens", 0),
+                    output_tokens=result.get("output_tokens", 0),
+                    tool_calls=result.get("tool_calls", 0),
+                    llm_calls=result.get("llm_calls", 0)
+                )
+            except (json.JSONDecodeError, AttributeError) as e:
+                logger.warning(f"[APIReference] Failed to parse JSON: {e}. Storing empty endpoint list.")
+                state["api_endpoints"] = []
+                await self.log_manager.log_async(
+                    job_id=job_id,
+                    log_type=LogType.WARNING,
+                    message="⚠️ No API endpoints extracted",
+                    agent_name="APIReference"
+                )
+                # End metrics tracking (success with warning)
+                metrics.end_agent(
+                    "APIReference",
+                    success=True,
+                    input_tokens=result.get("input_tokens", 0),
+                    output_tokens=result.get("output_tokens", 0),
+                    tool_calls=result.get("tool_calls", 0),
+                    llm_calls=result.get("llm_calls", 0)
+                )
+        else:
+            logger.error(f"APIReference failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("APIReference", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "APIReference"
+        return state
+
+    async def call_graph_node(self, state: DocGenState) -> DocGenState:
+        """Run Call Graph agent - writes Architecture section"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("CallGraph")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="🔗 Running Architecture Writer (3/7)...",
+            agent_name="CallGraph"
+        )
+
+        llm = get_llm(model_name=settings.CALL_GRAPH_MODEL, temperature=0.7)
+        result = await run_call_graph_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            output = result.get("output", "")
+            sections_dict = state.get("readme_sections") or {}
+            self._parse_and_store_sections(output, sections_dict)
+            state["readme_sections"] = sections_dict
+
+            logger.info(f"[CallGraph] Stored sections: {list(sections_dict.keys())}")
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Architecture section completed",
+                agent_name="CallGraph"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "CallGraph",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"CallGraph failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("CallGraph", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "CallGraph"
+        return state
+
+    async def error_analysis_node(self, state: DocGenState) -> DocGenState:
+        """Run Error Analysis agent - writes Troubleshooting section"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("ErrorAnalysis")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="⚠️ Running Troubleshooting Writer (4/7)...",
+            agent_name="ErrorAnalysis"
+        )
+
+        llm = get_llm(model_name=settings.ERROR_ANALYSIS_MODEL, temperature=0.7)
+        result = await run_error_analysis_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            output = result.get("output", "")
+            sections_dict = state.get("readme_sections") or {}
+            self._parse_and_store_sections(output, sections_dict)
+            state["readme_sections"] = sections_dict
+
+            logger.info(f"[ErrorAnalysis] Stored sections: {list(sections_dict.keys())}")
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Troubleshooting section completed",
+                agent_name="ErrorAnalysis"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "ErrorAnalysis",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"ErrorAnalysis failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("ErrorAnalysis", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "ErrorAnalysis"
+        return state
+
+    async def env_config_node(self, state: DocGenState) -> DocGenState:
+        """Run Environment Config agent - writes Configuration section"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("EnvConfig")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="⚙️ Running Configuration Writer (5/7)...",
+            agent_name="EnvConfig"
+        )
+
+        llm = get_llm(model_name=settings.ENV_CONFIG_MODEL, temperature=0.7)
+        result = await run_env_config_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            output = result.get("output", "")
+
+            # DEBUG: Log raw output
+            logger.info(f"[EnvConfig] raw_output_head={output[:400]!r}")
+            logger.info(f"[EnvConfig] raw_output_tail={output[-400:]!r}")
+
+            sections_dict = state.get("readme_sections") or {}
+            self._parse_and_store_sections(output, sections_dict)
+            state["readme_sections"] = sections_dict
+
+            logger.info(f"[EnvConfig] Stored sections: {list(sections_dict.keys())}")
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Configuration section completed",
+                agent_name="EnvConfig"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "EnvConfig",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"EnvConfig failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("EnvConfig", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "EnvConfig"
+        return state
+
+    async def dependency_analyzer_node(self, state: DocGenState) -> DocGenState:
+        """Run Dependency Analyzer agent - writes Prerequisites & Deployment sections"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("DependencyAnalyzer")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="📦 Running Prerequisites & Deployment Writer (6/7)...",
+            agent_name="DependencyAnalyzer"
+        )
+
+        llm = get_llm(model_name=settings.DEPENDENCY_ANALYZER_MODEL, temperature=0.7)
+        repo_url = state.get("repo_url", "")
+        result = await run_dependency_analyzer_agent(llm=llm, repo_path=target_path, job_id=job_id, repo_url=repo_url)
+
+        if result.get("success"):
+            output = result.get("output", "")
+
+            # DEBUG: Log raw output
+            logger.info(f"[DependencyAnalyzer] raw_output_head={output[:400]!r}")
+            logger.info(f"[DependencyAnalyzer] raw_output_tail={output[-400:]!r}")
+
+            sections_dict = state.get("readme_sections") or {}
+            self._parse_and_store_sections(output, sections_dict)
+            state["readme_sections"] = sections_dict
+
+            logger.info(f"[DependencyAnalyzer] Stored sections: {list(sections_dict.keys())}")
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Prerequisites & Deployment sections completed",
+                agent_name="DependencyAnalyzer"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "DependencyAnalyzer",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"DependencyAnalyzer failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("DependencyAnalyzer", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "DependencyAnalyzer"
+        return state
+
+    # Evidence Aggregation
+    async def evidence_aggregator_node(self, state: DocGenState) -> DocGenState:
+        """
+        DUAL-MODE Evidence Aggregator - Collects evidence from file system and agent outputs.
+
+        This node creates the central EvidencePacket by:
+        1. Direct file system checks (requirements.txt, package.json, etc.)
+        2. Extracting structured data from agent outputs (dual-mode: supports both strings and JSON)
+
+        FIX 1: Dual-mode aggregator - works with current string outputs AND future JSON outputs
+        FIX 2: Deterministic repo_name derivation from URL or folder path
+        FIX: Uses target_path (selected project) instead of repo_path (root)
+        """
+        job_id = state["job_id"]
+        repo_url = state.get("repo_url", "")
+        readme_sections = state.get("readme_sections", {})
+
+        # CRITICAL: Use target path (respects project selection)
+        target_path = self._get_target_path(state)
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="📊 Aggregating evidence from repository...",
+            agent_name="EvidenceAggregator"
+        )
+
+        try:
+            # FIX 2: Derive repo_name deterministically (never from LLM output)
+            # Use selected project name if available, otherwise derive from URL/path
+            selected_projects = state.get("selected_projects")
+            if selected_projects and len(selected_projects) > 0:
+                repo_name = selected_projects[0]
+            elif repo_url:
+                # Parse from GitHub URL: github.com/user/repo-name
+                match = re.search(r'github\.com/[^/]+/([^/\.]+)', repo_url)
+                repo_name = match.group(1) if match else os.path.basename(target_path)
+            else:
+                # Use folder name
+                repo_name = os.path.basename(target_path) if target_path else "Repository"
+
+            # Initialize evidence packet with target_path
+            evidence = EvidencePacket(repo_name=repo_name, repo_path=target_path)
+
+            # === DIRECT FILE SYSTEM CHECKS (don't rely on agent outputs) ===
+
+            # Check for Python dependencies (root and subdirectories)
+            python_dep_locations = [
+                os.path.join(target_path, "requirements.txt"),
+                os.path.join(target_path, "api", "requirements.txt"),
+                os.path.join(target_path, "backend", "requirements.txt"),
+                os.path.join(target_path, "server", "requirements.txt")
+            ]
+
+            for requirements_path in python_dep_locations:
+                if os.path.exists(requirements_path):
+                    rel_path = os.path.relpath(requirements_path, target_path)
+                    evidence.add_evidence(EvidenceItem(
+                        category="dependency",
+                        key=rel_path,
+                        value="Python dependencies",
+                        source_files=[rel_path]
+                    ))
+                    try:
+                        with open(requirements_path, 'r', encoding='utf-8', errors='ignore') as f:
+                            deps = [
+                                line.split('==')[0].split('>=')[0].split('~=')[0].strip()
+                                for line in f
+                                if line.strip() and not line.startswith('#')
+                            ]
+                            evidence.python_deps.extend(deps)
+                            logger.info(f"[Evidence] Found {len(deps)} Python dependencies in {rel_path}")
+                    except Exception as e:
+                        logger.warning(f"[Evidence] Failed to parse {rel_path}: {e}")
+
+            if evidence.python_deps:
+                evidence.has_backend = True
+                # Remove duplicates
+                evidence.python_deps = list(set(evidence.python_deps))
+
+            # Check for Node.js dependencies (root and subdirectories)
+            node_dep_locations = [
+                os.path.join(target_path, "package.json"),
+                os.path.join(target_path, "ui", "package.json"),
+                os.path.join(target_path, "frontend", "package.json"),
+                os.path.join(target_path, "client", "package.json")
+            ]
+
+            for package_json_path in node_dep_locations:
+                if os.path.exists(package_json_path):
+                    rel_path = os.path.relpath(package_json_path, target_path)
+                    evidence.has_frontend = True
+                    try:
+                        with open(package_json_path, 'r', encoding='utf-8') as f:
+                            pkg = json.load(f)
+                            deps = list(pkg.get("dependencies", {}).keys())
+                            evidence.node_deps.extend(deps)
+
+                            # Detect frontend framework
+                            if "react" in deps and not evidence.frontend_framework:
+                                evidence.frontend_framework = "React"
+                            elif "vue" in deps and not evidence.frontend_framework:
+                                evidence.frontend_framework = "Vue"
+                            elif "@angular/core" in deps and not evidence.frontend_framework:
+                                evidence.frontend_framework = "Angular"
+
+                            evidence.add_evidence(EvidenceItem(
+                                category="dependency",
+                                key=rel_path,
+                                value=f"Node.js project with {len(deps)} dependencies",
+                                source_files=[rel_path]
+                            ))
+                            logger.info(f"[Evidence] Found {len(deps)} Node dependencies in {rel_path}")
+                    except Exception as e:
+                        logger.warning(f"[Evidence] Failed to parse {rel_path}: {e}")
+
+            if evidence.node_deps:
+                # Remove duplicates
+                evidence.node_deps = list(set(evidence.node_deps))
+
+            # Check for Docker
+            dockerfile_path = os.path.join(target_path, "Dockerfile")
+            compose_path = os.path.join(target_path, "docker-compose.yml")
+            if os.path.exists(dockerfile_path):
+                evidence.has_docker = True
+                evidence.docker_files.append("Dockerfile")
+                evidence.add_evidence(EvidenceItem(
+                    category="infrastructure",
+                    key="Dockerfile",
+                    value="Docker containerization",
+                    source_files=["Dockerfile"]
+                ))
+            if os.path.exists(compose_path):
+                evidence.has_docker = True
+                evidence.docker_files.append("docker-compose.yml")
+                evidence.add_evidence(EvidenceItem(
+                    category="infrastructure",
+                    key="docker-compose.yml",
+                    value="Docker Compose orchestration",
+                    source_files=["docker-compose.yml"]
+                ))
+
+            if evidence.has_docker:
+                logger.info(f"[Evidence] Found Docker files: {evidence.docker_files}")
+
+            # Check for .env files
+            env_example_path = os.path.join(target_path, ".env.example")
+            if os.path.exists(env_example_path):
+                evidence.env_files.append(".env.example")
+                evidence.add_evidence(EvidenceItem(
+                    category="config",
+                    key=".env.example",
+                    value="Environment configuration template",
+                    source_files=[".env.example"]
+                ))
+                logger.info("[Evidence] Found .env.example")
+
+            # Extract API endpoints from state (populated by API Reference agent)
+            api_endpoints = state.get("api_endpoints", [])
+            if api_endpoints:
+                evidence.api_endpoints = api_endpoints
+                logger.info(f"[Evidence] Extracted {len(api_endpoints)} API endpoints from state")
+
+            # Detect languages from file extensions
+            try:
+                for root, dirs, files in os.walk(target_path):
+                    # Skip node_modules, .git, venv, etc.
+                    dirs[:] = [d for d in dirs if d not in ['.git', 'node_modules', 'venv', '__pycache__', 'dist', 'build']]
+
+                    for file in files:
+                        ext = os.path.splitext(file)[1]
+                        if ext in ['.py', '.js', '.jsx', '.ts', '.tsx', '.java', '.go', '.rs', '.cpp', '.c', '.rb']:
+                            lang_map = {
+                                '.py': 'Python', '.js': 'JavaScript', '.jsx': 'JavaScript',
+                                '.ts': 'TypeScript', '.tsx': 'TypeScript', '.java': 'Java',
+                                '.go': 'Go', '.rs': 'Rust', '.cpp': 'C++', '.c': 'C', '.rb': 'Ruby'
+                            }
+                            lang = lang_map.get(ext, 'Unknown')
+                            evidence.languages[lang] = evidence.languages.get(lang, 0) + 1
+
+                logger.info(f"[Evidence] Detected languages: {evidence.languages}")
+            except Exception as e:
+                logger.warning(f"[Evidence] Failed to detect languages: {e}")
+
+            # Store evidence packet in state
+            state["evidence_packet"] = evidence
+
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message=f"✅ Evidence aggregated: {len(evidence.python_deps)} Python deps, {len(evidence.node_deps)} Node deps, {len(evidence.docker_files)} Docker files",
+                agent_name="EvidenceAggregator"
+            )
+
+            logger.info(f"[Evidence] Final evidence: {evidence.to_dict()}")
+
+        except Exception as e:
+            logger.error(f"Evidence aggregation failed: {e}")
+            # Create minimal evidence packet on failure
+            state["evidence_packet"] = EvidencePacket(
+                repo_name=os.path.basename(target_path) if target_path else "Repository",
+                repo_path=target_path
+            )
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.WARNING,
+                message=f"⚠️ Evidence aggregation failed, using minimal evidence: {str(e)}",
+                agent_name="EvidenceAggregator"
+            )
+
+        state["current_agent"] = "EvidenceAggregator"
+        return state
+
+    # Planning
+    async def planner_node(self, state: DocGenState) -> DocGenState:
+        """Run Planner agent - decides which sections to include"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("Planner")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="📋 Running Planner (7/7)...",
+            agent_name="Planner"
+        )
+
+        llm = get_llm(model_name=settings.PLANNER_MODEL, temperature=0.7)
+        result = await run_planner_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            output = result.get("output", "")
+            # Try to parse JSON output
+            import json
+            try:
+                plan_data = json.loads(output)
+                state["project_type"] = plan_data.get("project_type", "Unknown")
+                state["documentation_sections"] = plan_data.get("sections", ["Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "Troubleshooting"])
+                logger.info(f"[Planner] Planned sections: {state['documentation_sections']}")
+            except:
+                state["project_type"] = "Unknown"
+                state["documentation_sections"] = ["Project Overview", "Features", "Architecture", "Prerequisites", "Quick Start Deployment", "Troubleshooting"]
+
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message=f"✅ Planner completed - {len(state['documentation_sections'])} sections planned",
+                agent_name="Planner"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "Planner",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"Planner failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("Planner", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "Planner"
+        return state
+
+    async def mermaid_node(self, state: DocGenState) -> DocGenState:
+        """Run Mermaid Diagram agent - generates architecture diagram with semantic validation"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+        evidence_packet = state.get("evidence_packet")
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("Mermaid")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="📊 Generating architecture diagram...",
+            agent_name="Mermaid"
+        )
+
+        llm = get_llm(model_name=settings.MERMAID_MODEL, temperature=0.7)
+        # Pass API endpoints from state to Mermaid agent
+        api_endpoints = state.get("api_endpoints", [])
+        result = await run_mermaid_agent(llm=llm, repo_path=target_path, job_id=job_id, api_endpoints=api_endpoints)
+
+        if result.get("success"):
+            diagram_output = result.get("output", "")
+            # Extract only the mermaid code (remove markdown blocks and extra text)
+            diagram_code = self._extract_mermaid_code(diagram_output)
+            if diagram_code:
+                # === NEW: Semantic Validation (FIX 4 applied) ===
+                is_valid, errors = self._validate_mermaid_semantics(diagram_code, evidence_packet)
+
+                if not is_valid:
+                    logger.warning(f"[Mermaid] Semantic validation failed: {errors}")
+                    await self.log_manager.log_async(
+                        job_id=job_id,
+                        log_type=LogType.WARNING,
+                        message=f"⚠️ Diagram has semantic issues: {', '.join(errors[:2])}",
+                        agent_name="Mermaid"
+                    )
+                    # Note: We still use the diagram, but log the issues
+                    # Future enhancement: add a retry mechanism here
+
+                state["mermaid_diagrams"] = {"architecture": diagram_code}
+                logger.info(f"[Mermaid] Extracted diagram: {len(diagram_code)} chars")
+            else:
+                state["mermaid_diagrams"] = {}
+                logger.warning("[Mermaid] Could not extract valid mermaid code")
+
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message="✅ Mermaid Generator completed",
+                agent_name="Mermaid"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "Mermaid",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"Mermaid failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("Mermaid", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "Mermaid"
+        return state
+
+    def _extract_mermaid_code(self, text: str) -> str:
+        """Extract clean mermaid code from agent output"""
+        # Try to find mermaid code block
+        patterns = [
+            r'```mermaid\s+(.*?)\s+```',  # ```mermaid ... ```
+            r'```\s+(graph\s+TD.*?)```',   # ``` graph TD ... ```
+            r'(graph\s+TD.*?)(?=\n\n|\Z)'  # graph TD ... (until double newline or end)
+        ]
+
+        for pattern in patterns:
+            match = re.search(pattern, text, re.DOTALL)
+            if match:
+                code = match.group(1).strip()
+                # Validate it starts with graph/flowchart
+                if code.startswith(('graph ', 'flowchart ', 'sequenceDiagram', 'classDiagram')):
+                    return code
+
+        # Fallback: if text starts with graph/flowchart directly
+        if text.strip().startswith(('graph ', 'flowchart ')):
+            return text.strip()
+
+        return ""
+
+    def _validate_mermaid_semantics(self, diagram_code: str, evidence_packet) -> tuple:
+        """
+        Validate Mermaid diagram semantics (FIX 4 applied - minimal rules only).
+
+        Returns:
+            (is_valid, errors_list)
+        """
+        errors = []
+        lines = diagram_code.split('\n')
+
+        # Rule 1: No endpoint nodes with paths/methods
+        endpoint_patterns = ['/upload', '/query', '/health', '/api/', 'GET ', 'POST ', 'PUT ', 'DELETE ']
+        for line in lines:
+            for pattern in endpoint_patterns:
+                if pattern in line and '[' in line:
+                    errors.append(f"Diagram contains endpoint/route node: {pattern}")
+                    break
+
+        # Rule 2: Must include User or Client
+        has_user = any(('User' in line or 'Client' in line) and '[' in line for line in lines)
+        if not has_user:
+            errors.append("Diagram should include User or Client node")
+
+        # Rule 3: Must have Backend if backend exists
+        if evidence_packet and evidence_packet.has_backend:
+            has_backend = any(('API' in line or 'Backend' in line or 'Server' in line)
+                             and '[' in line for line in lines)
+            if not has_backend:
+                errors.append("Diagram missing Backend/API node (backend detected in repo)")
+
+        # Rule 4: Must have Frontend if frontend exists
+        if evidence_packet and evidence_packet.has_frontend:
+            has_frontend = any(('Frontend' in line or 'UI' in line or 'Client' in line or 'Web' in line)
+                              and '[' in line for line in lines)
+            if not has_frontend:
+                errors.append(f"Diagram missing Frontend/UI node ({evidence_packet.frontend_framework} detected)")
+
+        # Rule 5: Must have Database if common DB deps found
+        if evidence_packet:
+            db_deps = ['sqlalchemy', 'psycopg2', 'pymongo', 'mysql', 'redis', 'elasticsearch']
+            has_db_dep = any(dep in [d.lower() for d in evidence_packet.python_deps] for dep in db_deps)
+            if has_db_dep:
+                has_db_node = any(('Database' in line or 'DB' in line or 'Storage' in line or 'Cache' in line)
+                                 and '[' in line for line in lines)
+                if not has_db_node:
+                    errors.append("Diagram missing Database node (database dependency detected)")
+
+        return (len(errors) == 0, errors)
+
+    # QA Validation
+    async def qa_validator_node(self, state: DocGenState) -> DocGenState:
+        """Run QA Validator agent - validates sections BEFORE assembly with evidence-based guardrails"""
+        job_id = state["job_id"]
+        readme_sections = state.get("readme_sections", {})
+        evidence_packet = state.get("evidence_packet")
+
+        # Start metrics tracking
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("QAValidator")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="✅ Validating README sections with evidence checks...",
+            agent_name="QAValidator"
+        )
+
+        llm = get_llm(model_name=settings.QA_VALIDATOR_MODEL, temperature=0.7)
+        result = await run_qa_validator_agent(
+            llm=llm,
+            readme_sections=readme_sections,
+            job_id=job_id,
+            evidence_packet=evidence_packet
+        )
+
+        if result.get("success"):
+            qa_output = result.get("output", "")
+            # Try to parse QA score
+            import json
+            try:
+                qa_data = json.loads(qa_output)
+                state["qa_score"] = qa_data.get("qa_score", 75)
+                state["qa_passed"] = qa_data.get("qa_passed", True)
+                state["qa_validation_result"] = qa_data
+            except:
+                state["qa_score"] = 75
+                state["qa_passed"] = True
+                state["qa_validation_result"] = {"output": qa_output}
+
+            await self.log_manager.log_async(
+                job_id=job_id,
+                log_type=LogType.SUCCESS,
+                message=f"✅ QA Validator completed (Score: {state.get('qa_score', 'N/A')})",
+                agent_name="QAValidator"
+            )
+            # End metrics tracking (success)
+            metrics.end_agent(
+                "QAValidator",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            logger.error(f"QAValidator failed: {result.get('error')}")
+            # End metrics tracking (failure)
+            metrics.end_agent("QAValidator", success=False, error_message=result.get('error'))
+
+        state["current_agent"] = "QAValidator"
+        return state
+
+    async def assembly_node(self, state: DocGenState) -> DocGenState:
+        """Assemble final README with GenAISamples structure (EXACT logic from docugen)"""
+        job_id = state["job_id"]
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="🔨 Assembling final README..."
+        )
+
+        readme_parts = []
+        readme_sections = state.get("readme_sections", {})
+        mermaid_diagrams = state.get("mermaid_diagrams", {})
+        repo_name = state.get('repo_name', 'Project')
+
+        # Helper function to convert kebab-case/snake_case to Title Case
+        def to_title_case(text: str) -> str:
+            """Convert 'rag-chatbot' or 'doc_summarization' to 'Rag Chatbot' or 'Doc Summarization'"""
+            return ' '.join(word.capitalize() for word in text.replace('-', ' ').replace('_', ' ').split())
+
+        # 1. ## Title (H2, not H1!) - Convert to Title Case
+        readme_parts.append(f"## {to_title_case(repo_name)}\n\n")
+
+        # 2. Brief intro (extract ONLY first 1-2 sentences from Project Overview as teaser)
+        if "Project Overview" in readme_sections:
+            overview_content = readme_sections["Project Overview"]
+            # Extract content after heading
+            lines = overview_content.split('\n')
+            content_text = []
+            found_heading = False
+
+            for line in lines:
+                if line.startswith("## Project Overview"):
+                    found_heading = True
+                    continue
+                if found_heading and line.strip():
+                    content_text.append(line.strip())
+
+            # Join all content and split by sentences
+            full_text = ' '.join(content_text)
+            # Split by period followed by space (basic sentence splitting)
+            sentences = [s.strip() + '.' for s in full_text.split('. ') if s.strip()]
+
+            # Take only the first sentence as intro (to avoid duplication)
+            if sentences:
+                intro = sentences[0]
+                readme_parts.append(f"{intro}\n\n")
+
+        # Define explicit section order (chronological)
+        SECTION_ORDER = [
+            "Project Overview",
+            "Features",
+            "Architecture",
+            "Prerequisites",
+            "Quick Start Deployment",
+            "User Interface",
+            "Configuration",
+            "Troubleshooting"
+        ]
+
+        # 3. ## Table of Contents (use explicit order)
+        readme_parts.append("## Table of Contents\n\n")
+        for section in SECTION_ORDER:
+            if section in readme_sections:
+                anchor = section.lower().replace(" ", "-").replace("/", "")
+                readme_parts.append(f"- [{section}](#{anchor})\n")
+        readme_parts.append("\n")
+
+        # 4. --- separator
+        readme_parts.append("---\n\n")
+
+        # 5. Add all sections in explicit order with --- separators
+        architecture_section_found = False
+
+        for section in SECTION_ORDER:
+            if section not in readme_sections:
+                continue
+
+            content = readme_sections[section]
+            # Add section content
+            readme_parts.append(content)
+            readme_parts.append("\n\n")
+
+            # Insert Architecture diagram RIGHT after Architecture section content
+            if section.lower() == "architecture":
+                architecture_section_found = True
+                if mermaid_diagrams:
+                    for diagram_name, diagram_code in mermaid_diagrams.items():
+                        readme_parts.append(f"```mermaid\n{diagram_code}\n```\n\n")
+                    mermaid_diagrams = {}  # Clear so we don't add again
+
+            # Add --- separator after each section
+            readme_parts.append("---\n\n")
+
+        # 6. If diagrams were generated but no Architecture section exists, add minimal Architecture section with diagram
+        if mermaid_diagrams and not architecture_section_found:
+            readme_parts.append("## Architecture\n\n")
+            for diagram_name, diagram_code in mermaid_diagrams.items():
+                readme_parts.append(f"```mermaid\n{diagram_code}\n```\n\n")
+            readme_parts.append("---\n\n")
+
+        state["final_readme"] = "".join(readme_parts)
+        state["workflow_status"] = "completed"
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.SUCCESS,
+            message="✅ Documentation generation complete!"
+        )
+
+        # Finalize metrics and log summary
+        metrics = self._get_metrics_collector(job_id)
+        metrics.finalize_workflow()
+        summary = metrics.get_summary()
+
+        # Build per-agent metrics display
+        agent_metrics_lines = []
+        for agent in summary['agents']:
+            if agent['success']:
+                # Calculate per-agent TPS (output tokens per second)
+                agent_duration_sec = agent['duration_ms'] / 1000 if agent['duration_ms'] > 0 else 0
+                agent_tps = agent['output_tokens'] / agent_duration_sec if agent_duration_sec > 0 else 0.0
+
+                agent_metrics_lines.append(
+                    f"   ├─ {agent['agent_name']}: total={agent['total_tokens']:,} "
+                    f"(out={agent['output_tokens']:,}), {agent['duration_ms']:,.0f}ms, outTPS={agent_tps:.2f}"
+                )
+
+        agent_metrics_str = "\n".join(agent_metrics_lines)
+
+        # Log metrics summary to agent logs panel
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.INFO,
+            message=f"\n📊 **Workflow Metrics Summary**\n"
+                    f"├─ Total Agents: {summary['workflow']['total_agents']}\n"
+                    f"├─ Successful: {summary['workflow']['successful_agents']}\n"
+                    f"├─ Failed: {summary['workflow']['failed_agents']}\n"
+                    f"├─ Total Duration: {summary['workflow']['total_duration_seconds']}s\n"
+                    f"├─ Total Tokens: {summary['workflow']['total_tokens']:,}\n"
+                    f"│  ├─ Input: {summary['workflow']['total_input_tokens']:,}\n"
+                    f"│  └─ Output: {summary['workflow']['total_output_tokens']:,}\n"
+                    f"├─ Total Tool Calls: {summary['workflow']['total_tool_calls']}\n"
+                    f"├─ Total LLM Calls: {summary['workflow']['total_llm_calls']}\n"
+                    f"├─ Workflow Average TPS: {summary['workflow']['average_tps']} tokens/sec\n"
+                    f"│\n"
+                    f"├─ **Per-Agent Metrics (Model TPS)**\n"
+                    f"{agent_metrics_str}\n"
+        )
+
+        logger.info(f"[{job_id}] Metrics Summary: {summary}")
+
+        # Cleanup
+        if state.get("repo_path"):
+            self.git_service.cleanup_repository(state["repo_path"])
+
+        return state
+
+
+# Global workflow instance
+_workflow: SimplifiedDocuGenWorkflow = None
+
+
+async def get_workflow() -> SimplifiedDocuGenWorkflow:
+    """Get or create workflow instance"""
+    global _workflow
+    if _workflow is None:
+        _workflow = SimplifiedDocuGenWorkflow()
+        await _workflow.create_workflow()
+    return _workflow
diff --git a/DocuGenMicroagents/docker-compose.yml b/DocuGenMicroagents/docker-compose.yml
new file mode 100644
index 0000000000..4fdced3e0d
--- /dev/null
+++ b/DocuGenMicroagents/docker-compose.yml
@@ -0,0 +1,64 @@
+services:
+  backend:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+    container_name: docugen-microagents-backend
+    ports:
+      - "5001:5001"
+    env_file:
+      - ./api/.env
+    environment:
+      - PYTHONUNBUFFERED=1
+      - HOST=0.0.0.0
+      - API_PORT=5001
+    volumes:
+      - ./api:/app
+      - backend-tmp:/app/tmp
+      - /var/run/docker.sock:/var/run/docker.sock  # Docker socket for MCP server
+    networks:
+      - docugen-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  frontend:
+    build:
+      context: ./ui
+      dockerfile: Dockerfile
+    container_name: docugen-microagents-frontend
+    ports:
+      - "3000:3000"
+    environment:
+      - HOST=0.0.0.0
+      - PORT=3000
+      - VITE_API_URL=/api
+      - VITE_API_TARGET=http://backend:5001
+    volumes:
+      - ./ui:/app
+      - /app/node_modules
+    depends_on:
+      backend:
+        condition: service_healthy
+    networks:
+      - docugen-network
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:3000', (r) => process.exit(r.statusCode === 200 ? 0 : 1))\""]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+networks:
+  docugen-network:
+    driver: bridge
+    name: docugen-microagents-network
+
+volumes:
+  backend-tmp:
+    driver: local
diff --git a/DocuGenMicroagents/docs/CUSTOMIZATION.md b/DocuGenMicroagents/docs/CUSTOMIZATION.md
new file mode 100644
index 0000000000..652e083e19
--- /dev/null
+++ b/DocuGenMicroagents/docs/CUSTOMIZATION.md
@@ -0,0 +1,1015 @@
+# DocuGen Micro-Agents - Customization Guide
+
+This documentation covers how to customize the DocuGen Micro-Agents application for organizational workflows, including modifying agent behavior, strategic file sampling, workflow logic, and model configurations.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Architecture Summary](#architecture-summary)
+3. [Strategic File Sampling](#strategic-file-sampling)
+4. [Customizing Section Writer Agents](#customizing-section-writer-agents)
+5. [Customizing Coordination Agents](#customizing-coordination-agents)
+6. [Customizing Workflow Logic](#customizing-workflow-logic)
+7. [Adding Custom Tools](#adding-custom-tools)
+8. [Model Configuration](#model-configuration)
+9. [Advanced Scenarios](#advanced-scenarios)
+
+---
+
+## Overview
+
+DocuGen Micro-Agents is designed for extension at multiple layers:
+- **Prompt engineering** - Modify agent-specific system prompts
+- **Strategic sampling** - Configure file reading strategies for context optimization
+- **Section customization** - Modify which sections are generated
+- **Workflow modification** - Change execution flow, add validation gates
+- **Tool extension** - Add custom repository analysis tools
+- **Model configuration** - Use different LLM configurations per agent
+
+All customization points are centralized in well-defined files. This guide provides concrete examples for common modification scenarios.
+
+---
+
+## Architecture Summary
+
+### File Structure
+
+```
+docugen-microagents/api/
+├── agents/
+│   ├── code_explorer_agent.py         # Overview + Features writer
+│   ├── api_reference_agent.py         # API endpoint extractor
+│   ├── call_graph_agent.py            # Architecture writer
+│   ├── error_analysis_agent.py        # Troubleshooting writer
+│   ├── env_config_agent.py            # Configuration writer
+│   ├── dependency_analyzer_agent.py   # Prerequisites + Deployment writer
+│   ├── planner_agent.py               # Section selector
+│   ├── mermaid_agent.py               # Diagram generator + validator
+│   └── qa_validator_agent.py          # Quality assurance
+├── tools/
+│   └── repo_tools.py                  # Strategic file reading + analysis tools
+├── core/
+│   └── metrics_collector.py           # Token usage, TPS, duration tracking
+├── models/
+│   ├── state.py                       # LangGraph state definition
+│   └── evidence.py                    # Evidence-based architecture
+├── workflow.py                         # LangGraph workflow orchestration
+├── config.py                           # Configuration and settings
+└── server.py                           # FastAPI server with SSE streaming
+```
+
+### Micro-Agent Execution Flow
+
+**Section Writer Agents** (6 agents - write sections directly):
+1. **Code Explorer** - Writes "Project Overview" + "Features" sections
+2. **API Reference** - Extracts API endpoints (structured data, not markdown)
+3. **Call Graph** - Writes "Architecture" section
+4. **Error Analysis** - Writes "Troubleshooting" section
+5. **Env Config** - Writes "Configuration" section
+6. **Dependency Analyzer** - Writes "Prerequisites" + "Quick Start Deployment" sections
+
+**Coordination Agents** (3 agents - orchestration):
+7. **Evidence Aggregator** (node, not agent) - Consolidates filesystem evidence
+8. **Planner** - Decides which sections to include in final README
+9. **Mermaid Generator** - Creates and validates architecture diagram
+10. **QA Validator** - Validates sections against evidence, checks for hallucinations
+
+**Post-Workflow:**
+11. **Assembly** (node) - Combines sections into final README
+12. **PR Agent** (optional) - Creates GitHub pull request via MCP
+
+---
+
+## Strategic File Sampling
+
+**Location:** `docugen-microagents/api/tools/repo_tools.py`
+
+### Understanding Strategic Sampling
+
+The system implements three intelligent file reading strategies to optimize context usage with small language models (Qwen3-4B with 8K context window). All strategies work within a configurable line budget.
+
+**Configuration:**
+```python
+# In api/config.py
+MAX_LINES_PER_FILE: int = 500  # Line budget per file (pattern_window extracts ~150-300 lines)
+
+# In api/.env
+MAX_LINES_PER_FILE=500        # Line budget per file (pattern_window strategy extracts ~150-300 lines focusing on key patterns)
+```
+
+### Three Strategies
+
+#### 1. Full Strategy (simple)
+```python
+# Reads first N lines within budget
+strategy="full"  # Returns first 500 lines
+```
+
+**When to use:**
+- Small files (< 200 lines)
+- Configuration files
+- Simple scripts
+
+**Behavior:**
+- Deterministic and simple
+- May miss important code at end of file
+- Fast execution
+
+#### 2. Smart Strategy (structural)
+```python
+# Extracts top + function/class signatures + bottom
+strategy="smart"  # Returns ~100-200 lines
+```
+
+**Logic:**
+```python
+# From tools/repo_tools.py lines 95-126
+def _smart_sample_lines(lines: List[str], max_lines: int):
+    top_n = min(50, max_lines)
+    bottom_n = min(30, max_lines - top_n)
+    middle_budget = max(0, max_lines - top_n - bottom_n)
+
+    # Extract function/class signatures from middle
+    sigs = []
+    for ln in lines[top_n:len(lines) - bottom_n]:
+        if ln.lstrip().startswith(("def ", "async def ", "class ")):
+            sigs.append(ln)
+
+    return top + sigs + bottom
+```
+
+**When to use:**
+- Python modules with many functions
+- Class-heavy OOP code
+- Preserving file structure overview
+
+**Behavior:**
+- Preserves imports (top)
+- Captures all function/class signatures
+- Includes file ending (bottom)
+- Typical extraction: 100-200 lines
+
+#### 3. Pattern Window Strategy (context-aware) ⭐ DEFAULT
+```python
+# Extracts ±6 lines around high-value patterns
+strategy="pattern_window"  # Returns ~150-300 lines
+```
+
+**Logic:**
+```python
+# From tools/repo_tools.py lines 129-222
+def _pattern_window_lines(lines: List[str], max_lines: int):
+    patterns = [
+        r"@app\.(get|post|put|delete)\b",      # FastAPI routes
+        r"@router\.(get|post|put|delete)\b",   # FastAPI router
+        r"\bAPIRouter\b",                       # Router definitions
+        r"\btry:\b",                            # Error handling
+        r"\bexcept\b",                          # Exception handlers
+        r"\braise\b",                           # Error raising
+        r'if __name__\s*==\s*[\'"]__main__[\'"]',  # Entry points
+        r"\buvicorn\.run\b",                    # Server startup
+        r"\bdef main\(",                        # Main functions
+    ]
+
+    # Find all pattern matches
+    # Create windows of ±6 lines around each match
+    # Merge overlapping windows
+    # Return within max_lines budget
+```
+
+**When to use:** (DEFAULT for all agents)
+- API route files
+- Error handling logic
+- Entry point detection
+- High-value code extraction
+
+**Behavior:**
+- Detects FastAPI/Flask routes, error handlers, entry points
+- Extracts ±6 lines around each match
+- Falls back to smart strategy if no patterns found
+- Typical extraction: 150-300 lines
+- Maximizes information density
+
+### Customizing Sampling Strategy
+
+#### Example 1: Change Default Strategy for All Agents
+
+```python
+# In tools/repo_tools.py, line 912 (Code Explorer binding)
+@tool
+def read_file(
+    file_path: str,
+    max_lines: int = None,
+    strategy: Literal["full", "smart", "pattern_window"] = "smart"  # Change from "pattern_window"
+) -> str:
+    """Read a file with smart strategy as default"""
+    return read_file_tool.func(
+        repo_path=repo_path,
+        file_path=file_path,
+        max_lines=max_lines,
+        strategy=strategy
+    )
+```
+
+#### Example 2: Add Custom Pattern for Domain-Specific Code
+
+```python
+# In tools/repo_tools.py, add to _pattern_window_lines patterns list
+def _pattern_window_lines(lines: List[str], max_lines: int):
+    patterns = [
+        # Existing patterns...
+        r"@app\.(get|post|put|delete)\b",
+
+        # NEW: Domain-specific patterns for your organization
+        r"@dataclass",                           # Python dataclasses
+        r"@celery\.task",                        # Celery background tasks
+        r"class\s+\w+\(BaseModel\)",             # Pydantic models
+        r"def\s+test_\w+",                       # Test functions
+        r"@pytest\.fixture",                     # Pytest fixtures
+        r"@tool",                                # LangChain tools
+        r"@app\.middleware",                     # Middleware definitions
+        r"@app\.exception_handler",              # Exception handlers
+    ]
+```
+
+#### Example 3: Adjust Line Budget for Larger Context Models
+
+```python
+# If using larger models with more context (e.g., 32K context)
+# In api/.env
+MAX_LINES_PER_FILE=800  # Increase budget for larger models
+
+# Pattern window will extract ~300-500 lines
+# Smart strategy will extract ~200-400 lines
+```
+
+#### Example 4: Force Full Strategy for Specific File Types
+
+```python
+# In tools/repo_tools.py, modify read_file_tool
+@tool
+def read_file_tool(
+    repo_path: str,
+    file_path: str,
+    max_lines: int = None,
+    strategy: Literal["full", "smart", "pattern_window"] = "full"
+) -> str:
+    """Read file with strategy selection"""
+    if max_lines is None:
+        max_lines = settings.MAX_LINES_PER_FILE
+
+    # Force full strategy for config files
+    if file_path.endswith(('.json', '.yaml', '.yml', '.toml', '.ini')):
+        strategy = "full"
+
+    # Force pattern_window for API files
+    elif 'routes/' in file_path or 'api/' in file_path:
+        strategy = "pattern_window"
+
+    # Original logic continues...
+```
+
+---
+
+## Customizing Section Writer Agents
+
+### Code Explorer Agent (Overview + Features Writer)
+
+**Location:** `docugen-microagents/api/agents/code_explorer_agent.py`
+
+The Code Explorer writes two sections directly: "Project Overview" and "Features".
+
+#### Example: Customize Output Format
+
+```python
+# In agents/code_explorer_agent.py
+CODE_EXPLORER_SYSTEM_PROMPT = """You are an expert Code Explorer agent...
+
+**Output Format (CRITICAL - FOLLOW EXACTLY):**
+
+## Project Overview
+
+[Write 2-3 paragraphs describing the application's purpose, architecture pattern, and value proposition]
+
+## Features
+
+**Backend Features:**
+- Feature 1 (with file reference)
+- Feature 2 (with evidence from code)
+- Feature 3 (extracted from actual implementation)
+
+**Frontend Features:**
+- Feature 1 (with component reference)
+- Feature 2 (with framework details)
+
+**NEW REQUIREMENT - Security Features:**
+- Authentication mechanism (with file:line reference)
+- Authorization model (with evidence)
+- Data encryption approach (if detected)
+"""
+```
+
+#### Example: Force Deeper File Analysis
+
+```python
+CODE_EXPLORER_SYSTEM_PROMPT = """...
+
+**Required Tool Usage Pattern (ENHANCED):**
+
+1. list_directory(".") - Get root structure
+2. detect_languages() - Get language breakdown
+3. extract_dependencies() - Get all dependencies
+4. read_file("README.md", strategy="full") - Check existing docs
+5. read_file("main entry file", strategy="pattern_window") - Analyze entry point
+
+**NEW: Deep Security Analysis**
+6. list_directory("auth") or list_directory("middleware") - Find auth code
+7. read_file("auth/main.py", strategy="pattern_window") - Extract auth logic
+8. read_file(".env.example", strategy="full") - Identify secret requirements
+
+**NEW: API Analysis**
+9. list_directory("routes") or list_directory("api") - Find API routes
+10. read_file("routes/*.py", strategy="pattern_window") - Extract all endpoints
+"""
+```
+
+### API Reference Agent (Endpoint Extractor)
+
+**Location:** `docugen-microagents/api/agents/api_reference_agent.py`
+
+This agent extracts API endpoints as structured JSON data (not markdown).
+
+#### Example: Customize Endpoint Extraction Format
+
+```python
+# In agents/api_reference_agent.py
+API_REFERENCE_SYSTEM_PROMPT = """...
+
+**Output Format (JSON ONLY - NO MARKDOWN):**
+
+```json
+{
+  "endpoints": [
+    {
+      "method": "POST",
+      "path": "/api/documents",
+      "file": "api/routes/documents.py",
+      "line": 45,
+      "description": "Upload and process document",
+      "request_body": "DocumentInput model",
+      "response": "DocumentResponse model",
+      "auth_required": true,
+      "rate_limit": "10/minute"
+    }
+  ]
+}
+```
+
+**NEW FIELDS TO EXTRACT:**
+- auth_required: Check for @requires_auth, Depends(get_current_user), etc.
+- rate_limit: Look for @limiter.limit decorators
+- deprecated: Check for @deprecated decorators
+"""
+```
+
+### Dependency Analyzer Agent (Prerequisites + Deployment Writer)
+
+**Location:** `docugen-microagents/api/agents/dependency_analyzer_agent.py`
+
+#### Example: Add Docker Compose Analysis
+
+```python
+DEPENDENCY_ANALYZER_SYSTEM_PROMPT = """...
+
+**Required Analysis:**
+
+1. **Prerequisites Section:**
+   - Runtime versions (Python 3.11+, Node 20+, etc.)
+   - System dependencies (Redis, PostgreSQL, etc.)
+   - API keys and credentials
+
+2. **Quick Start Deployment Section:**
+   - Installation commands
+   - Setup instructions
+   - Running the application
+
+**NEW: Docker Compose Analysis**
+3. If docker-compose.yml exists:
+   - Read docker-compose.yml with strategy="full"
+   - List all services defined
+   - Extract port mappings
+   - Document volume mounts
+   - Include docker-compose up command
+
+   Example output:
+   ```markdown
+   ## Quick Start Deployment
+
+   ### Docker Deployment (Recommended)
+
+   The application uses Docker Compose with 3 services:
+   - backend (FastAPI) - Port 8000
+   - frontend (React) - Port 3000
+   - database (PostgreSQL) - Port 5432
+
+   \`\`\`bash
+   docker-compose up -d
+   \`\`\`
+   ```
+"""
+```
+
+---
+
+## Customizing Coordination Agents
+
+### Planner Agent (Section Selector)
+
+**Location:** `docugen-microagents/api/agents/planner_agent.py`
+
+The Planner decides which sections to include in the final README based on project type.
+
+#### Example: Add Custom "Performance" Section
+
+```python
+# In agents/planner_agent.py
+PLANNER_SYSTEM_PROMPT = """...
+
+**Standard Sections (REQUIRED for ALL projects):**
+1. Project Overview
+2. Features
+3. Architecture
+4. Prerequisites
+5. Quick Start Deployment
+
+**Conditional Sections (include if applicable):**
+6. User Interface - If frontend detected (React, Vue, Angular)
+7. Configuration - If .env.example exists
+8. Troubleshooting - If error handlers or try/except blocks found
+
+**NEW: Performance Section (conditional)**
+9. Performance - Include if:
+   - Caching detected (Redis, Memcached dependencies)
+   - Performance monitoring (Prometheus, Datadog integrations)
+   - Load balancing configuration (nginx.conf, HAProxy)
+   - Database optimization (indexes, query optimization comments)
+   - CDN configuration (Cloudflare, Fastly)
+
+**Detection Logic for Performance Section:**
+```python
+# Check for performance indicators
+if any(dep in dependencies for dep in ['redis', 'memcached', 'prometheus-client']):
+    sections.append("Performance")
+if 'nginx.conf' in config_files or 'load_balancer' in directories:
+    sections.append("Performance")
+```
+"""
+```
+
+### Mermaid Generator Agent (Diagram Creator)
+
+**Location:** `docugen-microagents/api/agents/mermaid_agent.py`
+
+#### Example: Customize Diagram Style
+
+```python
+MERMAID_SYSTEM_PROMPT = """...
+
+**Diagram Requirements:**
+
+1. **Architecture Diagram (graph TB):**
+   - Maximum 8-10 nodes
+   - Show user flow: User/Client → Frontend → Backend → Database
+   - Include external integrations (LLM Provider, Auth Service, etc.)
+
+**NEW: Corporate Color Scheme**
+2. **Styling (REQUIRED):**
+   ```mermaid
+   graph TB
+       A[Frontend]:::frontend
+       B[Backend API]:::backend
+       C[Database]:::database
+       D[External Service]:::external
+
+       classDef frontend fill:#3b82f6,stroke:#1e40af,color:#fff
+       classDef backend fill:#10b981,stroke:#059669,color:#fff
+       classDef database fill:#f59e0b,stroke:#d97706,color:#fff
+       classDef external fill:#8b5cf6,stroke:#6d28d9,color:#fff
+   ```
+
+3. **Node Naming Rules:**
+   - Use service names, not technical jargon
+   - Good: "User Authentication", "Document Processor"
+   - Bad: "JWT Middleware", "PDF Parser Class"
+"""
+```
+
+### QA Validator Agent (Quality Assurance)
+
+**Location:** `docugen-microagents/api/agents/qa_validator_agent.py`
+
+#### Example: Add Custom Validation Rules
+
+```python
+QA_VALIDATOR_SYSTEM_PROMPT = """...
+
+**Validation Checks (Evidence-Based):**
+
+1. **Hallucination Detection:**
+   - Verify all dependencies mentioned exist in evidence.python_deps or evidence.node_deps
+   - Verify all environment variables match evidence.env_variables
+   - Verify technology stack matches evidence.languages
+
+2. **Completeness Checks:**
+   - All sections have > 100 characters
+   - Prerequisites lists actual version requirements
+   - Configuration section covers all .env.example variables
+
+**NEW: Custom Corporate Validation**
+3. **Security Documentation (REQUIRED for ALL projects):**
+   - Must mention authentication mechanism (if any)
+   - Must document all *_SECRET, *_KEY, *_TOKEN env vars
+   - Must warn about credential security
+
+4. **Compliance Check (REQUIRED for enterprise):**
+   - If project handles PII: Must mention data protection
+   - If project logs data: Must mention audit logging
+   - If project uses external APIs: Must mention API key security
+
+**Scoring:**
+- Base score: 75
+- +5 for each security item documented
+- +10 for compliance documentation
+- -10 for each hallucination detected
+- -5 for incomplete sections
+"""
+```
+
+---
+
+## Customizing Workflow Logic
+
+**Location:** `docugen-microagents/api/workflow.py`
+
+### Example: Add Approval Gate After Section Writers
+
+Require human approval after all section writers complete, before coordination agents run.
+
+**Step 1:** Add approval state in `models/state.py`:
+
+```python
+class DocGenState(TypedDict):
+    # Existing fields
+    job_id: str
+    repo_url: str
+    # ...
+
+    # NEW: Approval gate
+    sections_approved: Optional[bool]
+```
+
+**Step 2:** Add conditional routing in `workflow.py`:
+
+```python
+class SimplifiedDocuGenWorkflow:
+    async def create_workflow(self) -> StateGraph:
+        workflow = StateGraph(DocGenState)
+
+        # Existing nodes...
+        workflow.add_node("dependency_analyzer", self.dependency_analyzer_node)
+        workflow.add_node("evidence_aggregator", self.evidence_aggregator_node)
+
+        # Add edges
+        workflow.add_edge("dependency_analyzer", "evidence_aggregator")
+
+        # NEW: Add approval gate before planner
+        workflow.add_conditional_edges(
+            "evidence_aggregator",
+            self._check_sections_approval,
+            {
+                "approved": "planner",
+                "pending": END  # Pause for approval
+            }
+        )
+
+    def _check_sections_approval(self, state: DocGenState) -> str:
+        """Check if sections were approved"""
+        if state.get("sections_approved") is None:
+            # First time: pause for approval
+            return "pending"
+        elif state["sections_approved"]:
+            return "approved"
+        else:
+            # Rejected: end workflow
+            return END
+```
+
+**Step 3:** Add API endpoint in `server.py`:
+
+```python
+@app.post("/api/approve-sections/{job_id}")
+async def approve_sections(job_id: str, approved: bool = True):
+    """Approve section writer outputs before coordination"""
+    workflow = await get_workflow()
+    config = {"configurable": {"thread_id": job_id}}
+
+    # Update state with approval
+    await workflow.graph.aupdate_state(
+        config,
+        {"sections_approved": approved}
+    )
+
+    if approved:
+        # Resume workflow
+        async for event in workflow.graph.astream(None, config):
+            pass
+
+    return {"status": "approved" if approved else "rejected"}
+```
+
+### Example: Skip Mermaid Generation for APIs
+
+```python
+def _should_generate_diagram(self, state: DocGenState) -> str:
+    """Skip diagrams for API-only projects"""
+    evidence = state.get("evidence_packet")
+
+    # Skip if only backend, no frontend
+    if evidence and evidence.has_backend and not evidence.has_frontend:
+        logger.info("Skipping diagram: API-only project")
+        return "skip"
+
+    return "generate"
+
+# In workflow setup:
+workflow.add_conditional_edges(
+    "planner",
+    self._should_generate_diagram,
+    {
+        "generate": "mermaid",
+        "skip": "qa_validator"
+    }
+)
+```
+
+---
+
+## Adding Custom Tools
+
+**Location:** `docugen-microagents/api/tools/repo_tools.py`
+
+### Example: Add Database Schema Extraction Tool
+
+```python
+from langchain.tools import tool
+import re
+from pathlib import Path
+
+@tool
+def extract_database_schema_tool(repo_path: str) -> str:
+    """
+    Extract database schema from SQLAlchemy models or Prisma schema files.
+
+    Args:
+        repo_path: Absolute path to repository root
+
+    Returns:
+        Formatted database schema with tables and columns
+    """
+    schema_info = []
+
+    # Check for Prisma schema
+    prisma_file = Path(repo_path) / "prisma" / "schema.prisma"
+    if prisma_file.exists():
+        with open(prisma_file) as f:
+            content = f.read()
+            models = re.findall(r'model\s+(\w+)\s*\{([^}]+)\}', content, re.DOTALL)
+            for model_name, model_body in models:
+                fields = re.findall(r'(\w+)\s+(\w+)', model_body)
+                schema_info.append(f"Table: {model_name}")
+                for field_name, field_type in fields:
+                    schema_info.append(f"  - {field_name}: {field_type}")
+
+    # Check for SQLAlchemy models
+    models_dir = Path(repo_path) / "models"
+    if models_dir.exists():
+        for model_file in models_dir.glob("*.py"):
+            with open(model_file) as f:
+                content = f.read()
+                tables = re.findall(r'class\s+(\w+)\([^)]*Base[^)]*\):', content)
+                for table in tables:
+                    schema_info.append(f"Table: {table} ({model_file.name})")
+
+    if not schema_info:
+        return "No database schema files found"
+
+    return "\n".join(schema_info)
+```
+
+**Bind tool for agents:**
+
+```python
+def make_bound_tools_for_code_explorer(repo_path: str) -> List:
+    """Create tools with repo_path pre-bound"""
+
+    @tool
+    def extract_database_schema() -> str:
+        """Extract database schema. No arguments needed."""
+        return extract_database_schema_tool.func(repo_path=repo_path)
+
+    return [
+        list_directory,
+        read_file,
+        detect_languages,
+        extract_dependencies,
+        extract_database_schema  # NEW
+    ]
+```
+
+**Update agent prompt:**
+
+```python
+CODE_EXPLORER_SYSTEM_PROMPT = """...
+
+**Tool Usage:**
+1. list_directory(".")
+2. detect_languages()
+3. extract_dependencies()
+4. extract_database_schema()  # NEW - Get DB schema
+5. read_file("main.py", strategy="pattern_window")
+
+**Required Analysis:**
+...
+4. **Database Schema (if database detected):**
+   - Use extract_database_schema() to get table definitions
+   - List primary tables and relationships
+   - Example: "Database: PostgreSQL with 5 tables (users, documents, sessions, ...)"
+"""
+```
+
+---
+
+## Model Configuration
+
+**Location:** `docugen-microagents/api/config.py`
+
+### Current Configuration (Qwen3-4B for all agents)
+
+```python
+# In .env file
+AUTH_MODE=genai_gateway
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your-api-key
+
+# All agents use Qwen3-4B-Instruct (optimized for Intel Xeon)
+CODE_EXPLORER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+API_REFERENCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+CALL_GRAPH_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ERROR_ANALYSIS_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ENV_CONFIG_MODEL=Qwen/Qwen3-4B-Instruct-2507
+DEPENDENCY_ANALYZER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+PLANNER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+MERMAID_MODEL=Qwen/Qwen3-4B-Instruct-2507
+QA_VALIDATOR_MODEL=Qwen/Qwen3-4B-Instruct-2507
+WRITER_MODEL=Qwen/Qwen3-4B-Instruct-2507  # Legacy, not used
+```
+
+### Example: Use Larger Model for QA Validator
+
+```python
+# If you have access to larger models for quality assurance
+QA_VALIDATOR_MODEL=Qwen/Qwen2.5-32B-Instruct
+```
+
+### Example: Add Custom Model for Compliance Agent
+
+```python
+# In config.py
+class Settings(BaseSettings):
+    # Existing model configs...
+    CODE_EXPLORER_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+
+    # NEW: Custom agent model
+    COMPLIANCE_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+```
+
+---
+
+## Advanced Scenarios
+
+### Scenario 1: Add Compliance Section Writer Agent
+
+**Step 1:** Create `agents/compliance_agent.py`:
+
+```python
+from langchain_core.language_models import BaseChatModel
+from langchain_core.prompts import ChatPromptTemplate
+from tools.repo_tools import make_bound_tools_for_code_explorer
+
+COMPLIANCE_SYSTEM_PROMPT = """You are a Compliance Documentation Specialist.
+
+**Your Task:**
+Write a comprehensive "Compliance" section for the README.
+
+**Required Content:**
+1. Data Classification - What types of data does this system process?
+2. Access Controls - Authentication and authorization mechanisms
+3. Audit Logging - What actions are logged and where?
+4. Encryption - Data at rest and in transit
+5. Compliance Frameworks - SOC2, HIPAA, GDPR considerations
+
+**Tools Available:**
+- list_directory(path) - List directory contents
+- read_file(file_path, strategy) - Read file with strategy
+- detect_languages() - Get language breakdown
+- extract_dependencies() - Get all dependencies
+
+**Output Format:**
+
+## Compliance
+
+### Data Classification
+[Describe what types of data the system processes...]
+
+### Access Controls
+[Document authentication and authorization...]
+
+### Audit Logging
+[Describe what is logged and retention...]
+
+### Encryption
+[Document encryption at rest and in transit...]
+
+### Compliance Frameworks
+[List applicable frameworks and how system complies...]
+"""
+
+async def run_compliance_agent(llm: BaseChatModel, repo_path: str, job_id: str) -> dict:
+    """Run compliance documentation agent"""
+    from langchain.agents import create_react_agent, AgentExecutor
+    from langchain_core.prompts import PromptTemplate
+
+    # Bind tools
+    tools = make_bound_tools_for_code_explorer(repo_path)
+
+    # Create ReAct agent
+    agent_prompt = PromptTemplate.from_template("""...React template...""")
+    agent = create_react_agent(llm, tools, agent_prompt)
+
+    # Execute
+    executor = AgentExecutor(
+        agent=agent,
+        tools=tools,
+        verbose=True,
+        max_iterations=15,
+        handle_parsing_errors=True
+    )
+
+    result = await executor.ainvoke({
+        "system_prompt": COMPLIANCE_SYSTEM_PROMPT,
+        "repo_path": repo_path
+    })
+
+    return {
+        "success": True,
+        "output": result["output"],
+        "input_tokens": 0,  # Extract from result
+        "output_tokens": 0,
+        "tool_calls": 0,
+        "llm_calls": 0
+    }
+```
+
+**Step 2:** Add node to workflow:
+
+```python
+# In workflow.py
+from agents.compliance_agent import run_compliance_agent
+
+class SimplifiedDocuGenWorkflow:
+    async def create_workflow(self) -> StateGraph:
+        # Add compliance node
+        workflow.add_node("compliance", self.compliance_node)
+
+        # Insert after dependency_analyzer, before evidence_aggregator
+        workflow.add_edge("dependency_analyzer", "compliance")
+        workflow.add_edge("compliance", "evidence_aggregator")
+
+    async def compliance_node(self, state: DocGenState) -> DocGenState:
+        """Run Compliance agent"""
+        job_id = state["job_id"]
+        target_path = self._get_target_path(state)
+
+        metrics = self._get_metrics_collector(job_id)
+        metrics.start_agent("Compliance")
+
+        await self.log_manager.log_async(
+            job_id=job_id,
+            log_type=LogType.WORKFLOW_PROGRESS,
+            message="📋 Running Compliance Writer (7/8)...",
+            agent_name="Compliance"
+        )
+
+        llm = get_llm(model_name=settings.COMPLIANCE_MODEL, temperature=0.7)
+        result = await run_compliance_agent(llm=llm, repo_path=target_path, job_id=job_id)
+
+        if result.get("success"):
+            output = result.get("output", "")
+            sections_dict = state.get("readme_sections") or {}
+            self._parse_and_store_sections(output, sections_dict)
+            state["readme_sections"] = sections_dict
+
+            metrics.end_agent(
+                "Compliance",
+                success=True,
+                input_tokens=result.get("input_tokens", 0),
+                output_tokens=result.get("output_tokens", 0),
+                tool_calls=result.get("tool_calls", 0),
+                llm_calls=result.get("llm_calls", 0)
+            )
+        else:
+            metrics.end_agent("Compliance", success=False)
+
+        return state
+```
+
+**Step 3:** Add to config:
+
+```python
+# In config.py
+COMPLIANCE_MODEL: str = "Qwen/Qwen3-4B-Instruct-2507"
+
+# In .env
+COMPLIANCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+```
+
+---
+
+## Configuration Reference
+
+### Environment Variables
+
+```bash
+# LLM Configuration
+AUTH_MODE=genai_gateway
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your-api-key
+
+# Micro-Agent Model Configuration (all use Qwen3-4B)
+CODE_EXPLORER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+API_REFERENCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+CALL_GRAPH_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ERROR_ANALYSIS_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ENV_CONFIG_MODEL=Qwen/Qwen3-4B-Instruct-2507
+DEPENDENCY_ANALYZER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+PLANNER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+MERMAID_MODEL=Qwen/Qwen3-4B-Instruct-2507
+QA_VALIDATOR_MODEL=Qwen/Qwen3-4B-Instruct-2507
+
+# GitHub Integration (MCP)
+GITHUB_TOKEN=ghp_...
+
+# Repository Analysis Limits
+MAX_REPO_SIZE=10737418240          # 10GB in bytes
+MAX_FILE_SIZE=1000000               # 1MB in bytes
+MAX_FILES_TO_SCAN=500               # Maximum files to analyze
+MAX_LINES_PER_FILE=500              # Line budget per file (pattern_window extracts ~150-300 lines)
+
+# Agent Settings
+AGENT_TEMPERATURE=0.7
+AGENT_MAX_TOKENS=1000
+AGENT_TIMEOUT=300                   # 5 minutes
+
+# Server Configuration
+API_PORT=5001
+HOST=0.0.0.0
+CORS_ORIGINS=["http://localhost:3000"]
+```
+
+---
+
+## Testing Customizations
+
+After making customizations, test with representative repositories:
+
+```bash
+# Test with different project types
+1. Simple web app (React + FastAPI)
+2. Complex monorepo (multiple services)
+3. API-only service (FastAPI/Spring Boot)
+4. CLI tool (Python script)
+
+# Validate outputs:
+- Check all custom sections appear
+- Verify custom tools are called in logs
+- Confirm tone and format match requirements
+- Test strategic sampling extracts key patterns
+- Verify metrics tracking (tokens, TPS, duration)
+- Test with private repos (authentication)
+```
+
+Review agent logs in real-time via the UI to debug ReAct reasoning loops, tool usage, and file sampling strategies.
+
+---
diff --git a/DocuGenMicroagents/docs/GENERIC_USAGE.md b/DocuGenMicroagents/docs/GENERIC_USAGE.md
new file mode 100644
index 0000000000..5f92c25beb
--- /dev/null
+++ b/DocuGenMicroagents/docs/GENERIC_USAGE.md
@@ -0,0 +1,1402 @@
+# DocuGen Micro-Agents - Generic Usage Guide
+
+This documentation covers how to deploy and use DocuGen Micro-Agents to automatically generate comprehensive README documentation for any software repository.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [System Architecture](#system-architecture)
+3. [Prerequisites](#prerequisites)
+4. [Deployment](#deployment)
+5. [Generating Documentation](#generating-documentation)
+6. [Supported Project Types](#supported-project-types)
+7. [Understanding Output](#understanding-output)
+8. [Limitations](#limitations)
+9. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+DocuGen Micro-Agents is a specialized multi-agent system that autonomously generates comprehensive README documentation for software repositories. The system uses **9 micro-agents** that work together to analyze code structure, extract dependencies, understand architecture, and produce professional technical documentation based on actual code rather than templates.
+
+### Core Capabilities
+
+- **Micro-agent architecture** with 9 specialized agents for targeted analysis
+- **Strategic file sampling** to optimize context usage and processing speed
+- **Evidence-based documentation** - every statement verified through code analysis
+- **Autonomous repository exploration** using ReAct (Reason-Act-Observe) pattern
+- **Multi-language support** with automatic technology stack detection
+- **Monorepo project detection** with human-in-the-loop selection
+- **Architecture diagram generation** with Mermaid syntax validation
+- **GitHub pull request creation** for documentation submission
+- **Real-time agent activity streaming** via Server-Sent Events
+- **Performance metrics tracking** with per-agent token usage and blast radius reports
+
+### Design Philosophy
+
+DocuGen generates documentation from code analysis, not assumptions. Every feature, dependency, and configuration mentioned in the output is extracted from actual files in your repository. If information cannot be verified through code inspection, it is omitted rather than fabricated.
+
+**Key Principles:**
+- **Evidence-first**: All agents write findings to a central EvidencePacket
+- **Specialized roles**: Each agent focuses on a specific analysis domain
+- **Context-efficient**: Strategic file sampling keeps processing under LLM context limits
+- **Quality-assured**: QA Validator scores all sections before final assembly
+
+---
+
+## System Architecture
+
+### Micro-Agent Overview
+
+DocuGen uses **9 specialized micro-agents** organized into three categories:
+
+#### 1. Section Writer Agents (6 agents)
+These agents analyze code and contribute specific sections to the documentation:
+
+- **Code Explorer** - Filesystem structure, languages, key files
+- **API Reference** - REST/GraphQL endpoints, request/response schemas
+- **Call Graph** - Function relationships, entry points, call paths
+- **Error Analysis** - Exception handlers, error patterns, logging
+- **Env Config** - Environment variables, configuration files
+- **Dependency Analyzer** - Package dependencies, security vulnerabilities
+
+#### 2. Coordination Agents (3 agents)
+These agents orchestrate documentation generation:
+
+- **Planner** - Determines sections to generate based on project type
+- **Mermaid Generator** - Creates validated architecture diagrams
+- **QA Validator** - Scores documentation quality (0-100) and validates completeness
+
+#### 3. Infrastructure Nodes
+- **Evidence Aggregator** - Consolidates filesystem data for all agents
+- **PR Agent** (via MCP) - Creates GitHub pull requests
+
+### Micro-Agent Execution Flow
+
+```mermaid
+graph TB
+    subgraph "Frontend Layer"
+        UI[React UI<br/>Repository URL input<br/>Agent log streaming<br/>Project selection<br/>README preview]
+    end
+
+    subgraph "Backend Layer"
+        API[FastAPI Server<br/>REST API endpoints<br/>SSE streaming<br/>Job orchestration]
+        WF[LangGraph Workflow<br/>State management<br/>Agent orchestration<br/>Checkpointing]
+        GIT[Git Service<br/>Repository cloning<br/>Branch operations]
+        MCP[GitHub MCP<br/>PR creation<br/>Docker integration]
+    end
+
+    subgraph "Micro-Agent Pipeline"
+        direction TB
+        A1[1. Clone Repository<br/>GitService clones repo]
+        A2[2. Evidence Aggregator<br/>Scans filesystem, builds EvidencePacket]
+        A3[3. Section Writer Agents<br/>6 agents run in parallel]
+        A4[4. Planner<br/>Determines sections based on project type]
+        A5[5. Project Selection<br/>Human-in-the-loop gate for monorepos]
+        A6[6. Writer Coordination<br/>Generates markdown sections]
+        A7[7. Mermaid Generator<br/>Creates validated diagrams]
+        A8[8. QA Validator<br/>Scores quality 0-100]
+        A9[9. Assembly<br/>Combines all sections into final README]
+
+        A1 --> A2
+        A2 --> A3
+        A3 --> A4
+        A4 --> A5
+        A5 --> A6
+        A6 --> A7
+        A7 --> A8
+        A8 --> A9
+    end
+
+    subgraph "External Services"
+        LLM[LLM Provider<br/>Qwen3-4B via GenAI Gateway or Keycloak]
+        GITHUB[GitHub<br/>Public/private repos]
+    end
+
+    UI -->|HTTP/SSE| API
+    API -->|Executes| WF
+    WF -->|Orchestrates| A1
+    A1 -->|Uses| GIT
+    GIT -->|Clones from| GITHUB
+    A3 & A6 & A7 & A8 -->|LLM calls| LLM
+    A9 -->|Creates PR via| MCP
+    MCP -->|Pushes to| GITHUB
+    API -->|Streams logs| UI
+
+    classDef frontend fill:#3b82f6,stroke:#1e40af,color:#fff
+    classDef backend fill:#10b981,stroke:#059669,color:#fff
+    classDef agent fill:#f59e0b,stroke:#d97706,color:#fff
+    classDef external fill:#6366f1,stroke:#4f46e5,color:#fff
+
+    class UI frontend
+    class API,WF,GIT,MCP backend
+    class A1,A2,A3,A4,A5,A6,A7,A8,A9 agent
+    class LLM,GITHUB external
+```
+
+### Strategic File Sampling
+
+DocuGen uses **intelligent file sampling** to work within LLM context limits:
+
+**MAX_LINES_PER_FILE=500** (configurable) acts as a budget, not a guarantee. Three strategies are available:
+
+#### 1. Pattern Window Strategy (DEFAULT)
+- Detects high-value patterns (routes, error handlers, entry points)
+- Extracts ±6 lines around each match
+- **Typical extraction: 150-300 lines from 500 budget**
+- Used by all agents by default
+
+**Detected patterns:**
+```python
+@app.get(), @router.post()       # FastAPI/Flask routes
+try:, except:, raise              # Error handling
+if __name__ == "__main__":        # Entry points
+def main(, uvicorn.run()          # Main functions
+```
+
+#### 2. Smart Strategy
+- Extracts top + function/class signatures + bottom
+- **Typical extraction: 100-200 lines**
+- Good for structural overviews
+
+#### 3. Full Strategy
+- Takes first N lines (up to 500)
+- Simple but can waste context on comments
+
+**Why this matters:**
+- Qwen3-4B has 8K context window
+- pattern_window keeps each file read to ~150-300 lines
+- Allows processing more files within context limits
+- Maximizes information density per token
+
+**Configuration location:** `api/tools/repo_tools.py` (lines 95-222)
+
+### Agent Communication Model
+
+Each micro-agent operates autonomously with access to repository tools:
+
+#### Section Writer Agents
+
+**Code Explorer Agent**
+- **Tools**: list_directory, read_file, detect_languages, extract_dependencies
+- **Output**: File structure tree, language distribution, key files list
+- **Strategy**: pattern_window for key files, smart for structure
+
+**API Reference Agent**
+- **Tools**: read_file, grep_search
+- **Output**: Endpoint list with HTTP methods, request/response schemas
+- **Strategy**: pattern_window for route files
+
+**Call Graph Agent**
+- **Tools**: read_file, grep_search
+- **Output**: Function call relationships, entry points, call paths
+- **Strategy**: pattern_window for function definitions
+
+**Error Analysis Agent**
+- **Tools**: read_file, grep_search
+- **Output**: Exception handlers, error patterns, logging strategies
+- **Strategy**: pattern_window for error handling code
+
+**Env Config Agent**
+- **Tools**: read_file
+- **Output**: Environment variable list, configuration files found
+- **Strategy**: full for .env.example files (typically small)
+
+**Dependency Analyzer Agent**
+- **Tools**: read_file, extract_dependencies
+- **Output**: Dependency report, security warnings, version conflicts
+- **Strategy**: full for package files (small)
+
+#### Coordination Agents
+
+**Planner Agent**
+- **Input**: Evidence from all section writers
+- **Output**: List of sections to generate (e.g., Prerequisites, Architecture, Configuration)
+- **Logic**: Determines sections based on project type and detected features
+
+**Mermaid Generator Agent**
+- **Tools**: Repository access + Mermaid syntax validation
+- **Output**: Validated Mermaid diagrams showing system architecture
+- **Strategy**: pattern_window for architecture-relevant files
+
+**QA Validator Agent**
+- **Input**: All generated sections
+- **Output**: Quality score (0-100), validation result with feedback
+- **Criteria**: Completeness, accuracy, clarity, technical depth
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+**For Docker Deployment:**
+- Docker Engine 20.10+
+- Docker Compose 2.0+
+- 4GB RAM minimum (8GB recommended for large repos)
+- 20GB disk space
+
+**For Local Development:**
+- Python 3.11+
+- Node.js 20+
+- pip and npm package managers
+- Git 2.30+
+
+### Required Credentials
+
+**LLM API Configuration** (required)
+
+Choose one authentication mode:
+
+**Option 1: GenAI Gateway (Recommended)**
+```bash
+AUTH_MODE=genai_gateway
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your-api-key
+```
+
+**Option 2: Keycloak (Enterprise)**
+```bash
+AUTH_MODE=keycloak
+BASE_URL=https://your-inference-endpoint.company.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your-client-secret
+```
+
+**GitHub Personal Access Token** (optional, for private repos and PR creation)
+```bash
+# Generate at: https://github.com/settings/tokens
+# Required scopes: repo (full control of private repositories)
+GITHUB_TOKEN=ghp_...
+```
+
+### Repository Requirements
+
+The target repository must meet these criteria:
+- Cloneable via HTTPS (public or with valid token)
+- Size under 10GB (configurable via MAX_REPO_SIZE)
+- Contains at least one package manager file (package.json, requirements.txt, Gemfile, pom.xml, etc.)
+- Has readable file permissions
+
+---
+
+## Deployment
+
+### Docker Deployment (Production)
+
+**Step 1:** Configure environment
+
+Create `api/.env`:
+```bash
+# ==========================================
+# Authentication Configuration
+# ==========================================
+AUTH_MODE=genai_gateway
+GENAI_GATEWAY_URL=https://your-gateway-url.com
+GENAI_GATEWAY_API_KEY=your-api-key
+
+# OR for enterprise Keycloak authentication:
+# AUTH_MODE=keycloak
+# BASE_URL=https://your-inference-endpoint.company.com
+# KEYCLOAK_REALM=master
+# KEYCLOAK_CLIENT_ID=api
+# KEYCLOAK_CLIENT_SECRET=your-client-secret
+
+# ==========================================
+# Micro-Agent Model Configuration
+# ==========================================
+# All agents use Qwen3-4B-Instruct (optimized SLM for code analysis)
+CODE_EXPLORER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+API_REFERENCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+CALL_GRAPH_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ERROR_ANALYSIS_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ENV_CONFIG_MODEL=Qwen/Qwen3-4B-Instruct-2507
+DEPENDENCY_ANALYZER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+PLANNER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+MERMAID_MODEL=Qwen/Qwen3-4B-Instruct-2507
+QA_VALIDATOR_MODEL=Qwen/Qwen3-4B-Instruct-2507
+WRITER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+
+# ==========================================
+# Repository Analysis Limits
+# ==========================================
+TEMP_REPO_DIR=./tmp/repos
+MAX_REPO_SIZE=10737418240    # 10GB in bytes
+MAX_FILE_SIZE=1000000         # 1MB in bytes
+MAX_FILES_TO_SCAN=500         # Maximum number of files to analyze
+MAX_LINES_PER_FILE=500        # Line budget per file (pattern_window extracts ~150-300 lines)
+
+# ==========================================
+# Agent Execution Settings
+# ==========================================
+AGENT_TEMPERATURE=0.7         # Model temperature (0.0-1.0)
+AGENT_MAX_TOKENS=1000         # Maximum tokens per agent response
+AGENT_TIMEOUT=300             # Agent timeout in seconds (5 minutes)
+
+# ==========================================
+# GitHub Integration (MCP)
+# ==========================================
+# Optional: Required for automatic PR creation
+GITHUB_TOKEN=your-github-token-here
+
+# ==========================================
+# Server Configuration
+# ==========================================
+API_PORT=5001
+HOST=0.0.0.0
+CORS_ORIGINS=["http://localhost:3000", "http://localhost:3001", "http://localhost:5173"]
+```
+
+**Step 2:** Deploy services
+
+```bash
+cd docugen-microagents
+docker-compose up -d
+```
+
+**Step 3:** Verify deployment
+
+```bash
+# Check container status
+docker-compose ps
+
+# Expected output:
+# docugen-backend    Up (healthy)
+# docugen-frontend   Up (healthy)
+
+# View logs
+docker-compose logs -f
+
+# Access application
+# Frontend: http://localhost:3000
+# Backend:  http://localhost:5001
+# Health:   http://localhost:5001/health
+```
+
+### Local Development Deployment
+
+**Step 1:** Backend setup
+
+```bash
+cd docugen-microagents/api
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Create .env file (see Docker deployment section for full configuration)
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run server
+python server.py
+```
+
+**Step 2:** Frontend setup
+
+```bash
+cd docugen-microagents/ui
+
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+```
+
+**Step 3:** Access application
+
+```
+Frontend: http://localhost:3000
+Backend:  http://localhost:5001
+```
+
+---
+
+## Generating Documentation
+
+### Basic Workflow
+
+**Step 1:** Enter repository URL
+
+Supported formats:
+```
+# Full repository
+https://github.com/owner/repository
+
+# Specific branch
+https://github.com/owner/repository/tree/dev
+
+# Subfolder (for monorepos)
+https://github.com/owner/repository/tree/main/services/api
+```
+
+**Step 2:** Initiate generation
+
+Click "Generate Documentation". The system will:
+1. Parse and validate the URL
+2. Clone the repository
+3. Run Evidence Aggregator to scan filesystem
+4. Execute 6 section writer agents in parallel
+5. Run coordination agents (Planner → Writer → Mermaid → QA)
+
+**Step 3:** Monitor micro-agent activity
+
+Real-time logs display:
+- **Repository cloning progress**
+- **Evidence Aggregator** - Filesystem scanning
+- **Section Writer Agents** (parallel execution):
+  - Code Explorer - Language detection, key files
+  - API Reference - Endpoint discovery
+  - Call Graph - Function relationships
+  - Error Analysis - Exception handling patterns
+  - Env Config - Environment variables
+  - Dependency Analyzer - Package analysis
+- **Planner** - Section determination
+- **Writer** - Documentation generation with ReAct loops
+- **Mermaid Generator** - Diagram creation and validation
+- **QA Validator** - Quality scoring (0-100)
+- **Performance Metrics** - Token usage, TPS, blast radius
+
+**Step 4:** Project selection (monorepos only)
+
+If multiple projects are detected:
+1. Review detected projects list
+2. Select ONE project to document
+3. Click "Continue"
+
+The workflow resumes automatically after selection.
+
+**Step 5:** Review output
+
+When complete:
+- **QA Score displayed** (e.g., "Quality Score: 87/100")
+- **Preview README** in the UI
+- **Download** as README.md file
+- **Create GitHub pull request** (if GITHUB_TOKEN configured)
+- **View performance metrics** - Total tokens, duration, agent-level breakdown
+
+### Project Selection Logic
+
+DocuGen automatically detects projects based on:
+- Package manager files (package.json, requirements.txt, pom.xml, etc.)
+- Directory structure patterns
+- Configuration files (docker-compose.yml, Dockerfile, etc.)
+
+**Detection Rules:**
+```
+Project indicators:
+- package.json → Node.js project
+- requirements.txt → Python project
+- pom.xml or build.gradle → Java project
+- Cargo.toml → Rust project
+- go.mod → Go project
+- Gemfile → Ruby project
+- composer.json → PHP project
+- *.csproj → .NET project
+```
+
+Monorepo example:
+```
+repo/
+├── services/
+│   ├── auth-api/         ← Detected project 1 (package.json)
+│   ├── data-pipeline/    ← Detected project 2 (requirements.txt)
+│   └── frontend/         ← Detected project 3 (package.json)
+```
+
+**Selection UI:**
+```
+Detected Projects:
+[x] services/auth-api (Node.js)
+[ ] services/data-pipeline (Python)
+[ ] services/frontend (Node.js)
+
+[Continue with Selected Project]
+```
+
+### Creating Pull Requests
+
+**Prerequisites:**
+- GITHUB_TOKEN configured in .env
+- Token has `repo` scope
+- Target repository is on GitHub
+
+**Process:**
+1. Generate documentation
+2. Review README output
+3. Click "Create PR"
+4. System will:
+   - Create branch: `docs/update-readme-{timestamp}`
+   - Commit README.md
+   - Create pull request to base branch
+   - Return PR URL
+
+**PR Contents:**
+- **Title**: `[AI] Update documentation`
+- **Body**: Generated by DocuGen Micro-Agents with metadata
+- **Files**: README.md
+- **Base branch**: Extracted from URL (e.g., `dev`, `main`)
+
+---
+
+## Supported Project Types
+
+### Fully Supported
+
+**Web Applications**
+- React, Vue, Angular, Svelte frontends
+- FastAPI, Flask, Django, Express, Spring Boot backends
+- Full-stack applications (MERN, MEAN, LAMP)
+
+**REST APIs**
+- OpenAPI/Swagger documented services
+- RESTful microservices
+- GraphQL APIs (via API Reference Agent)
+
+**CLI Tools**
+- Python click/argparse applications
+- Node.js commander applications
+- Go cobra applications
+
+**Libraries and SDKs**
+- NPM packages
+- PyPI packages
+- Maven/Gradle libraries
+- Go modules
+- RubyGems
+
+**Microservices**
+- Docker Compose multi-service applications
+- Kubernetes-deployed services
+- Monorepo microservice architectures
+
+### Partially Supported
+
+**Mobile Applications**
+- React Native (JavaScript dependencies detected)
+- Flutter (Dart dependencies detected)
+- Native iOS/Android (limited package manager detection)
+
+**Data Pipelines**
+- Apache Airflow DAGs
+- Apache Spark jobs
+- ETL scripts
+
+**Infrastructure as Code**
+- Terraform configurations
+- CloudFormation templates
+- Ansible playbooks
+
+### Not Supported
+
+- Pure documentation repositories (no code to analyze)
+- Binary-only releases
+- Repositories without package managers
+- Obfuscated or minified code without source
+
+---
+
+## Understanding Output
+
+### Generated Sections
+
+The **Planner Agent** determines which sections to generate based on project type. Common sections:
+
+**Project Overview**
+- Purpose and value proposition
+- High-level architecture pattern
+- Technology stack summary
+
+**Features**
+- User-facing capabilities
+- Organized by component (Backend/Frontend)
+- Based on code analysis from **Code Explorer** and **API Reference** agents
+
+Example:
+```markdown
+## Features
+
+**Backend (FastAPI)**
+- Multiple input format support (text, PDF, audio, video)
+- Streaming and non-streaming response modes
+- Support for vLLM, TGI, and Ollama providers
+- File validation with size limits
+
+**Frontend (React)**
+- Drag-and-drop file upload
+- Real-time summary display
+- Mobile-responsive design
+```
+
+**API Reference**
+- Generated by **API Reference Agent**
+- Detected endpoints with HTTP methods
+- Request/response schemas
+- Authentication requirements
+
+Example:
+```markdown
+## API Reference
+
+### POST /api/summarize
+Generates a summary from uploaded document.
+
+**Request:**
+- Content-Type: multipart/form-data
+- Body: `file` (PDF, TXT, MP3, MP4)
+
+**Response:**
+{
+  "summary": "Generated summary text...",
+  "duration": 1.23
+}
+```
+
+**Architecture**
+- Generated by **Mermaid Generator Agent**
+- Validated Mermaid diagrams
+- System component visualization
+- Data flow diagrams
+
+Example:
+```mermaid
+graph TB
+    A[React Frontend] --> B[FastAPI Backend]
+    B --> C[LLM Provider]
+    B --> D[Document Processor]
+    D --> E[PDF Service]
+    D --> F[Audio Transcription]
+```
+
+**Prerequisites**
+- Required tools and versions from **Dependency Analyzer Agent**
+- API keys and credentials from **Env Config Agent**
+- System requirements
+
+**Configuration**
+- Environment variables from **Env Config Agent**
+- Actual variable names and purposes from .env.example
+- Configuration file examples
+
+**Error Handling**
+- Exception handling patterns from **Error Analysis Agent**
+- Logging strategies
+- Common error scenarios
+
+**Quick Start**
+- Installation commands
+- Setup instructions
+- Running the application
+
+### Quality Assurance
+
+The **QA Validator Agent** scores documentation on a 0-100 scale:
+
+**Scoring Criteria:**
+- **Completeness** (25 points) - All expected sections present
+- **Accuracy** (25 points) - Technically correct information
+- **Clarity** (25 points) - Clear, understandable language
+- **Technical Depth** (25 points) - Sufficient detail for developers
+
+**Score Interpretation:**
+- **90-100**: Excellent - Production-ready documentation
+- **80-89**: Good - Minor improvements needed
+- **70-79**: Fair - Some sections need enhancement
+- **Below 70**: Needs work - Significant gaps or errors
+
+**QA Report Example:**
+```json
+{
+  "score": 87,
+  "passed": true,
+  "feedback": {
+    "strengths": [
+      "Comprehensive API documentation with examples",
+      "Clear installation instructions",
+      "Well-structured architecture diagram"
+    ],
+    "improvements": [
+      "Add troubleshooting section for common errors",
+      "Include performance benchmarks",
+      "Expand testing documentation"
+    ]
+  }
+}
+```
+
+### Performance Metrics
+
+DocuGen tracks detailed metrics for each agent:
+
+**Per-Agent Metrics:**
+- **Tokens used** - Input + output tokens
+- **Duration** - Processing time in milliseconds
+- **TPS** (Tokens Per Second) - Generation speed
+- **LLM calls** - Number of API requests
+- **Tool calls** - Number of tool invocations
+
+**Blast Radius Report:**
+- Total tokens across all agents
+- Total duration
+- Most expensive agent
+- Context efficiency score
+
+Example metrics display:
+```
+Performance Metrics:
+- Total tokens: 45,231
+- Total duration: 23.4s
+- Code Explorer: 12,450 tokens (5.2s)
+- API Reference: 8,120 tokens (3.1s)
+- Dependency Analyzer: 6,340 tokens (2.8s)
+- Writer: 15,221 tokens (8.9s)
+- QA Validator: 3,100 tokens (1.4s)
+```
+
+### Quality Characteristics
+
+Documentation generated by DocuGen exhibits these traits:
+
+**Accuracy**
+- All dependencies extracted from package files by **Dependency Analyzer**
+- Code snippets are actual code from repository
+- Configuration variables match .env.example files (via **Env Config Agent**)
+- Commands match package.json scripts or Makefiles
+
+**Specificity**
+- File paths reference actual repository files
+- Version numbers match package manager specifications
+- Port numbers match configuration files
+- Directory structures match actual layout
+
+**Completeness**
+- All detected features documented (via **Code Explorer**)
+- All package manager dependencies listed (via **Dependency Analyzer**)
+- All environment variables explained (via **Env Config Agent**)
+- All major components represented in diagrams (via **Mermaid Generator**)
+- Error handling documented (via **Error Analysis Agent**)
+- API endpoints cataloged (via **API Reference Agent**)
+
+---
+
+## Limitations
+
+### Functional Limitations
+
+**Code Analysis Depth**
+- Analyzes structure and configuration, not runtime behavior
+- Does not execute code or run tests
+- Cannot verify if setup instructions actually work
+- Does not understand complex business logic
+- Limited to static analysis patterns
+
+**Context Boundaries**
+- Only analyzes files in the repository
+- Does not read external documentation (wikis, Confluence)
+- Does not access git history or issue trackers
+- Does not read inline comments extensively
+- MAX_LINES_PER_FILE budget limits depth per file
+
+**Single Project Focus**
+- Monorepos require selecting one project at a time
+- Cannot document all services in one generation pass
+- Each project must have clear boundaries
+
+**Git Provider Support**
+- PR creation only works with GitHub repositories
+- GitLab and Bitbucket not supported for PR creation
+- Cloning works with any Git provider
+
+### Technical Constraints
+
+**Repository Size**
+- Default limit: 10GB
+- Large repositories may timeout or hit memory limits
+- Use subfolder URLs for focused analysis
+
+**File Count**
+- Default: 500 files scanned
+- Very large codebases may not be fully analyzed
+- Adjust MAX_FILES_TO_SCAN in configuration
+
+**Token Limits**
+- Large repositories generate extensive context
+- Qwen3-4B has 8K context window
+- Strategic file sampling mitigates this (pattern_window extracts ~150-300 lines per file)
+- Processing time scales with repository size
+
+**Language Support**
+- Best support for Python, JavaScript/TypeScript, Java, Go
+- Limited support for less common languages
+- Depends on package manager file formats
+
+**Micro-Agent Constraints**
+- Each agent has AGENT_TIMEOUT (default 300s)
+- Failed agents logged in state.failed_agents
+- Retry logic limited to 3 attempts per agent
+
+---
+
+## Troubleshooting
+
+### Repository Access Issues
+
+**Symptom:** "Repository not found or access denied"
+
+**Diagnosis:**
+```bash
+# Test repository URL
+curl -I https://github.com/owner/repo
+
+# If 404: Repository does not exist or is private
+# If 200: Repository exists and is public
+```
+
+**Resolution:**
+1. Verify repository URL spelling
+2. For private repositories:
+   - Add GITHUB_TOKEN to api/.env
+   - Ensure token has `repo` scope
+   - Regenerate token if expired
+3. Restart backend to load new token:
+   ```bash
+   docker-compose restart backend
+   ```
+
+### Micro-Agent Failures
+
+**Symptom:** Specific agent fails (e.g., "API Reference Agent failed")
+
+**Diagnosis:**
+```bash
+# Check backend logs for agent-specific errors
+docker-compose logs backend | grep -i "agent.*error"
+
+# Look for:
+# - "Failed to parse JSON from agent output"
+# - LLM API errors (connection refused, invalid key, rate limits)
+# - Tool execution failures
+# - Timeout errors (exceeds AGENT_TIMEOUT)
+```
+
+**Resolution:**
+1. **JSON parsing errors:**
+   - Agent output format invalid
+   - Check agent prompt in agents/ directory
+   - Verify model supports JSON output
+
+2. **LLM API errors:**
+   - Verify LLM endpoint is accessible
+   - Check API key is valid (GENAI_GATEWAY_API_KEY or KEYCLOAK_CLIENT_SECRET)
+   - Verify model names match available models
+
+3. **Timeout errors:**
+   - Increase AGENT_TIMEOUT in .env (default 300s)
+   - Reduce MAX_FILES_TO_SCAN or MAX_LINES_PER_FILE
+   - Use subfolder URL for smaller scope
+
+4. **Tool execution failures:**
+   - Check repository permissions (read access)
+   - Verify file paths are valid
+   - Check TEMP_REPO_DIR has write permissions
+
+**View failed agents:**
+```bash
+# Check state.failed_agents in logs
+docker-compose logs backend | grep "failed_agents"
+```
+
+### Log Streaming Issues
+
+**Symptom:** Agent logs appear all at once at the end
+
+**Cause:** Python output buffering
+
+**Resolution:**
+
+For Docker deployment (already configured):
+```yaml
+# docker-compose.yml includes:
+environment:
+  - PYTHONUNBUFFERED=1
+```
+
+For local deployment:
+```bash
+# Run with unbuffered output
+PYTHONUNBUFFERED=1 python server.py
+```
+
+### Pull Request Creation Failures
+
+**Symptom:** "MCP PR Agent error: No such file or directory"
+
+**Cause:** Docker CLI not installed in backend container
+
+**Resolution:**
+
+Verify Docker CLI installation in backend:
+```bash
+docker-compose exec backend which docker
+# Should return: /usr/bin/docker
+```
+
+If not installed, rebuild backend:
+```bash
+docker-compose up -d --build backend
+```
+
+### Monorepo Project Detection
+
+**Symptom:** Projects not detected or wrong projects detected
+
+**Diagnosis:**
+```bash
+# Check for package manager files
+docker-compose exec backend ls -la ./tmp/repos/*/
+
+# Look for:
+# - package.json (Node.js)
+# - requirements.txt (Python)
+# - pom.xml (Java)
+# - go.mod (Go)
+```
+
+**Resolution:**
+1. Ensure projects have package manager files
+2. Use subfolder URL to target specific project
+3. Customize detection logic in utils/__init__.py (see CUSTOMIZATION.md)
+
+### Memory and Performance Issues
+
+**Symptom:** Container OOM errors or slow performance
+
+**Diagnosis:**
+```bash
+# Check container resource usage
+docker stats docugen-backend
+```
+
+**Resolution:**
+1. Increase Docker memory limits:
+   ```yaml
+   # docker-compose.yml
+   services:
+     backend:
+       deploy:
+         resources:
+           limits:
+             memory: 8G  # Increase from default 4G
+   ```
+
+2. Reduce repository scan scope:
+   ```bash
+   # In .env
+   MAX_FILES_TO_SCAN=300
+   MAX_LINES_PER_FILE=300
+   ```
+
+3. Use subfolder URLs for targeted analysis
+
+4. Check agent metrics for expensive agents:
+   ```bash
+   docker-compose logs backend | grep "agent_metrics"
+   ```
+
+### Context Window Exceeded
+
+**Symptom:** "Context length exceeded" errors from LLM
+
+**Diagnosis:**
+```bash
+# Check blast_radius_report in logs
+docker-compose logs backend | grep "blast_radius"
+
+# Look for total_tokens_used exceeding 8000 (Qwen3-4B context window)
+```
+
+**Resolution:**
+1. Reduce MAX_LINES_PER_FILE:
+   ```bash
+   # In .env
+   MAX_LINES_PER_FILE=300  # Reduce from 500
+   ```
+
+2. Use pattern_window strategy (already default):
+   - Automatically limits to ~150-300 lines per file
+   - Verify in logs: "Using pattern_window strategy"
+
+3. Reduce MAX_FILES_TO_SCAN:
+   ```bash
+   # In .env
+   MAX_FILES_TO_SCAN=300  # Reduce from 500
+   ```
+
+4. Use subfolder URL for smaller scope
+
+### QA Validator Low Scores
+
+**Symptom:** QA scores consistently below 70
+
+**Diagnosis:**
+```bash
+# Check QA validation results
+docker-compose logs backend | grep -A 20 "qa_validation_result"
+
+# Review feedback in logs:
+# - Missing sections
+# - Incomplete information
+# - Technical inaccuracies
+```
+
+**Resolution:**
+1. **Missing sections:**
+   - Add missing package manager files to repository
+   - Ensure key configuration files exist (.env.example, docker-compose.yml)
+
+2. **Incomplete information:**
+   - Increase MAX_LINES_PER_FILE for more context
+   - Run specific agents with verbose logging
+
+3. **Technical inaccuracies:**
+   - Review agent prompts in agents/ directory
+   - Adjust model temperature (AGENT_TEMPERATURE)
+   - Try different model (upgrade from Qwen3-4B to larger model)
+
+4. **Customize QA criteria:**
+   - Edit agents/qa_validator.py
+   - Adjust scoring weights (see CUSTOMIZATION.md)
+
+### Health Check Failures
+
+**Symptom:** Containers show "unhealthy" status
+
+**Diagnosis:**
+```bash
+# Check health endpoint
+curl http://localhost:5001/health
+
+# Check logs
+docker-compose logs backend
+```
+
+**Resolution:**
+1. Verify ports are not in use:
+   ```bash
+   netstat -an | grep 5001
+   netstat -an | grep 3000
+   ```
+
+2. Check if services are running:
+   ```bash
+   docker-compose ps
+   ```
+
+3. Restart services:
+   ```bash
+   docker-compose restart
+   ```
+
+---
+
+## Best Practices
+
+### Repository Preparation
+
+**Include Configuration Examples**
+```bash
+# Provide .env.example with all variables
+cp .env .env.example
+
+# Document each variable with inline comments
+AUTH_MODE=genai_gateway                      # Required: Authentication mode
+GENAI_GATEWAY_URL=https://your-gateway.com   # Required: GenAI Gateway URL
+GENAI_GATEWAY_API_KEY=your-key-here          # Required: GenAI Gateway API key
+DATABASE_URL=postgresql://...                # Required: PostgreSQL connection string
+REDIS_URL=redis://...                        # Optional: Redis for caching
+```
+
+**Write Clear README Sections**
+- Even basic setup instructions help
+- DocuGen extracts and improves existing content
+- Better input leads to better output
+
+**Use Standard Project Structure**
+```
+project/
+├── src/ or app/          # Source code
+├── tests/                # Tests
+├── docs/                 # Documentation
+├── config/               # Configuration
+├── package.json          # Dependencies
+├── .env.example          # Environment template
+└── README.md             # Basic docs
+```
+
+**Add API Documentation**
+- Use OpenAPI/Swagger specs
+- Add docstrings to route handlers
+- **API Reference Agent** extracts this automatically
+
+**Document Error Handling**
+- Use try/except blocks consistently
+- **Error Analysis Agent** detects these patterns
+
+### Documentation Review
+
+**Always Review Generated Output**
+- AI-generated content is 80-90% accurate
+- Verify technical details and commands
+- Add domain-specific context AI cannot infer
+- Correct any misinterpretations
+
+**Check QA Score**
+- Scores below 80 warrant review
+- Review QA feedback for specific improvements
+- Re-run generation after fixing issues
+
+**Iterative Improvement**
+- Run DocuGen on updated code
+- Compare with previous output
+- Identify and fix recurring issues
+- Customize prompts if needed (see CUSTOMIZATION.md)
+
+### Model Selection
+
+**Configure models for all agents**
+```bash
+# Qwen3-4B-Instruct (default) - Balanced cost/quality
+CODE_EXPLORER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+API_REFERENCE_MODEL=Qwen/Qwen3-4B-Instruct-2507
+CALL_GRAPH_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ERROR_ANALYSIS_MODEL=Qwen/Qwen3-4B-Instruct-2507
+ENV_CONFIG_MODEL=Qwen/Qwen3-4B-Instruct-2507
+DEPENDENCY_ANALYZER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+PLANNER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+MERMAID_MODEL=Qwen/Qwen3-4B-Instruct-2507
+QA_VALIDATOR_MODEL=Qwen/Qwen3-4B-Instruct-2507
+WRITER_MODEL=Qwen/Qwen3-4B-Instruct-2507
+```
+
+**Model Selection Guidance:**
+- **Qwen3-4B-Instruct**: Fast, cost-effective, good for most projects (8K context)
+- **Qwen2.5-32B-Instruct**: Higher quality, slower, better for complex codebases (32K context)
+- **Mix and match**: Use 4B for simple agents (Env Config), 32B for complex agents (Writer)
+
+**Batching and Caching**
+- Generate docs once per release
+- Cache results for repeated queries
+- Use git hooks to trigger only on significant changes
+
+### Performance Optimization
+
+**Monitor Metrics**
+- Check blast_radius_report after each run
+- Identify expensive agents
+- Optimize prompts or reduce scope
+
+**Adjust Sampling Strategy**
+```python
+# In tools/repo_tools.py, customize for your domain:
+strategy = "pattern_window"  # Default - best for most projects
+strategy = "smart"           # Faster, less context per file
+strategy = "full"            # Maximum detail, highest token usage
+```
+
+**Parallel Execution**
+- Section writer agents already run in parallel
+- 6 agents = ~6x speedup over sequential execution
+- Monitor logs to verify parallel execution
+
+**Token Budget Management**
+```bash
+# Conservative (faster, lower cost)
+MAX_LINES_PER_FILE=300
+MAX_FILES_TO_SCAN=300
+
+# Balanced (default)
+MAX_LINES_PER_FILE=500
+MAX_FILES_TO_SCAN=500
+
+# Aggressive (slower, higher quality for large repos)
+MAX_LINES_PER_FILE=700
+MAX_FILES_TO_SCAN=700
+```
+
+---
+
+## Integration Patterns
+
+### CI/CD Integration
+
+Run DocuGen automatically on pull requests or releases. Example GitHub Actions workflow:
+
+```yaml
+name: Generate Documentation
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Run DocuGen Micro-Agents
+        env:
+          GENAI_GATEWAY_URL: ${{ secrets.GENAI_GATEWAY_URL }}
+          GENAI_GATEWAY_API_KEY: ${{ secrets.GENAI_GATEWAY_API_KEY }}
+        run: |
+          docker run -v $(pwd):/repo \
+            -e AUTH_MODE=genai_gateway \
+            -e GENAI_GATEWAY_URL=$GENAI_GATEWAY_URL \
+            -e GENAI_GATEWAY_API_KEY=$GENAI_GATEWAY_API_KEY \
+            docugen-microagents:latest \
+            /repo
+
+      - name: Commit README
+        run: |
+          git config user.name "DocuGen Bot"
+          git config user.email "bot@example.com"
+          git add README.md
+          git commit -m "docs: Update README [automated]"
+          git push
+```
+
+### API Usage
+
+Programmatic access for automation:
+
+```python
+import requests
+import time
+
+# Start documentation generation
+response = requests.post(
+    "http://localhost:5001/api/generate-docs",
+    json={"repo_url": "https://github.com/owner/repo"}
+)
+job_id = response.json()["job_id"]
+
+# Poll for completion
+while True:
+    status = requests.get(f"http://localhost:5001/api/status/{job_id}")
+    data = status.json()
+
+    if data["status"] == "complete":
+        # Check QA score
+        qa_score = data.get("qa_score", 0)
+        print(f"Documentation generated with QA score: {qa_score}/100")
+
+        # Get performance metrics
+        metrics = data.get("agent_metrics", {})
+        total_tokens = data.get("total_tokens_used", 0)
+        print(f"Total tokens: {total_tokens}")
+        break
+
+    time.sleep(5)
+
+# Download README
+readme = requests.get(f"http://localhost:5001/api/download/{job_id}")
+with open("README.md", "w") as f:
+    f.write(readme.text)
+```
+
+### Webhook Integration
+
+Trigger documentation generation on git push:
+
+```python
+# webhook_server.py
+from flask import Flask, request
+import requests
+
+app = Flask(__name__)
+
+@app.route("/webhook", methods=["POST"])
+def github_webhook():
+    payload = request.json
+
+    # Trigger on push to main branch
+    if payload["ref"] == "refs/heads/main":
+        repo_url = payload["repository"]["html_url"]
+
+        # Start DocuGen
+        response = requests.post(
+            "http://localhost:5001/api/generate-docs",
+            json={"repo_url": repo_url}
+        )
+
+        return {"status": "started", "job_id": response.json()["job_id"]}
+
+    return {"status": "ignored"}
+
+if __name__ == "__main__":
+    app.run(port=8000)
+```
+
+**Configure GitHub webhook:**
+```
+Payload URL: http://your-server:8000/webhook
+Content type: application/json
+Events: Push events
+```
+
+---
+
+## Advanced Usage
+
+### Customizing Micro-Agents
+
+See **CUSTOMIZATION.md** for detailed customization guides:
+
+- Customizing section writer agents (Code Explorer, API Reference, etc.)
+- Customizing coordination agents (Planner, Mermaid, QA Validator)
+- Adding custom tools
+- Modifying strategic file sampling
+- Adding new micro-agents
+- Workflow customization
+
+### Environment Variables Reference
+
+See **api/.env.example** for complete list with descriptions.
+
+**Key variables:**
+- `AUTH_MODE` - Authentication mode (genai_gateway | keycloak)
+- `MAX_LINES_PER_FILE` - File sampling budget (default 500)
+- `AGENT_TIMEOUT` - Agent execution timeout in seconds (default 300)
+- `AGENT_TEMPERATURE` - Model temperature 0.0-1.0 (default 0.7)
+- `AGENT_MAX_TOKENS` - Max tokens per agent response (default 1000)
+
+### Metrics and Observability
+
+**Available metrics:**
+- Per-agent token usage
+- Per-agent execution duration
+- LLM call counts
+- Tool call counts
+- TPS (Tokens Per Second)
+- Blast radius (total context usage)
+
+**Accessing metrics:**
+```bash
+# View in logs
+docker-compose logs backend | grep "agent_metrics"
+
+# Or via API
+curl http://localhost:5001/api/metrics/{job_id}
+```
+
+---
+
+**For customization and development guides, see CUSTOMIZATION.md**
diff --git a/DocuGenMicroagents/docs/images/01-homepage-input.png b/DocuGenMicroagents/docs/images/01-homepage-input.png
new file mode 100644
index 0000000000..07645f2973
Binary files /dev/null and b/DocuGenMicroagents/docs/images/01-homepage-input.png differ
diff --git a/DocuGenMicroagents/docs/images/02-agent-workflow.png b/DocuGenMicroagents/docs/images/02-agent-workflow.png
new file mode 100644
index 0000000000..23e7bb3ad9
Binary files /dev/null and b/DocuGenMicroagents/docs/images/02-agent-workflow.png differ
diff --git a/DocuGenMicroagents/docs/images/03-progress-tracking.png b/DocuGenMicroagents/docs/images/03-progress-tracking.png
new file mode 100644
index 0000000000..731cddf333
Binary files /dev/null and b/DocuGenMicroagents/docs/images/03-progress-tracking.png differ
diff --git a/DocuGenMicroagents/docs/images/04-generated-readme.png b/DocuGenMicroagents/docs/images/04-generated-readme.png
new file mode 100644
index 0000000000..0d7460e546
Binary files /dev/null and b/DocuGenMicroagents/docs/images/04-generated-readme.png differ
diff --git a/DocuGenMicroagents/docs/images/05-pr-agent-execution.png b/DocuGenMicroagents/docs/images/05-pr-agent-execution.png
new file mode 100644
index 0000000000..bd34fcfd72
Binary files /dev/null and b/DocuGenMicroagents/docs/images/05-pr-agent-execution.png differ
diff --git a/DocuGenMicroagents/docs/images/06-pr-created.png b/DocuGenMicroagents/docs/images/06-pr-created.png
new file mode 100644
index 0000000000..5b822a2607
Binary files /dev/null and b/DocuGenMicroagents/docs/images/06-pr-created.png differ
diff --git a/DocuGenMicroagents/docs/images/07-metrics.png b/DocuGenMicroagents/docs/images/07-metrics.png
new file mode 100644
index 0000000000..db3989c475
Binary files /dev/null and b/DocuGenMicroagents/docs/images/07-metrics.png differ
diff --git a/DocuGenMicroagents/ui/.dockerignore b/DocuGenMicroagents/ui/.dockerignore
new file mode 100644
index 0000000000..aca46af5bd
--- /dev/null
+++ b/DocuGenMicroagents/ui/.dockerignore
@@ -0,0 +1,39 @@
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+yarn.lock
+
+dist/
+build/
+.next/
+out/
+
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+coverage/
+.nyc_output/
+
+.env
+.env.local
+.env.*.local
+
+.git/
+.gitignore
+
+README.md
+*.md
+
+Dockerfile
+.dockerignore
+
+.DS_Store
+Thumbs.db
+
+*.log
+.cache/
diff --git a/DocuGenMicroagents/ui/Dockerfile b/DocuGenMicroagents/ui/Dockerfile
new file mode 100644
index 0000000000..7803a7f8eb
--- /dev/null
+++ b/DocuGenMicroagents/ui/Dockerfile
@@ -0,0 +1,29 @@
+# Multi-stage build for DocuGen AI Frontend
+FROM node:20-slim
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production=false
+
+# Copy application code
+COPY . .
+
+# Expose port
+EXPOSE 3000
+
+# Set environment for Vite
+ENV HOST=0.0.0.0
+ENV PORT=3000
+ENV VITE_API_TARGET=http://backend:5001
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD node -e "require('http').get('http://localhost:3000', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+# Run development server with environment variable
+CMD ["sh", "-c", "VITE_API_TARGET=http://backend:5001 npm run dev -- --host 0.0.0.0 --port 3000"]
diff --git a/DocuGenMicroagents/ui/index.html b/DocuGenMicroagents/ui/index.html
new file mode 100644
index 0000000000..d8acf77636
--- /dev/null
+++ b/DocuGenMicroagents/ui/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>DocuGen AI - Automatic Documentation Generator</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
diff --git a/DocuGenMicroagents/ui/nginx.conf b/DocuGenMicroagents/ui/nginx.conf
new file mode 100644
index 0000000000..080a102832
--- /dev/null
+++ b/DocuGenMicroagents/ui/nginx.conf
@@ -0,0 +1,64 @@
+server {
+    listen 8080;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
+
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "no-referrer-when-downgrade" always;
+
+    # SPA routing - serve index.html for all routes
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API proxy to backend
+    location /api/ {
+        proxy_pass http://backend:5001;
+        proxy_http_version 1.1;
+
+        # SSE support
+        proxy_set_header Connection '';
+        proxy_set_header Cache-Control 'no-cache';
+        proxy_buffering off;
+        chunked_transfer_encoding on;
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Timeouts for long-running requests
+        proxy_connect_timeout 300s;
+        proxy_send_timeout 300s;
+        proxy_read_timeout 300s;
+    }
+
+    # Static files caching
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Disable access log for static files
+    location = /favicon.ico {
+        log_not_found off;
+        access_log off;
+    }
+
+    location = /robots.txt {
+        log_not_found off;
+        access_log off;
+    }
+}
diff --git a/DocuGenMicroagents/ui/package.json b/DocuGenMicroagents/ui/package.json
new file mode 100644
index 0000000000..5a6520f7d8
--- /dev/null
+++ b/DocuGenMicroagents/ui/package.json
@@ -0,0 +1,38 @@
+{
+  "name": "docugen-ui",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "github-markdown-css": "^5.8.1",
+    "highlight.js": "^11.11.1",
+    "lucide-react": "^0.294.0",
+    "mermaid": "^11.12.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-markdown": "^9.0.1",
+    "react-mermaid2": "^0.1.4",
+    "rehype-highlight": "^7.0.0",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.3.6",
+    "vite": "^5.0.8"
+  }
+}
diff --git a/DocuGenMicroagents/ui/postcss.config.js b/DocuGenMicroagents/ui/postcss.config.js
new file mode 100644
index 0000000000..2e7af2b7f1
--- /dev/null
+++ b/DocuGenMicroagents/ui/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
diff --git a/DocuGenMicroagents/ui/src/App.jsx b/DocuGenMicroagents/ui/src/App.jsx
new file mode 100644
index 0000000000..b8e969c932
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/App.jsx
@@ -0,0 +1,137 @@
+import { useState, useEffect } from 'react'
+import Header from './components/Header'
+import DocGenInterface from './components/DocGenInterface'
+import AgentLogPanel from './components/AgentLogPanel'
+import ResultsViewer from './components/ResultsViewer'
+import ProjectSelector from './components/ProjectSelector'
+import { api } from './services/api'
+
+function App() {
+  const [currentJob, setCurrentJob] = useState(null)
+  const [logs, setLogs] = useState([])
+  const [logsOpen, setLogsOpen] = useState(false)
+  const [generatedReadme, setGeneratedReadme] = useState(null)
+  const [workflowStatus, setWorkflowStatus] = useState('idle') // idle, running, completed, failed
+  const [workflowError, setWorkflowError] = useState(null) // Store error message from backend
+  const [awaitingProjectSelection, setAwaitingProjectSelection] = useState(false)
+  const [detectedProjects, setDetectedProjects] = useState(null)
+  const [skippedFolders, setSkippedFolders] = useState(null)
+
+  // Poll job status to check for project selection
+  useEffect(() => {
+    if (!currentJob || workflowStatus === 'completed' || workflowStatus === 'failed') {
+      return
+    }
+
+    const pollInterval = setInterval(async () => {
+      try {
+        const status = await api.getJobStatus(currentJob)
+
+        if (status.awaiting_project_selection && !awaitingProjectSelection) {
+          // Only update once when state changes to awaiting_selection
+          console.log('DEBUG: API Status Response:', status)
+          console.log('DEBUG: Skipped Folders from API:', status.skipped_folders)
+          setAwaitingProjectSelection(true)
+          setDetectedProjects(status.detected_projects)
+          setSkippedFolders(status.skipped_folders || [])
+          setWorkflowStatus('awaiting_selection')
+        }
+
+        // Check for error in job status
+        if (status.error_message && status.status === 'failed') {
+          setWorkflowError(status.error_message)
+          setWorkflowStatus('failed')
+        }
+      } catch (error) {
+        console.error('Failed to poll job status:', error)
+      }
+    }, 2000) // Poll every 2 seconds
+
+    return () => clearInterval(pollInterval)
+  }, [currentJob, workflowStatus, awaitingProjectSelection])
+
+  const handleJobStart = (jobId) => {
+    setCurrentJob(jobId)
+    setLogs([])
+    setGeneratedReadme(null)
+    setWorkflowStatus('running')
+    setWorkflowError(null) // Clear previous errors
+    setAwaitingProjectSelection(false)
+    setDetectedProjects(null)
+    setSkippedFolders(null)
+    // Don't auto-open logs panel - let user click to open
+  }
+
+  const handleLogReceived = (log) => {
+    setLogs(prevLogs => [...prevLogs, log])
+
+    // Check if workflow is complete - ONLY match the final completion message
+    if (log.log_type === 'success' && log.message.includes('Documentation generation complete')) {
+      setWorkflowStatus('completed')
+    } else if (log.log_type === 'error') {
+      setWorkflowStatus('failed')
+      // Errors are already shown in agent logs, no need for additional alert
+    }
+  }
+
+  const handleReadmeGenerated = (readme) => {
+    setGeneratedReadme(readme)
+  }
+
+  const handleProjectsSelected = () => {
+    setAwaitingProjectSelection(false)
+    setDetectedProjects(null)
+    setSkippedFolders(null)
+    setWorkflowStatus('running')
+  }
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 via-white to-purple-50">
+      <Header
+        onLogsToggle={() => setLogsOpen(!logsOpen)}
+        hasActiveJob={!!currentJob}
+        workflowStatus={workflowStatus}
+      />
+
+      <main className="container mx-auto px-4 py-6 max-w-5xl">
+        <div className="space-y-6">
+          {/* Top: Input Interface */}
+          <DocGenInterface
+            onJobStart={handleJobStart}
+            onLogReceived={handleLogReceived}
+            currentJob={currentJob}
+            workflowStatus={workflowStatus}
+            workflowError={workflowError}
+          />
+
+          {/* Middle: Project Selection (shown when multiple projects detected) */}
+          {awaitingProjectSelection && detectedProjects && (
+            <ProjectSelector
+              currentJob={currentJob}
+              detectedProjects={detectedProjects}
+              skippedFolders={skippedFolders}
+              onProjectsSelected={handleProjectsSelected}
+            />
+          )}
+
+          {/* Bottom: Results Viewer */}
+          <ResultsViewer
+            readme={generatedReadme}
+            onReadmeGenerated={handleReadmeGenerated}
+            currentJob={currentJob}
+            workflowStatus={workflowStatus}
+          />
+        </div>
+      </main>
+
+      <AgentLogPanel
+        isOpen={logsOpen}
+        onClose={() => setLogsOpen(false)}
+        logs={logs}
+        currentJob={currentJob}
+      />
+    </div>
+  )
+}
+
+export default App
diff --git a/DocuGenMicroagents/ui/src/components/AgentLogPanel.jsx b/DocuGenMicroagents/ui/src/components/AgentLogPanel.jsx
new file mode 100644
index 0000000000..b43f61b901
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/components/AgentLogPanel.jsx
@@ -0,0 +1,138 @@
+import { X, Bot, CheckCircle, AlertCircle, Info, Zap } from 'lucide-react'
+
+function AgentLogPanel({ isOpen, onClose, logs, currentJob }) {
+  if (!isOpen) return null
+
+  const getLogIcon = (logType) => {
+    switch (logType) {
+      case 'agent_start':
+        return <Bot className="w-4 h-4 text-blue-500" />
+      case 'agent_complete':
+        return <CheckCircle className="w-4 h-4 text-green-500" />
+      case 'agent_thinking':
+        return <Zap className="w-4 h-4 text-yellow-500" />
+      case 'error':
+        return <AlertCircle className="w-4 h-4 text-red-500" />
+      case 'success':
+        return <CheckCircle className="w-4 h-4 text-green-500" />
+      default:
+        return <Info className="w-4 h-4 text-gray-500" />
+    }
+  }
+
+  const getLogColor = (logType) => {
+    switch (logType) {
+      case 'agent_start':
+        return 'bg-blue-50 border-blue-200'
+      case 'agent_complete':
+        return 'bg-green-50 border-green-200'
+      case 'agent_thinking':
+        return 'bg-yellow-50 border-yellow-200'
+      case 'error':
+        return 'bg-red-50 border-red-200'
+      case 'success':
+        return 'bg-green-50 border-green-200'
+      default:
+        return 'bg-gray-50 border-gray-200'
+    }
+  }
+
+  const formatTimestamp = (timestamp) => {
+    return new Date(timestamp).toLocaleTimeString()
+  }
+
+  return (
+    <div className="fixed inset-0 bg-black bg-opacity-50 z-50 flex items-center justify-center p-4">
+      <div className="bg-white rounded-xl shadow-2xl w-full max-w-4xl max-h-[80vh] flex flex-col">
+        {/* Header */}
+        <div className="flex items-center justify-between p-6 border-b border-gray-200">
+          <div>
+            <h2 className="text-2xl font-bold text-gray-800">Agent Activity Log</h2>
+            {currentJob && (
+              <p className="text-sm text-gray-500 mt-1">Job ID: {currentJob}</p>
+            )}
+          </div>
+          <button
+            onClick={onClose}
+            className="p-2 hover:bg-gray-100 rounded-lg transition-colors"
+          >
+            <X className="w-6 h-6 text-gray-500" />
+          </button>
+        </div>
+
+        {/* Logs Content */}
+        <div className="flex-1 overflow-y-auto p-6 space-y-3">
+          {logs.length === 0 ? (
+            <div className="flex flex-col items-center justify-center h-full text-gray-400">
+              <Bot className="w-16 h-16 mb-4 opacity-50" />
+              <p className="text-lg font-medium">No activity yet</p>
+              <p className="text-sm">Agent logs will appear here during generation</p>
+            </div>
+          ) : (
+            logs.map((log, index) => (
+              <div
+                key={index}
+                className={`p-4 rounded-lg border ${getLogColor(log.log_type)}`}
+              >
+                <div className="flex items-start space-x-3">
+                  <div className="flex-shrink-0 mt-0.5">
+                    {getLogIcon(log.log_type)}
+                  </div>
+                  <div className="flex-1 min-w-0">
+                    <div className="flex items-center justify-between mb-1">
+                      {log.agent_name && (
+                        <span className="text-xs font-semibold text-gray-700 uppercase tracking-wide">
+                          {log.agent_name}
+                        </span>
+                      )}
+                      {log.timestamp && (
+                        <span className="text-xs text-gray-500">
+                          {formatTimestamp(log.timestamp)}
+                        </span>
+                      )}
+                    </div>
+                    <p className="text-sm text-gray-800 whitespace-pre-wrap">{log.message}</p>
+
+                    {/* Metadata */}
+                    {log.metadata && Object.keys(log.metadata).length > 0 && (
+                      <div className="mt-2 p-2 bg-white bg-opacity-50 rounded text-xs font-mono">
+                        {JSON.stringify(log.metadata, null, 2)}
+                      </div>
+                    )}
+                  </div>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+
+        {/* Footer Stats */}
+        {logs.length > 0 && (
+          <div className="border-t border-gray-200 p-4 bg-gray-50">
+            <div className="flex items-center justify-between text-sm">
+              <span className="text-gray-600">
+                Total Events: <span className="font-semibold text-gray-800">{logs.length}</span>
+              </span>
+              <div className="flex space-x-4">
+                <span className="text-gray-600">
+                  Agents: <span className="font-semibold text-blue-600">
+                    {new Set(logs.filter(l => l.agent_name).map(l => l.agent_name)).size}
+                  </span>
+                </span>
+                {logs.filter(l => l.log_type === 'error').length > 0 && (
+                  <span className="text-gray-600">
+                    Errors: <span className="font-semibold text-red-600">
+                      {logs.filter(l => l.log_type === 'error').length}
+                    </span>
+                  </span>
+                )}
+              </div>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default AgentLogPanel
diff --git a/DocuGenMicroagents/ui/src/components/DocGenInterface.jsx b/DocuGenMicroagents/ui/src/components/DocGenInterface.jsx
new file mode 100644
index 0000000000..0ed555781d
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/components/DocGenInterface.jsx
@@ -0,0 +1,220 @@
+import { useState, useEffect } from 'react'
+import { Github, Play, Loader2, CheckCircle, AlertCircle, Clock } from 'lucide-react'
+import { api } from '../services/api'
+
+function DocGenInterface({ onJobStart, onLogReceived, currentJob, workflowStatus, workflowError }) {
+  const [repoUrl, setRepoUrl] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState(null)
+  const [sseConnection, setSseConnection] = useState(null)
+
+  // Update local error when workflow error changes
+  useEffect(() => {
+    if (workflowError) {
+      setError(workflowError)
+      setLoading(false)
+    }
+  }, [workflowError])
+
+  // Clean up SSE connection on unmount
+  useEffect(() => {
+    return () => {
+      if (sseConnection) {
+        sseConnection.close()
+      }
+    }
+  }, [sseConnection])
+
+  // Connect to SSE stream when job starts
+  useEffect(() => {
+    if (currentJob && !sseConnection) {
+      console.log('Connecting to SSE for job:', currentJob)
+
+      const eventSource = api.connectToLogs(
+        currentJob,
+        (log) => {
+          console.log('Received log:', log)
+          onLogReceived(log)
+
+          // Stop loading when workflow completes or fails
+          if (log.log_type === 'success' && log.message.includes('complete')) {
+            setLoading(false)
+          } else if (log.log_type === 'error') {
+            setLoading(false)
+          }
+        },
+        (error) => {
+          console.error('SSE connection error:', error)
+          setError('Connection to the server was lost. Please try again.')
+          setLoading(false)
+        }
+      )
+
+      setSseConnection(eventSource)
+
+      return () => {
+        console.log('Closing SSE connection')
+        eventSource.close()
+      }
+    }
+  }, [currentJob])
+
+  // Stop loading when workflow status changes to completed or failed
+  useEffect(() => {
+    if (workflowStatus === 'completed' || workflowStatus === 'failed') {
+      setLoading(false)
+    }
+  }, [workflowStatus])
+
+  const handleSubmit = async (e) => {
+    e.preventDefault()
+    setError(null)
+    setLoading(true)
+
+    try {
+      // Validate URL
+      if (!repoUrl.trim()) {
+        throw new Error('Please enter a GitHub repository URL.')
+      }
+
+      if (!repoUrl.includes('github.com')) {
+        throw new Error('Please provide a valid GitHub repository URL (e.g., https://github.com/username/repository)')
+      }
+
+      // Note: Subfolder URLs are now supported! (e.g., /tree/main/path/to/folder)
+
+      // Start documentation generation
+      const response = await api.generateDocs(repoUrl)
+      onJobStart(response.job_id)
+
+    } catch (err) {
+      // Extract error message from axios error response or use default
+      const errorMessage = err.response?.data?.detail || err.response?.data?.message || err.message || 'Failed to start documentation generation. Please try again.'
+      setError(errorMessage)
+      setLoading(false)
+    }
+  }
+
+  const isDisabled = loading || workflowStatus === 'running'
+
+  const getStatusMessage = () => {
+    switch (workflowStatus) {
+      case 'running':
+        return {
+          icon: <Clock className="w-4 h-4 text-blue-500 animate-spin" />,
+          bg: 'bg-blue-50 border-blue-200',
+          text: 'text-blue-800',
+          message: 'AI agents are analyzing your repository and generating documentation. Click "Agent Logs" in the header to watch the progress.'
+        }
+      case 'completed':
+        return {
+          icon: <CheckCircle className="w-4 h-4 text-green-500" />,
+          bg: 'bg-green-50 border-green-200',
+          text: 'text-green-800',
+          message: 'Documentation generation complete! Check the generated README below.'
+        }
+      case 'failed':
+        return {
+          icon: <AlertCircle className="w-4 h-4 text-red-500" />,
+          bg: 'bg-red-50 border-red-200',
+          text: 'text-red-800',
+          message: workflowError || 'Documentation generation failed. Please check the Agent Logs for details.'
+        }
+      default:
+        return null
+    }
+  }
+
+  const statusInfo = getStatusMessage()
+
+  return (
+    <div className="bg-white rounded-xl shadow-lg p-6 border border-gray-200">
+      <div className="mb-6">
+        <h2 className="text-2xl font-bold text-gray-800 mb-2">Generate Documentation</h2>
+        <p className="text-gray-600">Enter a GitHub repository URL to generate comprehensive documentation</p>
+      </div>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        {/* Repository URL Input */}
+        <div>
+          <label htmlFor="repoUrl" className="block text-sm font-medium text-gray-700 mb-2">
+            GitHub Repository URL
+          </label>
+          <div className="relative">
+            <div className="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
+              <Github className="w-5 h-5 text-gray-400" />
+            </div>
+            <input
+              type="text"
+              id="repoUrl"
+              value={repoUrl}
+              onChange={(e) => setRepoUrl(e.target.value)}
+              placeholder="https://github.com/username/repository"
+              disabled={isDisabled}
+              className="w-full pl-10 pr-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent disabled:bg-gray-100 disabled:cursor-not-allowed"
+            />
+          </div>
+          <p className="mt-2 text-xs text-gray-500">
+            Max repo size: 10GB. Analyzes up to 500 files (1MB max each, upto 500 lines/file). All limits configurable in backend .env
+          </p>
+        </div>
+
+
+        {/* Error Message */}
+        {error && (
+          <div className="p-4 bg-red-50 border border-red-200 rounded-lg">
+            <div className="flex items-start space-x-3">
+              <AlertCircle className="w-5 h-5 text-red-600 flex-shrink-0 mt-0.5" />
+              <div className="flex-1">
+                <p className="text-sm font-medium text-red-800">{error}</p>
+              </div>
+              <button
+                onClick={() => setError(null)}
+                className="text-red-400 hover:text-red-600 text-xl leading-none"
+              >
+                ×
+              </button>
+            </div>
+          </div>
+        )}
+
+        {/* Submit Button */}
+        <button
+          type="submit"
+          disabled={isDisabled}
+          className="w-full flex items-center justify-center space-x-2 px-6 py-3 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-lg font-medium hover:from-blue-600 hover:to-purple-700 transition-all disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading || workflowStatus === 'running' ? (
+            <>
+              <Loader2 className="w-5 h-5 animate-spin" />
+              <span>Generating...</span>
+            </>
+          ) : (
+            <>
+              <Play className="w-5 h-5" />
+              <span>Generate Documentation</span>
+            </>
+          )}
+        </button>
+      </form>
+
+      {/* Workflow Status */}
+      {currentJob && statusInfo && (
+        <div className={`mt-6 p-4 rounded-lg border ${statusInfo.bg}`}>
+          <div className="flex items-start space-x-3">
+            <div className="flex-shrink-0 mt-0.5">
+              {statusInfo.icon}
+            </div>
+            <div className="flex-1">
+              <p className={`text-sm ${statusInfo.text}`}>
+                {statusInfo.message}
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default DocGenInterface
diff --git a/DocuGenMicroagents/ui/src/components/Header.jsx b/DocuGenMicroagents/ui/src/components/Header.jsx
new file mode 100644
index 0000000000..9c654bad8e
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/components/Header.jsx
@@ -0,0 +1,70 @@
+import { FileText, Activity, CheckCircle, XCircle, Clock } from 'lucide-react'
+
+function Header({ onLogsToggle, hasActiveJob, workflowStatus }) {
+  const getStatusIcon = () => {
+    switch (workflowStatus) {
+      case 'running':
+        return <Clock className="w-5 h-5 text-blue-500 animate-spin" />
+      case 'completed':
+        return <CheckCircle className="w-5 h-5 text-green-500" />
+      case 'failed':
+        return <XCircle className="w-5 h-5 text-red-500" />
+      default:
+        return null
+    }
+  }
+
+  const getStatusText = () => {
+    switch (workflowStatus) {
+      case 'running':
+        return 'Generating...'
+      case 'completed':
+        return 'Completed'
+      case 'failed':
+        return 'Failed'
+      default:
+        return 'Ready'
+    }
+  }
+
+  return (
+    <header className="bg-white shadow-sm border-b border-gray-200">
+      <div className="container mx-auto px-4 py-4 max-w-7xl">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center space-x-3">
+            <div className="bg-gradient-to-br from-blue-500 to-purple-600 p-2 rounded-lg">
+              <FileText className="w-6 h-6 text-white" />
+            </div>
+            <div>
+              <h1 className="text-2xl font-bold bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
+                DocuGen AI
+              </h1>
+              <p className="text-sm text-gray-500">Automatic Documentation Generator</p>
+            </div>
+          </div>
+
+          <div className="flex items-center space-x-4">
+            {/* Status Indicator */}
+            {hasActiveJob && (
+              <div className="flex items-center space-x-2 px-4 py-2 bg-gray-50 rounded-lg border border-gray-200">
+                {getStatusIcon()}
+                <span className="text-sm font-medium text-gray-700">{getStatusText()}</span>
+              </div>
+            )}
+
+            {/* Agent Logs Button */}
+            <button
+              onClick={onLogsToggle}
+              className="flex items-center space-x-2 px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 transition-colors"
+            >
+              <Activity className="w-5 h-5" />
+              <span>Agent Logs</span>
+            </button>
+          </div>
+        </div>
+      </div>
+    </header>
+  )
+}
+
+export default Header
diff --git a/DocuGenMicroagents/ui/src/components/ProjectSelector.jsx b/DocuGenMicroagents/ui/src/components/ProjectSelector.jsx
new file mode 100644
index 0000000000..279da952e9
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/components/ProjectSelector.jsx
@@ -0,0 +1,275 @@
+import { useState, useEffect } from 'react'
+import { Folder, CheckSquare, Square, Play, Loader2, CheckCheck, XSquare, Search, AlertCircle } from 'lucide-react'
+import { api } from '../services/api'
+
+function ProjectSelector({ currentJob, detectedProjects, skippedFolders, onProjectsSelected }) {
+  const [selectedPaths, setSelectedPaths] = useState([])
+  const [submitting, setSubmitting] = useState(false)
+  const [searchQuery, setSearchQuery] = useState('')
+  const [error, setError] = useState(null)
+
+  // Debug logging
+  console.log('DEBUG ProjectSelector - skippedFolders:', skippedFolders)
+  console.log('DEBUG ProjectSelector - skippedFolders type:', typeof skippedFolders)
+  console.log('DEBUG ProjectSelector - skippedFolders length:', skippedFolders?.length)
+
+  // Initialize with empty selection (better UX for large repos)
+  useEffect(() => {
+    if (detectedProjects && detectedProjects.length > 0) {
+      // For small repos (< 10 projects), select all. For large repos, select none.
+      if (detectedProjects.length <= 10) {
+        setSelectedPaths(detectedProjects.map(p => p.path))
+      } else {
+        setSelectedPaths([])
+      }
+    }
+  }, [detectedProjects])
+
+  const selectAll = () => {
+    const filtered = getFilteredProjects()
+    setSelectedPaths(prev => {
+      const newPaths = filtered.map(p => p.path)
+      return Array.from(new Set([...prev, ...newPaths]))
+    })
+  }
+
+  const deselectAll = () => {
+    const filtered = getFilteredProjects()
+    const filteredPaths = filtered.map(p => p.path)
+    setSelectedPaths(prev => prev.filter(path => !filteredPaths.includes(path)))
+  }
+
+  const getFilteredProjects = () => {
+    if (!detectedProjects) return []
+    if (!searchQuery.trim()) return detectedProjects
+
+    const query = searchQuery.toLowerCase()
+    return detectedProjects.filter(p =>
+      p.name.toLowerCase().includes(query) ||
+      p.path.toLowerCase().includes(query) ||
+      p.types.some(t => t.toLowerCase().includes(query))
+    )
+  }
+
+  const toggleProject = (path) => {
+    setError(null) // Clear error when user changes selection
+    setSelectedPaths(prev => {
+      if (prev.includes(path)) {
+        return prev.filter(p => p !== path)
+      } else {
+        return [...prev, path]
+      }
+    })
+  }
+
+  const handleSubmit = async () => {
+    if (selectedPaths.length === 0) {
+      setError('Please select at least one project to document')
+      return
+    }
+
+    setSubmitting(true)
+    setError(null)
+    try {
+      await api.selectProjects(currentJob, selectedPaths)
+      onProjectsSelected()
+    } catch (err) {
+      console.error('Failed to submit project selection:', err)
+      // Extract error message from backend response
+      const errorMessage = err.response?.data?.detail || 'Failed to submit selection. Please try again.'
+      setError(errorMessage)
+      setSubmitting(false)
+    }
+  }
+
+  if (!detectedProjects || detectedProjects.length === 0) {
+    return null
+  }
+
+  const filteredProjects = getFilteredProjects()
+  const filteredSelectedCount = filteredProjects.filter(p => selectedPaths.includes(p.path)).length
+
+  return (
+    <div className="bg-gradient-to-r from-purple-50 to-blue-50 rounded-xl border-2 border-purple-200 p-6">
+      <div className="mb-4">
+        <h3 className="text-xl font-bold text-gray-800 mb-2">
+          🔍 Multiple Projects Detected
+        </h3>
+        <p className="text-sm text-gray-600">
+          {detectedProjects.length} project(s) Found in this repository. Select a project to generate Readme file.
+        </p>
+      </div>
+
+      {/* Error Banner */}
+      {error && (
+        <div className="mb-4 p-4 bg-red-50 border-2 border-red-300 rounded-lg">
+          <div className="flex items-start space-x-3">
+            <AlertCircle className="w-5 h-5 text-red-600 flex-shrink-0 mt-0.5" />
+            <div className="flex-1">
+              <p className="text-sm font-medium text-red-800">{error}</p>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Search and Bulk Actions */}
+      <div className="mb-4 space-y-3">
+        {/* Search Bar */}
+        <div className="relative">
+          <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 w-5 h-5 text-gray-400" />
+          <input
+            type="text"
+            placeholder="Search projects by name, path, or type..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="w-full pl-10 pr-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-purple-500 focus:border-transparent"
+          />
+        </div>
+
+        {/* Bulk Selection Buttons */}
+        <div className="flex items-center justify-between">
+          <div className="flex space-x-2">
+            <button
+              onClick={selectAll}
+              className="flex items-center space-x-1 px-3 py-1.5 bg-white border border-purple-300 text-purple-700 rounded-lg hover:bg-purple-50 text-sm font-medium transition-colors"
+            >
+              <CheckCheck className="w-4 h-4" />
+              <span>Select {searchQuery ? 'Filtered' : 'All'}</span>
+            </button>
+            <button
+              onClick={deselectAll}
+              className="flex items-center space-x-1 px-3 py-1.5 bg-white border border-gray-300 text-gray-700 rounded-lg hover:bg-gray-50 text-sm font-medium transition-colors"
+            >
+              <XSquare className="w-4 h-4" />
+              <span>Deselect {searchQuery ? 'Filtered' : 'All'}</span>
+            </button>
+          </div>
+          <p className="text-sm text-gray-600">
+            {selectedPaths.length} of {detectedProjects.length} selected
+          </p>
+        </div>
+      </div>
+
+      {/* Project List */}
+      <div className="space-y-3 mb-6 max-h-96 overflow-y-auto">
+        {filteredProjects.length === 0 ? (
+          <div className="text-center py-8 text-gray-500">
+            <Search className="w-12 h-12 mx-auto mb-2 opacity-50" />
+            <p>No projects match your search criteria.</p>
+          </div>
+        ) : (
+          filteredProjects.map((project) => {
+            const isSelected = selectedPaths.includes(project.path)
+            const projectTypes = project.types.join(', ')
+            const isRoot = project.path === '/'
+
+            return (
+              <div
+                key={project.path}
+              onClick={() => toggleProject(project.path)}
+              className={`
+                flex items-start space-x-3 p-4 rounded-lg border-2 cursor-pointer transition-all
+                ${isSelected
+                  ? 'bg-white border-purple-500 shadow-md'
+                  : 'bg-gray-50 border-gray-200 hover:border-purple-300'
+                }
+              `}
+            >
+              <div className="flex-shrink-0 mt-1">
+                {isSelected ? (
+                  <CheckSquare className="w-5 h-5 text-purple-600" />
+                ) : (
+                  <Square className="w-5 h-5 text-gray-400" />
+                )}
+              </div>
+
+              <div className="flex-grow">
+                <div className="flex items-center space-x-2">
+                  <Folder className="w-5 h-5 text-purple-600" />
+                  <h4 className="font-semibold text-gray-800">
+                    {project.name}
+                    {isRoot && <span className="text-xs ml-2 text-purple-600">(Root)</span>}
+                  </h4>
+                </div>
+
+                <p className="text-sm text-gray-600 mt-1">
+                  <span className="font-medium">Path:</span> {project.path}
+                </p>
+
+                <p className="text-sm text-gray-600">
+                  <span className="font-medium">Type:</span> {projectTypes}
+                </p>
+
+                <div className="flex space-x-4 text-xs text-gray-500 mt-2">
+                  <span>{project.file_count} files</span>
+                  <span>{project.dir_count} directories</span>
+                </div>
+
+                {project.indicators && project.indicators.length > 0 && (
+                  <div className="mt-2">
+                    <div className="flex flex-wrap gap-1">
+                      {project.indicators.map((indicator, i) => (
+                        <span
+                          key={i}
+                          className="px-2 py-0.5 bg-purple-100 text-purple-700 text-xs rounded"
+                        >
+                          {indicator}
+                        </span>
+                      ))}
+                    </div>
+                  </div>
+                )}
+              </div>
+            </div>
+          )
+        })
+        )}
+      </div>
+
+      {/* Skipped Folders Section */}
+      {skippedFolders && skippedFolders.length > 0 && (
+        <div className="mb-6 p-4 bg-gray-50 rounded-lg border border-gray-200">
+          <h4 className="text-sm font-semibold text-gray-700 mb-2">
+             Skipped Folders ({skippedFolders.length})
+          </h4>
+          <p className="text-xs text-gray-600 mb-3">
+            The following folders were not detected as code projects:
+          </p>
+          <ul className="space-y-1">
+            {skippedFolders.map((folder, idx) => (
+              <li key={idx} className="text-sm text-gray-700">
+                • <span className="font-medium">{folder.name}</span> - {folder.reason} <span className="text-gray-500">({folder.details})</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      <div className="flex items-center justify-between pt-4 border-t border-gray-200">
+        <p className="text-sm text-gray-600">
+          {selectedPaths.length} project{selectedPaths.length !== 1 ? 's' : ''} selected
+        </p>
+
+        <button
+          onClick={handleSubmit}
+          disabled={submitting || selectedPaths.length === 0}
+          className="flex items-center space-x-2 px-6 py-3 bg-gradient-to-r from-purple-600 to-blue-600 text-white rounded-lg font-medium hover:from-purple-700 hover:to-blue-700 transition-all disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {submitting ? (
+            <>
+              <Loader2 className="w-5 h-5 animate-spin" />
+              <span>Processing...</span>
+            </>
+          ) : (
+            <>
+              <Play className="w-5 h-5" />
+              <span>Generate Documentation</span>
+            </>
+          )}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+export default ProjectSelector
diff --git a/DocuGenMicroagents/ui/src/components/ResultsViewer.jsx b/DocuGenMicroagents/ui/src/components/ResultsViewer.jsx
new file mode 100644
index 0000000000..f6629bbbf6
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/components/ResultsViewer.jsx
@@ -0,0 +1,290 @@
+import { useState, useEffect } from 'react'
+import { Download, Copy, Check, FileText, Loader2, AlertCircle, GitPullRequest, ExternalLink } from 'lucide-react'
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+import rehypeHighlight from 'rehype-highlight'
+import Mermaid from 'react-mermaid2'
+import { api } from '../services/api'
+
+// Import GitHub markdown CSS and syntax highlighting theme
+import 'github-markdown-css/github-markdown.css'
+import 'highlight.js/styles/github.css'
+
+function ResultsViewer({ readme, onReadmeGenerated, currentJob, workflowStatus }) {
+  const [copied, setCopied] = useState(false)
+  const [markdownContent, setMarkdownContent] = useState(null)
+  const [projectTitle, setProjectTitle] = useState(null)
+  const [creatingPR, setCreatingPR] = useState(false)
+  const [prUrl, setPrUrl] = useState(null)
+  const [prError, setPrError] = useState(null)
+
+  // Helper function to convert title to proper case
+  const toTitleCase = (str) => {
+    return str
+      .split(/[-_\s]+/)
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join(' ')
+  }
+
+  // Extract project title from markdown content
+  useEffect(() => {
+    if (markdownContent) {
+      const lines = markdownContent.split('\n')
+      // Look for H2 (## Title) in first 15 lines
+      for (let i = 0; i < Math.min(15, lines.length); i++) {
+        const line = lines[i].trim()
+        if (line.startsWith('## ')) {
+          const title = line.substring(3).trim()
+          setProjectTitle(toTitleCase(title))
+          break
+        } else if (line.startsWith('# ') && !line.startsWith('## ')) {
+          const title = line.substring(2).trim()
+          setProjectTitle(toTitleCase(title))
+          break
+        }
+      }
+    }
+  }, [markdownContent])
+
+  // Fetch final README when workflow completes
+  useEffect(() => {
+    console.log('[ResultsViewer] useEffect triggered:', { workflowStatus, currentJob, hasMarkdown: !!markdownContent })
+    if (workflowStatus === 'completed' && currentJob && !markdownContent) {
+      console.log('[ResultsViewer] Conditions met - starting fetch')
+      const fetchReadme = async () => {
+        try {
+          console.log('Fetching job status for:', currentJob)
+          const jobStatus = await api.getJobStatus(currentJob)
+          console.log('Job status:', jobStatus)
+
+          // Check if README is ready in job storage
+          if (jobStatus.readme_preview || jobStatus.status === 'completed') {
+            // Try to download the full README
+            try {
+              const readmeBlob = await api.downloadReadme(currentJob)
+              const readmeText = await readmeBlob.text()
+              console.log('Downloaded README:', readmeText.substring(0, 100))
+              setMarkdownContent(readmeText)
+              if (onReadmeGenerated) {
+                onReadmeGenerated(readmeText)
+              }
+            } catch (err) {
+              console.warn('Could not download README, using preview:', err)
+              // Fallback to preview if download fails
+              if (jobStatus.readme_preview) {
+                setMarkdownContent(jobStatus.readme_preview)
+                if (onReadmeGenerated) {
+                  onReadmeGenerated(jobStatus.readme_preview)
+                }
+              }
+            }
+          }
+        } catch (error) {
+          console.error('Failed to fetch README:', error)
+        }
+      }
+
+      // Small delay to let backend finish processing
+      const timer = setTimeout(fetchReadme, 1000)
+      return () => clearTimeout(timer)
+    }
+  }, [workflowStatus, currentJob, markdownContent])
+
+  const handleCopy = async () => {
+    if (markdownContent) {
+      await navigator.clipboard.writeText(markdownContent)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    }
+  }
+
+  const handleDownload = () => {
+    if (markdownContent) {
+      const blob = new Blob([markdownContent], { type: 'text/markdown' })
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement('a')
+      a.href = url
+      a.download = 'README.md'
+      document.body.appendChild(a)
+      a.click()
+      document.body.removeChild(a)
+      URL.revokeObjectURL(url)
+    }
+  }
+
+  const handleCreatePR = async () => {
+    if (!currentJob) return
+
+    setCreatingPR(true)
+    setPrError(null)
+
+    try {
+      const result = await api.createPullRequest(currentJob)
+
+      if (result.status === 'success') {
+        setPrUrl(result.pr_url)
+        console.log('PR created successfully:', result.pr_url)
+      } else {
+        setPrError(result.message || 'Failed to create PR')
+      }
+    } catch (error) {
+      console.error('Failed to create PR:', error)
+      setPrError(error.response?.data?.detail || error.message || 'Failed to create pull request')
+    } finally {
+      setCreatingPR(false)
+    }
+  }
+
+  // Only render the component when README is completed and ready
+  if (workflowStatus !== 'completed' || !markdownContent) {
+    return null
+  }
+
+  return (
+    <div className="bg-white rounded-xl shadow-lg p-6 border border-gray-200 flex flex-col">
+      {/* Header */}
+      <div className="flex items-center justify-between mb-6">
+        <div className="flex items-center space-x-3">
+          <FileText className="w-6 h-6 text-purple-600" />
+          <div>
+            <h2 className="text-2xl font-bold text-gray-800">README</h2>
+            {projectTitle && (
+              <p className="text-sm text-gray-600 mt-0.5">{projectTitle}</p>
+            )}
+          </div>
+        </div>
+
+        <div className="flex space-x-2">
+          <button
+            onClick={handleCopy}
+            className="p-2 hover:bg-gray-100 rounded-lg transition-colors"
+            title="Copy to clipboard"
+          >
+            {copied ? (
+              <Check className="w-5 h-5 text-green-500" />
+            ) : (
+              <Copy className="w-5 h-5 text-gray-600" />
+            )}
+          </button>
+          <button
+            onClick={handleDownload}
+            className="p-2 hover:bg-gray-100 rounded-lg transition-colors"
+            title="Download README.md"
+          >
+            <Download className="w-5 h-5 text-gray-600" />
+          </button>
+
+          {/* Create PR Button */}
+          {prUrl ? (
+            <a
+              href={prUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="flex items-center space-x-2 px-4 py-2 bg-green-600 text-white rounded-lg hover:bg-green-700 transition-colors"
+              title="View Pull Request"
+            >
+              <Check className="w-4 h-4" />
+              <span className="text-sm font-medium">View PR</span>
+              <ExternalLink className="w-4 h-4" />
+            </a>
+          ) : (
+            <button
+              onClick={handleCreatePR}
+              disabled={creatingPR}
+              className="flex items-center space-x-2 px-4 py-2 bg-purple-600 text-white rounded-lg hover:bg-purple-700 disabled:bg-purple-400 disabled:cursor-not-allowed transition-colors"
+              title="Create Pull Request on GitHub"
+            >
+              {creatingPR ? (
+                <>
+                  <Loader2 className="w-4 h-4 animate-spin" />
+                  <span className="text-sm font-medium">Creating PR...</span>
+                </>
+              ) : (
+                <>
+                  <GitPullRequest className="w-4 h-4" />
+                  <span className="text-sm font-medium">Create PR</span>
+                </>
+              )}
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Content */}
+      <div className="overflow-y-auto border border-gray-200 rounded-lg bg-white" style={{ maxHeight: '70vh' }}>
+        {/* Markdown Content with GitHub styling */}
+        <div className="markdown-body" style={{ backgroundColor: 'white', padding: '24px' }}>
+          <ReactMarkdown
+            remarkPlugins={[remarkGfm]}
+            rehypePlugins={[rehypeHighlight]}
+            components={{
+              code({ node, inline, className, children, ...props }) {
+                const match = /language-(\w+)/.exec(className || '')
+                const language = match ? match[1] : null
+
+                // Render Mermaid diagrams
+                if (!inline && language === 'mermaid') {
+                  return (
+                    <div className="my-4 bg-white p-4 rounded-lg border border-gray-300 flex items-center justify-center">
+                      <Mermaid chart={String(children).replace(/\n$/, '')} />
+                    </div>
+                  )
+                }
+
+                // Regular code blocks
+                return (
+                  <code className={className} {...props}>
+                    {children}
+                  </code>
+                )
+              }
+            }}
+          >
+            {markdownContent}
+          </ReactMarkdown>
+        </div>
+      </div>
+
+      {/* Footer Info */}
+      {markdownContent && (
+        <div className="mt-4 pt-4 border-t border-gray-200">
+          <div className="flex items-center justify-between text-sm text-gray-600">
+            <span>
+              Lines: <span className="font-semibold">{markdownContent.split('\n').length}</span>
+            </span>
+            <span>
+              Characters: <span className="font-semibold">{markdownContent.length}</span>
+            </span>
+            <span>
+              Words: <span className="font-semibold">{markdownContent.split(/\s+/).length}</span>
+            </span>
+          </div>
+        </div>
+      )}
+
+      {/* PR Error Display */}
+      {prError && (
+        <div className="mt-4 p-4 bg-red-50 border border-red-200 rounded-lg flex items-start space-x-3">
+          <AlertCircle className="w-5 h-5 text-red-600 flex-shrink-0 mt-0.5" />
+          <div className="flex-1">
+            <h3 className="text-sm font-semibold text-red-800">Failed to Create Pull Request</h3>
+            <p className="text-sm text-red-700 mt-1">{prError}</p>
+            {prError.includes('GITHUB_TOKEN') && (
+              <p className="text-xs text-red-600 mt-2">
+                Make sure GITHUB_TOKEN is configured in your backend environment variables.
+              </p>
+            )}
+          </div>
+          <button
+            onClick={() => setPrError(null)}
+            className="text-red-400 hover:text-red-600"
+          >
+            ×
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default ResultsViewer
diff --git a/DocuGenMicroagents/ui/src/images/UI_2.png b/DocuGenMicroagents/ui/src/images/UI_2.png
new file mode 100644
index 0000000000..c519526f30
Binary files /dev/null and b/DocuGenMicroagents/ui/src/images/UI_2.png differ
diff --git a/DocuGenMicroagents/ui/src/images/UI_4.png b/DocuGenMicroagents/ui/src/images/UI_4.png
new file mode 100644
index 0000000000..e095ef5c14
Binary files /dev/null and b/DocuGenMicroagents/ui/src/images/UI_4.png differ
diff --git a/DocuGenMicroagents/ui/src/images/UI_5_agent.png b/DocuGenMicroagents/ui/src/images/UI_5_agent.png
new file mode 100644
index 0000000000..3380c5b1c0
Binary files /dev/null and b/DocuGenMicroagents/ui/src/images/UI_5_agent.png differ
diff --git a/DocuGenMicroagents/ui/src/index.css b/DocuGenMicroagents/ui/src/index.css
new file mode 100644
index 0000000000..abd21268e2
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/index.css
@@ -0,0 +1,156 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+#root {
+  min-height: 100vh;
+}
+
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}
+
+/* GitHub Markdown Styling Overrides */
+.markdown-body {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 100%;
+  margin: 0;
+  padding: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', sans-serif;
+  font-size: 16px;
+  line-height: 1.6;
+  color: #24292f !important; /* Force dark text */
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+}
+
+/* Ensure all headings are visible */
+.markdown-body h1,
+.markdown-body h2,
+.markdown-body h3,
+.markdown-body h4,
+.markdown-body h5,
+.markdown-body h6 {
+  color: #24292f !important;
+  font-weight: 600 !important;
+  margin-top: 24px !important;
+  margin-bottom: 16px !important;
+}
+
+/* Ensure paragraphs and lists are visible */
+.markdown-body p,
+.markdown-body li,
+.markdown-body span,
+.markdown-body div {
+  color: #24292f !important;
+  max-width: 100%;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+}
+
+/* Prevent list overflow */
+.markdown-body ul,
+.markdown-body ol {
+  max-width: 100%;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+  padding-left: 2em;
+}
+
+/* Links */
+.markdown-body a {
+  color: #0969da !important;
+  text-decoration: none;
+}
+
+.markdown-body a:hover {
+  text-decoration: underline;
+}
+
+/* Syntax highlighting for code blocks */
+.markdown-body pre {
+  background-color: #f6f8fa !important;
+  padding: 16px !important;
+  border-radius: 6px !important;
+  overflow-x: auto !important;
+  margin: 16px 0 !important;
+  max-width: 100%;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+.markdown-body pre code {
+  background-color: transparent !important;
+  padding: 0 !important;
+  color: #24292f !important;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+/* Inline code */
+.markdown-body code {
+  background-color: rgba(175, 184, 193, 0.2) !important;
+  padding: 0.2em 0.4em !important;
+  border-radius: 6px !important;
+  font-family: 'SFMono-Regular', 'Consolas', 'Liberation Mono', 'Menlo', monospace !important;
+  font-size: 85% !important;
+  color: #24292f !important;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+}
+
+/* Blockquotes */
+.markdown-body blockquote {
+  padding: 0 1em !important;
+  color: #57606a !important;
+  border-left: 0.25em solid #d0d7de !important;
+  margin: 16px 0 !important;
+}
+
+/* Tables */
+.markdown-body table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 16px 0;
+}
+
+.markdown-body th,
+.markdown-body td {
+  padding: 6px 13px;
+  border: 1px solid #d0d7de;
+  color: #24292f !important;
+}
+
+.markdown-body th {
+  background-color: #f6f8fa;
+  font-weight: 600;
+}
+
+/* Horizontal rule */
+.markdown-body hr {
+  height: 0.25em;
+  padding: 0;
+  margin: 24px 0;
+  background-color: #d0d7de;
+  border: 0;
+}
+
+/* Task lists */
+.markdown-body input[type="checkbox"] {
+  margin-right: 0.5em;
+}
diff --git a/DocuGenMicroagents/ui/src/main.jsx b/DocuGenMicroagents/ui/src/main.jsx
new file mode 100644
index 0000000000..54b39dd1d9
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/main.jsx
@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
diff --git a/DocuGenMicroagents/ui/src/services/api.js b/DocuGenMicroagents/ui/src/services/api.js
new file mode 100644
index 0000000000..a339f53afc
--- /dev/null
+++ b/DocuGenMicroagents/ui/src/services/api.js
@@ -0,0 +1,112 @@
+import axios from 'axios'
+
+// Use environment variable or default to /api for production (nginx proxy)
+// In development: http://localhost:5001/api
+// In production Docker: /api (proxied by nginx)
+const API_BASE_URL = import.meta.env.VITE_API_URL || '/api'
+
+export const api = {
+  /**
+   * Start documentation generation workflow
+   * @param {string} repoUrl - GitHub repository URL
+   * @returns {Promise<{job_id: string, status: string}>}
+   */
+  generateDocs: async (repoUrl) => {
+    const response = await axios.post(`${API_BASE_URL}/generate-docs`, {
+      repo_url: repoUrl
+    })
+    return response.data
+  },
+
+  /**
+   * Get job status
+   * @param {string} jobId - Job ID
+   * @returns {Promise<object>}
+   */
+  getJobStatus: async (jobId) => {
+    const response = await axios.get(`${API_BASE_URL}/status/${jobId}`)
+    return response.data
+  },
+
+  /**
+   * Connect to SSE stream for real-time logs
+   * @param {string} jobId - Job ID
+   * @param {function} onMessage - Callback for log messages
+   * @param {function} onError - Callback for errors
+   * @returns {EventSource} SSE connection
+   */
+  connectToLogs: (jobId, onMessage, onError) => {
+    const eventSource = new EventSource(`${API_BASE_URL}/logs/${jobId}`)
+
+    eventSource.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data)
+        onMessage(data)
+      } catch (error) {
+        console.error('Failed to parse SSE message:', error)
+      }
+    }
+
+    eventSource.onerror = (error) => {
+      console.error('SSE connection error:', error)
+      if (onError) onError(error)
+      eventSource.close()
+    }
+
+    return eventSource
+  },
+
+  /**
+   * Approve agent output and continue workflow
+   * @param {string} jobId - Job ID
+   */
+  approveStep: async (jobId) => {
+    const response = await axios.post(`${API_BASE_URL}/approve/${jobId}`)
+    return response.data
+  },
+
+  /**
+   * Reject agent output and retry with feedback
+   * @param {string} jobId - Job ID
+   * @param {string} feedback - Feedback for retry
+   */
+  rejectStep: async (jobId, feedback) => {
+    const response = await axios.post(`${API_BASE_URL}/reject/${jobId}`, {
+      feedback
+    })
+    return response.data
+  },
+
+  /**
+   * Download generated README
+   * @param {string} jobId - Job ID
+   */
+  downloadReadme: async (jobId) => {
+    const response = await axios.get(`${API_BASE_URL}/download/${jobId}`, {
+      responseType: 'blob'
+    })
+    return response.data
+  },
+
+  /**
+   * Submit project selection
+   * @param {string} jobId - Job ID
+   * @param {string[]} selectedProjectPaths - Array of selected project paths
+   */
+  selectProjects: async (jobId, selectedProjectPaths) => {
+    const response = await axios.post(`${API_BASE_URL}/select-projects/${jobId}`, {
+      selected_project_paths: selectedProjectPaths
+    })
+    return response.data
+  },
+
+  /**
+   * Create GitHub Pull Request with generated README
+   * @param {string} jobId - Job ID
+   * @returns {Promise<{status: string, message: string, pr_url?: string}>}
+   */
+  createPullRequest: async (jobId) => {
+    const response = await axios.post(`${API_BASE_URL}/create-pr/${jobId}`)
+    return response.data
+  }
+}
diff --git a/DocuGenMicroagents/ui/tailwind.config.js b/DocuGenMicroagents/ui/tailwind.config.js
new file mode 100644
index 0000000000..dca8ba02d3
--- /dev/null
+++ b/DocuGenMicroagents/ui/tailwind.config.js
@@ -0,0 +1,11 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
diff --git a/DocuGenMicroagents/ui/vite.config.js b/DocuGenMicroagents/ui/vite.config.js
new file mode 100644
index 0000000000..a36a5e79a0
--- /dev/null
+++ b/DocuGenMicroagents/ui/vite.config.js
@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: true,
+    port: 3000,
+    proxy: {
+      '/api': {
+        // Use 'backend' hostname in Docker, 'localhost' when running locally
+        target: process.env.VITE_API_TARGET || 'http://localhost:5001',
+        changeOrigin: true
+      }
+    }
+  }
+})
diff --git a/MultiAgentQnA/.gitignore b/MultiAgentQnA/.gitignore
new file mode 100644
index 0000000000..729e5b1860
--- /dev/null
+++ b/MultiAgentQnA/.gitignore
@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.log
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+dist/
+.cache/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build
+build/
+*.so
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+
diff --git a/MultiAgentQnA/QUICKSTART.md b/MultiAgentQnA/QUICKSTART.md
new file mode 100644
index 0000000000..4270bce82c
--- /dev/null
+++ b/MultiAgentQnA/QUICKSTART.md
@@ -0,0 +1,201 @@
+# Quick Start Guide
+
+Get up and running with the Multi-Agent Q&A application in 5 minutes!
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Valid enterprise-inference API credentials
+
+## Step-by-Step Setup
+
+### 1. Configure Environment Variables
+
+Create the API environment file:
+
+```bash
+cd multiagent-qna
+cp api/env.example api/.env
+```
+
+Edit `api/.env` with your credentials:
+
+```env
+BASE_URL=https://your-enterprise-inference-url.com
+KEYCLOAK_CLIENT_ID=your_client_id
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+```
+
+### 2. Start with Docker Compose
+
+```bash
+cd multiagent-qna
+docker-compose up --build
+```
+
+Wait for both services to start:
+- Backend API on http://localhost:5001
+- Frontend UI on http://localhost:3000
+
+### 3. Access the Application
+
+Open your browser and navigate to:
+
+```
+http://localhost:3000
+```
+
+You should see the Multi-Agent Q&A interface!
+
+## Alternative: Local Development
+
+### Backend
+
+```bash
+cd multiagent-qna/api
+
+# Create virtual environment (recommended)
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the server
+uvicorn server:app --reload --host 0.0.0.0 --port 5001
+```
+
+### Frontend
+
+```bash
+cd multiagent-qna/ui
+
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+```
+
+## Testing the Application
+
+### Test the Chat Interface
+
+1. Navigate to the Chat page
+2. Type a question, for example:
+   - **Code**: "How do I create a Python function?"
+   - **RAG**: "Find information about machine learning"
+   - **General**: "What is the weather like?"
+
+3. The system will automatically route your question to the appropriate agent
+
+### Test the Settings
+
+1. Click on "Settings" in the header
+2. Modify agent configurations:
+   - Change roles, goals, or backstories
+   - Adjust max iterations
+   - Toggle verbose mode
+3. Click "Save Configuration"
+4. Test with new questions
+
+## Verify Everything Works
+
+### Check API Health
+
+```bash
+curl http://localhost:5001/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "api_configured": true
+}
+```
+
+### Test Chat Endpoint
+
+```bash
+curl -X POST http://localhost:5001/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello!"}'
+```
+
+Expected response:
+```json
+{
+  "response": "Response from agent...",
+  "agent": "normal_agent"
+}
+```
+
+## Common First-Time Issues
+
+### Port Already in Use
+
+**Error**: `Address already in use`
+
+**Solution**:
+```bash
+# Find and kill process on port 5001
+lsof -ti:5001 | xargs kill -9
+
+# Find and kill process on port 3000
+lsof -ti:3000 | xargs kill -9
+
+# Or change ports in docker-compose.yml
+```
+
+### Cannot Connect to Enterprise API
+
+**Error**: `Authentication failed`
+
+**Solution**:
+1. Double-check your `.env` credentials
+2. Verify BASE_URL is correct
+3. Ensure network access to enterprise-inference API
+
+### UI Shows "Failed to get response"
+
+**Solution**:
+1. Check backend logs: `docker logs multiagent-qna-backend`
+2. Verify API is running: `curl http://localhost:5001/health`
+3. Check browser console for errors
+
+## Next Steps
+
+- Read the [README.md](README.md) for detailed documentation
+- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for more help
+- Customize agent configurations in the Settings page
+- Integrate with your own knowledge bases or APIs
+
+## Architecture Overview
+
+```
+User Query
+    ↓
+Orchestration Agent (routes to appropriate specialist)
+    ↓
+┌─────────────────────────────────────────┐
+│                                         │
+├─ Code Agent ─── For programming Q&A     │
+├─ RAG Agent ──── For document retrieval  │
+└─ Normal Agent ── For general questions  │
+```
+
+The system automatically detects query type and routes to the best agent!
+
+## Need Help?
+
+- Check logs: `docker logs multiagent-qna-backend`
+- Review [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+- Verify environment variables are set correctly
+
+Happy chatting! 🚀
+
diff --git a/MultiAgentQnA/README.md b/MultiAgentQnA/README.md
new file mode 100644
index 0000000000..f65a4cb5f4
--- /dev/null
+++ b/MultiAgentQnA/README.md
@@ -0,0 +1,251 @@
+## Multi-Agent Q&A Application
+
+A sophisticated multi-agent Q&A application featuring intelligent task delegation to specialized agents with enterprise inference integration.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick Start Deployment](#quick-start-deployment)
+- [User Interface](#user-interface)
+- [Troubleshooting](#troubleshooting)
+
+---
+## Project Overview
+
+The multiagent-qna project is a sophisticated Question & Answer application built on a multi-agent architecture. Its core function is to receive a user's query, intelligently determine the nature of the question, and delegate it to the most suitable specialized agent for generating a high-quality response. The system is designed for enterprise environments, integrating with enterprise-grade inference APIs for its language model interactions.
+
+---
+
+## Features
+
+- **Multi-Agent Architecture**: Orchestration agent that intelligently routes queries to specialized agents
+- **Specialized Agents**:
+  - **Code Agent**: Handles code-related questions and programming queries
+  - **RAG Agent**: Retrieves and answers questions from documents
+  - **Normal Agent**: Handles general questions and conversations
+- **Modern UI**: ChatGPT-like interface with settings management
+- **Enterprise Integration**: Uses enterprise-inference API for LLM interactions
+- **Configurable**: Easily configure agent roles, goals, and behavior via UI
+
+---
+
+## Architecture
+
+Below is the multi-agent system architecture showing how user queries are intelligently routed to specialized agents. The orchestration layer analyzes incoming queries using keyword detection and delegates them to the appropriate agent (Code, RAG, or Normal) for processing, ensuring each query is handled by the most qualified specialist.
+
+```mermaid
+graph TD
+    A[User Interface] -->|Query| B[FastAPI Backend]
+    B --> C[Orchestration Logic]
+    C -->|Keyword Analysis| D{Agent Router}
+
+    D -->|Code Keywords| E[Code Agent]
+    D -->|RAG Keywords| F[RAG Agent]
+    D -->|Default| G[Normal Agent]
+
+    F -->|Search| H[FAISS Vector Store]
+    H -->|Context| F
+
+    E -->|Prompt + Role| I[LLM API]
+    F -->|Prompt + Role + Context| I
+    G -->|Prompt + Role| I
+
+    I -->|Response| B
+    B -->|Answer| A
+
+    J[Keycloak Auth] -.->|Token| I
+    K[PDF Upload] -->|Documents| H
+
+    style C fill:#e1f5ff
+    style D fill:#fff4e1
+    style E fill:#ffe1e1
+    style F fill:#e1ffe1
+    style G fill:#f0e1ff
+    style I fill:#ffebe1
+```
+
+The application consists of:
+1. **Orchestration Agent**: Analyzes user queries and delegates to appropriate specialized agents
+2. **Specialized Agents**: Each handles a specific domain (code, RAG, general)
+3. **API Layer**: FastAPI backend with enterprise-inference integration
+4. **UI**: React-based chat interface with settings management
+
+**Service Components:**
+
+1. **React Web UI (Port 3000)** -  Provides ChatGPT-like interface with settings management for configuring agent roles, goals, and behavior
+
+2. **FastAPI Backend (Port 5001)** - Orchestrates multi-agent system, analyzes queries using keyword detection, delegates to specialized agents (Code, RAG, Normal), and manages FAISS vector store for document retrieval
+
+**Typical Flow:**
+
+1. User submits a query through the chat interface.
+2. The FastAPI backend receives the query and passes it to the orchestration logic.
+3. The orchestration logic analyzes the query using keyword detection to determine intent.
+4. The agent router delegates the query to the appropriate specialized agent:
+   - **Code-related queries** (keywords: code, function, debug, etc.) → Code Agent
+   - **Document-based queries** (keywords: document, PDF, search, etc.) → RAG Agent
+   - **General queries** → Normal Agent
+5. If RAG Agent is selected:
+   - Searches the FAISS vector store for relevant document context
+   - Retrieves matching chunks to augment the prompt
+6. The selected agent constructs a specialized prompt with its role, goal, and context.
+7. The system authenticates with Keycloak and obtains an access token.
+8. The agent calls the enterprise LLM API with the token and specialized prompt.
+9. The LLM (Llama-3.1-8B-Instruct) generates a response tailored to the agent's expertise.
+10. The response is returned to the user via the UI with agent attribution showing which specialist handled the query.
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+Before you begin, ensure you have the following installed:
+
+- **Docker and Docker Compose**
+- **Enterprise inference endpoint access** (Keycloak authentication)
+
+### Verify Docker Installation
+
+```bash
+# Check Docker version
+docker --version
+
+# Check Docker Compose version
+docker compose version
+
+# Verify Docker is running
+docker ps
+```
+---
+
+## Quick Start Deployment
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/opea-project/GenAIExamples.git
+cd GenAIExamples/MultiAgentQnA
+```
+
+### Set up the Environment
+
+This application requires an `.env` file in the `api` directory for proper configuration. Create it with the commands below:
+
+```bash
+# Create the .env file in the api directory
+mkdir -p api
+cat > api/.env << EOF
+BASE_URL=https://your-enterprise-inference-url.com
+KEYCLOAK_CLIENT_ID=your_client_id
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+EOF
+```
+
+Or manually create `api/.env` with:
+
+```bash
+BASE_URL=https://your-enterprise-inference-url.com
+KEYCLOAK_CLIENT_ID=your_client_id
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+```
+
+**Note**: The docker-compose.yml file automatically loads environment variables from `./api/.env` for the backend service.
+
+### Running the Application
+
+Start both API and UI services together with Docker Compose:
+
+```bash
+# From the MultiAgentQnA directory
+docker compose up --build
+
+# Or run in detached mode (background)
+docker compose up -d --build
+```
+
+The API will be available at: `http://localhost:5001`  
+The UI will be available at: `http://localhost:3000`
+
+**View logs**:
+
+```bash
+# All services
+docker compose logs -f
+
+# Backend only
+docker compose logs -f backend
+
+# Frontend only
+docker compose logs -f frontend
+```
+
+**Verify the services are running**:
+
+```bash
+# Check API health
+curl http://localhost:5001/health
+
+# Check if containers are running
+docker compose ps
+```
+---
+
+## User Interface
+
+**Using the Application**
+
+Make sure you are at the localhost:3000 url
+
+You will be directed to the main page which has each feature
+
+![User Interface](images/ui.png)
+
+### Chat Interface
+
+1. Navigate to the chat interface
+2. Type your question in the input box
+3. The orchestration agent will analyze your query and route it to the appropriate specialized agent
+4. View the response with agent attribution
+
+### Settings Page
+
+Configure agents:
+- **Orchestration Agent**: Role, goal, and backstory
+- **Code Agent**: Code-specific configuration
+- **RAG Agent**: Document retrieval settings
+- **Normal Agent**: General conversation settings
+
+**UI Configuration**
+
+When running with Docker Compose, the UI automatically connects to the backend API. The frontend is available at `http://localhost:3000` and the API at `http://localhost:5001`.
+
+For production deployments, you may want to configure a reverse proxy or update the API URL in the frontend configuration.
+
+### Stopping the Application
+
+
+```bash
+docker compose down
+```
+
+---
+
+## Troubleshooting
+
+For comprehensive troubleshooting guidance, common issues, and solutions, refer to:
+
+[TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+
+
diff --git a/MultiAgentQnA/TROUBLESHOOTING.md b/MultiAgentQnA/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..2d6500321d
--- /dev/null
+++ b/MultiAgentQnA/TROUBLESHOOTING.md
@@ -0,0 +1,289 @@
+# Troubleshooting Guide
+
+This document addresses common issues you may encounter when running the Multi-Agent Q&A application.
+
+## Table of Contents
+
+1. [Environment Setup](#environment-setup)
+2. [API Issues](#api-issues)
+3. [UI Issues](#ui-issues)
+4. [Agent Issues](#agent-issues)
+5. [Docker Issues](#docker-issues)
+
+---
+
+## Environment Setup
+
+### Issue: Missing environment variables
+
+**Symptoms:**
+- API fails to start
+- Authentication errors
+- "Configuration error" messages
+
+**Solution:**
+1. Ensure you have created `api/.env` file based on `api/env.example`
+2. Verify all required variables are set:
+   ```bash
+   BASE_URL=https://your-api-url.com
+   KEYCLOAK_CLIENT_ID=your_client_id
+   KEYCLOAK_CLIENT_SECRET=your_client_secret
+   ```
+3. Check that the `.env` file is in the `api/` directory
+
+### Issue: Python dependencies not installing
+
+**Symptoms:**
+- Import errors
+- "Module not found" errors
+
+**Solution:**
+```bash
+cd api
+pip install -r requirements.txt
+```
+
+---
+
+## API Issues
+
+### Issue: Authentication fails
+
+**Symptoms:**
+- "Authentication failed" errors
+- 401 Unauthorized responses
+
+**Solution:**
+1. Verify your `KEYCLOAK_CLIENT_SECRET` is correct
+2. Check that `BASE_URL` points to the correct endpoint
+3. Ensure network connectivity to the enterprise-inference API
+4. Verify SSL certificate issues by checking if `verify=False` is needed in api_client.py
+
+### Issue: API returns empty responses
+
+**Symptoms:**
+- No content in chat responses
+- "Unexpected response structure" errors
+
+**Solution:**
+1. Check the model endpoints in `.env`:
+   ```bash
+   EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+   INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+   ```
+2. Verify the inference API is returning valid responses
+3. Check API logs for detailed error messages
+
+### Issue: API is slow to respond
+
+**Symptoms:**
+- Long wait times for responses
+- Timeout errors
+
+**Solution:**
+1. Reduce `max_tokens` in agent configurations
+2. Set `max_iter` to a lower value (e.g., 5-10 instead of 15)
+3. Check network latency to enterprise-inference API
+
+---
+
+## UI Issues
+
+### Issue: Cannot connect to API
+
+**Symptoms:**
+- "Failed to get response" errors
+- Network errors in browser console
+
+**Solution:**
+1. Verify backend is running on port 5001:
+   ```bash
+   curl http://localhost:5001/health
+   ```
+2. Check Vite proxy configuration in `ui/vite.config.js`
+3. Ensure CORS is properly configured in `api/server.py`
+
+### Issue: Page doesn't load
+
+**Symptoms:**
+- Blank page
+- JavaScript errors in console
+
+**Solution:**
+1. Install dependencies:
+   ```bash
+   cd ui
+   npm install
+   ```
+2. Clear browser cache and reload
+3. Check for console errors in browser DevTools
+
+---
+
+## Agent Issues
+
+### Issue: Wrong agent is selected
+
+**Symptoms:**
+- Code questions routed to general agent
+- RAG questions not using retrieval
+
+**Solution:**
+1. The routing is based on keyword detection in `agents.py`
+2. Review `determine_agent_type()` function
+3. Add custom keywords to improve routing accuracy
+
+### Issue: Agent configuration not saved
+
+**Symptoms:**
+- Settings revert after saving
+- Default configuration persists
+
+**Solution:**
+1. Check browser console for API errors
+2. Verify `/config` POST endpoint is working:
+   ```bash
+   curl -X POST http://localhost:5001/config \
+     -H "Content-Type: application/json" \
+     -d '{"orchestration": {"role": "Test"}}'
+   ```
+
+---
+
+## Docker Issues
+
+### Issue: Containers won't start
+
+**Symptoms:**
+- `docker-compose up` fails
+- Port already in use errors
+
+**Solution:**
+1. Stop existing containers:
+   ```bash
+   docker-compose down
+   ```
+2. Check for port conflicts:
+   ```bash
+   # Check if ports are in use
+   lsof -i :5001  # API
+   lsof -i :3000  # UI
+   ```
+3. Rebuild containers:
+   ```bash
+   docker-compose up --build
+   ```
+
+### Issue: Environment variables not loading
+
+**Symptoms:**
+- Configuration defaults being used
+- Authentication errors in containers
+
+**Solution:**
+1. Ensure `.env` file exists in `api/` directory
+2. Check docker-compose.yml references the env_file correctly:
+   ```yaml
+   env_file:
+     - ./api/.env
+   ```
+3. Restart containers after creating `.env`:
+   ```bash
+   docker-compose restart backend
+   ```
+
+### Issue: Volume mounting not working
+
+**Symptoms:**
+- Code changes not reflecting in containers
+- Hot reload not working
+
+**Solution:**
+1. Verify volume mounts in docker-compose.yml:
+   ```yaml
+   volumes:
+     - ./api:/app
+   ```
+2. Check file permissions
+3. Restart containers after configuration changes
+
+---
+
+## General Debugging Tips
+
+### Check Logs
+
+**Backend:**
+```bash
+# Docker
+docker logs multiagent-qna-backend
+
+# Local
+tail -f api/logs/app.log
+```
+
+**Frontend:**
+```bash
+# Docker
+docker logs multiagent-qna-frontend
+
+# Local - check browser DevTools console
+```
+
+### Test API Endpoints
+
+```bash
+# Health check
+curl http://localhost:5001/health
+
+# Configuration
+curl http://localhost:5001/config
+
+# Chat
+curl -X POST http://localhost:5001/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello!"}'
+```
+
+### Common Python Debugging
+
+```python
+# Add verbose logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Check agent configuration
+from services.agents import get_code_agent
+agent = get_code_agent()
+print(agent.role, agent.goal)
+```
+
+---
+
+## Performance Optimization
+
+1. **Reduce Token Usage:**
+   - Lower `max_tokens` in API calls
+   - Reduce `max_iter` for agents
+   - Use caching where possible
+
+2. **Optimize Agent Routing:**
+   - Fine-tune keyword detection
+   - Consider using more sophisticated classification
+
+3. **Batch Processing:**
+   - Process multiple queries in parallel
+   - Use connection pooling for API calls
+
+---
+
+## Still Having Issues?
+
+1. Check the [README.md](README.md) for setup instructions
+2. Review error logs in detail
+3. Verify all prerequisites are met
+4. Ensure network connectivity to enterprise-inference API
+5. Test API endpoints independently
+
+For additional help, please check the project documentation or contact support.
+
diff --git a/MultiAgentQnA/api/Dockerfile b/MultiAgentQnA/api/Dockerfile
new file mode 100644
index 0000000000..e957a3ba75
--- /dev/null
+++ b/MultiAgentQnA/api/Dockerfile
@@ -0,0 +1,20 @@
+FROM python:3.10-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy requirements file
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application files into the container
+COPY . .
+
+# Expose the port the service runs on
+EXPOSE 5001
+
+# Command to run the application
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "5001", "--reload"]
+
diff --git a/MultiAgentQnA/api/__init__.py b/MultiAgentQnA/api/__init__.py
new file mode 100644
index 0000000000..25f9058b60
--- /dev/null
+++ b/MultiAgentQnA/api/__init__.py
@@ -0,0 +1,4 @@
+"""
+Multi-Agent Q&A API
+"""
+
diff --git a/MultiAgentQnA/api/config.py b/MultiAgentQnA/api/config.py
new file mode 100644
index 0000000000..d7153c25d2
--- /dev/null
+++ b/MultiAgentQnA/api/config.py
@@ -0,0 +1,40 @@
+"""
+Configuration settings for Multi-Agent Q&A API
+"""
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# API Configuration
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+
+# Custom API Configuration
+BASE_URL = os.getenv("BASE_URL", "https://api.example.com")
+KEYCLOAK_REALM = os.getenv("KEYCLOAK_REALM", "master")
+KEYCLOAK_CLIENT_ID = os.getenv("KEYCLOAK_CLIENT_ID", "api")
+KEYCLOAK_CLIENT_SECRET = os.getenv("KEYCLOAK_CLIENT_SECRET")
+
+# Model Configuration
+EMBEDDING_MODEL_ENDPOINT = os.getenv("EMBEDDING_MODEL_ENDPOINT", "bge-base-en-v1.5")
+INFERENCE_MODEL_ENDPOINT = os.getenv("INFERENCE_MODEL_ENDPOINT", "Llama-3.1-8B-Instruct")
+EMBEDDING_MODEL_NAME = os.getenv("EMBEDDING_MODEL_NAME", "bge-base-en-v1.5")
+INFERENCE_MODEL_NAME = os.getenv("INFERENCE_MODEL_NAME", "meta-llama/Llama-3.1-8B-Instruct")
+
+# Validate required configuration
+if not OPENAI_API_KEY and not KEYCLOAK_CLIENT_SECRET:
+    raise ValueError("Either OPENAI_API_KEY or KEYCLOAK_CLIENT_SECRET must be set in environment variables")
+
+# Application Settings
+APP_TITLE = "Multi-Agent Q&A"
+APP_DESCRIPTION = "A multi-agent Q&A system using CrewAI"
+APP_VERSION = "1.0.0"
+
+# CORS Settings
+CORS_ALLOW_ORIGINS = ["*"]  # Update with specific origins in production
+CORS_ALLOW_CREDENTIALS = True
+CORS_ALLOW_METHODS = ["*"]
+CORS_ALLOW_HEADERS = ["*"]
+
diff --git a/MultiAgentQnA/api/env.example b/MultiAgentQnA/api/env.example
new file mode 100644
index 0000000000..c3630cfacf
--- /dev/null
+++ b/MultiAgentQnA/api/env.example
@@ -0,0 +1,15 @@
+# Enterprise Inference API Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_secret_here
+
+# Model Endpoints
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+
+# Optional: OpenAI API Key (alternative to enterprise-inference)
+# OPENAI_API_KEY=sk-...
+
diff --git a/MultiAgentQnA/api/models.py b/MultiAgentQnA/api/models.py
new file mode 100644
index 0000000000..94a7f3e69c
--- /dev/null
+++ b/MultiAgentQnA/api/models.py
@@ -0,0 +1,70 @@
+"""
+Pydantic models for request/response validation
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, Any
+
+
+class ChatMessage(BaseModel):
+    """Individual chat message"""
+    role: str = Field(..., description="Message role (user or assistant)")
+    content: str = Field(..., description="Message content")
+    agent: Optional[str] = Field(None, description="Agent that generated the response")
+
+
+class ChatRequest(BaseModel):
+    """Request model for chat messages"""
+    message: str = Field(..., min_length=1, description="User message")
+    agent_config: Optional[Dict[str, Any]] = Field(None, description="Optional agent configuration")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "message": "How do I implement a recursive function in Python?",
+                "agent_config": None
+            }
+        }
+
+
+class ChatResponse(BaseModel):
+    """Response model for chat messages"""
+    response: str = Field(..., description="Agent response")
+    agent: str = Field(..., description="Agent that generated the response")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "response": "A recursive function calls itself...",
+                "agent": "code_agent"
+            }
+        }
+
+
+class AgentConfig(BaseModel):
+    """Configuration for a single agent"""
+    role: str = Field(..., description="Agent role")
+    goal: str = Field(..., description="Agent goal")
+    backstory: str = Field(..., description="Agent backstory")
+    max_iter: Optional[int] = Field(15, description="Maximum iterations")
+    verbose: Optional[bool] = Field(True, description="Verbose output")
+
+
+class AgentConfigs(BaseModel):
+    """Configuration for all agents"""
+    orchestration: Optional[AgentConfig] = None
+    code: Optional[AgentConfig] = None
+    rag: Optional[AgentConfig] = None
+    normal: Optional[AgentConfig] = None
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check"""
+    status: str = Field(..., description="Health status")
+    api_configured: bool = Field(..., description="Whether API is configured")
+
+
+class ConfigResponse(BaseModel):
+    """Response model for configuration"""
+    config: Dict[str, Any] = Field(..., description="Current agent configuration")
+
diff --git a/MultiAgentQnA/api/rag_index/documents.pkl b/MultiAgentQnA/api/rag_index/documents.pkl
new file mode 100644
index 0000000000..f3cb9736fe
Binary files /dev/null and b/MultiAgentQnA/api/rag_index/documents.pkl differ
diff --git a/MultiAgentQnA/api/rag_index/index.faiss b/MultiAgentQnA/api/rag_index/index.faiss
new file mode 100644
index 0000000000..93684dd23d
Binary files /dev/null and b/MultiAgentQnA/api/rag_index/index.faiss differ
diff --git a/MultiAgentQnA/api/requirements.txt b/MultiAgentQnA/api/requirements.txt
new file mode 100644
index 0000000000..a040c46117
--- /dev/null
+++ b/MultiAgentQnA/api/requirements.txt
@@ -0,0 +1,14 @@
+fastapi>=0.109.0
+uvicorn[standard]>=0.27.0
+python-dotenv>=1.0.0
+openai>=1.10.0
+python-multipart>=0.0.6
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+cryptography>=3.1.0
+httpx>=0.24.0
+requests>=2.31.0
+pypdf>=3.17.0
+faiss-cpu>=1.7.4
+numpy>=1.24.0
+
diff --git a/MultiAgentQnA/api/server.py b/MultiAgentQnA/api/server.py
new file mode 100644
index 0000000000..0bfb7c34db
--- /dev/null
+++ b/MultiAgentQnA/api/server.py
@@ -0,0 +1,290 @@
+"""
+FastAPI server with routes for Multi-Agent Q&A API
+"""
+
+import logging
+import os
+import tempfile
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, HTTPException, status, UploadFile, File
+from fastapi.middleware.cors import CORSMiddleware
+
+import config
+from models import (
+    ChatRequest, ChatResponse, HealthResponse, 
+    AgentConfigs, ConfigResponse
+)
+from services import process_query, update_agent_configs
+from services.rag_service import get_rag_service
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# In-memory log store for agent activity
+agent_activity_logs = []
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context manager for FastAPI app"""
+    # Startup
+    logger.info("Initializing Multi-Agent Q&A API")
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down Multi-Agent Q&A API")
+
+
+# Initialize FastAPI app
+app = FastAPI(
+    title=config.APP_TITLE,
+    description=config.APP_DESCRIPTION,
+    version=config.APP_VERSION,
+    lifespan=lifespan
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.CORS_ALLOW_ORIGINS,
+    allow_credentials=config.CORS_ALLOW_CREDENTIALS,
+    allow_methods=config.CORS_ALLOW_METHODS,
+    allow_headers=config.CORS_ALLOW_HEADERS,
+)
+
+
+# ==================== Routes ====================
+
+@app.get("/")
+def root():
+    """Health check endpoint"""
+    return {
+        "message": "Multi-Agent Q&A API is running",
+        "version": config.APP_VERSION,
+        "status": "healthy"
+    }
+
+
+@app.get("/health", response_model=HealthResponse)
+def health_check():
+    """Detailed health check"""
+    api_configured = bool(config.KEYCLOAK_CLIENT_SECRET or config.OPENAI_API_KEY)
+    return HealthResponse(
+        status="healthy",
+        api_configured=api_configured
+    )
+
+
+@app.post("/chat", response_model=ChatResponse)
+def chat_endpoint(request: ChatRequest):
+    """
+    Process a chat message using the multi-agent system
+    
+    - **message**: User message/query
+    - **agent_config**: Optional agent configuration override
+    """
+    if not request.message or not request.message.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Message cannot be empty"
+        )
+    
+    try:
+        # Process the query with the appropriate agent
+        response, agent = process_query(
+            query=request.message,
+            agent_config=request.agent_config
+        )
+        
+        return ChatResponse(
+            response=response,
+            agent=agent
+        )
+        
+    except Exception as e:
+        logger.error(f"Error processing query: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing query: {str(e)}"
+        )
+
+
+@app.get("/config", response_model=ConfigResponse)
+def get_config():
+    """Get current agent configuration"""
+    from services.agents import (
+        DEFAULT_ORCHESTRATION_CONFIG,
+        DEFAULT_CODE_CONFIG,
+        DEFAULT_RAG_CONFIG,
+        DEFAULT_NORMAL_CONFIG
+    )
+    
+    return ConfigResponse(
+        config={
+            "orchestration": DEFAULT_ORCHESTRATION_CONFIG,
+            "code": DEFAULT_CODE_CONFIG,
+            "rag": DEFAULT_RAG_CONFIG,
+            "normal": DEFAULT_NORMAL_CONFIG
+        }
+    )
+
+
+@app.post("/config")
+def update_config(configs: AgentConfigs):
+    """Update agent configurations"""
+    try:
+        config_dict = {}
+        
+        if configs.orchestration:
+            config_dict["orchestration"] = {
+                "role": configs.orchestration.role,
+                "goal": configs.orchestration.goal,
+                "backstory": configs.orchestration.backstory,
+                "max_iter": configs.orchestration.max_iter,
+                "verbose": configs.orchestration.verbose
+            }
+        
+        if configs.code:
+            config_dict["code"] = {
+                "role": configs.code.role,
+                "goal": configs.code.goal,
+                "backstory": configs.code.backstory,
+                "max_iter": configs.code.max_iter,
+                "verbose": configs.code.verbose
+            }
+        
+        if configs.rag:
+            config_dict["rag"] = {
+                "role": configs.rag.role,
+                "goal": configs.rag.goal,
+                "backstory": configs.rag.backstory,
+                "max_iter": configs.rag.max_iter,
+                "verbose": configs.rag.verbose
+            }
+        
+        if configs.normal:
+            config_dict["normal"] = {
+                "role": configs.normal.role,
+                "goal": configs.normal.goal,
+                "backstory": configs.normal.backstory,
+                "max_iter": configs.normal.max_iter,
+                "verbose": configs.normal.verbose
+            }
+        
+        update_agent_configs(config_dict)
+        
+        return {"message": "Configuration updated successfully", "status": "success"}
+        
+    except Exception as e:
+        logger.error(f"Error updating configuration: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error updating configuration: {str(e)}"
+        )
+
+
+@app.get("/logs")
+def get_logs():
+    """Get agent activity logs"""
+    from services.agents import activity_logs
+    
+    # Return last 100 logs
+    return {
+        "logs": activity_logs[-100:],
+        "total": len(activity_logs)
+    }
+
+
+@app.post("/rag/upload")
+def upload_pdf(file: UploadFile = File(...)):
+    """
+    Upload a PDF file and build RAG index
+    
+    - **file**: PDF file to upload and index
+    """
+    if not file.filename.endswith('.pdf'):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Only PDF files are supported"
+        )
+    
+    try:
+        # Save uploaded file temporarily
+        with tempfile.NamedTemporaryFile(delete=False, suffix='.pdf') as tmp_file:
+            content = file.file.read()
+            tmp_file.write(content)
+            tmp_path = tmp_file.name
+        
+        try:
+            # Process PDF
+            rag_service = get_rag_service()
+            chunks = rag_service.process_pdf(tmp_path)
+            
+            # Build index
+            rag_service.build_index(chunks)
+            
+            logger.info(f"Successfully indexed {len(chunks)} chunks from {file.filename}")
+            
+            return {
+                "message": f"Successfully uploaded and indexed PDF: {file.filename}",
+                "filename": file.filename,
+                "chunks": len(chunks),
+                "status": "success"
+            }
+            
+        finally:
+            # Clean up temporary file
+            if os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+                
+    except Exception as e:
+        logger.error(f"Error uploading PDF: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing PDF: {str(e)}"
+        )
+
+
+@app.get("/rag/status")
+def get_rag_status():
+    """Get RAG index status"""
+    try:
+        rag_service = get_rag_service()
+        status_info = rag_service.get_status()
+        return status_info
+    except Exception as e:
+        logger.error(f"Error getting RAG status: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error getting status: {str(e)}"
+        )
+
+
+@app.delete("/rag/index")
+def delete_rag_index():
+    """Delete the RAG index"""
+    try:
+        rag_service = get_rag_service()
+        deleted = rag_service.delete_index()
+        return {
+            "message": "RAG index deleted successfully" if deleted else "No index to delete",
+            "status": "success"
+        }
+    except Exception as e:
+        logger.error(f"Error deleting RAG index: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error deleting index: {str(e)}"
+        )
+
+
+# Entry point for running with uvicorn
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=5001)
+
diff --git a/MultiAgentQnA/api/services/__init__.py b/MultiAgentQnA/api/services/__init__.py
new file mode 100644
index 0000000000..9d574a1f0f
--- /dev/null
+++ b/MultiAgentQnA/api/services/__init__.py
@@ -0,0 +1,25 @@
+"""
+Services module for Multi-Agent Q&A
+"""
+
+from .api_client import get_api_client, APIClient
+from .agents import (
+    get_orchestration_agent, 
+    get_code_agent, 
+    get_rag_agent, 
+    get_normal_agent,
+    update_agent_configs,
+    process_query
+)
+
+__all__ = [
+    "get_api_client",
+    "APIClient",
+    "get_orchestration_agent",
+    "get_code_agent",
+    "get_rag_agent",
+    "get_normal_agent",
+    "update_agent_configs",
+    "process_query"
+]
+
diff --git a/MultiAgentQnA/api/services/agents.py b/MultiAgentQnA/api/services/agents.py
new file mode 100644
index 0000000000..f8e756c072
--- /dev/null
+++ b/MultiAgentQnA/api/services/agents.py
@@ -0,0 +1,303 @@
+"""
+Multi-Agent Q&A System
+Simplified agent implementation without CrewAI dependency
+"""
+
+import logging
+from typing import Dict, Any, Optional
+from datetime import datetime
+from services.api_client import get_api_client
+from services.rag_service import get_rag_service
+
+logger = logging.getLogger(__name__)
+
+# Activity logs for agent interactions
+activity_logs = []
+
+
+def add_activity_log(message: str, log_type: str = "info"):
+    """Add an activity log entry"""
+    from datetime import datetime
+    activity_logs.append({
+        "timestamp": datetime.now().isoformat(),
+        "type": log_type,
+        "message": message
+    })
+    # Keep only last 500 logs
+    if len(activity_logs) > 500:
+        activity_logs.pop(0)
+
+# Default configurations
+DEFAULT_ORCHESTRATION_CONFIG = {
+    "role": "Orchestration Coordinator",
+    "goal": "Analyze user queries and delegate them to the most appropriate specialized agent",
+    "backstory": "You are an expert coordinator who understands different types of questions. You excel at categorizing queries and routing them to the right specialist: code questions to developers, document questions to researchers, and general questions to assistants.",
+    "max_tokens": 500,
+    "temperature": 0.7
+}
+
+DEFAULT_CODE_CONFIG = {
+    "role": "Senior Software Developer",
+    "goal": "Answer coding questions with accurate, practical, and well-explained solutions",
+    "backstory": "You are an experienced software engineer with expertise in multiple programming languages. You provide clear, working code examples and best practices.",
+    "max_tokens": 500,
+    "temperature": 0.5
+}
+
+DEFAULT_RAG_CONFIG = {
+    "role": "Research Assistant",
+    "goal": "Retrieve information from documents and provide accurate answers",
+    "backstory": "You are a skilled researcher who excels at finding relevant information from knowledge bases and synthesizing comprehensive answers.",
+    "max_tokens": 800,
+    "temperature": 0.7
+}
+
+DEFAULT_NORMAL_CONFIG = {
+    "role": "Helpful Assistant",
+    "goal": "Provide clear, accurate, and helpful answers to general questions",
+    "backstory": "You are a knowledgeable assistant who loves helping people with their questions. You provide thoughtful and informative responses.",
+    "max_tokens": 500,
+    "temperature": 0.7
+}
+
+
+def get_orchestration_agent(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Get orchestration agent configuration"""
+    return config if config else DEFAULT_ORCHESTRATION_CONFIG
+
+
+def get_code_agent(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Get code agent configuration"""
+    return config if config else DEFAULT_CODE_CONFIG
+
+
+def get_rag_agent(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Get RAG agent configuration"""
+    return config if config else DEFAULT_RAG_CONFIG
+
+
+def get_normal_agent(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Get normal agent configuration"""
+    return config if config else DEFAULT_NORMAL_CONFIG
+
+
+def determine_agent_type(query: str, verbose: bool = True) -> tuple[str, str]:
+    """
+    Determine which agent should handle the query
+    
+    Args:
+        query: User query
+        verbose: Whether to log the decision
+        
+    Returns:
+        Tuple of (agent_type, reasoning)
+    """
+    query_lower = query.lower()
+    
+    # Check for code-related keywords
+    code_keywords = ['code', 'programming', 'function', 'variable', 'debug', 'error', 
+                     'python', 'javascript', 'java', 'c++', 'git', 'repo', 'repository',
+                     'algorithm', 'data structure', 'api', 'syntax', 'compile', 'test']
+    if any(keyword in query_lower for keyword in code_keywords):
+        matched_keywords = [kw for kw in code_keywords if kw in query_lower]
+        reasoning = f"Code keywords detected: {', '.join(matched_keywords[:3])}"
+        if verbose:
+            logger.info(f"🔍 ORCHESTRATION: {reasoning} → Routing to Code Agent")
+            add_activity_log(f"🔍 {reasoning} → Routing to Code Agent", "info")
+        return 'code', reasoning
+    
+    # Check for document/retrieval-related keywords
+    rag_keywords = ['document', 'file', 'pdf', 'retrieve', 'search', 'find in',
+                   'according to', 'read', 'extract', 'index']
+    if any(keyword in query_lower for keyword in rag_keywords):
+        matched_keywords = [kw for kw in rag_keywords if kw in query_lower]
+        reasoning = f"RAG keywords detected: {', '.join(matched_keywords[:3])}"
+        if verbose:
+            logger.info(f"🔍 ORCHESTRATION: {reasoning} → Routing to RAG Agent")
+            add_activity_log(f"🔍 {reasoning} → Routing to RAG Agent", "info")
+        return 'rag', reasoning
+    
+    # Default to normal agent
+    reasoning = "No specialized keywords found, using general agent"
+    if verbose:
+        logger.info(f"🔍 ORCHESTRATION: {reasoning} → Routing to General Agent")
+        add_activity_log(f"🔍 {reasoning} → Routing to General Agent", "info")
+    return 'normal', reasoning
+
+
+def process_query(query: str, agent_config: Optional[Dict[str, Any]] = None, verbose: bool = True) -> tuple[str, str]:
+    """
+    Process a query using the appropriate agent with full logging
+    
+    Args:
+        query: User query
+        agent_config: Optional agent configuration
+        verbose: Whether to log agent interactions
+        
+    Returns:
+        Tuple of (response, agent_name)
+    """
+    # Step 1: Orchestration - Determine which agent to use
+    if verbose:
+        logger.info("=" * 80)
+        logger.info("🎯 ORCHESTRATION: Analyzing user query")
+        logger.info(f"📝 Query: {query}")
+        logger.info("=" * 80)
+        add_activity_log("🎯 ORCHESTRATION: Analyzing user query", "info")
+        add_activity_log(f"📝 Query: {query}", "info")
+    
+    agent_type, reasoning = determine_agent_type(query, verbose=verbose)
+    
+    try:
+        # Get agent configurations if provided
+        code_config = None
+        rag_config = None
+        normal_config = None
+        
+        if agent_config:
+            code_config = agent_config.get("code")
+            rag_config = agent_config.get("rag")
+            normal_config = agent_config.get("normal")
+        
+        # Get the appropriate agent config
+        if agent_type == 'code':
+            agent_config_data = get_code_agent(code_config)
+            agent_name = 'code_agent'
+        elif agent_type == 'rag':
+            agent_config_data = get_rag_agent(rag_config)
+            agent_name = 'rag_agent'
+        else:
+            agent_config_data = get_normal_agent(normal_config)
+            agent_name = 'normal_agent'
+        
+        # Step 2: Agent configuration
+        if verbose:
+            logger.info("")
+            logger.info(f"🤖 AGENT SELECTED: {agent_name}")
+            logger.info(f"   Role: {agent_config_data.get('role', 'Assistant')}")
+            logger.info(f"   Goal: {agent_config_data.get('goal', 'Help the user')}")
+            logger.info("")
+            add_activity_log(f"🤖 AGENT SELECTED: {agent_name}", "info")
+            add_activity_log(f"   Role: {agent_config_data.get('role', 'Assistant')}", "info")
+        
+        # Build the prompt with agent context
+        role = agent_config_data.get("role", "Assistant")
+        goal = agent_config_data.get("goal", "Help the user")
+        backstory = agent_config_data.get("backstory", "You are a helpful assistant")
+        
+        # Step 3: Agent processing
+        if verbose:
+            logger.info("💭 AGENT THINKING: Processing query with agent-specific context...")
+            add_activity_log("💭 AGENT THINKING: Processing query with agent-specific context...", "info")
+        
+        api_client = get_api_client()
+        
+        # Handle RAG agent differently - search documents first
+        if agent_type == 'rag':
+            try:
+                rag_service = get_rag_service()
+                if verbose:
+                    add_activity_log("🔍 RAG: Searching document index...", "info")
+                
+                # Search for relevant documents
+                results = rag_service.search(query, k=3)
+                
+                if results:
+                    # Build context from retrieved documents
+                    context_parts = []
+                    for i, result in enumerate(results, 1):
+                        doc_text = result['document']['text']
+                        similarity = result['similarity']
+                        context_parts.append(f"Document {i} (similarity: {similarity:.2f}):\n{doc_text}")
+                    
+                    context = "\n\n".join(context_parts)
+                    
+                    if verbose:
+                        add_activity_log(f"📄 RAG: Found {len(results)} relevant documents", "info")
+                        logger.info(f"RAG retrieval: Found {len(results)} relevant documents")
+                    
+                    system_prompt = f"""You are a {role}.
+
+Your goal: {goal}
+
+{backstory}
+
+Use the following retrieved documents to answer the question. If the documents don't contain relevant information, say so.
+
+Retrieved Documents:
+{context}
+
+Now answer the following question based on the documents above:"""
+                else:
+                    if verbose:
+                        add_activity_log("⚠️ RAG: No documents found in index", "warning")
+                    
+                    system_prompt = f"""You are a {role}.
+
+Your goal: {goal}
+
+{backstory}
+
+Note: No documents are currently indexed. You cannot answer questions about documents until documents are uploaded.
+
+Now answer the following question:"""
+            except Exception as e:
+                logger.error(f"Error in RAG retrieval: {str(e)}")
+                if verbose:
+                    add_activity_log(f"❌ RAG Error: {str(e)}", "error")
+                
+                # Fall back to normal prompt
+                system_prompt = f"""You are a {role}.
+
+Your goal: {goal}
+
+{backstory}
+
+Now answer the following question:"""
+        else:
+            # For non-RAG agents, use standard prompt
+            system_prompt = f"""You are a {role}.
+
+Your goal: {goal}
+
+{backstory}
+
+Now answer the following question:"""
+        
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": query}
+        ]
+        
+        response = api_client.chat_complete(
+            messages=messages,
+            max_tokens=agent_config_data.get("max_tokens", 500),
+            temperature=agent_config_data.get("temperature", 0.7)
+        )
+        
+        if verbose:
+            logger.info(f"✅ AGENT RESPONSE: Generated {len(str(response))} characters")
+            logger.info("=" * 80)
+            logger.info("")
+            add_activity_log(f"✅ AGENT RESPONSE: Generated {len(str(response))} characters", "success")
+        
+        return str(response), agent_name
+        
+    except Exception as e:
+        error_msg = f"❌ ERROR: {str(e)}"
+        logger.error(error_msg, exc_info=True)
+        add_activity_log(error_msg, "error")
+        raise
+
+
+def update_agent_configs(configs: Dict[str, Any]) -> None:
+    """
+    Update all agent configurations (stored as defaults for future queries)
+    
+    Args:
+        configs: Dictionary containing agent configurations
+    """
+    # In this simplified version, configs are used at query time
+    # This function exists for API compatibility
+    logger.info("Agent configurations updated")
+
diff --git a/MultiAgentQnA/api/services/api_client.py b/MultiAgentQnA/api/services/api_client.py
new file mode 100644
index 0000000000..0965de89fa
--- /dev/null
+++ b/MultiAgentQnA/api/services/api_client.py
@@ -0,0 +1,214 @@
+"""
+API Client for authentication and API calls
+Similar to rag-chatbot implementation
+"""
+
+import logging
+import requests
+import httpx
+from typing import Optional
+import config
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+    """
+    Client for handling authentication and API calls
+    """
+    
+    def __init__(self):
+        self.base_url = config.BASE_URL
+        self.token = None
+        self.http_client = None
+        self._authenticate()
+    
+    def _authenticate(self) -> None:
+        """
+        Authenticate and obtain access token from Keycloak
+        """
+        token_url = f"{self.base_url}/token"
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": config.KEYCLOAK_CLIENT_ID,
+            "client_secret": config.KEYCLOAK_CLIENT_SECRET,
+        }
+        
+        try:
+            response = requests.post(token_url, data=payload, verify=False)
+            
+            if response.status_code == 200:
+                self.token = response.json().get("access_token")
+                logger.info(f"✓ Access token obtained: {self.token[:20]}..." if self.token else "Failed to get token")
+                
+                # Create httpx client with SSL verification disabled (like -k in curl)
+                self.http_client = httpx.Client(verify=False)
+                
+            else:
+                logger.error(f"Error obtaining token: {response.status_code} - {response.text}")
+                raise Exception(f"Authentication failed: {response.status_code}")
+                
+        except Exception as e:
+            logger.error(f"Error during authentication: {str(e)}")
+            raise
+    
+    def get_embedding_client(self):
+        """
+        Get OpenAI-style client for embeddings
+        Uses bge-base-en-v1.5 endpoint
+        """
+        from openai import OpenAI
+        
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{config.EMBEDDING_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+    
+    def get_inference_client(self):
+        """
+        Get OpenAI-style client for inference/completions
+        Uses Llama-3.1-8B-Instruct endpoint
+        """
+        from openai import OpenAI
+        
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{config.INFERENCE_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+    
+    def embed_text(self, text: str) -> list:
+        """
+        Get embedding for text
+        Uses the bge-base-en-v1.5 embedding model
+        
+        Args:
+            text: Text to embed
+            
+        Returns:
+            List of embedding values
+        """
+        try:
+            client = self.get_embedding_client()
+            # Call the embeddings endpoint
+            response = client.embeddings.create(
+                model=config.EMBEDDING_MODEL_NAME,
+                input=text
+            )
+            return response.data[0].embedding
+        except Exception as e:
+            logger.error(f"Error generating embedding: {str(e)}")
+            raise
+    
+    def embed_texts(self, texts: list) -> list:
+        """
+        Get embeddings for multiple texts
+        Batches requests to avoid exceeding API limits (max batch size: 32)
+        
+        Args:
+            texts: List of texts to embed
+            
+        Returns:
+            List of embedding vectors
+        """
+        try:
+            BATCH_SIZE = 32  # Maximum allowed batch size
+            all_embeddings = []
+            client = self.get_embedding_client()
+            
+            # Process in batches of 32
+            for i in range(0, len(texts), BATCH_SIZE):
+                batch = texts[i:i + BATCH_SIZE]
+                logger.info(f"Processing embedding batch {i//BATCH_SIZE + 1}/{(len(texts) + BATCH_SIZE - 1)//BATCH_SIZE} ({len(batch)} texts)")
+                
+                response = client.embeddings.create(
+                    model=config.EMBEDDING_MODEL_NAME,
+                    input=batch
+                )
+                batch_embeddings = [data.embedding for data in response.data]
+                all_embeddings.extend(batch_embeddings)
+            
+            return all_embeddings
+        except Exception as e:
+            logger.error(f"Error generating embeddings: {str(e)}")
+            raise
+    
+    def chat_complete(self, messages: list, max_tokens: int = 500, temperature: float = 0.7) -> str:
+        """
+        Get chat completion from the inference model
+        
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            max_tokens: Maximum tokens to generate
+            temperature: Temperature for generation
+            
+        Returns:
+            Generated text
+        """
+        try:
+            client = self.get_inference_client()
+            # Convert messages to a prompt for the completions endpoint
+            # (since Llama models use completions, not chat.completions)
+            prompt = ""
+            for msg in messages:
+                role = msg.get('role', 'user')
+                content = msg.get('content', '')
+                if role == 'system':
+                    prompt += f"System: {content}\n\n"
+                elif role == 'user':
+                    prompt += f"User: {content}\n\n"
+                elif role == 'assistant':
+                    prompt += f"Assistant: {content}\n\n"
+            prompt += "Assistant:"
+            
+            logger.info(f"Calling inference with prompt length: {len(prompt)}")
+            
+            response = client.completions.create(
+                model=config.INFERENCE_MODEL_NAME,
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature
+            )
+            
+            # Handle response structure
+            if hasattr(response, 'choices') and len(response.choices) > 0:
+                choice = response.choices[0]
+                if hasattr(choice, 'text'):
+                    return choice.text
+                elif hasattr(choice, 'message') and hasattr(choice.message, 'content'):
+                    return choice.message.content
+                else:
+                    logger.error(f"Unexpected response structure: {type(choice)}, {choice}")
+                    return str(choice)
+            else:
+                logger.error(f"Unexpected response: {type(response)}, {response}")
+                return ""
+        except Exception as e:
+            logger.error(f"Error generating chat completion: {str(e)}", exc_info=True)
+            raise
+    
+    def __del__(self):
+        """
+        Cleanup: close httpx client
+        """
+        if self.http_client:
+            self.http_client.close()
+
+
+# Global API client instance
+_api_client: Optional[APIClient] = None
+
+
+def get_api_client() -> APIClient:
+    """
+    Get or create the global API client instance
+    
+    Returns:
+        APIClient instance
+    """
+    global _api_client
+    if _api_client is None:
+        _api_client = APIClient()
+    return _api_client
+
diff --git a/MultiAgentQnA/api/services/rag_service.py b/MultiAgentQnA/api/services/rag_service.py
new file mode 100644
index 0000000000..874b7d1439
--- /dev/null
+++ b/MultiAgentQnA/api/services/rag_service.py
@@ -0,0 +1,293 @@
+"""
+RAG Service for PDF processing and vector store management
+Handles PDF parsing, text chunking, and FAISS vector operations
+"""
+
+import os
+import logging
+import shutil
+from typing import List, Optional, Dict, Any
+import numpy as np
+import faiss
+from pypdf import PdfReader
+import config
+from services.api_client import get_api_client
+
+logger = logging.getLogger(__name__)
+
+# Constants
+VECTOR_STORE_DIR = "./rag_index"
+CHUNK_SIZE = 1000  # Characters per chunk
+CHUNK_OVERLAP = 200  # Overlap between chunks
+
+
+class RAGService:
+    """
+    Service for RAG operations: PDF processing, embedding, and retrieval
+    """
+    
+    def __init__(self):
+        self.api_client = get_api_client()
+        self.vector_store_path = VECTOR_STORE_DIR
+        self.index: Optional[faiss.Index] = None
+        self.documents: List[Dict[str, Any]] = []
+        self._ensure_directory()
+    
+    def _ensure_directory(self):
+        """Ensure the vector store directory exists"""
+        os.makedirs(self.vector_store_path, exist_ok=True)
+    
+    def process_pdf(self, pdf_path: str) -> List[Dict[str, Any]]:
+        """
+        Process a PDF file and extract text chunks
+        
+        Args:
+            pdf_path: Path to the PDF file
+            
+        Returns:
+            List of document chunks with metadata
+        """
+        try:
+            logger.info(f"Processing PDF: {pdf_path}")
+            reader = PdfReader(pdf_path)
+            
+            # Extract text from all pages
+            full_text = ""
+            for i, page in enumerate(reader.pages):
+                page_text = page.extract_text()
+                if page_text:
+                    full_text += f"\n--- Page {i+1} ---\n{page_text}\n"
+            
+            if not full_text.strip():
+                raise ValueError("No text extracted from PDF")
+            
+            # Chunk the text
+            chunks = self._chunk_text(full_text, metadata={"source": pdf_path})
+            
+            logger.info(f"Extracted {len(chunks)} chunks from PDF")
+            return chunks
+            
+        except Exception as e:
+            logger.error(f"Error processing PDF: {str(e)}")
+            raise
+    
+    def _chunk_text(self, text: str, metadata: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """
+        Split text into overlapping chunks
+        
+        Args:
+            text: Text to chunk
+            metadata: Metadata to attach to chunks
+            
+        Returns:
+            List of chunk dictionaries
+        """
+        chunks = []
+        
+        # Split by paragraphs first
+        paragraphs = text.split('\n\n')
+        current_chunk = ""
+        current_size = 0
+        
+        for para in paragraphs:
+            para_size = len(para)
+            
+            # If adding this paragraph would exceed chunk size, save current chunk
+            if current_size + para_size > CHUNK_SIZE and current_chunk:
+                chunks.append({
+                    "text": current_chunk,
+                    "metadata": {**metadata, "chunk_index": len(chunks)}
+                })
+                
+                # Start new chunk with overlap
+                overlap_text = current_chunk[-CHUNK_OVERLAP:] if len(current_chunk) > CHUNK_OVERLAP else current_chunk
+                current_chunk = overlap_text + " " + para
+                current_size = len(current_chunk)
+            else:
+                current_chunk += "\n\n" + para if current_chunk else para
+                current_size = len(current_chunk)
+        
+        # Add the last chunk
+        if current_chunk:
+            chunks.append({
+                "text": current_chunk,
+                "metadata": {**metadata, "chunk_index": len(chunks)}
+            })
+        
+        return chunks
+    
+    def build_index(self, chunks: List[Dict[str, Any]]) -> None:
+        """
+        Create embeddings and build FAISS index
+        
+        Args:
+            chunks: List of document chunks
+        """
+        try:
+            logger.info(f"Building FAISS index with {len(chunks)} chunks")
+            
+            # Extract texts
+            texts = [chunk["text"] for chunk in chunks]
+            
+            # Get embeddings from API
+            embeddings = self.api_client.embed_texts(texts)
+            
+            # Convert to numpy array
+            embedding_dim = len(embeddings[0])
+            embeddings_array = np.array(embeddings, dtype=np.float32)
+            
+            # Create FAISS index (using L2 distance)
+            self.index = faiss.IndexFlatL2(embedding_dim)
+            self.index.add(embeddings_array)
+            
+            # Store documents
+            self.documents = chunks
+            
+            # Save to disk
+            self._save_index()
+            
+            logger.info(f"Index built successfully with {self.index.ntotal} vectors")
+            
+        except Exception as e:
+            logger.error(f"Error building index: {str(e)}")
+            raise
+    
+    def _save_index(self):
+        """Save FAISS index and documents to disk"""
+        try:
+            # Save FAISS index
+            faiss.write_index(self.index, os.path.join(self.vector_store_path, "index.faiss"))
+            
+            # Save documents as a simple format (JSON would be better but keeping it simple)
+            import pickle
+            with open(os.path.join(self.vector_store_path, "documents.pkl"), "wb") as f:
+                pickle.dump(self.documents, f)
+            
+            logger.info(f"Index saved to {self.vector_store_path}")
+            
+        except Exception as e:
+            logger.error(f"Error saving index: {str(e)}")
+            raise
+    
+    def load_index(self) -> bool:
+        """
+        Load FAISS index from disk
+        
+        Returns:
+            True if loaded successfully, False otherwise
+        """
+        try:
+            faiss_path = os.path.join(self.vector_store_path, "index.faiss")
+            docs_path = os.path.join(self.vector_store_path, "documents.pkl")
+            
+            if not os.path.exists(faiss_path) or not os.path.exists(docs_path):
+                logger.warning("No existing index found")
+                return False
+            
+            # Load FAISS index
+            self.index = faiss.read_index(faiss_path)
+            
+            # Load documents
+            import pickle
+            with open(docs_path, "rb") as f:
+                self.documents = pickle.load(f)
+            
+            logger.info(f"Loaded index with {self.index.ntotal} vectors")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error loading index: {str(e)}")
+            return False
+    
+    def search(self, query: str, k: int = 3) -> List[Dict[str, Any]]:
+        """
+        Search for similar documents
+        
+        Args:
+            query: Search query
+            k: Number of results to return
+            
+        Returns:
+            List of matching documents with similarity scores
+        """
+        try:
+            if not self.index or self.index.ntotal == 0:
+                logger.warning("No index loaded or index is empty")
+                return []
+            
+            # Get query embedding
+            query_embedding = self.api_client.embed_text(query)
+            query_vector = np.array([query_embedding], dtype=np.float32)
+            
+            # Search
+            distances, indices = self.index.search(query_vector, k)
+            
+            # Retrieve documents
+            results = []
+            for i, idx in enumerate(indices[0]):
+                if idx < len(self.documents):
+                    results.append({
+                        "document": self.documents[idx],
+                        "score": float(distances[0][i]),
+                        "similarity": 1.0 / (1.0 + float(distances[0][i]))  # Convert distance to similarity
+                    })
+            
+            return results
+            
+        except Exception as e:
+            logger.error(f"Error searching: {str(e)}")
+            raise
+    
+    def delete_index(self) -> bool:
+        """
+        Delete the vector store
+        
+        Returns:
+            True if deleted successfully
+        """
+        try:
+            if os.path.exists(self.vector_store_path):
+                shutil.rmtree(self.vector_store_path)
+                logger.info("Vector store deleted")
+                self.index = None
+                self.documents = []
+                return True
+            return False
+            
+        except Exception as e:
+            logger.error(f"Error deleting vector store: {str(e)}")
+            raise
+    
+    def get_status(self) -> Dict[str, Any]:
+        """
+        Get the status of the vector store
+        
+        Returns:
+            Dictionary with status information
+        """
+        return {
+            "index_exists": self.index is not None,
+            "num_documents": self.index.ntotal if self.index else 0,
+            "num_vectors": self.index.ntotal if self.index else 0,
+            "path": self.vector_store_path
+        }
+
+
+# Global RAG service instance
+_rag_service: Optional[RAGService] = None
+
+
+def get_rag_service() -> RAGService:
+    """
+    Get or create the global RAG service instance
+    
+    Returns:
+        RAGService instance
+    """
+    global _rag_service
+    if _rag_service is None:
+        _rag_service = RAGService()
+        # Try to load existing index
+        _rag_service.load_index()
+    return _rag_service
+
diff --git a/MultiAgentQnA/docker-compose.yml b/MultiAgentQnA/docker-compose.yml
new file mode 100644
index 0000000000..18976cefa7
--- /dev/null
+++ b/MultiAgentQnA/docker-compose.yml
@@ -0,0 +1,38 @@
+services:
+  # Backend API (Python)
+  backend:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+    container_name: multiagent-qna-backend
+    ports:
+      - "5001:5001"
+    env_file:
+      - ./api/.env
+    volumes:
+      - ./api:/app
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  # Frontend UI (React)
+  frontend:
+    build:
+      context: ./ui
+      dockerfile: Dockerfile
+    container_name: multiagent-qna-frontend
+    ports:
+      - "3000:3000"
+    depends_on:
+      - backend
+    networks:
+      - app_network
+    restart: unless-stopped
+
+##################################
+# 🔗 Shared Network
+##################################
+networks:
+  app_network:
+    driver: bridge
+
diff --git a/MultiAgentQnA/images/ui.png b/MultiAgentQnA/images/ui.png
new file mode 100644
index 0000000000..fa9a77802a
Binary files /dev/null and b/MultiAgentQnA/images/ui.png differ
diff --git a/MultiAgentQnA/ui/Dockerfile b/MultiAgentQnA/ui/Dockerfile
new file mode 100644
index 0000000000..4a92b94094
--- /dev/null
+++ b/MultiAgentQnA/ui/Dockerfile
@@ -0,0 +1,20 @@
+FROM node:18
+
+# Set the working directory
+WORKDIR /app
+
+# Copy package.json
+COPY package.json ./
+
+# Install dependencies (this will create package-lock.json if missing)
+RUN npm install
+
+# Copy the rest of the application files
+COPY . .
+
+# Expose the port the app runs on
+EXPOSE 3000
+
+# Command to run the application
+CMD ["npm", "run", "dev"]
+
diff --git a/MultiAgentQnA/ui/index.html b/MultiAgentQnA/ui/index.html
new file mode 100644
index 0000000000..7f3995c6dd
--- /dev/null
+++ b/MultiAgentQnA/ui/index.html
@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Multi-Agent Q&A</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
+
diff --git a/MultiAgentQnA/ui/package.json b/MultiAgentQnA/ui/package.json
new file mode 100644
index 0000000000..d4caceaf35
--- /dev/null
+++ b/MultiAgentQnA/ui/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "multiagent-qna-ui",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "axios": "^1.6.0",
+    "lucide-react": "^0.294.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.3.6",
+    "vite": "^5.0.8"
+  }
+}
+
diff --git a/MultiAgentQnA/ui/postcss.config.js b/MultiAgentQnA/ui/postcss.config.js
new file mode 100644
index 0000000000..b4a6220e2d
--- /dev/null
+++ b/MultiAgentQnA/ui/postcss.config.js
@@ -0,0 +1,7 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
+
diff --git a/MultiAgentQnA/ui/src/App.jsx b/MultiAgentQnA/ui/src/App.jsx
new file mode 100644
index 0000000000..36984f976a
--- /dev/null
+++ b/MultiAgentQnA/ui/src/App.jsx
@@ -0,0 +1,30 @@
+import { useState } from 'react'
+import Header from './components/Header'
+import ChatInterface from './components/ChatInterface'
+import SettingsPage from './components/SettingsPage'
+import LogsPanel from './components/LogsPanel'
+
+function App() {
+  const [currentPage, setCurrentPage] = useState('chat')
+  const [logsOpen, setLogsOpen] = useState(false)
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 via-white to-purple-50">
+      <Header 
+        currentPage={currentPage} 
+        onPageChange={setCurrentPage}
+        onLogsToggle={() => setLogsOpen(!logsOpen)}
+      />
+      
+      <main className="container mx-auto px-4 py-8 max-w-6xl">
+        {currentPage === 'chat' && <ChatInterface />}
+        {currentPage === 'settings' && <SettingsPage />}
+      </main>
+
+      <LogsPanel isOpen={logsOpen} onClose={() => setLogsOpen(false)} />
+    </div>
+  )
+}
+
+export default App
+
diff --git a/MultiAgentQnA/ui/src/components/ChatInterface.jsx b/MultiAgentQnA/ui/src/components/ChatInterface.jsx
new file mode 100644
index 0000000000..51ff0701ba
--- /dev/null
+++ b/MultiAgentQnA/ui/src/components/ChatInterface.jsx
@@ -0,0 +1,320 @@
+import { useState, useRef, useEffect } from 'react'
+import { Send, Bot, User, AlertCircle, Code, FileText, MessageCircle, Upload, Check, X } from 'lucide-react'
+import { sendChatMessage, uploadPDF, getRAGStatus } from '../services/api'
+
+export default function ChatInterface() {
+  const [messages, setMessages] = useState([])
+  const [input, setInput] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const [uploading, setUploading] = useState(false)
+  const [uploadStatus, setUploadStatus] = useState(null)
+  const [ragStatus, setRagStatus] = useState(null)
+  const messagesEndRef = useRef(null)
+  const fileInputRef = useRef(null)
+
+  const scrollToBottom = () => {
+    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" })
+  }
+
+  useEffect(() => {
+    scrollToBottom()
+  }, [messages])
+
+  useEffect(() => {
+    loadRAGStatus()
+  }, [])
+
+  const loadRAGStatus = async () => {
+    try {
+      const status = await getRAGStatus()
+      setRagStatus(status)
+    } catch (error) {
+      console.error('Error loading RAG status:', error)
+    }
+  }
+
+  const handleFileUpload = async (e) => {
+    const file = e.target.files[0]
+    console.log('File selected:', file)
+    
+    if (!file) {
+      console.log('No file selected')
+      return
+    }
+
+    if (!file.type.includes('pdf')) {
+      alert('Only PDF files are supported')
+      return
+    }
+
+    console.log('Starting upload for:', file.name)
+    setUploading(true)
+    setUploadStatus(null)
+
+    try {
+      const result = await uploadPDF(file)
+      console.log('Upload successful:', result)
+      setUploadStatus({ success: true, message: result.message, chunks: result.chunks })
+      await loadRAGStatus()
+      
+      // Show success message in chat
+      const successMsg = {
+        type: 'assistant',
+        content: `✅ PDF uploaded successfully! Indexed ${result.chunks} chunks. You can now ask questions about this document.`,
+        timestamp: new Date()
+      }
+      setMessages(prev => [...prev, successMsg])
+    } catch (error) {
+      console.error('Upload error:', error)
+      setUploadStatus({ success: false, message: error.message })
+      const errorMsg = {
+        type: 'error',
+        content: `Failed to upload PDF: ${error.message}`,
+        timestamp: new Date()
+      }
+      setMessages(prev => [...prev, errorMsg])
+    } finally {
+      setUploading(false)
+      // Clear file input
+      if (fileInputRef.current) {
+        fileInputRef.current.value = ''
+      }
+    }
+  }
+
+  const handleSubmit = async (e) => {
+    e.preventDefault()
+    
+    if (!input.trim()) return
+
+    const userMessage = {
+      type: 'user',
+      content: input,
+      timestamp: new Date()
+    }
+
+    setMessages(prev => [...prev, userMessage])
+    setInput('')
+    setIsLoading(true)
+
+    try {
+      const response = await sendChatMessage(input)
+      
+      const botMessage = {
+        type: 'assistant',
+        content: response.response,
+        agent: response.agent,
+        timestamp: new Date()
+      }
+      
+      setMessages(prev => [...prev, botMessage])
+    } catch (error) {
+      const errorMessage = {
+        type: 'error',
+        content: error.message || 'Failed to get response. Please try again.',
+        timestamp: new Date()
+      }
+      setMessages(prev => [...prev, errorMessage])
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const getAgentIcon = (agent) => {
+    switch (agent) {
+      case 'code_agent':
+        return <Code className="w-4 h-4" />
+      case 'rag_agent':
+        return <FileText className="w-4 h-4" />
+      case 'normal_agent':
+        return <MessageCircle className="w-4 h-4" />
+      default:
+        return <Bot className="w-4 h-4" />
+    }
+  }
+
+  const getAgentBadge = (agent) => {
+    switch (agent) {
+      case 'code_agent':
+        return <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-blue-100 text-blue-800">
+          Code Agent
+        </span>
+      case 'rag_agent':
+        return <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-purple-100 text-purple-800">
+          RAG Agent
+        </span>
+      case 'normal_agent':
+        return <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-green-100 text-green-800">
+          General Agent
+        </span>
+      default:
+        return null
+    }
+  }
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 flex flex-col h-[600px]">
+      {/* Chat Header */}
+      <div className="border-b border-gray-200 p-4">
+        <div className="flex items-center justify-between mb-2">
+          <h2 className="text-lg font-semibold text-gray-800 flex items-center space-x-2">
+            <Bot className="w-5 h-5 text-purple-500" />
+            <span>Multi-Agent Chat</span>
+          </h2>
+          {ragStatus && ragStatus.index_exists && (
+            <span className="text-xs px-2 py-1 bg-purple-100 text-purple-700 rounded-full font-medium">
+              📄 {ragStatus.num_documents} docs indexed
+            </span>
+          )}
+        </div>
+        <p className="text-sm text-gray-500">
+          Ask anything - code questions, document queries, or general questions
+        </p>
+      </div>
+
+      {/* Messages Container */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-4 scrollbar-hide">
+        {messages.length === 0 && (
+          <div className="h-full flex items-center justify-center">
+            <div className="text-center space-y-4 max-w-md">
+              <Bot className="w-20 h-20 text-gray-300 mx-auto" />
+              <div>
+                <h3 className="text-lg font-semibold text-gray-700 mb-2">Get Started</h3>
+                <p className="text-gray-500 mb-4">Our intelligent multi-agent system will route your question to the best specialist:</p>
+                <div className="flex flex-col space-y-2 text-sm">
+                  <div className="flex items-center space-x-2 text-gray-600">
+                    <Code className="w-4 h-4 text-blue-500" />
+                    <span><strong>Code Agent</strong> - Programming, algorithms, debugging</span>
+                  </div>
+                  <div className="flex items-center space-x-2 text-gray-600">
+                    <FileText className="w-4 h-4 text-purple-500" />
+                    <span><strong>RAG Agent</strong> - Document retrieval and research</span>
+                  </div>
+                  <div className="flex items-center space-x-2 text-gray-600">
+                    <MessageCircle className="w-4 h-4 text-green-500" />
+                    <span><strong>General Agent</strong> - Everything else</span>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        )}
+
+        {messages.map((message, index) => (
+          <div
+            key={index}
+            className={`flex items-start space-x-3 ${
+              message.type === 'user' ? 'flex-row-reverse space-x-reverse' : ''
+            }`}
+          >
+            <div className={`flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center ${
+              message.type === 'user' 
+                ? 'bg-gradient-to-br from-blue-500 to-purple-600' 
+                : message.type === 'error'
+                ? 'bg-red-500'
+                : 'bg-gray-200'
+            }`}>
+              {message.type === 'user' ? (
+                <User className="w-5 h-5 text-white" />
+              ) : message.type === 'error' ? (
+                <AlertCircle className="w-5 h-5 text-white" />
+              ) : (
+                getAgentIcon(message.agent)
+              )}
+            </div>
+
+            <div className={`flex-1 max-w-[80%] ${
+              message.type === 'user' ? 'items-end' : 'items-start'
+            }`}>
+              {message.agent && message.type !== 'error' && (
+                <div className="mb-1">
+                  {getAgentBadge(message.agent)}
+                </div>
+              )}
+              <div className={`rounded-lg p-3 ${
+                message.type === 'user'
+                  ? 'bg-gradient-to-br from-blue-500 to-purple-600 text-white'
+                  : message.type === 'error'
+                  ? 'bg-red-50 border border-red-200 text-red-700'
+                  : 'bg-gray-100 text-gray-800'
+              }`}>
+                <p className="text-sm whitespace-pre-wrap">{message.content}</p>
+              </div>
+              <p className="text-xs text-gray-400 mt-1">
+                {message.timestamp.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}
+              </p>
+            </div>
+          </div>
+        ))}
+
+        {isLoading && (
+          <div className="flex items-start space-x-3">
+            <div className="flex-shrink-0 w-8 h-8 rounded-full bg-gray-200 flex items-center justify-center">
+              <Bot className="w-5 h-5 text-gray-600" />
+            </div>
+            <div className="bg-gray-100 rounded-lg p-3">
+              <div className="flex space-x-2">
+                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style={{ animationDelay: '0ms' }}></div>
+                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style={{ animationDelay: '150ms' }}></div>
+                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style={{ animationDelay: '300ms' }}></div>
+              </div>
+            </div>
+          </div>
+        )}
+
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Input Form */}
+      <div className="border-t border-gray-200 p-4">
+        <form onSubmit={handleSubmit} className="flex space-x-2">
+          <input
+            type="text"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder="Ask a question..."
+            disabled={isLoading || uploading}
+            className="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-purple-500 disabled:bg-gray-100 disabled:cursor-not-allowed"
+          />
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept=".pdf"
+            onChange={handleFileUpload}
+            className="hidden"
+          />
+          <button
+            type="button"
+            onClick={(e) => {
+              console.log('Upload button clicked!', fileInputRef.current)
+              e.preventDefault()
+              fileInputRef.current?.click()
+            }}
+            disabled={isLoading || uploading}
+            className="px-4 py-2 bg-purple-500 text-white rounded-lg hover:bg-purple-600 disabled:opacity-50 disabled:cursor-not-allowed transition-all font-medium shadow-sm flex items-center space-x-2"
+          >
+            {uploading ? (
+              <>
+                <div className="w-4 h-4 border-2 border-white border-t-transparent rounded-full animate-spin"></div>
+              </>
+            ) : (
+              <Upload className="w-4 h-4" />
+            )}
+          </button>
+          <button
+            type="submit"
+            disabled={!input.trim() || isLoading || uploading}
+            className="px-6 py-2 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-lg hover:from-blue-600 hover:to-purple-700 disabled:opacity-50 disabled:cursor-not-allowed transition-all font-medium shadow-sm flex items-center space-x-2"
+          >
+            <Send className="w-4 h-4" />
+            <span>Send</span>
+          </button>
+        </form>
+        <p className="text-xs text-gray-500 mt-2">
+          Press Enter to send • Upload PDFs for document questions • The AI will route your question to the best specialist
+        </p>
+      </div>
+    </div>
+  )
+}
+
diff --git a/MultiAgentQnA/ui/src/components/Header.jsx b/MultiAgentQnA/ui/src/components/Header.jsx
new file mode 100644
index 0000000000..c2db298232
--- /dev/null
+++ b/MultiAgentQnA/ui/src/components/Header.jsx
@@ -0,0 +1,53 @@
+import { Bot, Terminal } from 'lucide-react'
+
+export default function Header({ currentPage, onPageChange, onLogsToggle }) {
+  return (
+    <header className="bg-gradient-to-r from-blue-600 to-purple-700 shadow-lg">
+      <div className="container mx-auto px-4 py-6">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center space-x-3">
+            <div className="bg-white rounded-lg p-2">
+              <Bot className="w-8 h-8 text-purple-600" />
+            </div>
+            <div>
+              <h1 className="text-2xl font-bold text-white">Multi-Agent Q&A</h1>
+              <p className="text-blue-100 text-sm">Intelligent question answering with specialized agents</p>
+            </div>
+          </div>
+          
+          <nav className="flex space-x-4">
+            <button
+              onClick={() => onPageChange('chat')}
+              className={`px-4 py-2 rounded-lg font-medium transition-all ${
+                currentPage === 'chat'
+                  ? 'bg-white text-purple-700 shadow-md'
+                  : 'text-white hover:bg-white/20'
+              }`}
+            >
+              Chat
+            </button>
+            <button
+              onClick={() => onPageChange('settings')}
+              className={`px-4 py-2 rounded-lg font-medium transition-all ${
+                currentPage === 'settings'
+                  ? 'bg-white text-purple-700 shadow-md'
+                  : 'text-white hover:bg-white/20'
+              }`}
+            >
+              Settings
+            </button>
+            <button
+              onClick={onLogsToggle}
+              className="px-4 py-2 rounded-lg font-medium transition-all text-white hover:bg-white/20 flex items-center space-x-2"
+              title="View agent logs"
+            >
+              <Terminal className="w-4 h-4" />
+              <span>Logs</span>
+            </button>
+          </nav>
+        </div>
+      </div>
+    </header>
+  )
+}
+
diff --git a/MultiAgentQnA/ui/src/components/LogsPanel.jsx b/MultiAgentQnA/ui/src/components/LogsPanel.jsx
new file mode 100644
index 0000000000..281a66fd95
--- /dev/null
+++ b/MultiAgentQnA/ui/src/components/LogsPanel.jsx
@@ -0,0 +1,134 @@
+import { useState, useEffect } from 'react'
+import { Terminal, Copy, Check, X, RefreshCw } from 'lucide-react'
+import { getLogs } from '../services/api'
+
+export default function LogsPanel({ isOpen, onClose }) {
+  const [logs, setLogs] = useState([])
+  const [copied, setCopied] = useState(false)
+  const [autoRefresh, setAutoRefresh] = useState(true)
+
+  const fetchLogs = async () => {
+    try {
+      const response = await getLogs()
+      if (response && response.logs) {
+        setLogs(response.logs.reverse()) // Show newest first
+      }
+    } catch (error) {
+      console.error('Error fetching logs:', error)
+    }
+  }
+
+  useEffect(() => {
+    if (isOpen) {
+      fetchLogs()
+    }
+  }, [isOpen])
+
+  useEffect(() => {
+    if (isOpen && autoRefresh) {
+      const interval = setInterval(fetchLogs, 2000) // Refresh every 2 seconds
+      return () => clearInterval(interval)
+    }
+  }, [isOpen, autoRefresh])
+
+  const copyLogs = () => {
+    const logsText = logs.map(log => {
+      const timestamp = new Date(log.timestamp).toLocaleTimeString()
+      return `[${timestamp}] ${log.type.toUpperCase()}: ${log.message}`
+    }).join('\n')
+    navigator.clipboard.writeText(logsText)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  const clearLogs = () => {
+    setLogs([])
+    fetchLogs()
+  }
+
+  if (!isOpen) return null
+
+  return (
+    <div className="fixed inset-0 bg-black bg-opacity-50 z-50 flex items-center justify-center p-4">
+      <div className="bg-gray-900 rounded-lg shadow-xl w-full max-w-4xl h-[600px] flex flex-col border border-gray-700">
+        {/* Header */}
+        <div className="bg-gray-800 px-4 py-3 rounded-t-lg flex items-center justify-between border-b border-gray-700">
+          <div className="flex items-center space-x-2">
+            <Terminal className="w-5 h-5 text-green-400" />
+            <h2 className="text-lg font-semibold text-white">Agent Activity Logs</h2>
+          </div>
+            <div className="flex items-center space-x-2">
+            <button
+              onClick={fetchLogs}
+              className="px-3 py-1 text-sm bg-gray-700 hover:bg-gray-600 text-white rounded transition-all flex items-center space-x-1"
+            >
+              <RefreshCw className="w-4 h-4" />
+              <span>Refresh</span>
+            </button>
+            <button
+              onClick={copyLogs}
+              className="px-3 py-1 text-sm bg-gray-700 hover:bg-gray-600 text-white rounded transition-all flex items-center space-x-1"
+            >
+              {copied ? (
+                <>
+                  <Check className="w-4 h-4" />
+                  <span>Copied!</span>
+                </>
+              ) : (
+                <>
+                  <Copy className="w-4 h-4" />
+                  <span>Copy</span>
+                </>
+              )}
+            </button>
+            <button
+              onClick={onClose}
+              className="px-3 py-1 text-sm bg-red-600 hover:bg-red-700 text-white rounded transition-all flex items-center space-x-1"
+            >
+              <X className="w-4 h-4" />
+              <span>Close</span>
+            </button>
+          </div>
+        </div>
+
+        {/* Logs Content */}
+        <div className="flex-1 overflow-y-auto p-4 font-mono text-sm bg-gray-950 scrollbar-hide">
+          {logs.length === 0 ? (
+            <div className="text-gray-500 text-center py-8">
+              No logs available yet
+            </div>
+          ) : (
+            <div className="space-y-1">
+              {logs.map((log, index) => (
+                <div 
+                  key={index} 
+                  className="flex items-start space-x-2 text-gray-300 hover:bg-gray-800 px-2 py-1 rounded"
+                >
+                  <span className="text-gray-500 text-xs min-w-[70px]">
+                    {new Date(log.timestamp).toLocaleTimeString()}
+                  </span>
+                  <span className={`font-semibold min-w-[80px] ${
+                    log.type === 'info' ? 'text-blue-400' :
+                    log.type === 'warning' ? 'text-yellow-400' :
+                    log.type === 'error' ? 'text-red-400' :
+                    log.type === 'success' ? 'text-green-400' :
+                    'text-gray-400'
+                  }`}>
+                    [{log.type.toUpperCase()}]
+                  </span>
+                  <span className="flex-1">{log.message}</span>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="bg-gray-800 px-4 py-2 rounded-b-lg border-t border-gray-700 text-xs text-gray-400">
+          💡 These logs show agent routing decisions and activity in real-time
+        </div>
+      </div>
+    </div>
+  )
+}
+
diff --git a/MultiAgentQnA/ui/src/components/SettingsPage.jsx b/MultiAgentQnA/ui/src/components/SettingsPage.jsx
new file mode 100644
index 0000000000..9893a5fdbc
--- /dev/null
+++ b/MultiAgentQnA/ui/src/components/SettingsPage.jsx
@@ -0,0 +1,245 @@
+import { useState, useEffect } from 'react'
+import { Save, Code, FileText, MessageCircle, Settings as SettingsIcon } from 'lucide-react'
+import { getAgentConfig, updateAgentConfig } from '../services/api'
+
+export default function SettingsPage() {
+  const [config, setConfig] = useState({
+    orchestration: {
+      role: '',
+      goal: '',
+      backstory: '',
+      max_iter: 15,
+      verbose: true
+    },
+    code: {
+      role: '',
+      goal: '',
+      backstory: '',
+      max_iter: 15,
+      verbose: true
+    },
+    rag: {
+      role: '',
+      goal: '',
+      backstory: '',
+      max_iter: 15,
+      verbose: true
+    },
+    normal: {
+      role: '',
+      goal: '',
+      backstory: '',
+      max_iter: 15,
+      verbose: true
+    }
+  })
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [isSaving, setIsSaving] = useState(false)
+  const [message, setMessage] = useState('')
+
+  useEffect(() => {
+    loadConfig()
+  }, [])
+
+  const loadConfig = async () => {
+    setIsLoading(true)
+    try {
+      const response = await getAgentConfig()
+      setConfig(response.config)
+    } catch (error) {
+      setMessage('Failed to load configuration. Using defaults.')
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  const handleSave = async () => {
+    setIsSaving(true)
+    setMessage('')
+    
+    try {
+      await updateAgentConfig(config)
+      setMessage('Configuration saved successfully!')
+    } catch (error) {
+      setMessage('Failed to save configuration.')
+    } finally {
+      setIsSaving(false)
+      setTimeout(() => setMessage(''), 3000)
+    }
+  }
+
+  const handleAgentConfigChange = (agentType, field, value) => {
+    setConfig(prev => ({
+      ...prev,
+      [agentType]: {
+        ...prev[agentType],
+        [field]: value
+      }
+    }))
+  }
+
+  const AgentConfigCard = ({ agentType, agentName, icon: Icon, color }) => {
+    const colorClasses = {
+      purple: { bg: 'bg-purple-100', text: 'text-purple-600' },
+      blue: { bg: 'bg-blue-100', text: 'text-blue-600' },
+      green: { bg: 'bg-green-100', text: 'text-green-600' }
+    }
+    const classes = colorClasses[color] || colorClasses.purple
+    
+    return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+      <div className="flex items-center space-x-3 mb-4 pb-4 border-b border-gray-200">
+        <div className={`p-2 rounded-lg ${classes.bg}`}>
+          <Icon className={`w-6 h-6 ${classes.text}`} />
+        </div>
+        <h3 className="text-lg font-semibold text-gray-800">{agentName}</h3>
+      </div>
+
+      <div className="space-y-4">
+        <div>
+          <label className="block text-sm font-medium text-gray-700 mb-1">
+            Role
+          </label>
+          <input
+            type="text"
+            value={config[agentType].role}
+            onChange={(e) => handleAgentConfigChange(agentType, 'role', e.target.value)}
+            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-purple-500"
+            placeholder="e.g., Senior Software Developer"
+          />
+        </div>
+
+        <div>
+          <label className="block text-sm font-medium text-gray-700 mb-1">
+            Goal
+          </label>
+          <textarea
+            value={config[agentType].goal}
+            onChange={(e) => handleAgentConfigChange(agentType, 'goal', e.target.value)}
+            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-purple-500"
+            placeholder="Agent's primary goal"
+            rows="2"
+          />
+        </div>
+
+        <div>
+          <label className="block text-sm font-medium text-gray-700 mb-1">
+            Backstory
+          </label>
+          <textarea
+            value={config[agentType].backstory}
+            onChange={(e) => handleAgentConfigChange(agentType, 'backstory', e.target.value)}
+            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-purple-500"
+            placeholder="Agent's background and expertise"
+            rows="3"
+          />
+        </div>
+
+        <div className="grid grid-cols-2 gap-4">
+          <div>
+            <label className="block text-sm font-medium text-gray-700 mb-1">
+              Max Iterations
+            </label>
+            <input
+              type="number"
+              value={config[agentType].max_iter}
+              onChange={(e) => handleAgentConfigChange(agentType, 'max_iter', parseInt(e.target.value))}
+              className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-purple-500"
+              min="1"
+              max="50"
+            />
+          </div>
+
+          <div className="flex items-center pt-6">
+            <label className="flex items-center space-x-2 cursor-pointer">
+              <input
+                type="checkbox"
+                checked={config[agentType].verbose}
+                onChange={(e) => handleAgentConfigChange(agentType, 'verbose', e.target.checked)}
+                className="w-4 h-4 text-purple-600 border-gray-300 rounded focus:ring-purple-500"
+              />
+              <span className="text-sm font-medium text-gray-700">Verbose</span>
+            </label>
+          </div>
+        </div>
+      </div>
+    </div>
+    )
+  }
+
+  if (isLoading) {
+    return (
+      <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-12 flex items-center justify-center">
+        <div className="text-center">
+          <div className="w-12 h-12 border-4 border-purple-500 border-t-transparent rounded-full animate-spin mx-auto mb-4"></div>
+          <p className="text-gray-600">Loading configuration...</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+        <div className="flex items-center justify-between mb-4">
+          <div className="flex items-center space-x-3">
+            <SettingsIcon className="w-6 h-6 text-purple-600" />
+            <h2 className="text-xl font-bold text-gray-800">Agent Configuration</h2>
+          </div>
+          <button
+            onClick={handleSave}
+            disabled={isSaving}
+            className="px-6 py-2 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-lg hover:from-blue-600 hover:to-purple-700 disabled:opacity-50 disabled:cursor-not-allowed transition-all font-medium shadow-sm flex items-center space-x-2"
+          >
+            <Save className="w-4 h-4" />
+            <span>{isSaving ? 'Saving...' : 'Save Configuration'}</span>
+          </button>
+        </div>
+
+        {message && (
+          <div className={`p-3 rounded-lg mb-4 ${
+            message.includes('success') 
+              ? 'bg-green-50 text-green-700 border border-green-200' 
+              : 'bg-red-50 text-red-700 border border-red-200'
+          }`}>
+            {message}
+          </div>
+        )}
+
+        <p className="text-gray-600 text-sm">
+          Configure the behavior and expertise of each agent in the multi-agent system.
+          Changes will be applied to new conversations.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+        <AgentConfigCard
+          agentType="orchestration"
+          agentName="Orchestration Agent"
+          icon={SettingsIcon}
+          color="purple"
+        />
+        <AgentConfigCard
+          agentType="code"
+          agentName="Code Agent"
+          icon={Code}
+          color="blue"
+        />
+        <AgentConfigCard
+          agentType="rag"
+          agentName="RAG Agent"
+          icon={FileText}
+          color="purple"
+        />
+        <AgentConfigCard
+          agentType="normal"
+          agentName="General Agent"
+          icon={MessageCircle}
+          color="green"
+        />
+      </div>
+    </div>
+  )
+}
+
diff --git a/MultiAgentQnA/ui/src/index.css b/MultiAgentQnA/ui/src/index.css
new file mode 100644
index 0000000000..1a25c1afc4
--- /dev/null
+++ b/MultiAgentQnA/ui/src/index.css
@@ -0,0 +1,26 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+#root {
+  min-height: 100vh;
+}
+
+.scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+.scrollbar-hide::-webkit-scrollbar {
+  display: none;
+}
+
diff --git a/MultiAgentQnA/ui/src/main.jsx b/MultiAgentQnA/ui/src/main.jsx
new file mode 100644
index 0000000000..299bc52310
--- /dev/null
+++ b/MultiAgentQnA/ui/src/main.jsx
@@ -0,0 +1,11 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
+
diff --git a/MultiAgentQnA/ui/src/services/api.js b/MultiAgentQnA/ui/src/services/api.js
new file mode 100644
index 0000000000..1d050388a8
--- /dev/null
+++ b/MultiAgentQnA/ui/src/services/api.js
@@ -0,0 +1,132 @@
+import axios from 'axios'
+
+// API base URL - uses Vite proxy in development (proxies to localhost:5001)
+const API_BASE_URL = import.meta.env.VITE_API_URL || '/api'
+
+const api = axios.create({
+  baseURL: API_BASE_URL,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+})
+
+/**
+ * Send a chat message to the multi-agent system
+ * @param {string} message - The user message
+ * @param {Object} agentConfig - Optional agent configuration
+ * @returns {Promise} Response with the answer and agent used
+ */
+export const sendChatMessage = async (message, agentConfig = null) => {
+  try {
+    const response = await api.post('/chat', { 
+      message,
+      agent_config: agentConfig
+    })
+    return response.data
+  } catch (error) {
+    console.error('Chat error:', error)
+    throw new Error(
+      error.response?.data?.detail || 'Failed to get response. Please try again.'
+    )
+  }
+}
+
+/**
+ * Get current agent configuration
+ * @returns {Promise} Agent configuration
+ */
+export const getAgentConfig = async () => {
+  try {
+    const response = await api.get('/config')
+    return response.data
+  } catch (error) {
+    console.error('Config fetch error:', error)
+    throw new Error('Failed to fetch configuration')
+  }
+}
+
+/**
+ * Update agent configuration
+ * @param {Object} config - Agent configuration
+ * @returns {Promise} Update status
+ */
+export const updateAgentConfig = async (config) => {
+  try {
+    const response = await api.post('/config', config)
+    return response.data
+  } catch (error) {
+    console.error('Config update error:', error)
+    throw new Error(
+      error.response?.data?.detail || 'Failed to update configuration'
+    )
+  }
+}
+
+/**
+ * Check API health
+ * @returns {Promise} Health status
+ */
+export const checkHealth = async () => {
+  try {
+    const response = await api.get('/health')
+    return response.data
+  } catch (error) {
+    console.error('Health check error:', error)
+    throw new Error('API is not available')
+  }
+}
+
+/**
+ * Get agent activity logs
+ * @returns {Promise} Agent logs
+ */
+export const getLogs = async () => {
+  try {
+    const response = await api.get('/logs')
+    return response.data
+  } catch (error) {
+    console.error('Logs fetch error:', error)
+    throw new Error('Failed to fetch logs')
+  }
+}
+
+/**
+ * Upload a PDF file for RAG indexing
+ * @param {File} file - PDF file to upload
+ * @returns {Promise} Upload result
+ */
+export const uploadPDF = async (file) => {
+  try {
+    const formData = new FormData()
+    formData.append('file', file)
+    
+    const response = await api.post('/rag/upload', formData, {
+      headers: {
+        'Content-Type': 'multipart/form-data',
+      },
+    })
+    return response.data
+  } catch (error) {
+    console.error('PDF upload error:', error)
+    throw new Error(
+      error.response?.data?.detail || 'Failed to upload PDF'
+    )
+  }
+}
+
+/**
+ * Get RAG index status
+ * @returns {Promise} RAG status
+ */
+export const getRAGStatus = async () => {
+  try {
+    const response = await api.get('/rag/status')
+    return response.data
+  } catch (error) {
+    console.error('RAG status error:', error)
+    throw new Error('Failed to fetch RAG status')
+  }
+}
+
+export default api
+
diff --git a/MultiAgentQnA/ui/tailwind.config.js b/MultiAgentQnA/ui/tailwind.config.js
new file mode 100644
index 0000000000..d37737fc01
--- /dev/null
+++ b/MultiAgentQnA/ui/tailwind.config.js
@@ -0,0 +1,12 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+
diff --git a/MultiAgentQnA/ui/vite.config.js b/MultiAgentQnA/ui/vite.config.js
new file mode 100644
index 0000000000..a20f408af9
--- /dev/null
+++ b/MultiAgentQnA/ui/vite.config.js
@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: true,
+    port: 3000,
+    proxy: {
+      '/api': {
+        target: 'http://backend:5001',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, '')
+      }
+    }
+  }
+})
+
diff --git a/PdfToPodcast/.env.example b/PdfToPodcast/.env.example
new file mode 100644
index 0000000000..f4a431d1f0
--- /dev/null
+++ b/PdfToPodcast/.env.example
@@ -0,0 +1,15 @@
+# Backend Configuration
+CORS_ORIGINS=http://localhost:3000
+
+# Service URLs (for local development)
+PDF_SERVICE_URL=http://pdf-service:8001
+LLM_SERVICE_URL=http://llm-service:8002
+TTS_SERVICE_URL=http://tts-service:8003
+BACKEND_API_URL=http://localhost:8000
+
+# File Upload Configuration
+MAX_FILE_SIZE=10485760  # 10MB in bytes
+
+# Environment
+NODE_ENV=development
+PYTHON_ENV=development
diff --git a/PdfToPodcast/.gitignore b/PdfToPodcast/.gitignore
new file mode 100644
index 0000000000..ddbd29e73c
--- /dev/null
+++ b/PdfToPodcast/.gitignore
@@ -0,0 +1,79 @@
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+venv/
+env/
+ENV/
+.venv
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-debug.log*
+dist/
+dist-ssr/
+*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Docker
+*.log
+
+# Uploads and outputs
+uploads/
+outputs/
+*.mp3
+*.wav
+microservices/tts-service/static/audio/
+
+# Exception: Allow voice sample files
+!ui/public/voice-samples/*.mp3
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Misc
+.cache/
+*.bak
+*.tmp
diff --git a/PdfToPodcast/Dockerfile b/PdfToPodcast/Dockerfile
new file mode 100644
index 0000000000..a2e48a3c82
--- /dev/null
+++ b/PdfToPodcast/Dockerfile
@@ -0,0 +1,18 @@
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file first to leverage Docker layer caching
+COPY requirements.txt .
+
+RUN pip install -r requirements.txt
+
+# Copy the rest of the application files into the container
+COPY simple_backend.py .
+
+# Expose the port the service runs on
+EXPOSE 8000
+
+# Command to run the application
+CMD ["python", "-m", "uvicorn", "simple_backend:app", "--host", "0.0.0.0", "--port", "8000"]
\ No newline at end of file
diff --git a/PdfToPodcast/README.md b/PdfToPodcast/README.md
new file mode 100644
index 0000000000..4add705f69
--- /dev/null
+++ b/PdfToPodcast/README.md
@@ -0,0 +1,252 @@
+## PDF to Podcast Generator
+
+AI-powered application that transforms PDF documents into engaging podcast-style audio conversations. This application can be deployed using either OpenAI APIs or enterprise inference endpoints.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick Start Deployment](#quick-start-deployment)
+- [User Interface](#user-interface)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Overview
+
+PDF to Podcast Generator is a microservices-based application that converts PDF documents into natural podcast-style audio conversations. The system extracts text from PDFs, generates engaging dialogue using Large Language Models, and synthesizes high-quality audio using Text-to-Speech technology.
+
+---
+
+## Features
+
+- Digital PDF text extraction with support for text-based PDFs up to 10 MB
+- AI-powered script generation with natural host and guest conversation format
+- Supports multiple LLM backends: OpenAI GPT-4 or custom enterprise inference endpoints
+- High-quality audio generation using OpenAI TTS with 6 different voice options
+- Modern React web interface with real-time progress tracking
+- Integrated audio player with waveform visualization
+- Project management and organization with download functionality
+- RESTful API for integration with JSON-based communication
+
+---
+
+## Architecture
+
+This application uses a microservices architecture where each service handles a specific part of the podcast generation process. The React frontend communicates with a backend gateway that orchestrates requests across three specialized services: PDF processing, script generation, and audio synthesis. The LLM service can be configured to use either OpenAI GPT models or custom enterprise inference endpoints with Keycloak authentication, while the TTS service uses OpenAI for audio generation. This separation allows for flexible deployment options and easy scaling of individual components.
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        A[React Web UI<br/>Port 3000]
+    end
+
+    subgraph "API Gateway Layer"
+        B[Backend Gateway<br/>Port 8000]
+    end
+
+    subgraph "Processing Services"
+        C[PDF Service<br/>Port 8001]
+        D[LLM Service<br/>Port 8002]
+        E[TTS Service<br/>Port 8003]
+    end
+
+    subgraph "External Services"
+        F[OpenAI GPT-4 / Enterprise LLM]
+        G[OpenAI TTS]
+    end
+
+    A -->|HTTP POST| B
+    B -->|PDF Upload| C
+    B -->|Script Request| D
+    B -->|Audio Request| E
+    C -->|Extracted Text| B
+    D -->|API Request| F
+    F -->|Script| D
+    D -->|Dialogue Script| B
+    E -->|API Request| G
+    G -->|Audio Segments| E
+    E -->|Mixed Audio| B
+    B -->|JSON Response| A
+
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#ffe1f5
+    style D fill:#ffe1f5
+    style E fill:#ffe1f5
+    style F fill:#e1ffe1
+    style G fill:#e1ffe1
+```
+
+This application is built using FastAPI microservices architecture with Docker containerization.
+
+**Service Components:**
+
+1. **React Web UI (Port 3000)** - Handles file uploads, displays generation progress, and provides audio playback interface
+
+2. **Backend Gateway (Port 8000)** - Routes requests to microservices and manages job lifecycle and state
+
+3. **PDF Service (Port 8001)** - Extracts text from PDF files using PyPDF2 and pdfplumber libraries (no external API dependencies)
+
+4. **LLM Service (Port 8002)** - Generates podcast dialogue scripts using OpenAI GPT-4 or custom enterprise inference endpoints with Keycloak authentication
+
+5. **TTS Service (Port 8003)** - Synthesizes audio using OpenAI TTS API with multiple voice support and audio mixing
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+Before you begin, ensure you have the following installed:
+
+- **Docker and Docker Compose**
+- **Enterprise inference endpoint access** (Keycloak authentication)
+- **OpenAPI KEY** (Need OpenAPI Key as enterprise inference doesn't have supported models for Audio and Video )
+
+### Verify Docker Installation
+
+```bash
+# Check Docker version
+docker --version
+
+# Check Docker Compose version
+docker compose version
+
+# Verify Docker is running
+docker ps
+```
+
+## Quick Start Deployment
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/opea-project/GenAIExamples.git
+cd GenAIExamples/PdfToPodcast
+```
+
+### Set up the Environment
+
+Each service needs its own `.env` file. Copy the example files and edit with your credentials.
+
+**1. PDF Service Configuration:**
+
+```bash
+cp api/pdf-service/.env.example api/pdf-service/.env
+```
+
+No changes needed. Uses default values.
+
+**2. TTS Service Configuration:**
+
+```bash
+cp api/tts-service/.env.example api/tts-service/.env
+```
+
+Open `api/tts-service/.env` and replace `your-openai-api-key-here` with your actual OpenAI API key.
+
+Available TTS voices: alloy, echo, fable, onyx, nova, shimmer. Default voices are alloy (host) and nova (guest).
+
+**3. LLM Service Configuration:**
+
+```bash
+cp api/llm-service/.env.example api/llm-service/.env
+```
+
+- Replace these placeholder values:
+  - `BASE_URL` with your enterprise API endpoint
+  - `KEYCLOAK_CLIENT_SECRET` with your actual client secret
+  - `INFERENCE_MODEL_ENDPOINT` if different from default
+  - `INFERENCE_MODEL_NAME` if different from default
+
+**4. Backend Service Configuration:**
+
+```bash
+cp .env.example .env
+```
+No changes needed. Uses default values.
+
+### Running the Application
+
+Start both API and UI services together with Docker Compose:
+
+```bash
+# From the PdfToPodcast directory
+docker compose up --build
+
+# Or run in detached mode (background)
+docker compose up -d --build
+```
+The Backend will be available at: http://localhost:8000
+
+The UI will be available at: http://localhost:3000
+
+The LLM-service will be available at: http://localhost:8002
+
+The PDF-service will be available at: http://localhost:8001
+
+The TTS-service will be available at: http://localhost:8003
+
+**View logs**:
+
+```bash
+# All services
+docker compose logs -f
+
+# Backend only
+docker compose logs -f backend
+
+# Frontend only
+docker compose logs -f frontend
+```
+
+**Verify the services are running**:
+
+```bash
+# Check API health
+curl http://localhost:8002/health
+
+# Check if containers are running
+docker compose ps
+```
+
+## User Interface
+
+**Using the Application**
+
+Make sure you are at the localhost:3000 url
+
+**Test the Application**
+
+1. Upload a PDF file (max 10MB)
+2. Wait for text extraction
+3. Select host and guest voices
+4. Click "Generate Script" and wait 15-30 seconds
+5. Review generated script
+6. Click "Generate Audio" and wait 30-60 seconds
+7. Listen to your podcast
+
+![Home Page](./ui/public/homepage.png)
+
+![Upload PDF](./ui/public/upload_pdf.png)
+
+![Select Voices](./ui/public/select_voices.png)
+
+![Final Podcast](./ui/public/final_podcast_page.png)
+
+
+### Stopping the Application
+
+
+```bash
+docker compose down
+```
+
+## Troubleshooting
+
+For detailed troubleshooting guidance and solutions to common issues, refer to:
+
+[TROUBLESHOOTING_and_ADDITIONAL_INFO.md](./TROUBLESHOOTING_and_ADDITIONAL_INFO.md)
diff --git a/PdfToPodcast/TROUBLESHOOTING_and_ADDITIONAL_INFO.md b/PdfToPodcast/TROUBLESHOOTING_and_ADDITIONAL_INFO.md
new file mode 100644
index 0000000000..d85e225080
--- /dev/null
+++ b/PdfToPodcast/TROUBLESHOOTING_and_ADDITIONAL_INFO.md
@@ -0,0 +1,191 @@
+# Troubleshooting Guide
+
+This guide provides solutions to common issues you may encounter while using the PDF to Podcast Generator.
+
+## Services Not Starting
+
+**Check container status:**
+```bash
+docker compose ps
+```
+
+**View error logs:**
+```bash
+docker compose logs backend
+```
+
+**Common issues:**
+
+1. **Port conflicts** - Ports 3000, 8000-8003 already in use
+   ```bash
+   # Windows
+   netstat -ano | findstr "3000 8000 8001 8002 8003"
+
+   # Linux/Mac
+   lsof -i :3000
+   ```
+
+2. **Missing API key** - Verify `.env` file contains valid OpenAI key
+
+3. **Insufficient memory** - Docker Desktop needs at least 4GB RAM
+
+4. **Docker not running** - Start Docker Desktop and wait for initialization
+
+## PDF Upload Fails
+
+**Possible causes:**
+- File exceeds 10MB limit
+- PDF is encrypted or password-protected
+- PDF contains only images without text
+- File is corrupted
+
+**Solutions:**
+```bash
+# Check PDF service logs
+docker compose logs pdf-service
+
+# Verify file size
+ls -lh your-file.pdf
+```
+
+## Script Generation Fails
+
+**Check OpenAI API status:**
+```bash
+# Test API key directly
+curl https://api.openai.com/v1/models \
+  -H "Authorization: Bearer sk-proj-your-key-here"
+```
+
+**Common issues:**
+- Invalid or expired API key
+- Insufficient API credits or quota exceeded
+- Rate limit reached
+- Network connectivity problems
+- PDF text extraction failed
+
+**Check LLM service logs:**
+```bash
+docker compose logs llm-service
+```
+
+## Audio Generation Fails
+
+**Verify TTS service:**
+```bash
+# Check if service is running
+docker compose ps tts-service
+
+# View TTS logs
+docker compose logs tts-service
+```
+
+**Common issues:**
+- OpenAI TTS API rate limits
+- Insufficient API credits
+- Network timeout during audio synthesis
+- Audio mixing errors
+- FFmpeg not available in container (should be installed via Dockerfile)
+
+## Audio Not Playing
+
+**Browser console errors:**
+- Open browser DevTools (F12)
+- Check Console tab for errors
+- Verify audio URL is accessible
+- Check CORS headers
+
+**Verify backend connectivity:**
+```bash
+curl http://localhost:8000/health
+```
+
+## Frontend Not Loading
+
+**Check frontend service:**
+```bash
+# View frontend logs
+docker compose logs frontend
+
+# Verify backend is accessible
+curl http://localhost:8000
+```
+
+**Common issues:**
+- Backend service not ready
+- CORS configuration incorrect
+- Port 3000 already in use
+- Build errors in frontend code
+
+## Service Management
+
+**View all service logs:**
+```bash
+docker compose logs -f
+```
+
+**Restart specific service:**
+```bash
+docker compose restart backend
+docker compose restart frontend
+```
+
+**Restart all services:**
+```bash
+docker compose restart
+```
+
+**Stop all services:**
+```bash
+docker compose down
+```
+
+**Rebuild and restart:**
+```bash
+docker compose up -d --build
+```
+
+## Clean Up and Restart
+
+**Complete reset:**
+```bash
+# Stop all containers
+docker compose down
+
+# Remove volumes
+docker volume prune
+
+# Remove images
+docker compose down --rmi all
+
+# Fresh start
+docker compose up -d --build
+```
+
+## Performance Metrics
+
+| Operation | Typical Duration | Notes |
+|-----------|------------------|-------|
+| PDF Upload | 1-3 seconds | Depends on file size |
+| Text Extraction | 2-5 seconds | For standard PDFs |
+| Script Generation | 15-25 seconds | Using GPT-4 |
+| Audio Generation | 20-40 seconds | For 2-minute podcast |
+| Total Workflow | 40-70 seconds | From PDF to audio |
+
+## Audio Specifications
+
+- Format: MP3
+- Bitrate: 192 kbps
+- Sample Rate: 24 kHz
+- File Size: Approximately 2-3 MB per minute
+- Quality: High-quality conversational audio
+
+## Getting Additional Help
+
+For issues not covered in this guide:
+1. Review service logs with `docker compose logs`
+2. Verify OpenAI API key and available credits
+3. Check Docker container status with `docker compose ps`
+4. Monitor API usage at https://platform.openai.com/usage
+5. Review OpenAI TTS Documentation: https://platform.openai.com/docs/guides/text-to-speech
+6. Check OpenAI API Reference: https://platform.openai.com/docs/api-reference
diff --git a/PdfToPodcast/api/llm-service/.env.example b/PdfToPodcast/api/llm-service/.env.example
new file mode 100644
index 0000000000..d81a359cba
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/.env.example
@@ -0,0 +1,20 @@
+# Custom API Configuration (Uncomment to use custom inference endpoint)
+BASE_URL=https://your-api-endpoint.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your-client-secret
+INFERENCE_MODEL_ENDPOINT=DeepSeek-R1-Distill-Qwen-32B
+INFERENCE_MODEL_NAME=deepseek-ai/DeepSeek-R1-Distill-Qwen-32B
+
+# Service Configuration
+SERVICE_PORT=8002
+
+# Model Settings
+DEFAULT_MODEL=gpt-4o-mini
+DEFAULT_TONE=conversational
+DEFAULT_MAX_LENGTH=2000
+
+# Generation Parameters
+TEMPERATURE=0.7
+MAX_TOKENS=4000
+MAX_RETRIES=3
diff --git a/PdfToPodcast/api/llm-service/Dockerfile b/PdfToPodcast/api/llm-service/Dockerfile
new file mode 100644
index 0000000000..2cea57c263
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/Dockerfile
@@ -0,0 +1,20 @@
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file into the container
+COPY requirements.txt .
+
+
+# Install Python dependencies
+RUN pip install -r requirements.txt
+
+# Copy the rest of the application files into the container
+COPY . .
+
+# Expose the port the service runs on
+EXPOSE 8002
+
+# Command to run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8002"]
diff --git a/PdfToPodcast/api/llm-service/README.md b/PdfToPodcast/api/llm-service/README.md
new file mode 100644
index 0000000000..16eefe7970
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/README.md
@@ -0,0 +1,249 @@
+# LLM Script Generation Microservice
+
+Converts PDF text into engaging podcast dialogue using OpenAI GPT-4.
+
+## Features
+
+**OpenAI Integration**
+- GPT-4 Turbo for high-quality scripts
+- GPT-3.5 Turbo for faster generation
+- Automatic retry with exponential backoff
+
+**Intelligent Dialogue Generation**
+- Natural, conversational podcast scripts
+- Host and guest roles
+- Questions, reactions, and transitions
+- Context-aware explanations
+
+**Multiple Conversation Tones**
+- Conversational (friendly, accessible)
+- Educational (structured, informative)
+- Professional (polished, authoritative)
+
+**Script Formatting & Validation**
+- JSON output parsing
+- Format validation
+- TTS preparation
+- Metadata calculation
+
+## API Endpoints
+
+### 1. Generate Script
+
+**POST** `/generate-script`
+
+Convert text content into podcast dialogue.
+
+**Request:**
+```json
+{
+  "text": "PDF content here...",
+  "host_name": "Alex",
+  "guest_name": "Sam",
+  "tone": "conversational",
+  "max_length": 2000,
+  "provider": "openai",
+  "job_id": "optional-tracking-id"
+}
+```
+
+**Response:**
+```json
+{
+  "script": [
+    {
+      "speaker": "host",
+      "text": "Welcome to today's show! We're exploring..."
+    },
+    {
+      "speaker": "guest",
+      "text": "Thanks for having me! This topic is fascinating because..."
+    }
+  ],
+  "metadata": {
+    "total_turns": 24,
+    "host_turns": 12,
+    "guest_turns": 12,
+    "total_words": 1850,
+    "estimated_duration_minutes": 12.3,
+    "tone": "conversational"
+  },
+  "status": "success"
+}
+```
+
+### 2. Refine Script
+
+**POST** `/refine-script`
+
+Improve an existing script.
+
+**Request:**
+```json
+{
+  "script": [
+    {"speaker": "host", "text": "..."},
+    {"speaker": "guest", "text": "..."}
+  ],
+  "provider": "openai"
+}
+```
+
+### 3. Validate Content
+
+**POST** `/validate-content`
+
+Check if content is suitable for podcast generation.
+
+**Response:**
+```json
+{
+  "valid": true,
+  "word_count": 1500,
+  "char_count": 9000,
+  "token_count": 2250,
+  "issues": [],
+  "recommendations": ["Consider using 'educational' tone for technical content"]
+}
+```
+
+### 4. Health Check
+
+**GET** `/health`
+
+Check service health and provider availability.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "openai_available": true,
+  "version": "1.0.0"
+}
+```
+
+### 5. Get Tones
+
+**GET** `/tones`
+
+List available conversation tones.
+
+### 6. Get Models
+
+**GET** `/models`
+
+List available LLM models.
+
+## Prerequisites
+
+- OpenAI API key
+- Python 3.9+
+
+## Installation
+
+### Using Docker
+
+```bash
+cd microservices/llm-service
+docker build -t llm-service .
+docker run -p 8002:8002 \
+  -e OPENAI_API_KEY=your_key \
+  llm-service
+```
+
+### Manual Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Configuration
+
+Create `.env` file:
+
+```env
+# Required
+OPENAI_API_KEY=sk-proj-your-key-here
+
+# Optional
+DEFAULT_MODEL=gpt-4-turbo-preview
+DEFAULT_TONE=conversational
+DEFAULT_MAX_LENGTH=2000
+TEMPERATURE=0.7
+MAX_TOKENS=4000
+SERVICE_PORT=8002
+```
+
+## Usage Examples
+
+### Python
+
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8002/generate-script",
+    json={
+        "text": "Your PDF content here...",
+        "host_name": "Alex",
+        "guest_name": "Jordan",
+        "tone": "conversational",
+        "max_length": 2000
+    }
+)
+
+result = response.json()
+print(f"Generated {len(result['script'])} dialogue turns")
+```
+
+### cURL
+
+```bash
+curl -X POST http://localhost:8002/generate-script \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Content to convert...",
+    "tone": "educational",
+    "max_length": 1500
+  }'
+```
+
+## Testing
+
+Test script generation:
+```bash
+curl -X POST http://localhost:8002/generate-script \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Test content", "tone": "conversational"}'
+```
+
+Test health:
+```bash
+curl http://localhost:8002/health
+```
+
+## Troubleshooting
+
+### OpenAI API Errors
+
+**Error**: `AuthenticationError`
+- Check `OPENAI_API_KEY` in environment
+- Verify key is active
+
+**Error**: `RateLimitError`
+- Service will retry automatically
+
+### Slow Response Times
+
+**Causes**:
+- Large content (> 5000 words)
+- API rate limits
+
+**Solutions**:
+- Break content into sections
+- Use faster model (gpt-3.5-turbo)
+- Reduce max_length
+
+## API Documentation
+
+View interactive API docs at `http://localhost:8002/docs`
diff --git a/PdfToPodcast/api/llm-service/app/__init__.py b/PdfToPodcast/api/llm-service/app/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/llm-service/app/api/__init__.py b/PdfToPodcast/api/llm-service/app/api/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/llm-service/app/api/routes.py b/PdfToPodcast/api/llm-service/app/api/routes.py
new file mode 100644
index 0000000000..94a43c9b46
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/api/routes.py
@@ -0,0 +1,194 @@
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict
+import logging
+
+from app.core.dialogue_generator import DialogueGenerator
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+# Initialize dialogue generator
+dialogue_generator = DialogueGenerator(
+    openai_api_key=settings.OPENAI_API_KEY,
+    default_model=settings.DEFAULT_MODEL
+)
+
+class GenerateScriptRequest(BaseModel):
+    text: str = Field(..., description="PDF content to convert")
+    host_name: str = Field(default="Host", description="Host name")
+    guest_name: str = Field(default="Guest", description="Guest name")
+    tone: str = Field(default="conversational", description="Conversation tone")
+    max_length: int = Field(default=2000, description="Target word count")
+    provider: str = Field(default="openai", description="LLM provider (openai only)")
+    job_id: Optional[str] = Field(default=None, description="Optional job ID")
+
+class RefineScriptRequest(BaseModel):
+    script: List[Dict[str, str]] = Field(..., description="Script to refine")
+    provider: str = Field(default="openai", description="LLM provider")
+
+class ValidateContentRequest(BaseModel):
+    text: str = Field(..., description="Content to validate")
+
+class ScriptResponse(BaseModel):
+    script: List[Dict[str, str]]
+    metadata: Dict
+    status: str
+
+class ValidationResponse(BaseModel):
+    valid: bool
+    word_count: int
+    char_count: int
+    token_count: int
+    issues: List[str]
+    recommendations: List[str]
+
+class HealthResponse(BaseModel):
+    status: str
+    llm_available: bool
+    llm_provider: str
+    version: str
+
+@router.post("/generate-script", response_model=ScriptResponse)
+async def generate_script(request: GenerateScriptRequest):
+    """
+    Generate podcast script from text content
+
+    - **text**: Source content from PDF
+    - **host_name**: Name for the host (default: "Host")
+    - **guest_name**: Name for the guest (default: "Guest")
+    - **tone**: Conversation tone (conversational/educational/professional)
+    - **max_length**: Target word count (default: 2000)
+    - **provider**: LLM provider (openai only, default: openai)
+    - **job_id**: Optional job ID for tracking
+
+    Returns podcast script with metadata
+    """
+    try:
+        logger.info(f"Generating script: tone={request.tone}, provider={request.provider}")
+
+        result = await dialogue_generator.generate_script(
+            text=request.text,
+            host_name=request.host_name,
+            guest_name=request.guest_name,
+            tone=request.tone,
+            max_length=request.max_length,
+            provider=request.provider
+        )
+
+        if request.job_id:
+            result["metadata"]["job_id"] = request.job_id
+
+        return ScriptResponse(**result)
+
+    except ValueError as e:
+        logger.error(f"Validation error: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Script generation failed: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Script generation failed: {str(e)}"
+        )
+
+@router.post("/refine-script", response_model=ScriptResponse)
+async def refine_script(request: RefineScriptRequest):
+    """
+    Refine an existing podcast script
+
+    - **script**: Current script to refine
+    - **provider**: LLM provider (default: openai)
+
+    Returns refined script with metadata
+    """
+    try:
+        logger.info(f"Refining script with {len(request.script)} turns")
+
+        result = await dialogue_generator.refine_script(
+            script=request.script,
+            provider=request.provider
+        )
+
+        return ScriptResponse(**result)
+
+    except Exception as e:
+        logger.error(f"Script refinement failed: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Script refinement failed: {str(e)}"
+        )
+
+@router.post("/validate-content", response_model=ValidationResponse)
+async def validate_content(request: ValidateContentRequest):
+    """
+    Validate if content is suitable for podcast generation
+
+    - **text**: Content to validate
+
+    Returns validation results with recommendations
+    """
+    try:
+        result = dialogue_generator.validate_content_length(request.text)
+        return ValidationResponse(**result)
+
+    except Exception as e:
+        logger.error(f"Validation failed: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Validation failed: {str(e)}"
+        )
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Check service health and LLM provider availability"""
+    llm_available = dialogue_generator.llm_client.is_available()
+
+    # Determine which provider is being used
+    if settings.BASE_URL and settings.KEYCLOAK_CLIENT_SECRET:
+        llm_provider = "Custom API (Keycloak)"
+    else:
+        llm_provider = "OpenAI"
+
+    return HealthResponse(
+        status="healthy" if llm_available else "degraded",
+        llm_available=llm_available,
+        llm_provider=llm_provider,
+        version="1.0.0"
+    )
+
+@router.get("/tones")
+async def get_available_tones():
+    """Get list of available conversation tones"""
+    return {
+        "tones": [
+            {
+                "id": "conversational",
+                "name": "Conversational",
+                "description": "Warm, friendly, and accessible conversation"
+            },
+            {
+                "id": "educational",
+                "name": "Educational",
+                "description": "Informative and structured learning experience"
+            },
+            {
+                "id": "professional",
+                "name": "Professional",
+                "description": "Polished and authoritative discussion"
+            }
+        ],
+        "default": "conversational"
+    }
+
+@router.get("/models")
+async def get_available_models():
+    """Get list of available LLM models"""
+    return {
+        "openai": [
+            "gpt-4-turbo-preview",
+            "gpt-4",
+            "gpt-3.5-turbo"
+        ],
+        "default": "gpt-4-turbo-preview"
+    }
diff --git a/PdfToPodcast/api/llm-service/app/config.py b/PdfToPodcast/api/llm-service/app/config.py
new file mode 100644
index 0000000000..0389d4ff2f
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/config.py
@@ -0,0 +1,39 @@
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+class Settings(BaseSettings):
+    """LLM Service Configuration"""
+
+    # Service info
+    SERVICE_NAME: str = "LLM Script Generation Service"
+    SERVICE_VERSION: str = "1.0.0"
+    SERVICE_PORT: int = 8002
+
+    # API Keys
+    OPENAI_API_KEY: Optional[str] = None
+
+    # Custom API Configuration
+    BASE_URL: Optional[str] = None
+    KEYCLOAK_REALM: str = "master"
+    KEYCLOAK_CLIENT_ID: str = "api"
+    KEYCLOAK_CLIENT_SECRET: Optional[str] = None
+
+    # Model Configuration
+    INFERENCE_MODEL_ENDPOINT: str = "DeepSeek-R1-Distill-Qwen-32B"
+    INFERENCE_MODEL_NAME: str = "deepseek-ai/DeepSeek-R1-Distill-Qwen-32B"
+
+    # Model settings
+    DEFAULT_MODEL: str = "gpt-4o-mini"  # Updated to current model
+    DEFAULT_TONE: str = "conversational"
+    DEFAULT_MAX_LENGTH: int = 2000
+
+    # Generation parameters
+    TEMPERATURE: float = 0.7
+    MAX_TOKENS: int = 4000
+    MAX_RETRIES: int = 3
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+settings = Settings()
diff --git a/PdfToPodcast/api/llm-service/app/core/__init__.py b/PdfToPodcast/api/llm-service/app/core/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/llm-service/app/core/dialogue_generator.py b/PdfToPodcast/api/llm-service/app/core/dialogue_generator.py
new file mode 100644
index 0000000000..1a716500d5
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/core/dialogue_generator.py
@@ -0,0 +1,222 @@
+import logging
+from typing import Dict, List, Optional
+from app.core.llm_client import LLMClient
+from app.core.prompt_builder import PromptBuilder
+from app.core.script_formatter import ScriptFormatter
+
+logger = logging.getLogger(__name__)
+
+class DialogueGenerator:
+    """
+    Main orchestrator for podcast dialogue generation
+    """
+
+    def __init__(
+        self,
+        openai_api_key: Optional[str] = None,
+        default_model: str = "gpt-4-turbo-preview"
+    ):
+        """
+        Initialize dialogue generator
+
+        Args:
+            openai_api_key: OpenAI API key
+            default_model: Default model to use
+        """
+        self.llm_client = LLMClient(
+            openai_api_key=openai_api_key,
+            default_model=default_model
+        )
+        self.prompt_builder = PromptBuilder()
+        self.formatter = ScriptFormatter()
+
+    async def generate_script(
+        self,
+        text: str,
+        host_name: str = "Host",
+        guest_name: str = "Guest",
+        tone: str = "conversational",
+        max_length: int = 2000,
+        provider: str = "openai",
+        **kwargs
+    ) -> Dict:
+        """
+        Generate podcast script from text
+
+        Args:
+            text: Source content
+            host_name: Host name
+            guest_name: Guest name
+            tone: Conversation tone
+            max_length: Target word count
+            provider: LLM provider to use
+            **kwargs: Additional parameters
+
+        Returns:
+            Dict with script and metadata
+        """
+        try:
+            logger.info(f"Generating script for {len(text)} chars of content")
+
+            # Validate input
+            if not text or len(text.strip()) < 50:
+                raise ValueError("Content too short for script generation")
+
+            # Build prompts
+            prompts = self.prompt_builder.build_generation_prompt(
+                content=text,
+                tone=tone,
+                max_length=max_length,
+                host_name=host_name,
+                guest_name=guest_name
+            )
+
+            # Generate with LLM
+            response = await self.llm_client.generate(
+                system_prompt=prompts["system"],
+                user_prompt=prompts["user"],
+                provider=provider,
+                temperature=0.7,
+                max_tokens=4000
+            )
+
+            # Parse and validate response
+            script = self.formatter.parse_llm_response(response)
+
+            if not self.formatter.validate_script(script):
+                raise ValueError("Generated script failed validation")
+
+            # Post-process script
+            script = self.formatter.merge_short_turns(script)
+            script = self.formatter.truncate_script(script, max_turns=50)
+
+            # Format for TTS
+            tts_script = self.formatter.format_for_tts(script)
+
+            # Calculate metadata
+            metadata = self.formatter.calculate_metadata(tts_script)
+            metadata["tone"] = tone
+            metadata["host_name"] = host_name
+            metadata["guest_name"] = guest_name
+            metadata["source_length"] = len(text)
+
+            logger.info(
+                f"Generated script: {metadata['total_turns']} turns, "
+                f"{metadata['estimated_duration_minutes']} min"
+            )
+
+            return {
+                "script": tts_script,
+                "metadata": metadata,
+                "status": "success"
+            }
+
+        except Exception as e:
+            logger.error(f"Script generation failed: {str(e)}")
+            raise
+
+    async def refine_script(
+        self,
+        script: List[Dict[str, str]],
+        provider: str = "openai"
+    ) -> Dict:
+        """
+        Refine an existing script
+
+        Args:
+            script: Current script
+            provider: LLM provider
+
+        Returns:
+            Dict with refined script and metadata
+        """
+        try:
+            logger.info(f"Refining script with {len(script)} turns")
+
+            # Build refinement prompts
+            prompts = self.prompt_builder.build_refinement_prompt(script)
+
+            # Generate refinement
+            response = await self.llm_client.generate(
+                system_prompt=prompts["system"],
+                user_prompt=prompts["user"],
+                provider=provider,
+                temperature=0.5,  # Lower temperature for refinement
+                max_tokens=4000
+            )
+
+            # Parse response
+            refined_script = self.formatter.parse_llm_response(response)
+
+            if not self.formatter.validate_script(refined_script):
+                logger.warning("Refined script invalid, returning original")
+                return {
+                    "script": script,
+                    "metadata": self.formatter.calculate_metadata(script),
+                    "status": "unchanged"
+                }
+
+            # Format and calculate metadata
+            tts_script = self.formatter.format_for_tts(refined_script)
+            metadata = self.formatter.calculate_metadata(tts_script)
+
+            logger.info("Script refinement successful")
+
+            return {
+                "script": tts_script,
+                "metadata": metadata,
+                "status": "refined"
+            }
+
+        except Exception as e:
+            logger.error(f"Script refinement failed: {str(e)}")
+            # Return original script on failure
+            return {
+                "script": script,
+                "metadata": self.formatter.calculate_metadata(script),
+                "status": "error",
+                "error": str(e)
+            }
+
+    def validate_content_length(self, text: str) -> Dict:
+        """
+        Validate if content is suitable for podcast generation
+
+        Args:
+            text: Content to validate
+
+        Returns:
+            Dict with validation results
+        """
+        word_count = len(text.split())
+        char_count = len(text)
+
+        # Check token count
+        token_count = self.llm_client.count_tokens(text)
+
+        issues = []
+        recommendations = []
+
+        # Too short
+        if word_count < 100:
+            issues.append("Content is very short")
+            recommendations.append("Add more context or background information")
+
+        # Too long
+        if token_count > 8000:
+            issues.append("Content may be too long for single request")
+            recommendations.append("Consider breaking into multiple sections")
+
+        # Very technical
+        technical_indicators = ["algorithm", "theorem", "equation", "formula"]
+        if any(word in text.lower() for word in technical_indicators):
+            recommendations.append("Consider using 'educational' tone for technical content")
+
+        return {
+            "valid": len(issues) == 0,
+            "word_count": word_count,
+            "char_count": char_count,
+            "token_count": token_count,
+            "issues": issues,
+            "recommendations": recommendations
+        }
diff --git a/PdfToPodcast/api/llm-service/app/core/llm_client.py b/PdfToPodcast/api/llm-service/app/core/llm_client.py
new file mode 100644
index 0000000000..efcdaa43f5
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/core/llm_client.py
@@ -0,0 +1,195 @@
+import openai
+from tenacity import retry, stop_after_attempt, wait_exponential
+import logging
+import json
+from typing import Dict, List, Optional
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+class LLMClient:
+    """
+    Client for interacting with OpenAI API or Custom API
+    """
+
+    def __init__(
+        self,
+        openai_api_key: Optional[str] = None,
+        default_model: str = "gpt-4-turbo-preview"
+    ):
+        """
+        Initialize LLM client
+
+        Args:
+            openai_api_key: OpenAI API key
+            default_model: Default model to use
+        """
+        self.openai_api_key = openai_api_key
+        self.default_model = default_model
+        self.custom_api_client = None
+        self.using_custom_api = False
+        self.openai_client = None
+
+        # Check if custom API is configured
+        if settings.BASE_URL and settings.KEYCLOAK_CLIENT_SECRET:
+            logger.info("Initializing LLM Client with custom API")
+            logger.info(f"Custom API Base URL: {settings.BASE_URL}")
+            logger.info(f"Model: {settings.INFERENCE_MODEL_NAME}")
+
+            try:
+                from app.services.api_client import get_api_client
+                self.custom_api_client = get_api_client()
+                if self.custom_api_client.is_authenticated():
+                    self.using_custom_api = True
+                    self.default_model = settings.INFERENCE_MODEL_NAME
+                    logger.info("Custom API client initialized successfully")
+                else:
+                    logger.error("Custom API authentication failed")
+            except Exception as e:
+                logger.error(f"Failed to initialize custom API client: {str(e)}")
+                self.using_custom_api = False
+        else:
+            logger.info("Initializing LLM Client with OpenAI")
+            # Initialize OpenAI client
+            if openai_api_key:
+                self.openai_client = openai.OpenAI(api_key=openai_api_key)
+            else:
+                self.openai_client = None
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=4, max=10)
+    )
+    async def generate_with_openai(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 4000
+    ) -> str:
+        """
+        Generate text using OpenAI or Custom API
+
+        Args:
+            system_prompt: System message
+            user_prompt: User message
+            model: Model to use (optional)
+            temperature: Sampling temperature
+            max_tokens: Maximum tokens to generate
+
+        Returns:
+            Generated text
+        """
+        # Use custom API if configured
+        if self.using_custom_api and self.custom_api_client:
+            try:
+                model = model or self.default_model
+                logger.info(f"Generating with custom API model: {model}")
+
+                messages = [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ]
+
+                content = self.custom_api_client.chat_complete(
+                    messages=messages,
+                    max_tokens=max_tokens,
+                    temperature=temperature
+                )
+
+                logger.info(f"Generated {len(content)} characters")
+                return content
+
+            except Exception as e:
+                logger.error(f"Custom API generation failed: {str(e)}")
+                raise
+
+        # Use OpenAI
+        if not self.openai_client:
+            raise ValueError("OpenAI API key not configured")
+
+        try:
+            model = model or self.default_model
+            logger.info(f"Generating with OpenAI model: {model}")
+
+            response = self.openai_client.chat.completions.create(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ],
+                temperature=temperature,
+                max_tokens=max_tokens,
+                response_format={"type": "json_object"} if "gpt-4" in model else None
+            )
+
+            content = response.choices[0].message.content
+            logger.info(f"Generated {len(content)} characters")
+
+            return content
+
+        except Exception as e:
+            logger.error(f"OpenAI generation failed: {str(e)}")
+            raise
+
+    async def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        provider: str = "openai",
+        **kwargs
+    ) -> str:
+        """
+        Generate text using OpenAI
+
+        Args:
+            system_prompt: System message
+            user_prompt: User message
+            provider: "openai" (for compatibility)
+            **kwargs: Additional parameters
+
+        Returns:
+            Generated text
+        """
+        return await self.generate_with_openai(
+            system_prompt,
+            user_prompt,
+            **kwargs
+        )
+
+    def count_tokens(self, text: str, model: str = "gpt-4") -> int:
+        """
+        Estimate token count for text
+
+        Args:
+            text: Text to count
+            model: Model for tokenization
+
+        Returns:
+            Estimated token count
+        """
+        try:
+            import tiktoken
+
+            encoding = tiktoken.encoding_for_model(model)
+            return len(encoding.encode(text))
+
+        except Exception as e:
+            logger.error(f"Token counting failed: {str(e)}")
+            # Rough estimate: ~4 characters per token
+            return len(text) // 4
+
+    def is_available(self, provider: str = "openai") -> bool:
+        """
+        Check if LLM client is available
+
+        Args:
+            provider: Provider to check
+
+        Returns:
+            True if available
+        """
+        if self.using_custom_api:
+            return self.custom_api_client is not None and self.custom_api_client.is_authenticated()
+        return self.openai_client is not None
diff --git a/PdfToPodcast/api/llm-service/app/core/prompt_builder.py b/PdfToPodcast/api/llm-service/app/core/prompt_builder.py
new file mode 100644
index 0000000000..93b5eb24ec
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/core/prompt_builder.py
@@ -0,0 +1,88 @@
+import logging
+from typing import Dict, Optional
+from app.prompts.templates import (
+    get_system_prompt,
+    get_user_prompt,
+    get_content_length_prompt
+)
+
+logger = logging.getLogger(__name__)
+
+class PromptBuilder:
+    """
+    Build prompts for podcast script generation
+    """
+
+    def __init__(self):
+        self.system_prompt = get_system_prompt()
+
+    def build_generation_prompt(
+        self,
+        content: str,
+        tone: str = "conversational",
+        max_length: int = 2000,
+        host_name: str = "Host",
+        guest_name: str = "Guest"
+    ) -> Dict[str, str]:
+        """
+        Build prompts for script generation
+
+        Args:
+            content: Source content
+            tone: Conversation tone
+            max_length: Target word count
+            host_name: Host name
+            guest_name: Guest name
+
+        Returns:
+            Dict with system and user prompts
+        """
+        # Calculate target number of dialogue turns
+        # Rough estimate: 50-100 words per turn
+        target_turns = max(10, min(30, max_length // 75))
+
+        # Build user prompt
+        user_prompt = get_user_prompt(
+            content=content,
+            tone=tone,
+            target_turns=target_turns
+        )
+
+        # Add length-specific guidance
+        content_length = len(content)
+        length_prompt = get_content_length_prompt(content_length, target_turns)
+
+        if length_prompt:
+            user_prompt += f"\n\n{length_prompt}"
+
+        # Add names if custom
+        if host_name != "Host" or guest_name != "Guest":
+            user_prompt += f"\n\nUse these names:\n- Host: {host_name}\n- Guest: {guest_name}"
+
+        logger.info(f"Built prompt for {content_length} chars, targeting {target_turns} turns")
+
+        return {
+            "system": self.system_prompt,
+            "user": user_prompt
+        }
+
+    def build_refinement_prompt(self, script: list) -> Dict[str, str]:
+        """
+        Build prompts for script refinement
+
+        Args:
+            script: Current script
+
+        Returns:
+            Dict with system and user prompts
+        """
+        from app.prompts.templates import SCRIPT_REFINEMENT_PROMPT
+
+        user_prompt = SCRIPT_REFINEMENT_PROMPT.format(
+            current_script=script
+        )
+
+        return {
+            "system": self.system_prompt,
+            "user": user_prompt
+        }
diff --git a/PdfToPodcast/api/llm-service/app/core/script_formatter.py b/PdfToPodcast/api/llm-service/app/core/script_formatter.py
new file mode 100644
index 0000000000..726bbff8a0
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/core/script_formatter.py
@@ -0,0 +1,281 @@
+import json
+import re
+import logging
+from typing import List, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+class ScriptFormatter:
+    """
+    Format and validate podcast scripts
+    """
+
+    def parse_llm_response(self, response: str) -> List[Dict[str, str]]:
+        """
+        Parse LLM response into structured script
+
+        Args:
+            response: Raw LLM response
+
+        Returns:
+            List of dialogue objects
+        """
+        try:
+            # Remove markdown code blocks if present
+            cleaned = self._remove_markdown(response)
+            logger.info(f"Cleaned response (first 200 chars): {cleaned[:200]}")
+
+            # Try to parse as JSON
+            script = json.loads(cleaned)
+            logger.info(f"Parsed JSON type: {type(script)}")
+
+            # Handle wrapped response (e.g., {"dialogue": [...]})
+            if isinstance(script, dict):
+                if "dialogue" in script:
+                    script = script["dialogue"]
+                    logger.info("Extracted dialogue from wrapped response")
+                elif "script" in script:
+                    script = script["script"]
+                    logger.info("Extracted script from wrapped response")
+                else:
+                    logger.error(f"Expected list or wrapped object, got dict with keys: {list(script.keys())}")
+                    raise ValueError("Script must be a list or contain 'dialogue'/'script' key")
+
+            # Validate format
+            if not isinstance(script, list):
+                logger.error(f"Expected list, got {type(script)}: {str(script)[:200]}")
+                raise ValueError("Script must be a list")
+
+            # Validate each dialogue
+            validated = []
+            for item in script:
+                if isinstance(item, dict) and "speaker" in item and "text" in item:
+                    validated.append({
+                        "speaker": str(item["speaker"]).lower(),
+                        "text": str(item["text"]).strip()
+                    })
+
+            if not validated:
+                raise ValueError("No valid dialogues found")
+
+            logger.info(f"Parsed {len(validated)} dialogue turns")
+            return validated
+
+        except json.JSONDecodeError as e:
+            logger.error(f"JSON parsing failed: {str(e)}")
+            # Try to extract dialogue from text
+            return self._extract_from_text(response)
+
+        except Exception as e:
+            logger.error(f"Script parsing failed: {str(e)}")
+            raise
+
+    def _remove_markdown(self, text: str) -> str:
+        """Remove markdown code blocks and reasoning tags"""
+        # Remove DeepSeek R1 thinking process (everything before </think>)
+        if '</think>' in text:
+            text = text.split('</think>', 1)[1]
+            logger.info("Removed DeepSeek R1 thinking process")
+
+        # Remove <think> tags if present
+        text = re.sub(r'<think>.*?</think>', '', text, flags=re.DOTALL)
+
+        # Remove ```json or ``` blocks
+        text = re.sub(r'```json\s*', '', text)
+        text = re.sub(r'```\s*', '', text)
+        return text.strip()
+
+    def _extract_from_text(self, text: str) -> List[Dict[str, str]]:
+        """
+        Extract dialogue from plain text format
+
+        Handles formats like:
+        Host: Welcome to the show!
+        Guest: Thanks for having me!
+        """
+        dialogues = []
+
+        # Split by lines
+        lines = text.split('\n')
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            # Match "Speaker: Text" format
+            match = re.match(r'^(Host|Guest|host|guest):(.+)$', line, re.IGNORECASE)
+            if match:
+                speaker = match.group(1).lower()
+                text = match.group(2).strip()
+
+                dialogues.append({
+                    "speaker": speaker,
+                    "text": text
+                })
+
+        if dialogues:
+            logger.info(f"Extracted {len(dialogues)} dialogues from text")
+            return dialogues
+
+        raise ValueError("Could not parse script format")
+
+    def validate_script(self, script: List[Dict[str, str]]) -> bool:
+        """
+        Validate script format
+
+        Args:
+            script: Script to validate
+
+        Returns:
+            True if valid
+        """
+        if not isinstance(script, list):
+            return False
+
+        if len(script) < 2:
+            logger.warning("Script too short (< 2 turns)")
+            return False
+
+        for item in script:
+            if not isinstance(item, dict):
+                return False
+            if "speaker" not in item or "text" not in item:
+                return False
+            if item["speaker"] not in ["host", "guest"]:
+                logger.warning(f"Invalid speaker: {item['speaker']}")
+                return False
+            if not item["text"].strip():
+                return False
+
+        return True
+
+    def format_for_tts(self, script: List[Dict[str, str]]) -> List[Dict[str, str]]:
+        """
+        Format script for TTS processing
+
+        Args:
+            script: Raw script
+
+        Returns:
+            TTS-ready script
+        """
+        formatted = []
+
+        for item in script:
+            text = item["text"]
+
+            # Clean up text for TTS
+            text = self._prepare_for_speech(text)
+
+            formatted.append({
+                "speaker": item["speaker"],
+                "text": text
+            })
+
+        return formatted
+
+    def _prepare_for_speech(self, text: str) -> str:
+        """
+        Prepare text for natural speech synthesis
+
+        Args:
+            text: Raw text
+
+        Returns:
+            Speech-ready text
+        """
+        # Remove excessive punctuation
+        text = re.sub(r'\.{2,}', '.', text)
+        text = re.sub(r'!{2,}', '!', text)
+        text = re.sub(r'\?{2,}', '?', text)
+
+        # Normalize whitespace
+        text = re.sub(r'\s+', ' ', text)
+
+        # Ensure proper spacing after punctuation
+        text = re.sub(r'([.!?])([A-Z])', r'\1 \2', text)
+
+        return text.strip()
+
+    def calculate_metadata(self, script: List[Dict[str, str]]) -> Dict:
+        """
+        Calculate script metadata
+
+        Args:
+            script: Script
+
+        Returns:
+            Metadata dict
+        """
+        total_words = sum(len(item["text"].split()) for item in script)
+        total_chars = sum(len(item["text"]) for item in script)
+
+        # Estimate duration (rough: 150 words per minute)
+        estimated_duration_minutes = total_words / 150
+
+        # Count turns per speaker
+        host_turns = sum(1 for item in script if item["speaker"] == "host")
+        guest_turns = sum(1 for item in script if item["speaker"] == "guest")
+
+        return {
+            "total_turns": len(script),
+            "host_turns": host_turns,
+            "guest_turns": guest_turns,
+            "total_words": total_words,
+            "total_characters": total_chars,
+            "estimated_duration_minutes": round(estimated_duration_minutes, 1),
+            "avg_words_per_turn": round(total_words / len(script), 1) if script else 0
+        }
+
+    def truncate_script(self, script: List[Dict[str, str]], max_turns: int) -> List[Dict[str, str]]:
+        """
+        Truncate script to maximum number of turns
+
+        Args:
+            script: Script to truncate
+            max_turns: Maximum turns
+
+        Returns:
+            Truncated script
+        """
+        if len(script) <= max_turns:
+            return script
+
+        logger.info(f"Truncating script from {len(script)} to {max_turns} turns")
+        return script[:max_turns]
+
+    def merge_short_turns(self, script: List[Dict[str, str]], min_words: int = 5) -> List[Dict[str, str]]:
+        """
+        Merge very short turns with adjacent turns from same speaker
+
+        Args:
+            script: Script to process
+            min_words: Minimum words per turn
+
+        Returns:
+            Merged script
+        """
+        if not script:
+            return script
+
+        merged = []
+        current = script[0].copy()
+
+        for item in script[1:]:
+            current_words = len(current["text"].split())
+
+            # If current turn is short and same speaker, merge
+            if current_words < min_words and item["speaker"] == current["speaker"]:
+                current["text"] += " " + item["text"]
+            else:
+                merged.append(current)
+                current = item.copy()
+
+        # Add last turn
+        merged.append(current)
+
+        if len(merged) < len(script):
+            logger.info(f"Merged {len(script) - len(merged)} short turns")
+
+        return merged
diff --git a/PdfToPodcast/api/llm-service/app/main.py b/PdfToPodcast/api/llm-service/app/main.py
new file mode 100644
index 0000000000..7f4d723f29
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/main.py
@@ -0,0 +1,101 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+import logging
+import sys
+import os
+
+from app.api.routes import router
+from app.config import settings
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+
+logger = logging.getLogger(__name__)
+
+# Create FastAPI app
+app = FastAPI(
+    title="LLM Script Generation Service",
+    description="Generate podcast scripts from text using AI",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(router, tags=["Script Generation"])
+
+@app.on_event("startup")
+async def startup_event():
+    """Run on application startup"""
+    logger.info("=" * 60)
+    logger.info("LLM Script Generation Service starting up...")
+    logger.info("=" * 60)
+    logger.info(f"Service running on port {settings.SERVICE_PORT}")
+
+    # Check if custom API is configured
+    if settings.BASE_URL and settings.KEYCLOAK_CLIENT_SECRET:
+        logger.info("LLM Provider: Custom API (Keycloak)")
+        logger.info(f"Custom API Base URL: {settings.BASE_URL}")
+        logger.info(f"Model: {settings.INFERENCE_MODEL_NAME}")
+    else:
+        logger.info("LLM Provider: OpenAI")
+        if settings.OPENAI_API_KEY:
+            logger.info("OpenAI API key configured")
+        else:
+            logger.warning("OpenAI API key not found")
+
+    logger.info("=" * 60)
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    """Run on application shutdown"""
+    logger.info("LLM Script Generation Service shutting down...")
+
+@app.get("/")
+async def root():
+    """Root endpoint"""
+    # Determine actual provider being used
+    if settings.BASE_URL and settings.KEYCLOAK_CLIENT_SECRET:
+        llm_provider = "Custom API (Keycloak)"
+        llm_model = settings.INFERENCE_MODEL_NAME
+    else:
+        llm_provider = "OpenAI"
+        llm_model = settings.DEFAULT_MODEL
+
+    return {
+        "service": "LLM Script Generation Service",
+        "version": "1.0.0",
+        "description": "Convert text content into engaging podcast dialogue",
+        "config": {
+            "llm_provider": llm_provider,
+            "llm_model": llm_model
+        },
+        "endpoints": {
+            "generate_script": "POST /generate-script - Generate podcast script",
+            "refine_script": "POST /refine-script - Refine existing script",
+            "validate_content": "POST /validate-content - Validate content suitability",
+            "health": "GET /health - Health check",
+            "tones": "GET /tones - Available conversation tones",
+            "models": "GET /models - Available LLM models",
+            "docs": "GET /docs - API documentation"
+        }
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=settings.SERVICE_PORT)
diff --git a/PdfToPodcast/api/llm-service/app/prompts/__init__.py b/PdfToPodcast/api/llm-service/app/prompts/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/llm-service/app/prompts/templates.py b/PdfToPodcast/api/llm-service/app/prompts/templates.py
new file mode 100644
index 0000000000..332d1b460d
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/prompts/templates.py
@@ -0,0 +1,204 @@
+"""
+Prompt templates for podcast script generation
+"""
+
+SYSTEM_PROMPT = """You are an expert podcast scriptwriter. Your task is to convert written content into engaging, natural-sounding podcast dialogue between a host and a guest that feels like a real human conversation.
+
+Guidelines:
+1. Create authentic, conversational dialogue that sounds natural when spoken aloud
+2. The host guides the conversation and asks insightful questions
+3. The guest provides detailed explanations and insights
+4. Include natural reactions, acknowledgments, and transitions
+5. Break down complex concepts into digestible explanations
+6. Add personality and enthusiasm while maintaining professionalism
+7. Use rhetorical devices like analogies, examples, and storytelling
+8. Vary sentence structure and length for natural flow
+9. Include thinking pauses, clarifications, and follow-up questions
+10. **MANDATORY**: The host MUST warmly welcome the guest by name in the introduction
+11. **MANDATORY**: End with a proper closing where BOTH host and guest say thank you and goodbye
+12. Use names throughout the conversation (host and guest should refer to each other by name occasionally)
+
+Closing Requirements:
+- Host should thank the guest by name and thank listeners
+- Guest should thank the host by name
+- Include a warm, natural sign-off
+- Don't end abruptly - have a proper conclusion
+
+Format:
+- Return ONLY a valid JSON array
+- Each dialogue turn must have "speaker" (either "host" or "guest") and "text" fields
+- Do not include any markdown formatting, code blocks, or explanations
+- Start directly with the JSON array
+
+Example output format:
+[
+  {"speaker": "host", "text": "Welcome to the show! I'm so excited to have you here today, Alex. We're diving into a fascinating topic!"},
+  {"speaker": "guest", "text": "Thanks for having me, Sarah! I'm really excited to be here and discuss this."},
+  {"speaker": "host", "text": "So Alex, let's start with the basics. What got you interested in this field?"},
+  ...content...
+  {"speaker": "host", "text": "Well, that's all the time we have today. Alex, thank you so much for joining us and sharing your insights!"},
+  {"speaker": "guest", "text": "Thank you for having me, Sarah! It was a pleasure."},
+  {"speaker": "host", "text": "And thank you to our listeners for tuning in. Until next time!"}
+]
+"""
+
+CONVERSATIONAL_TONE_PROMPT = """Create a warm, friendly, and accessible podcast script. Use:
+- Casual language and everyday examples
+- Humor where appropriate
+- Personal anecdotes and relatable scenarios
+- Enthusiastic reactions and encouragement
+- Simple explanations for complex topics
+- Host and guest refer to each other by name throughout
+- Begin with a warm welcome where the host greets the guest by name
+- End with proper thank yous and goodbye from both host and guest
+Target audience: General listeners who want to learn in an entertaining way"""
+
+EDUCATIONAL_TONE_PROMPT = """Create an informative and structured podcast script. Use:
+- Clear, precise language
+- Systematic breakdown of topics
+- Evidence-based explanations
+- Definitions of key terms
+- Logical progression of ideas
+- Expert insights and analysis
+Target audience: Learners seeking in-depth understanding"""
+
+PROFESSIONAL_TONE_PROMPT = """Create a polished, authoritative podcast script. Use:
+- Professional terminology when appropriate
+- Industry insights and best practices
+- Data-driven discussions
+- Strategic analysis
+- Formal yet engaging tone
+- Executive-level perspectives
+Target audience: Professionals and industry experts"""
+
+FEW_SHOT_EXAMPLES = """
+Example 1 - Technical Content:
+Source: "Neural networks consist of interconnected nodes organized in layers..."
+
+Script:
+[
+  {"speaker": "host", "text": "Welcome back to Tech Deep Dive! I'm so thrilled to have Dr. Sarah Chen with us today. Sarah, thanks for joining us!"},
+  {"speaker": "guest", "text": "[chuckles] Thanks for having me! I'm excited to be here and talk about one of my favorite topics."},
+  {"speaker": "host", "text": "So Sarah, let's break down neural networks. I know it sounds super technical, but can you help us understand what's actually happening?"},
+  {"speaker": "guest", "text": "Absolutely! [pause] Think of it like this - imagine a huge team of people, each person looking at one tiny piece of a puzzle. That's essentially what a neural network does."},
+  {"speaker": "host", "text": "Oh, interesting! So these 'people' are the nodes you mentioned?"},
+  {"speaker": "guest", "text": "[laughs] Exactly! And just like people in a team talk to each other, these nodes are all connected and pass information back and forth."}
+]
+
+Example 2 - Business Content:
+Source: "Market segmentation involves dividing a broad consumer market into sub-groups..."
+
+Script:
+[
+  {"speaker": "host", "text": "Welcome to Business Insights! I'm really happy to have marketing expert Alex Rodriguez joining us today. Alex, great to have you here!"},
+  {"speaker": "guest", "text": "Hey! Thanks so much for the invitation. [chuckles] Always happy to talk marketing strategy."},
+  {"speaker": "host", "text": "So Alex, market segmentation - that's a term we hear thrown around a lot in business. What does it really mean?"},
+  {"speaker": "guest", "text": "Great question! [pause] You know how Netflix doesn't show everyone the same homepage? They're segmenting their audience."},
+  {"speaker": "host", "text": "Ah, so it's about customizing the experience?"},
+  {"speaker": "guest", "text": "Precisely! [chuckles] Instead of treating millions of customers as one giant group, smart companies divide them into smaller segments based on what they actually want."}
+]
+
+Example 3 - Scientific Content:
+Source: "Photosynthesis is the process by which plants convert light energy into chemical energy..."
+
+Script:
+[
+  {"speaker": "host", "text": "Welcome to Science Simplified! Today I have the pleasure of chatting with Dr. Jamie Park, a botanist who makes plant science actually fun. Jamie, welcome!"},
+  {"speaker": "guest", "text": "[laughs] Thanks! I'm so glad to be here. Plants are my passion, so let's make this exciting!"},
+  {"speaker": "host", "text": "Perfect! So Jamie, we all learned about photosynthesis in school, but I'd love to really understand what's happening at a deeper level."},
+  {"speaker": "guest", "text": "Sure! [pause] At its core, photosynthesis is like nature's solar panel and battery system combined."},
+  {"speaker": "host", "text": "I love that analogy! So plants are capturing light and storing it somehow?"},
+  {"speaker": "guest", "text": "Exactly! [chuckles] They capture light energy and convert it into sugar - which is basically plant fuel. It's one of the most important chemical processes on Earth."},
+  {"speaker": "host", "text": "Why is it so crucial, Jamie?"},
+  {"speaker": "guest", "text": "Well, [pause] it's the foundation of almost all life! Plants create the oxygen we breathe and the food that feeds the entire food chain."}
+]
+"""
+
+USER_PROMPT_TEMPLATE = """Convert the following content into an engaging podcast script between a host and a guest.
+
+Content to convert:
+{content}
+
+Additional instructions:
+- Tone: {tone}
+- Target length: Approximately {target_turns} dialogue turns
+- **MANDATORY**: Start with the host warmly welcoming the guest by name
+- **MANDATORY**: End with BOTH host and guest saying thank you and goodbye naturally
+- Make it sound natural and conversational
+- Host and guest should refer to each other by name occasionally
+- Include questions, reactions, and clarifications
+- Break down complex ideas into understandable chunks
+- Add transitions between topics
+- Don't end abruptly - include a proper warm conclusion
+
+Remember: Return ONLY a JSON array with speaker and text fields. No markdown, no code blocks, no explanations."""
+
+SCRIPT_REFINEMENT_PROMPT = """Review and refine this podcast script to make it more engaging:
+
+Current script:
+{current_script}
+
+Improvements to make:
+1. Enhance natural flow and transitions
+2. Add more personality and enthusiasm
+3. Include better examples or analogies
+4. Vary sentence structure
+5. Add natural human reactions: [chuckles], [laughs], [pause], [sighs]
+6. Ensure host and guest use each other's names occasionally
+7. Make sure the opening has a warm welcome by name
+8. Add strategic pauses or emphasis cues for dramatic effect
+
+Return the improved script in the same JSON format."""
+
+SHORT_CONTENT_PROMPT = """The content is quite brief. Create a podcast script that:
+1. Starts with a warm welcome where the host greets the guest by name
+2. Introduces the topic engagingly
+3. Explores the key points in depth
+4. Discusses implications or applications
+5. Adds relevant examples or context
+6. Host and guest refer to each other by name throughout
+7. Ends with proper thank yous and goodbye from BOTH speakers
+8. Concludes with key takeaways
+
+Aim for {target_turns} dialogue turns to properly explore the topic."""
+
+LONG_CONTENT_PROMPT = """The content is extensive. Create a podcast script that:
+1. Starts with a warm welcome where the host greets the guest by name
+2. Identifies the main themes and key points
+3. Prioritizes the most important information
+4. Groups related concepts together
+5. Creates a logical narrative flow
+6. Host and guest refer to each other by name throughout
+7. Ends with proper thank yous and goodbye from BOTH speakers
+8. Summarizes complex sections concisely
+
+Focus on clarity and coherence while maintaining engagement and human warmth."""
+
+def get_system_prompt():
+    """Get the main system prompt"""
+    return SYSTEM_PROMPT
+
+def get_tone_prompt(tone: str) -> str:
+    """Get tone-specific guidance"""
+    tone_prompts = {
+        "conversational": CONVERSATIONAL_TONE_PROMPT,
+        "educational": EDUCATIONAL_TONE_PROMPT,
+        "professional": PROFESSIONAL_TONE_PROMPT,
+    }
+    return tone_prompts.get(tone.lower(), CONVERSATIONAL_TONE_PROMPT)
+
+def get_user_prompt(content: str, tone: str = "conversational", target_turns: int = 20) -> str:
+    """Build the user prompt"""
+    return USER_PROMPT_TEMPLATE.format(
+        content=content,
+        tone=get_tone_prompt(tone),
+        target_turns=target_turns
+    )
+
+def get_content_length_prompt(content_length: int, target_turns: int) -> str:
+    """Get prompt based on content length"""
+    if content_length < 500:
+        return SHORT_CONTENT_PROMPT.format(target_turns=target_turns)
+    elif content_length > 5000:
+        return LONG_CONTENT_PROMPT
+    return ""
diff --git a/PdfToPodcast/api/llm-service/app/services/__init__.py b/PdfToPodcast/api/llm-service/app/services/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/llm-service/app/services/api_client.py b/PdfToPodcast/api/llm-service/app/services/api_client.py
new file mode 100644
index 0000000000..c6d012cddd
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/app/services/api_client.py
@@ -0,0 +1,149 @@
+"""
+API Client for authentication and API calls
+Similar to RAG chatbot implementation
+"""
+
+import logging
+import requests
+import httpx
+from typing import Optional
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+    """
+    Client for handling authentication and API calls
+    """
+
+    def __init__(self):
+        self.base_url = settings.BASE_URL
+        self.token = None
+        self.http_client = None
+        self._authenticate()
+
+    def _authenticate(self) -> None:
+        """
+        Authenticate and obtain access token from Keycloak
+        """
+        token_url = f"{self.base_url}/token"
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": settings.KEYCLOAK_CLIENT_ID,
+            "client_secret": settings.KEYCLOAK_CLIENT_SECRET,
+        }
+
+        try:
+            response = requests.post(token_url, data=payload, verify=False)
+
+            if response.status_code == 200:
+                self.token = response.json().get("access_token")
+                logger.info(f"✓ Access token obtained: {self.token[:20]}..." if self.token else "Failed to get token")
+
+                # Create httpx client with SSL verification disabled (like -k in curl)
+                self.http_client = httpx.Client(verify=False)
+
+            else:
+                logger.error(f"Error obtaining token: {response.status_code} - {response.text}")
+                raise Exception(f"Authentication failed: {response.status_code}")
+
+        except Exception as e:
+            logger.error(f"Error during authentication: {str(e)}")
+            raise
+
+    def get_inference_client(self):
+        """
+        Get OpenAI-style client for inference/completions
+        Uses Llama-3.1-8B-Instruct endpoint
+        """
+        from openai import OpenAI
+
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{settings.INFERENCE_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+
+    def chat_complete(self, messages: list, max_tokens: int = 4000, temperature: float = 0.7) -> str:
+        """
+        Get chat completion from the inference model
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            max_tokens: Maximum tokens to generate
+            temperature: Temperature for generation
+
+        Returns:
+            Generated text
+        """
+        try:
+            client = self.get_inference_client()
+
+            # Convert messages to a prompt for the completions endpoint
+            prompt = ""
+            for msg in messages:
+                role = msg.get('role', 'user')
+                content = msg.get('content', '')
+                if role == 'system':
+                    prompt += f"{content}\n\n"
+                elif role == 'user':
+                    prompt += f"User: {content}\n\n"
+                elif role == 'assistant':
+                    prompt += f"Assistant: {content}\n\n"
+            prompt += "Assistant:"
+
+            logger.info(f"Calling inference with prompt length: {len(prompt)}")
+
+            # Use completions.create (not chat.completions) as per curl example
+            response = client.completions.create(
+                model=settings.INFERENCE_MODEL_NAME,
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature
+            )
+
+            # Handle response structure
+            if hasattr(response, 'choices') and len(response.choices) > 0:
+                choice = response.choices[0]
+                if hasattr(choice, 'text'):
+                    return choice.text
+                elif hasattr(choice, 'message') and hasattr(choice.message, 'content'):
+                    return choice.message.content
+                else:
+                    logger.error(f"Unexpected response structure: {type(choice)}, {choice}")
+                    return str(choice)
+            else:
+                logger.error(f"Unexpected response: {type(response)}, {response}")
+                return ""
+        except Exception as e:
+            logger.error(f"Error generating chat completion: {str(e)}", exc_info=True)
+            raise
+
+    def is_authenticated(self) -> bool:
+        """Check if client is authenticated"""
+        return self.token is not None and self.http_client is not None
+
+    def __del__(self):
+        """
+        Cleanup: close httpx client
+        """
+        if self.http_client:
+            self.http_client.close()
+
+
+# Global API client instance
+_api_client: Optional[APIClient] = None
+
+
+def get_api_client() -> APIClient:
+    """
+    Get or create the global API client instance
+
+    Returns:
+        APIClient instance
+    """
+    global _api_client
+    if _api_client is None:
+        _api_client = APIClient()
+    return _api_client
diff --git a/PdfToPodcast/api/llm-service/requirements.txt b/PdfToPodcast/api/llm-service/requirements.txt
new file mode 100644
index 0000000000..03ab61ab52
--- /dev/null
+++ b/PdfToPodcast/api/llm-service/requirements.txt
@@ -0,0 +1,11 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+openai==1.6.1
+pydantic==2.5.0
+pydantic-settings==2.1.0
+python-dotenv==1.0.0
+tiktoken==0.5.2
+tenacity==8.2.3
+httpx==0.25.2
+requests==2.31.0
diff --git a/PdfToPodcast/api/pdf-service/.env.example b/PdfToPodcast/api/pdf-service/.env.example
new file mode 100644
index 0000000000..02282e4327
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/.env.example
@@ -0,0 +1,17 @@
+# Service Configuration
+SERVICE_NAME=PDF Processing Service
+SERVICE_VERSION=1.0.0
+SERVICE_PORT=8001
+
+# File Processing
+MAX_FILE_SIZE=10485760
+UPLOAD_DIR=uploads
+
+# OCR Settings
+# TESSERACT_CMD=/usr/bin/tesseract
+OCR_LANGUAGE=eng
+OCR_DPI=300
+
+# Text Processing
+ENABLE_TEXT_CLEANING=true
+ENABLE_OCR_FALLBACK=true
diff --git a/PdfToPodcast/api/pdf-service/Dockerfile b/PdfToPodcast/api/pdf-service/Dockerfile
new file mode 100644
index 0000000000..8956189ee1
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/Dockerfile
@@ -0,0 +1,29 @@
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Install system dependencies for OCR (tesseract), PDF-to-image (poppler), and file type detection (libmagic1)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tesseract-ocr \
+    poppler-utils \
+    libmagic1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy the requirements file into the container
+COPY requirements.txt .
+
+# python-magic-bin is for Windows; python-magic is for Linux. This ensures the correct library is used.
+RUN sed -i 's/python-magic-bin/python-magic/' requirements.txt
+
+# Install Python dependencies
+RUN pip install -r requirements.txt
+
+# Copy the rest of the application files into the container
+COPY . .
+
+# Expose the port the service runs on
+EXPOSE 8001
+
+# Command to run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"]
diff --git a/PdfToPodcast/api/pdf-service/README.md b/PdfToPodcast/api/pdf-service/README.md
new file mode 100644
index 0000000000..a61e523f13
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/README.md
@@ -0,0 +1,285 @@
+# PDF Processing Microservice
+
+Extracts text from PDF documents with advanced OCR support for scanned documents.
+
+## Features
+
+**Multi-Method Extraction**
+- pdfplumber for complex layouts
+- PyPDF2 fallback
+- Tesseract OCR for scanned PDFs
+
+**Intelligent Processing**
+- Automatic scanned PDF detection
+- Multi-column layout handling
+- Table extraction
+- Structure analysis (headings, paragraphs)
+
+**Text Cleaning**
+- Header/footer removal
+- Page number removal
+- Whitespace normalization
+- Hyphenation fixing
+- OCR error correction
+
+**OCR Capabilities**
+- Multiple language support
+- Adjustable DPI settings
+- Confidence scoring
+- Image preprocessing
+
+## API Endpoints
+
+### 1. Extract Text (Smart Mode)
+
+**POST** `/extract`
+
+Intelligently extracts text using the best available method.
+
+**Parameters:**
+- `file`: PDF file (multipart/form-data)
+- `job_id`: Optional tracking ID
+- `clean_text`: Apply cleaning (default: true)
+- `use_ocr`: Enable OCR fallback (default: true)
+
+**Response:**
+```json
+{
+  "text": "Extracted text content...",
+  "metadata": {
+    "pages": 10,
+    "word_count": 5000,
+    "character_count": 30000,
+    "has_images": true,
+    "method": "pdfplumber"
+  },
+  "status": "success",
+  "method": "pdfplumber"
+}
+```
+
+### 2. Extract Structure
+
+**POST** `/extract-structure`
+
+Extracts hierarchical document structure.
+
+**Returns:**
+```json
+{
+  "structure": [
+    {
+      "page": 1,
+      "text": "Introduction",
+      "type": "heading",
+      "font_size": 18
+    },
+    {
+      "page": 1,
+      "text": "This document describes...",
+      "type": "paragraph",
+      "font_size": 12
+    }
+  ],
+  "sections": [
+    {
+      "heading": "Introduction",
+      "content": "..."
+    }
+  ],
+  "status": "success"
+}
+```
+
+### 3. Force OCR Extraction
+
+**POST** `/extract-with-ocr`
+
+Forces OCR processing for scanned PDFs.
+
+**Parameters:**
+- `file`: PDF file
+- `language`: OCR language code (default: "eng")
+- `dpi`: Image resolution (default: 300)
+
+**Response:**
+```json
+{
+  "text": "OCR extracted text...",
+  "metadata": {
+    "pages": 10,
+    "avg_confidence": 92.5,
+    "language": "eng",
+    "dpi": 300
+  },
+  "status": "success",
+  "method": "ocr"
+}
+```
+
+### 4. Health Check
+
+**GET** `/health`
+
+Check service health and capabilities.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "tesseract_available": true,
+  "version": "1.0.0"
+}
+```
+
+### 5. Supported Languages
+
+**GET** `/languages`
+
+Get list of available OCR languages.
+
+**Response:**
+```json
+{
+  "languages": ["eng", "fra", "deu", "spa"],
+  "default": "eng"
+}
+```
+
+## Prerequisites
+
+- Tesseract OCR (for scanned PDFs)
+- Poppler utils
+- Python 3.9+
+
+## Installation
+
+### Using Docker
+
+```bash
+cd microservices/pdf-service
+docker build -t pdf-service .
+docker run -p 8001:8001 pdf-service
+```
+
+### Manual Installation
+
+1. **Install System Dependencies**
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install tesseract-ocr tesseract-ocr-eng poppler-utils
+
+# macOS
+brew install tesseract poppler
+
+# Windows
+# Download Tesseract from: https://github.com/UB-Mannheim/tesseract/wiki
+# Download Poppler from: https://blog.alivate.com.au/poppler-windows/
+```
+
+2. **Install Python Dependencies**
+
+```bash
+pip install -r requirements.txt
+```
+
+3. **Run Service**
+
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
+```
+
+## Configuration
+
+Create `.env` file:
+
+```env
+SERVICE_PORT=8001
+MAX_FILE_SIZE=10485760
+TESSERACT_CMD=/usr/bin/tesseract
+OCR_LANGUAGE=eng
+OCR_DPI=300
+ENABLE_TEXT_CLEANING=true
+ENABLE_OCR_FALLBACK=true
+```
+
+## Usage Examples
+
+### Python
+
+```python
+import requests
+
+# Extract text
+with open("document.pdf", "rb") as f:
+    response = requests.post(
+        "http://localhost:8001/extract",
+        files={"file": f},
+        data={"clean_text": True, "use_ocr": True}
+    )
+
+result = response.json()
+print(f"Extracted {result['metadata']['word_count']} words")
+print(result['text'][:500])
+```
+
+### cURL
+
+```bash
+# Smart extraction
+curl -X POST http://localhost:8001/extract \
+  -F "file=@document.pdf" \
+  -F "clean_text=true" \
+  -F "use_ocr=true"
+
+# Force OCR
+curl -X POST http://localhost:8001/extract-with-ocr \
+  -F "file=@scanned.pdf" \
+  -F "language=eng" \
+  -F "dpi=300"
+```
+
+## Testing
+
+Test with sample PDF:
+```bash
+curl -X POST http://localhost:8001/extract \
+  -F "file=@sample.pdf"
+```
+
+Check service health:
+```bash
+curl http://localhost:8001/health
+```
+
+## Troubleshooting
+
+### Tesseract Not Found
+
+**Error**: `pytesseract.pytesseract.TesseractNotFoundError`
+
+**Solution**:
+```bash
+# Linux
+sudo apt-get install tesseract-ocr
+
+# Set path in .env
+TESSERACT_CMD=/usr/bin/tesseract
+```
+
+### Poor OCR Quality
+
+**Solutions**:
+- Increase DPI: `dpi=600`
+- Ensure good scan quality
+
+### Slow Processing
+
+**Solutions**:
+- Reduce DPI for OCR
+- Disable text cleaning if not needed
+
+## API Documentation
+
+View interactive API docs at `http://localhost:8001/docs`
diff --git a/PdfToPodcast/api/pdf-service/SERVICE_SUMMARY.md b/PdfToPodcast/api/pdf-service/SERVICE_SUMMARY.md
new file mode 100644
index 0000000000..2761561383
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/SERVICE_SUMMARY.md
@@ -0,0 +1,347 @@
+# PDF Processing Service - Implementation Summary
+
+## ✅ Completed Features
+
+### Core Modules
+
+#### 1. **PDF Extractor** (`app/core/pdf_extractor.py`)
+- Multiple extraction methods (pdfplumber, PyPDF2)
+- Intelligent fallback strategy
+- Table detection and extraction
+- Metadata extraction (title, author, etc.)
+- Scanned document detection
+- Page structure analysis
+- Multi-column layout handling
+
+**Key Methods:**
+- `extract()` - Main extraction with fallback
+- `check_if_scanned()` - Detect if OCR needed
+- `extract_page_structure()` - Analyze document hierarchy
+- `_group_words_into_lines()` - Layout preservation
+
+#### 2. **Text Cleaner** (`app/core/text_cleaner.py`)
+- Header/footer removal
+- Page number removal
+- Whitespace normalization
+- Hyphenation fixing (words split across lines)
+- Paragraph normalization
+- OCR error correction
+- Section extraction
+- Statistics generation
+
+**Key Methods:**
+- `clean()` - Main cleaning pipeline
+- `extract_sections()` - Split by headings
+- `remove_references()` - Remove bibliography
+- `get_statistics()` - Word/sentence counts
+
+#### 3. **OCR Handler** (`app/core/ocr_handler.py`)
+- Tesseract OCR integration
+- PDF to image conversion
+- Multi-language support
+- Image preprocessing (contrast, sharpness)
+- Confidence scoring
+- Language detection
+- Adjustable DPI settings
+
+**Key Methods:**
+- `extract_text_from_pdf()` - OCR for scanned PDFs
+- `_preprocess_image()` - Image enhancement
+- `_extract_with_confidence()` - Quality metrics
+- `is_tesseract_available()` - Capability check
+
+### API Endpoints
+
+#### 1. **POST /extract**
+Smart extraction with automatic method selection
+- Tries standard extraction first
+- Falls back to OCR if needed
+- Applies text cleaning
+- Returns metadata
+
+#### 2. **POST /extract-structure**
+Extracts hierarchical document structure
+- Identifies headings, paragraphs, lists
+- Analyzes font sizes
+- Extracts logical sections
+
+#### 3. **POST /extract-with-ocr**
+Forces OCR processing
+- For scanned documents
+- Configurable language and DPI
+- Includes confidence scores
+
+#### 4. **GET /health**
+Service health check
+- Reports Tesseract availability
+- Service version
+
+#### 5. **GET /languages**
+Lists supported OCR languages
+- All Tesseract languages
+- Default language
+
+### Configuration
+
+**File**: `app/config.py`
+
+Settings:
+- MAX_FILE_SIZE: 10MB
+- OCR_LANGUAGE: "eng"
+- OCR_DPI: 300
+- ENABLE_TEXT_CLEANING: true
+- ENABLE_OCR_FALLBACK: true
+
+### Docker Support
+
+**Updated Dockerfile** includes:
+- Tesseract OCR installation
+- Poppler utils (for pdf2image)
+- libmagic (file type detection)
+- All Python dependencies
+
+### Directory Structure
+
+```
+pdf-service/
+├── app/
+│   ├── __init__.py
+│   ├── main.py              ✅ FastAPI application
+│   ├── config.py            ✅ Configuration management
+│   ├── api/
+│   │   ├── __init__.py
+│   │   └── routes.py        ✅ API endpoints
+│   └── core/
+│       ├── __init__.py
+│       ├── pdf_extractor.py ✅ PDF extraction logic
+│       ├── text_cleaner.py  ✅ Text preprocessing
+│       └── ocr_handler.py   ✅ OCR processing
+├── requirements.txt         ✅ Updated with OCR deps
+├── Dockerfile              ✅ Updated with Tesseract
+├── README.md               ✅ Complete documentation
+├── SERVICE_SUMMARY.md      ✅ This file
+└── main.py.old             (backup of original)
+```
+
+## Technical Highlights
+
+### Smart Extraction Pipeline
+
+```python
+1. Upload PDF
+   ↓
+2. Try pdfplumber (best for complex layouts)
+   ↓ (if no text)
+3. Try PyPDF2 (fallback)
+   ↓ (if still no text)
+4. Check if scanned
+   ↓ (if scanned)
+5. Convert to images
+   ↓
+6. Apply OCR with Tesseract
+   ↓
+7. Clean extracted text
+   ↓
+8. Return results with metadata
+```
+
+### Text Cleaning Pipeline
+
+```python
+1. Normalize whitespace
+   ↓
+2. Remove headers/footers
+   ↓
+3. Remove noise patterns
+   ↓
+4. Fix hyphenation
+   ↓
+5. Normalize paragraphs
+   ↓
+6. Fix OCR errors (if aggressive)
+   ↓
+7. Return cleaned text
+```
+
+### OCR Processing Pipeline
+
+```python
+1. Convert PDF pages to images (DPI=300)
+   ↓
+2. For each image:
+   - Convert to grayscale
+   - Enhance contrast
+   - Enhance sharpness
+   ↓
+3. Run Tesseract OCR
+   ↓
+4. Extract confidence scores
+   ↓
+5. Combine pages
+   ↓
+6. Return text with metrics
+```
+
+## Usage Examples
+
+### Basic Extraction
+
+```bash
+curl -X POST http://localhost:8001/extract \
+  -F "file=@document.pdf" \
+  -F "clean_text=true"
+```
+
+### Force OCR
+
+```bash
+curl -X POST http://localhost:8001/extract-with-ocr \
+  -F "file=@scanned.pdf" \
+  -F "language=eng" \
+  -F "dpi=600"
+```
+
+### Extract Structure
+
+```bash
+curl -X POST http://localhost:8001/extract-structure \
+  -F "file=@document.pdf"
+```
+
+## Performance Metrics
+
+| Operation | Speed | Notes |
+|-----------|-------|-------|
+| Text PDF (10 pages) | ~10s | pdfplumber |
+| Scanned PDF (10 pages) | ~50s | OCR @ 300 DPI |
+| Structure Analysis | +2s | Additional processing |
+
+## Error Handling
+
+The service gracefully handles:
+- ✅ Corrupt PDFs (returns detailed error)
+- ✅ Non-PDF files (400 error)
+- ✅ Missing Tesseract (returns capability info)
+- ✅ OCR failures (falls back to standard)
+- ✅ Empty PDFs (returns empty text)
+- ✅ Large files (size validation)
+
+## Integration with Backend Gateway
+
+The backend gateway calls this service via:
+
+**URL**: `http://pdf-service:8001/extract`
+
+**Client Code**: `backend/app/services/pdf_client.py`
+
+```python
+class PDFServiceClient:
+    async def process_pdf(self, file_content, filename, job_id):
+        files = {"file": (filename, file_content, "application/pdf")}
+        params = {"job_id": job_id}
+        response = await client.post(
+            f"{self.base_url}/extract",
+            files=files,
+            params=params
+        )
+        return response.json()
+```
+
+## Dependencies Added
+
+```txt
+pytesseract==0.3.10       # OCR
+Pillow==10.1.0            # Image processing
+pdf2image==1.16.3         # PDF to image
+python-magic-bin==0.4.14  # File type detection
+langdetect==1.0.9         # Language detection
+```
+
+## Testing Recommendations
+
+1. **Unit Tests** (to be implemented):
+   - Test each extraction method
+   - Test text cleaning functions
+   - Test OCR with sample images
+
+2. **Integration Tests**:
+   - Test with various PDF types
+   - Test scanned vs text PDFs
+   - Test multi-column layouts
+
+3. **Performance Tests**:
+   - Benchmark extraction speed
+   - Memory usage monitoring
+   - Large file handling
+
+## Future Enhancements
+
+Potential improvements:
+- [ ] Batch processing support
+- [ ] Async processing with callbacks
+- [ ] Caching extracted text
+- [ ] More OCR languages pre-installed
+- [ ] PDF password handling
+- [ ] Image extraction endpoint
+- [ ] Form field extraction
+- [ ] Table extraction as structured data
+- [ ] Multi-threaded page processing
+- [ ] GPU-accelerated OCR
+
+## Known Limitations
+
+1. **File Size**: Limited to 10MB (configurable)
+2. **OCR Speed**: Slow for high DPI settings
+3. **Layout Complexity**: May lose formatting in complex layouts
+4. **Language Support**: Requires language data installation
+5. **Memory**: Large PDFs may consume significant memory
+
+## Deployment Notes
+
+### Docker Deployment
+
+```bash
+cd microservices/pdf-service
+docker build -t pdf-service:v1.0 .
+docker run -d -p 8001:8001 --name pdf-service pdf-service:v1.0
+```
+
+### Health Check
+
+```bash
+curl http://localhost:8001/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "tesseract_available": true,
+  "version": "1.0.0"
+}
+```
+
+### Logs
+
+```bash
+docker logs pdf-service
+```
+
+## API Documentation
+
+Interactive docs available at:
+- **Swagger UI**: http://localhost:8001/docs
+- **ReDoc**: http://localhost:8001/redoc
+
+## Status
+
+✅ **COMPLETE** - All required functionality implemented
+
+The PDF processing microservice is production-ready with:
+- Robust extraction methods
+- OCR support for scanned documents
+- Text cleaning and preprocessing
+- Structure analysis
+- Error handling
+- Docker support
+- Complete documentation
diff --git a/PdfToPodcast/api/pdf-service/app/__init__.py b/PdfToPodcast/api/pdf-service/app/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/pdf-service/app/api/__init__.py b/PdfToPodcast/api/pdf-service/app/api/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/pdf-service/app/api/routes.py b/PdfToPodcast/api/pdf-service/app/api/routes.py
new file mode 100644
index 0000000000..64516f077d
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/app/api/routes.py
@@ -0,0 +1,244 @@
+from fastapi import APIRouter, UploadFile, File, HTTPException, Form
+from pydantic import BaseModel
+from typing import Optional, List
+import logging
+
+from app.core.pdf_extractor import PDFExtractor
+from app.core.text_cleaner import TextCleaner
+from app.core.ocr_handler import OCRHandler
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+# Initialize processors
+pdf_extractor = PDFExtractor()
+text_cleaner = TextCleaner()
+ocr_handler = OCRHandler()
+
+class ExtractionResponse(BaseModel):
+    text: str
+    metadata: dict
+    status: str
+    method: str
+
+class HealthResponse(BaseModel):
+    status: str
+    tesseract_available: bool
+    version: str
+
+@router.post("/extract", response_model=ExtractionResponse)
+async def extract_text(
+    file: UploadFile = File(...),
+    job_id: Optional[str] = Form(None),
+    clean_text: bool = Form(True),
+    use_ocr: bool = Form(True)
+):
+    """
+    Extract text from PDF file
+
+    - **file**: PDF file to process
+    - **job_id**: Optional job ID for tracking
+    - **clean_text**: Apply text cleaning (default: True)
+    - **use_ocr**: Use OCR for scanned PDFs (default: True)
+
+    Returns extracted text with metadata
+    """
+    try:
+        # Validate file type
+        if not file.filename.endswith('.pdf'):
+            raise HTTPException(
+                status_code=400,
+                detail="Only PDF files are supported"
+            )
+
+        # Read file content
+        content = await file.read()
+        logger.info(f"Processing PDF: {file.filename} ({len(content)} bytes)")
+
+        # Extract text using standard methods
+        result = pdf_extractor.extract(content)
+
+        # Check if PDF is scanned and needs OCR
+        if use_ocr and (not result["text"].strip() or len(result["text"]) < 100):
+            logger.info("Low text content detected, checking if scanned...")
+
+            is_scanned = pdf_extractor.check_if_scanned(content)
+
+            if is_scanned and ocr_handler.is_tesseract_available():
+                logger.info("PDF appears to be scanned, using OCR...")
+                ocr_result = ocr_handler.extract_text_from_pdf(content)
+
+                if ocr_result["text"].strip():
+                    result = ocr_result
+                    logger.info("OCR extraction successful")
+
+        # Clean text if requested
+        if clean_text and result["text"]:
+            logger.info("Cleaning extracted text...")
+            cleaned_text = text_cleaner.clean(result["text"])
+
+            # Get text statistics
+            stats = text_cleaner.get_statistics(cleaned_text)
+            result["metadata"].update(stats)
+
+            result["text"] = cleaned_text
+
+        # Add job_id to result
+        if job_id:
+            result["metadata"]["job_id"] = job_id
+
+        logger.info(
+            f"Extraction complete: {result['metadata'].get('word_count', 0)} words, "
+            f"method: {result['method']}"
+        )
+
+        return ExtractionResponse(
+            text=result["text"],
+            metadata=result["metadata"],
+            status="success",
+            method=result["method"]
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error extracting text: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Error processing PDF: {str(e)}"
+        )
+
+@router.post("/extract-structure")
+async def extract_structure(
+    file: UploadFile = File(...),
+    job_id: Optional[str] = Form(None)
+):
+    """
+    Extract structured content from PDF (headings, paragraphs, etc.)
+
+    Returns hierarchical document structure
+    """
+    try:
+        if not file.filename.endswith('.pdf'):
+            raise HTTPException(
+                status_code=400,
+                detail="Only PDF files are supported"
+            )
+
+        content = await file.read()
+        logger.info(f"Extracting structure from: {file.filename}")
+
+        # Extract structure
+        structure = pdf_extractor.extract_page_structure(content)
+
+        # Extract text and clean it
+        result = pdf_extractor.extract(content)
+        cleaned_text = text_cleaner.clean(result["text"])
+
+        # Extract sections
+        sections = text_cleaner.extract_sections(cleaned_text)
+
+        return {
+            "job_id": job_id,
+            "filename": file.filename,
+            "structure": structure,
+            "sections": sections,
+            "status": "success"
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error extracting structure: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Error extracting structure: {str(e)}"
+        )
+
+@router.post("/extract-with-ocr")
+async def extract_with_ocr(
+    file: UploadFile = File(...),
+    language: str = Form("eng"),
+    dpi: int = Form(300)
+):
+    """
+    Force OCR extraction (for scanned PDFs)
+
+    - **file**: PDF file
+    - **language**: OCR language code (default: eng)
+    - **dpi**: Image resolution (default: 300)
+
+    Returns OCR-extracted text
+    """
+    try:
+        if not file.filename.endswith('.pdf'):
+            raise HTTPException(
+                status_code=400,
+                detail="Only PDF files are supported"
+            )
+
+        if not ocr_handler.is_tesseract_available():
+            raise HTTPException(
+                status_code=503,
+                detail="Tesseract OCR is not available on this server"
+            )
+
+        content = await file.read()
+        logger.info(f"Performing OCR on: {file.filename}")
+
+        # Extract with OCR
+        result = ocr_handler.extract_text_from_pdf(
+            content,
+            language=language,
+            dpi=dpi
+        )
+
+        # Clean text
+        if result["text"]:
+            result["text"] = text_cleaner.clean(result["text"])
+            stats = text_cleaner.get_statistics(result["text"])
+            result["metadata"].update(stats)
+
+        return {
+            "text": result["text"],
+            "metadata": result["metadata"],
+            "status": "success" if result["text"] else "failed",
+            "method": result["method"]
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"OCR extraction failed: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"OCR extraction failed: {str(e)}"
+        )
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Check service health and capabilities"""
+    tesseract_available = ocr_handler.is_tesseract_available()
+
+    return HealthResponse(
+        status="healthy",
+        tesseract_available=tesseract_available,
+        version="1.0.0"
+    )
+
+@router.get("/languages")
+async def get_supported_languages():
+    """Get list of supported OCR languages"""
+    try:
+        languages = ocr_handler.get_supported_languages()
+        return {
+            "languages": languages,
+            "default": "eng"
+        }
+    except Exception as e:
+        logger.error(f"Error getting languages: {str(e)}")
+        return {
+            "languages": ["eng"],
+            "default": "eng",
+            "error": str(e)
+        }
diff --git a/PdfToPodcast/api/pdf-service/app/config.py b/PdfToPodcast/api/pdf-service/app/config.py
new file mode 100644
index 0000000000..dd15203d6b
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/app/config.py
@@ -0,0 +1,29 @@
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+class Settings(BaseSettings):
+    """PDF Service Configuration"""
+
+    # Service info
+    SERVICE_NAME: str = "PDF Processing Service"
+    SERVICE_VERSION: str = "1.0.0"
+    SERVICE_PORT: int = 8001
+
+    # File processing
+    MAX_FILE_SIZE: int = 10485760  # 10MB
+    UPLOAD_DIR: str = "uploads"
+
+    # OCR settings
+    TESSERACT_CMD: Optional[str] = None  # Path to tesseract (None = auto-detect)
+    OCR_LANGUAGE: str = "eng"
+    OCR_DPI: int = 300
+
+    # Text processing
+    ENABLE_TEXT_CLEANING: bool = True
+    ENABLE_OCR_FALLBACK: bool = True
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+settings = Settings()
diff --git a/PdfToPodcast/api/pdf-service/app/core/__init__.py b/PdfToPodcast/api/pdf-service/app/core/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/pdf-service/app/core/ocr_handler.py b/PdfToPodcast/api/pdf-service/app/core/ocr_handler.py
new file mode 100644
index 0000000000..58ec30fb42
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/app/core/ocr_handler.py
@@ -0,0 +1,306 @@
+import pytesseract
+from pdf2image import convert_from_bytes
+from PIL import Image
+import io
+import logging
+from typing import List, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+class OCRHandler:
+    """
+    Handle OCR processing for scanned/image-based PDFs
+    """
+
+    def __init__(self, tesseract_cmd: Optional[str] = None):
+        """
+        Initialize OCR handler
+
+        Args:
+            tesseract_cmd: Path to tesseract executable (optional)
+        """
+        if tesseract_cmd:
+            pytesseract.pytesseract.tesseract_cmd = tesseract_cmd
+
+        self.supported_languages = ['eng']  # Can be extended
+
+    def extract_text_from_pdf(
+        self,
+        pdf_bytes: bytes,
+        language: str = 'eng',
+        dpi: int = 300
+    ) -> Dict:
+        """
+        Extract text from scanned PDF using OCR
+
+        Args:
+            pdf_bytes: PDF file content as bytes
+            language: OCR language (default: English)
+            dpi: DPI for PDF to image conversion
+
+        Returns:
+            Dict with extracted text and metadata
+        """
+        try:
+            logger.info(f"Starting OCR extraction with DPI={dpi}")
+
+            # Convert PDF pages to images
+            images = self._pdf_to_images(pdf_bytes, dpi=dpi)
+
+            if not images:
+                logger.error("No images extracted from PDF")
+                return {
+                    "text": "",
+                    "method": "ocr_failed",
+                    "metadata": {"error": "No images extracted"}
+                }
+
+            # Extract text from each page
+            page_texts = []
+            confidence_scores = []
+
+            for page_num, image in enumerate(images, 1):
+                logger.info(f"Processing page {page_num}/{len(images)}")
+
+                # Preprocess image
+                processed_image = self._preprocess_image(image)
+
+                # Extract text with confidence
+                result = self._extract_with_confidence(
+                    processed_image,
+                    language=language
+                )
+
+                page_texts.append(result["text"])
+                confidence_scores.append(result["confidence"])
+
+            # Combine all pages
+            full_text = "\n\n".join(page_texts)
+
+            # Calculate average confidence
+            avg_confidence = (
+                sum(confidence_scores) / len(confidence_scores)
+                if confidence_scores else 0
+            )
+
+            return {
+                "text": full_text,
+                "method": "ocr",
+                "metadata": {
+                    "pages": len(images),
+                    "word_count": len(full_text.split()),
+                    "character_count": len(full_text),
+                    "avg_confidence": round(avg_confidence, 2),
+                    "language": language,
+                    "dpi": dpi,
+                }
+            }
+
+        except Exception as e:
+            logger.error(f"OCR extraction failed: {str(e)}")
+            return {
+                "text": "",
+                "method": "ocr_failed",
+                "metadata": {"error": str(e)}
+            }
+
+    def _pdf_to_images(self, pdf_bytes: bytes, dpi: int = 300) -> List[Image.Image]:
+        """
+        Convert PDF pages to images
+
+        Args:
+            pdf_bytes: PDF content
+            dpi: Resolution for conversion
+
+        Returns:
+            List of PIL Images
+        """
+        try:
+            images = convert_from_bytes(
+                pdf_bytes,
+                dpi=dpi,
+                fmt='png',
+                thread_count=4
+            )
+            logger.info(f"Converted PDF to {len(images)} images")
+            return images
+
+        except Exception as e:
+            logger.error(f"PDF to image conversion failed: {str(e)}")
+            return []
+
+    def _preprocess_image(self, image: Image.Image) -> Image.Image:
+        """
+        Preprocess image for better OCR results
+
+        Args:
+            image: PIL Image
+
+        Returns:
+            Processed PIL Image
+        """
+        try:
+            # Convert to grayscale
+            image = image.convert('L')
+
+            # Increase contrast (simple thresholding)
+            # This helps with poor quality scans
+            from PIL import ImageEnhance
+
+            # Enhance contrast
+            enhancer = ImageEnhance.Contrast(image)
+            image = enhancer.enhance(2.0)
+
+            # Enhance sharpness
+            enhancer = ImageEnhance.Sharpness(image)
+            image = enhancer.enhance(2.0)
+
+            return image
+
+        except Exception as e:
+            logger.error(f"Image preprocessing failed: {str(e)}")
+            return image
+
+    def _extract_with_confidence(
+        self,
+        image: Image.Image,
+        language: str = 'eng'
+    ) -> Dict:
+        """
+        Extract text with confidence score
+
+        Args:
+            image: PIL Image
+            language: OCR language
+
+        Returns:
+            Dict with text and confidence
+        """
+        try:
+            # Get detailed OCR data
+            data = pytesseract.image_to_data(
+                image,
+                lang=language,
+                output_type=pytesseract.Output.DICT
+            )
+
+            # Extract text
+            text = pytesseract.image_to_string(image, lang=language)
+
+            # Calculate average confidence
+            confidences = [
+                int(conf)
+                for conf in data['conf']
+                if conf != '-1'
+            ]
+
+            avg_confidence = (
+                sum(confidences) / len(confidences)
+                if confidences else 0
+            )
+
+            return {
+                "text": text,
+                "confidence": avg_confidence
+            }
+
+        except Exception as e:
+            logger.error(f"OCR with confidence failed: {str(e)}")
+            # Fallback to simple extraction
+            try:
+                text = pytesseract.image_to_string(image, lang=language)
+                return {"text": text, "confidence": 0}
+            except:
+                return {"text": "", "confidence": 0}
+
+    def extract_text_from_image(
+        self,
+        image_bytes: bytes,
+        language: str = 'eng'
+    ) -> Dict:
+        """
+        Extract text from a single image
+
+        Args:
+            image_bytes: Image content as bytes
+            language: OCR language
+
+        Returns:
+            Dict with extracted text and metadata
+        """
+        try:
+            image = Image.open(io.BytesIO(image_bytes))
+            processed_image = self._preprocess_image(image)
+            result = self._extract_with_confidence(processed_image, language)
+
+            return {
+                "text": result["text"],
+                "method": "ocr",
+                "metadata": {
+                    "confidence": result["confidence"],
+                    "language": language,
+                    "word_count": len(result["text"].split()),
+                }
+            }
+
+        except Exception as e:
+            logger.error(f"Image OCR failed: {str(e)}")
+            return {
+                "text": "",
+                "method": "ocr_failed",
+                "metadata": {"error": str(e)}
+            }
+
+    def is_tesseract_available(self) -> bool:
+        """
+        Check if Tesseract is installed and available
+
+        Returns:
+            True if Tesseract is available
+        """
+        try:
+            pytesseract.get_tesseract_version()
+            return True
+        except Exception as e:
+            logger.error(f"Tesseract not available: {str(e)}")
+            return False
+
+    def get_supported_languages(self) -> List[str]:
+        """
+        Get list of supported OCR languages
+
+        Returns:
+            List of language codes
+        """
+        try:
+            langs = pytesseract.get_languages()
+            return langs
+        except Exception as e:
+            logger.error(f"Could not get languages: {str(e)}")
+            return self.supported_languages
+
+    def detect_language(self, image: Image.Image) -> str:
+        """
+        Attempt to detect language in image
+
+        Args:
+            image: PIL Image
+
+        Returns:
+            Detected language code
+        """
+        try:
+            # Tesseract can detect language
+            osd = pytesseract.image_to_osd(image)
+
+            # Parse OSD output for language
+            for line in osd.split('\n'):
+                if 'Script:' in line:
+                    script = line.split(':')[1].strip()
+                    logger.info(f"Detected script: {script}")
+
+            return 'eng'  # Default to English
+
+        except Exception as e:
+            logger.error(f"Language detection failed: {str(e)}")
+            return 'eng'
diff --git a/PdfToPodcast/api/pdf-service/app/core/pdf_extractor.py b/PdfToPodcast/api/pdf-service/app/core/pdf_extractor.py
new file mode 100644
index 0000000000..a583766a87
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/app/core/pdf_extractor.py
@@ -0,0 +1,281 @@
+import PyPDF2
+import pdfplumber
+import io
+import logging
+from typing import Dict, List, Tuple
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+class PDFExtractor:
+    """
+    Extract text and metadata from PDF files using multiple methods
+    """
+
+    def __init__(self):
+        self.extraction_methods = [
+            self._extract_with_pdfplumber,
+            self._extract_with_pypdf2,
+        ]
+
+    def extract(self, pdf_bytes: bytes) -> Dict:
+        """
+        Extract text from PDF using the best available method
+
+        Args:
+            pdf_bytes: PDF file content as bytes
+
+        Returns:
+            Dict with extracted text, metadata, and extraction info
+        """
+        try:
+            # Try pdfplumber first (best for complex layouts)
+            result = self._extract_with_pdfplumber(pdf_bytes)
+
+            # If no text found, try PyPDF2
+            if not result["text"].strip():
+                logger.warning("pdfplumber found no text, trying PyPDF2")
+                result = self._extract_with_pypdf2(pdf_bytes)
+
+            # Extract metadata
+            metadata = self._extract_metadata(pdf_bytes)
+            result["metadata"].update(metadata)
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Error extracting PDF: {str(e)}")
+            raise
+
+    def _extract_with_pdfplumber(self, pdf_bytes: bytes) -> Dict:
+        """Extract text using pdfplumber (best for complex layouts)"""
+        try:
+            text_parts = []
+            page_count = 0
+            has_images = False
+            tables_found = 0
+
+            with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
+                page_count = len(pdf.pages)
+
+                for page_num, page in enumerate(pdf.pages, 1):
+                    # Extract text
+                    page_text = page.extract_text()
+                    if page_text:
+                        text_parts.append(page_text)
+
+                    # Check for images
+                    if page.images:
+                        has_images = True
+
+                    # Extract tables if any
+                    tables = page.extract_tables()
+                    if tables:
+                        tables_found += len(tables)
+                        for table in tables:
+                            # Convert table to text
+                            table_text = self._table_to_text(table)
+                            text_parts.append(table_text)
+
+            full_text = "\n\n".join(text_parts)
+
+            return {
+                "text": full_text,
+                "method": "pdfplumber",
+                "metadata": {
+                    "pages": page_count,
+                    "has_images": has_images,
+                    "tables_found": tables_found,
+                    "word_count": len(full_text.split()),
+                    "character_count": len(full_text),
+                }
+            }
+
+        except Exception as e:
+            logger.error(f"pdfplumber extraction failed: {str(e)}")
+            return {"text": "", "method": "pdfplumber_failed", "metadata": {}}
+
+    def _extract_with_pypdf2(self, pdf_bytes: bytes) -> Dict:
+        """Extract text using PyPDF2 (fallback method)"""
+        try:
+            text_parts = []
+            pdf_reader = PyPDF2.PdfReader(io.BytesIO(pdf_bytes))
+            page_count = len(pdf_reader.pages)
+
+            for page_num, page in enumerate(pdf_reader.pages, 1):
+                page_text = page.extract_text()
+                if page_text:
+                    text_parts.append(page_text)
+
+            full_text = "\n\n".join(text_parts)
+
+            return {
+                "text": full_text,
+                "method": "pypdf2",
+                "metadata": {
+                    "pages": page_count,
+                    "word_count": len(full_text.split()),
+                    "character_count": len(full_text),
+                }
+            }
+
+        except Exception as e:
+            logger.error(f"PyPDF2 extraction failed: {str(e)}")
+            return {"text": "", "method": "pypdf2_failed", "metadata": {}}
+
+    def _extract_metadata(self, pdf_bytes: bytes) -> Dict:
+        """Extract PDF metadata"""
+        try:
+            pdf_reader = PyPDF2.PdfReader(io.BytesIO(pdf_bytes))
+            metadata = pdf_reader.metadata
+
+            if metadata:
+                return {
+                    "title": metadata.get("/Title", ""),
+                    "author": metadata.get("/Author", ""),
+                    "subject": metadata.get("/Subject", ""),
+                    "creator": metadata.get("/Creator", ""),
+                    "producer": metadata.get("/Producer", ""),
+                }
+            return {}
+
+        except Exception as e:
+            logger.error(f"Metadata extraction failed: {str(e)}")
+            return {}
+
+    def _table_to_text(self, table: List[List]) -> str:
+        """Convert table data to formatted text"""
+        if not table:
+            return ""
+
+        lines = []
+        for row in table:
+            # Filter out None values and join cells
+            cells = [str(cell) if cell else "" for cell in row]
+            line = " | ".join(cells)
+            lines.append(line)
+
+        return "\n".join(lines)
+
+    def check_if_scanned(self, pdf_bytes: bytes) -> bool:
+        """
+        Check if PDF is likely a scanned document (image-based)
+
+        Returns:
+            True if PDF appears to be scanned (needs OCR)
+        """
+        try:
+            # Extract text using both methods
+            text_length = 0
+
+            with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
+                for page in pdf.pages:
+                    text = page.extract_text()
+                    if text:
+                        text_length += len(text.strip())
+
+            # If very little text extracted, likely scanned
+            # Threshold: less than 50 characters per page on average
+            pdf_reader = PyPDF2.PdfReader(io.BytesIO(pdf_bytes))
+            page_count = len(pdf_reader.pages)
+
+            avg_chars_per_page = text_length / page_count if page_count > 0 else 0
+
+            return avg_chars_per_page < 50
+
+        except Exception as e:
+            logger.error(f"Error checking if scanned: {str(e)}")
+            return False
+
+    def extract_page_structure(self, pdf_bytes: bytes) -> List[Dict]:
+        """
+        Analyze document structure (headings, paragraphs)
+
+        Returns:
+            List of structured content blocks
+        """
+        try:
+            structure = []
+
+            with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
+                for page_num, page in enumerate(pdf.pages, 1):
+                    # Extract text with layout info
+                    words = page.extract_words()
+
+                    if not words:
+                        continue
+
+                    # Group words into lines
+                    lines = self._group_words_into_lines(words)
+
+                    # Classify lines (heading, paragraph, etc.)
+                    for line in lines:
+                        block = {
+                            "page": page_num,
+                            "text": line["text"],
+                            "type": self._classify_text_block(line),
+                            "font_size": line.get("font_size", 0),
+                        }
+                        structure.append(block)
+
+            return structure
+
+        except Exception as e:
+            logger.error(f"Structure extraction failed: {str(e)}")
+            return []
+
+    def _group_words_into_lines(self, words: List[Dict]) -> List[Dict]:
+        """Group words into lines based on vertical position"""
+        if not words:
+            return []
+
+        lines = []
+        current_line = []
+        current_y = words[0]["top"]
+        tolerance = 5  # pixels
+
+        for word in words:
+            if abs(word["top"] - current_y) <= tolerance:
+                current_line.append(word)
+            else:
+                if current_line:
+                    lines.append({
+                        "text": " ".join([w["text"] for w in current_line]),
+                        "font_size": max([w.get("height", 0) for w in current_line]),
+                        "y_position": current_y,
+                    })
+                current_line = [word]
+                current_y = word["top"]
+
+        # Add last line
+        if current_line:
+            lines.append({
+                "text": " ".join([w["text"] for w in current_line]),
+                "font_size": max([w.get("height", 0) for w in current_line]),
+                "y_position": current_y,
+            })
+
+        return lines
+
+    def _classify_text_block(self, line: Dict) -> str:
+        """Classify text block as heading, paragraph, etc."""
+        text = line["text"].strip()
+        font_size = line.get("font_size", 0)
+
+        # Simple heuristics
+        if not text:
+            return "empty"
+
+        # Large font = likely heading
+        if font_size > 14:
+            return "heading"
+
+        # All caps short text = likely heading
+        if text.isupper() and len(text.split()) <= 10:
+            return "heading"
+
+        # Numbered or bulleted
+        if text[0].isdigit() or text.startswith("•") or text.startswith("-"):
+            return "list_item"
+
+        return "paragraph"
diff --git a/PdfToPodcast/api/pdf-service/app/core/text_cleaner.py b/PdfToPodcast/api/pdf-service/app/core/text_cleaner.py
new file mode 100644
index 0000000000..2f53bf2c58
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/app/core/text_cleaner.py
@@ -0,0 +1,284 @@
+import re
+import logging
+from typing import List, Set
+
+logger = logging.getLogger(__name__)
+
+class TextCleaner:
+    """
+    Clean and preprocess extracted PDF text
+    """
+
+    def __init__(self):
+        # Common header/footer patterns
+        self.header_footer_patterns = [
+            r'^\d+$',  # Page numbers
+            r'^Page \d+',  # "Page N"
+            r'^\d+ of \d+$',  # "1 of 10"
+            r'^Copyright ©',  # Copyright notices
+            r'^©\s*\d{4}',  # © 2024
+            r'^All rights reserved',
+            r'^\d{4}-\d{2}-\d{2}$',  # Dates in headers
+        ]
+
+        # Common noise patterns
+        self.noise_patterns = [
+            r'\[image:.*?\]',  # Image placeholders
+            r'\[table:.*?\]',  # Table placeholders
+            r'\x0c',  # Form feed characters
+        ]
+
+    def clean(self, text: str, aggressive: bool = False) -> str:
+        """
+        Clean extracted text
+
+        Args:
+            text: Raw extracted text
+            aggressive: If True, apply more aggressive cleaning
+
+        Returns:
+            Cleaned text
+        """
+        if not text:
+            return ""
+
+        try:
+            # Step 1: Normalize whitespace
+            text = self._normalize_whitespace(text)
+
+            # Step 2: Remove headers and footers
+            text = self._remove_headers_footers(text)
+
+            # Step 3: Remove common noise patterns
+            text = self._remove_noise(text)
+
+            # Step 4: Fix hyphenation (words split across lines)
+            text = self._fix_hyphenation(text)
+
+            # Step 5: Remove extra line breaks
+            text = self._normalize_paragraphs(text)
+
+            # Step 6: Fix common OCR errors (if aggressive)
+            if aggressive:
+                text = self._fix_ocr_errors(text)
+
+            # Step 7: Final cleanup
+            text = text.strip()
+
+            return text
+
+        except Exception as e:
+            logger.error(f"Error cleaning text: {str(e)}")
+            return text
+
+    def _normalize_whitespace(self, text: str) -> str:
+        """Normalize whitespace characters"""
+        # Replace multiple spaces with single space
+        text = re.sub(r' +', ' ', text)
+
+        # Replace tabs with spaces
+        text = text.replace('\t', ' ')
+
+        # Normalize line endings
+        text = text.replace('\r\n', '\n').replace('\r', '\n')
+
+        # Remove trailing whitespace from lines
+        lines = [line.rstrip() for line in text.split('\n')]
+        text = '\n'.join(lines)
+
+        return text
+
+    def _remove_headers_footers(self, text: str) -> str:
+        """Remove common header and footer patterns"""
+        lines = text.split('\n')
+        cleaned_lines = []
+
+        for line in lines:
+            line_stripped = line.strip()
+
+            # Check if line matches header/footer patterns
+            is_header_footer = False
+            for pattern in self.header_footer_patterns:
+                if re.match(pattern, line_stripped, re.IGNORECASE):
+                    is_header_footer = True
+                    break
+
+            if not is_header_footer:
+                cleaned_lines.append(line)
+
+        return '\n'.join(cleaned_lines)
+
+    def _remove_noise(self, text: str) -> str:
+        """Remove noise patterns"""
+        for pattern in self.noise_patterns:
+            text = re.sub(pattern, '', text, flags=re.IGNORECASE)
+
+        return text
+
+    def _fix_hyphenation(self, text: str) -> str:
+        """
+        Fix words split across lines with hyphens
+
+        Example: "under-\nstand" -> "understand"
+        """
+        # Match word-hyphen-newline-word pattern
+        text = re.sub(r'(\w+)-\s*\n\s*(\w+)', r'\1\2', text)
+
+        return text
+
+    def _normalize_paragraphs(self, text: str) -> str:
+        """
+        Normalize paragraph breaks
+
+        - Single line breaks within paragraphs become spaces
+        - Multiple line breaks become paragraph breaks
+        """
+        # Replace 3+ line breaks with placeholder
+        text = re.sub(r'\n{3,}', '<<<PARAGRAPH>>>', text)
+
+        # Replace single/double line breaks with space
+        text = re.sub(r'\n{1,2}', ' ', text)
+
+        # Restore paragraph breaks
+        text = text.replace('<<<PARAGRAPH>>>', '\n\n')
+
+        # Remove extra spaces
+        text = re.sub(r' +', ' ', text)
+
+        return text
+
+    def _fix_ocr_errors(self, text: str) -> str:
+        """Fix common OCR errors"""
+        # Common OCR substitutions
+        ocr_fixes = {
+            r'\b0\b': 'O',  # Zero mistaken for O
+            r'\bl\b': 'I',  # lowercase L mistaken for I
+            r'\brn\b': 'm',  # rn mistaken for m
+            r'\|': 'I',  # Pipe mistaken for I
+        }
+
+        for pattern, replacement in ocr_fixes.items():
+            text = re.sub(pattern, replacement, text)
+
+        return text
+
+    def extract_sections(self, text: str) -> List[dict]:
+        """
+        Split text into logical sections based on headings
+
+        Returns:
+            List of sections with headings and content
+        """
+        sections = []
+        lines = text.split('\n')
+
+        current_section = {"heading": "Introduction", "content": []}
+
+        for line in lines:
+            line_stripped = line.strip()
+
+            if not line_stripped:
+                continue
+
+            # Check if line is a heading (simple heuristic)
+            if self._is_heading(line_stripped):
+                # Save previous section
+                if current_section["content"]:
+                    sections.append({
+                        "heading": current_section["heading"],
+                        "content": "\n".join(current_section["content"])
+                    })
+
+                # Start new section
+                current_section = {"heading": line_stripped, "content": []}
+            else:
+                current_section["content"].append(line_stripped)
+
+        # Add last section
+        if current_section["content"]:
+            sections.append({
+                "heading": current_section["heading"],
+                "content": "\n".join(current_section["content"])
+            })
+
+        return sections
+
+    def _is_heading(self, line: str) -> bool:
+        """Detect if a line is likely a heading"""
+        # Heuristics for heading detection
+        if not line:
+            return False
+
+        # All caps and short
+        if line.isupper() and len(line.split()) <= 10:
+            return True
+
+        # Starts with number (e.g., "1. Introduction")
+        if re.match(r'^\d+\.?\s+[A-Z]', line):
+            return True
+
+        # Common heading words
+        heading_keywords = [
+            'Introduction', 'Conclusion', 'Abstract', 'Summary',
+            'Chapter', 'Section', 'Background', 'Methods',
+            'Results', 'Discussion', 'References'
+        ]
+
+        for keyword in heading_keywords:
+            if line.startswith(keyword):
+                return True
+
+        return False
+
+    def remove_references(self, text: str) -> str:
+        """Remove references/bibliography section"""
+        # Common reference section markers
+        ref_markers = [
+            'References', 'Bibliography', 'Works Cited',
+            'REFERENCES', 'BIBLIOGRAPHY'
+        ]
+
+        lines = text.split('\n')
+        ref_start_idx = None
+
+        for i, line in enumerate(lines):
+            line_stripped = line.strip()
+            for marker in ref_markers:
+                if line_stripped == marker or line_stripped.startswith(marker):
+                    ref_start_idx = i
+                    break
+            if ref_start_idx is not None:
+                break
+
+        # Remove everything after reference section
+        if ref_start_idx is not None:
+            lines = lines[:ref_start_idx]
+
+        return '\n'.join(lines)
+
+    def get_statistics(self, text: str) -> dict:
+        """Get text statistics"""
+        if not text:
+            return {
+                "word_count": 0,
+                "character_count": 0,
+                "sentence_count": 0,
+                "paragraph_count": 0,
+                "avg_words_per_sentence": 0,
+            }
+
+        words = text.split()
+        sentences = re.split(r'[.!?]+', text)
+        paragraphs = text.split('\n\n')
+
+        word_count = len(words)
+        sentence_count = len([s for s in sentences if s.strip()])
+        paragraph_count = len([p for p in paragraphs if p.strip()])
+
+        return {
+            "word_count": word_count,
+            "character_count": len(text),
+            "sentence_count": sentence_count,
+            "paragraph_count": paragraph_count,
+            "avg_words_per_sentence": round(word_count / sentence_count, 2) if sentence_count > 0 else 0,
+        }
diff --git a/PdfToPodcast/api/pdf-service/app/main.py b/PdfToPodcast/api/pdf-service/app/main.py
new file mode 100644
index 0000000000..ae8fd80278
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/app/main.py
@@ -0,0 +1,70 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+import logging
+import sys
+
+from app.api.routes import router
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+
+logger = logging.getLogger(__name__)
+
+# Create FastAPI app
+app = FastAPI(
+    title="PDF Processing Service",
+    description="Extract text from PDFs with OCR support for scanned documents",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(router, tags=["PDF Processing"])
+
+@app.on_event("startup")
+async def startup_event():
+    """Run on application startup"""
+    logger.info("PDF Processing Service starting up...")
+    logger.info("Service running on port 8001")
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    """Run on application shutdown"""
+    logger.info("PDF Processing Service shutting down...")
+
+@app.get("/")
+async def root():
+    """Root endpoint"""
+    return {
+        "service": "PDF Processing Service",
+        "version": "1.0.0",
+        "description": "Extract text from PDFs with OCR support",
+        "endpoints": {
+            "extract": "POST /extract - Extract text from PDF",
+            "extract_structure": "POST /extract-structure - Extract document structure",
+            "extract_with_ocr": "POST /extract-with-ocr - Force OCR extraction",
+            "health": "GET /health - Health check",
+            "languages": "GET /languages - Supported OCR languages",
+            "docs": "GET /docs - API documentation"
+        }
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8001)
diff --git a/PdfToPodcast/api/pdf-service/requirements.txt b/PdfToPodcast/api/pdf-service/requirements.txt
new file mode 100644
index 0000000000..e71d89660e
--- /dev/null
+++ b/PdfToPodcast/api/pdf-service/requirements.txt
@@ -0,0 +1,14 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+PyPDF2==3.0.1
+pdfplumber==0.10.3
+pytesseract==0.3.10
+Pillow==10.1.0
+pdf2image==1.16.3
+python-dotenv==1.0.0
+pydantic==2.5.0
+pydantic-settings==2.1.0
+aiofiles==23.2.1
+python-magic==0.4.27
+langdetect==1.0.9
diff --git a/PdfToPodcast/api/tts-service/.env.example b/PdfToPodcast/api/tts-service/.env.example
new file mode 100644
index 0000000000..c5965720b3
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/.env.example
@@ -0,0 +1,22 @@
+# OpenAI API Configuration (Required for TTS)
+OPENAI_API_KEY=your-openai-api-key-here
+
+# Service Configuration
+SERVICE_NAME=TTS Audio Generation Service
+SERVICE_VERSION=1.0.0
+SERVICE_PORT=8003
+
+# TTS Settings
+TTS_MODEL=tts-1-hd
+DEFAULT_HOST_VOICE=alloy
+DEFAULT_GUEST_VOICE=nova
+
+# Audio Settings
+OUTPUT_DIR=static/audio
+AUDIO_FORMAT=mp3
+AUDIO_BITRATE=192k
+SILENCE_DURATION_MS=500
+
+# Processing
+MAX_CONCURRENT_REQUESTS=5
+MAX_SCRIPT_LENGTH=100
diff --git a/PdfToPodcast/api/tts-service/Dockerfile b/PdfToPodcast/api/tts-service/Dockerfile
new file mode 100644
index 0000000000..56ab7634d9
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/Dockerfile
@@ -0,0 +1,25 @@
+# --- Builder Stage ---
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# --- Final Stage ---
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+ && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY . .
+
+EXPOSE 8003
+
+CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8003"]
\ No newline at end of file
diff --git a/PdfToPodcast/api/tts-service/README.md b/PdfToPodcast/api/tts-service/README.md
new file mode 100644
index 0000000000..5e7f163561
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/README.md
@@ -0,0 +1,324 @@
+# TTS Audio Generation Microservice
+
+Converts podcast scripts into high-quality audio using OpenAI's Text-to-Speech API.
+
+## Features
+
+**OpenAI TTS Integration**
+- High-definition audio (tts-1-hd model)
+- Multiple voice options (alloy, echo, fable, onyx, nova, shimmer)
+- High-quality 24kHz audio output
+
+**Intelligent Audio Processing**
+- Concurrent segment generation (up to 5 parallel requests)
+- Automatic audio mixing with silence between turns
+- MP3 compression (192kbps) for optimal file size
+- Metadata tagging (title, artist, album)
+
+**Advanced Voice Management**
+- 6 distinct voice personalities
+- Host and guest voice selection
+- Voice sample generation
+- Voice metadata and descriptions
+
+## API Endpoints
+
+### 1. Generate Audio
+
+**POST** `/generate-audio`
+
+Convert script dialogue into podcast audio.
+
+**Request:**
+```json
+{
+  "script": [
+    {
+      "speaker": "host",
+      "text": "Welcome to today's show!"
+    },
+    {
+      "speaker": "guest",
+      "text": "Thanks for having me!"
+    }
+  ],
+  "host_voice": "alloy",
+  "guest_voice": "shimmer",
+  "job_id": "optional-tracking-id"
+}
+```
+
+**Response:**
+```json
+{
+  "job_id": "abc123",
+  "audio_url": "/static/abc123/podcast_abc123.mp3",
+  "local_path": "/path/to/file.mp3",
+  "metadata": {
+    "duration_seconds": 125.5,
+    "duration_minutes": 2.09,
+    "total_segments": 24,
+    "host_voice": "alloy",
+    "guest_voice": "shimmer",
+    "file_size_mb": 2.4
+  },
+  "status": "completed"
+}
+```
+
+### 2. Download Audio
+
+**GET** `/download/{job_id}`
+
+Download generated podcast audio file.
+
+**Response:** MP3 audio file
+
+### 3. Get Available Voices
+
+**GET** `/voices`
+
+List all available TTS voices with descriptions.
+
+**Response:**
+```json
+{
+  "voices": [
+    {
+      "id": "alloy",
+      "name": "Alloy",
+      "description": "Neutral and balanced",
+      "gender": "neutral"
+    },
+    {
+      "id": "echo",
+      "name": "Echo",
+      "description": "Deep and resonant",
+      "gender": "male"
+    }
+  ],
+  "default_host": "alloy",
+  "default_guest": "nova"
+}
+```
+
+### 4. Generate Voice Sample
+
+**POST** `/voice-sample/{voice_id}`
+
+Generate a sample audio clip for a specific voice.
+
+**Request:**
+```json
+{
+  "text": "Hello! This is a sample of my voice."
+}
+```
+
+**Response:**
+```json
+{
+  "voice_id": "alloy",
+  "sample_path": "/static/samples/sample_alloy.mp3",
+  "status": "success"
+}
+```
+
+### 5. Job Status
+
+**GET** `/status/{job_id}`
+
+Check generation status for a specific job.
+
+**Response:**
+```json
+{
+  "job_id": "abc123",
+  "status": "completed",
+  "progress": 100,
+  "message": "Audio generation complete",
+  "audio_url": "/download/abc123"
+}
+```
+
+### 6. Health Check
+
+**GET** `/health`
+
+Check service health and API availability.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "openai_available": true,
+  "version": "1.0.0"
+}
+```
+
+## Prerequisites
+
+- OpenAI API key
+- FFmpeg (included in Docker)
+- Python 3.9+
+
+## Installation
+
+### Using Docker
+
+```bash
+cd microservices/tts-service
+docker build -t tts-service .
+docker run -p 8003:8003 \
+  -e OPENAI_API_KEY=your_key \
+  tts-service
+```
+
+### Manual Installation
+
+Install FFmpeg:
+```bash
+# Ubuntu/Debian
+sudo apt-get install ffmpeg
+
+# macOS
+brew install ffmpeg
+```
+
+Install Python dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+## Configuration
+
+Create `.env` file:
+
+```env
+# Required
+OPENAI_API_KEY=sk-proj-your-key-here
+
+# Optional
+TTS_MODEL=tts-1-hd
+DEFAULT_HOST_VOICE=alloy
+DEFAULT_GUEST_VOICE=nova
+AUDIO_QUALITY=192k
+SAMPLE_RATE=24000
+CONCURRENT_REQUESTS=5
+SERVICE_PORT=8003
+```
+
+## Usage Examples
+
+### Python
+
+```python
+import requests
+
+# Generate audio
+response = requests.post(
+    "http://localhost:8003/generate-audio",
+    json={
+        "script": [
+            {"speaker": "host", "text": "Welcome!"},
+            {"speaker": "guest", "text": "Thanks!"}
+        ],
+        "host_voice": "onyx",
+        "guest_voice": "shimmer"
+    }
+)
+
+result = response.json()
+print(f"Audio generated: {result['audio_url']}")
+print(f"Duration: {result['metadata']['duration_minutes']} minutes")
+```
+
+### cURL
+
+```bash
+# Generate audio
+curl -X POST http://localhost:8003/generate-audio \
+  -H "Content-Type: application/json" \
+  -d '{
+    "script": [
+      {"speaker": "host", "text": "Hello!"},
+      {"speaker": "guest", "text": "Hi there!"}
+    ],
+    "host_voice": "alloy",
+    "guest_voice": "nova"
+  }'
+
+# Download audio
+curl http://localhost:8003/download/abc123 -o podcast.mp3
+
+# Get voices
+curl http://localhost:8003/voices
+```
+
+## Available Voices
+
+| Voice ID | Name | Description | Gender | Best For |
+|----------|------|-------------|--------|----------|
+| **alloy** | Alloy | Neutral and balanced | Neutral | General purpose |
+| **echo** | Echo | Deep and resonant | Male | Professional content |
+| **fable** | Fable | Expressive and dynamic | Neutral | Storytelling |
+| **onyx** | Onyx | Strong and authoritative | Male | Educational content |
+| **nova** | Nova | Warm and friendly | Female | Casual conversations |
+| **shimmer** | Shimmer | Bright and energetic | Female | Engaging discussions |
+
+## Testing
+
+Test audio generation:
+```bash
+curl -X POST http://localhost:8003/generate-audio \
+  -H "Content-Type: application/json" \
+  -d @test_script.json
+```
+
+Test health:
+```bash
+curl http://localhost:8003/health
+```
+
+Test voices:
+```bash
+curl http://localhost:8003/voices
+```
+
+## Troubleshooting
+
+### OpenAI API Errors
+
+**Error**: `AuthenticationError`
+- Check `OPENAI_API_KEY` in environment
+- Verify API key is active
+- Check account has TTS access
+
+**Error**: `RateLimitError`
+- Service will retry automatically
+- Consider reducing concurrent_requests
+
+### FFmpeg Not Found
+
+**Error**: `FileNotFoundError: ffmpeg`
+
+**Solution**:
+```bash
+sudo apt-get install ffmpeg  # Linux
+brew install ffmpeg          # macOS
+```
+
+### Slow Generation
+
+**Causes**:
+- Large number of dialogue turns
+- Network latency
+- API rate limits
+
+**Solutions**:
+- Break into smaller jobs
+- Use faster model (tts-1 instead of tts-1-hd)
+
+## API Documentation
+
+View interactive API docs at `http://localhost:8003/docs`
diff --git a/PdfToPodcast/api/tts-service/app/__init__.py b/PdfToPodcast/api/tts-service/app/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/tts-service/app/api/__init__.py b/PdfToPodcast/api/tts-service/app/api/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/tts-service/app/api/routes.py b/PdfToPodcast/api/tts-service/app/api/routes.py
new file mode 100644
index 0000000000..f5b5b08a8c
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/api/routes.py
@@ -0,0 +1,298 @@
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+from typing import List, Dict, Optional
+from pathlib import Path
+import logging
+import os
+import uuid
+
+from app.core.audio_generator import AudioGenerator
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+# Initialize audio generator
+OUTPUT_DIR = Path(settings.OUTPUT_DIR)
+audio_generator = AudioGenerator(
+    openai_api_key=settings.OPENAI_API_KEY or "",
+    output_dir=OUTPUT_DIR,
+    tts_model=settings.TTS_MODEL
+)
+
+# Job storage (in production, use Redis/database)
+jobs = {}
+
+class GenerateAudioRequest(BaseModel):
+    script: List[Dict[str, str]] = Field(..., description="Podcast script")
+    host_voice: str = Field(default="alloy", description="Host voice ID")
+    guest_voice: str = Field(default="nova", description="Guest voice ID")
+    job_id: Optional[str] = Field(default=None, description="Optional job ID")
+
+class AudioStatusResponse(BaseModel):
+    job_id: str
+    status: str
+    progress: int
+    message: str
+    audio_url: Optional[str] = None
+    metadata: Optional[Dict] = None
+
+class VoiceInfo(BaseModel):
+    id: str
+    name: str
+    description: str
+    gender: str
+    suitable_for: List[str]
+
+class VoicesResponse(BaseModel):
+    voices: List[Dict]
+    default_host: str
+    default_guest: str
+
+class HealthResponse(BaseModel):
+    status: str
+    tts_available: bool
+    version: str
+
+async def generation_task(
+    job_id: str,
+    script: List[Dict[str, str]],
+    host_voice: str,
+    guest_voice: str
+):
+    """Background task for audio generation"""
+    try:
+        # Update job status
+        jobs[job_id] = {
+            "status": "processing",
+            "progress": 0,
+            "message": "Starting audio generation..."
+        }
+
+        # Progress callback
+        async def progress_callback(job_id, progress, message):
+            jobs[job_id] = {
+                "status": "processing",
+                "progress": progress,
+                "message": message
+            }
+
+        # Generate podcast
+        result = await audio_generator.generate_podcast(
+            script=script,
+            host_voice=host_voice,
+            guest_voice=guest_voice,
+            job_id=job_id,
+            progress_callback=progress_callback
+        )
+
+        # Update job with results
+        jobs[job_id] = {
+            "status": "completed",
+            "progress": 100,
+            "message": "Audio generation complete!",
+            "audio_url": result["audio_url"],
+            "metadata": result["metadata"]
+        }
+
+        logger.info(f"Job {job_id} completed successfully")
+
+    except Exception as e:
+        logger.error(f"Job {job_id} failed: {str(e)}")
+        jobs[job_id] = {
+            "status": "failed",
+            "progress": 0,
+            "message": f"Error: {str(e)}"
+        }
+
+@router.post("/generate-audio")
+async def generate_audio(
+    request: GenerateAudioRequest,
+    background_tasks: BackgroundTasks
+):
+    """
+    Generate podcast audio from script
+
+    - **script**: List of dialogue objects with speaker and text
+    - **host_voice**: Voice ID for host (default: alloy)
+    - **guest_voice**: Voice ID for guest (default: nova)
+    - **job_id**: Optional job ID for tracking
+
+    Returns job ID for status tracking
+    """
+    try:
+        # Validate script
+        if not request.script or len(request.script) < 2:
+            raise HTTPException(
+                status_code=400,
+                detail="Script must have at least 2 dialogue turns"
+            )
+
+        # Generate job ID
+        job_id = request.job_id or str(uuid.uuid4())
+
+        # Initialize job
+        jobs[job_id] = {
+            "status": "queued",
+            "progress": 0,
+            "message": "Job queued for processing"
+        }
+
+        # Start background task
+        background_tasks.add_task(
+            generation_task,
+            job_id,
+            request.script,
+            request.host_voice,
+            request.guest_voice
+        )
+
+        logger.info(f"Started job {job_id}")
+
+        return {
+            "job_id": job_id,
+            "status": "queued",
+            "message": "Audio generation started"
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to start job: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to start audio generation: {str(e)}"
+        )
+
+@router.get("/status/{job_id}", response_model=AudioStatusResponse)
+async def get_status(job_id: str):
+    """
+    Get audio generation status
+
+    Returns current status and progress
+    """
+    if job_id not in jobs:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Job {job_id} not found"
+        )
+
+    job = jobs[job_id]
+
+    return AudioStatusResponse(
+        job_id=job_id,
+        status=job["status"],
+        progress=job["progress"],
+        message=job["message"],
+        audio_url=job.get("audio_url"),
+        metadata=job.get("metadata")
+    )
+
+@router.get("/download/{job_id}")
+async def download_audio(job_id: str):
+    """
+    Download generated podcast audio
+
+    Returns audio file for streaming/download
+    """
+    if job_id not in jobs:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Job {job_id} not found"
+        )
+
+    job = jobs[job_id]
+
+    if job["status"] != "completed":
+        raise HTTPException(
+            status_code=400,
+            detail=f"Job not completed. Status: {job['status']}"
+        )
+
+    # Get audio file path
+    audio_path = OUTPUT_DIR / job_id / f"podcast_{job_id}.mp3"
+
+    if not audio_path.exists():
+        raise HTTPException(
+            status_code=404,
+            detail="Audio file not found"
+        )
+
+    return FileResponse(
+        path=str(audio_path),
+        media_type="audio/mpeg",
+        filename=f"podcast_{job_id}.mp3"
+    )
+
+@router.get("/voices", response_model=VoicesResponse)
+async def get_voices():
+    """
+    Get list of available voices
+
+    Returns all available voices with metadata
+    """
+    try:
+        voices_data = audio_generator.get_available_voices()
+        return VoicesResponse(**voices_data)
+
+    except Exception as e:
+        logger.error(f"Failed to get voices: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to retrieve voices"
+        )
+
+@router.get("/voice-sample/{voice_id}")
+async def get_voice_sample(voice_id: str):
+    """
+    Get voice sample audio
+
+    Returns sample audio for the specified voice
+    """
+    try:
+        sample_path = await audio_generator.generate_voice_sample(voice_id)
+
+        return FileResponse(
+            path=str(sample_path),
+            media_type="audio/mpeg",
+            filename=f"sample_{voice_id}.mp3"
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to generate sample: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to generate voice sample: {str(e)}"
+        )
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Check service health"""
+    tts_available = audio_generator.tts_client.is_available()
+
+    return HealthResponse(
+        status="healthy" if tts_available else "degraded",
+        tts_available=tts_available,
+        version="1.0.0"
+    )
+
+@router.delete("/job/{job_id}")
+async def delete_job(job_id: str):
+    """Delete job and associated files"""
+    if job_id not in jobs:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Job {job_id} not found"
+        )
+
+    # Delete job directory
+    job_dir = OUTPUT_DIR / job_id
+    if job_dir.exists():
+        import shutil
+        shutil.rmtree(job_dir)
+
+    # Remove from jobs dict
+    del jobs[job_id]
+
+    return {"message": f"Job {job_id} deleted"}
diff --git a/PdfToPodcast/api/tts-service/app/config.py b/PdfToPodcast/api/tts-service/app/config.py
new file mode 100644
index 0000000000..26b7488ea5
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/config.py
@@ -0,0 +1,34 @@
+from pydantic_settings import BaseSettings
+from typing import Optional
+
+class Settings(BaseSettings):
+    """TTS Service Configuration"""
+
+    # Service info
+    SERVICE_NAME: str = "TTS Audio Generation Service"
+    SERVICE_VERSION: str = "1.0.0"
+    SERVICE_PORT: int = 8003
+
+    # API Keys
+    OPENAI_API_KEY: Optional[str] = None
+
+    # TTS settings
+    TTS_MODEL: str = "tts-1-hd"  # or tts-1 for faster/cheaper
+    DEFAULT_HOST_VOICE: str = "alloy"
+    DEFAULT_GUEST_VOICE: str = "nova"
+
+    # Audio settings
+    OUTPUT_DIR: str = "static/audio"
+    AUDIO_FORMAT: str = "mp3"
+    AUDIO_BITRATE: str = "192k"
+    SILENCE_DURATION_MS: int = 500
+
+    # Processing
+    MAX_CONCURRENT_REQUESTS: int = 5
+    MAX_SCRIPT_LENGTH: int = 100  # Max dialogue turns
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+settings = Settings()
diff --git a/PdfToPodcast/api/tts-service/app/config/voices.json b/PdfToPodcast/api/tts-service/app/config/voices.json
new file mode 100644
index 0000000000..8014b7a59d
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/config/voices.json
@@ -0,0 +1,50 @@
+{
+  "openai_voices": {
+    "alloy": {
+      "name": "Alloy",
+      "description": "Neutral and balanced voice",
+      "gender": "neutral",
+      "suitable_for": ["host", "guest"]
+    },
+    "echo": {
+      "name": "Echo",
+      "description": "Deep and resonant voice",
+      "gender": "male",
+      "suitable_for": ["host", "guest"]
+    },
+    "fable": {
+      "name": "Fable",
+      "description": "Expressive and dynamic voice",
+      "gender": "female",
+      "suitable_for": ["host", "guest"]
+    },
+    "onyx": {
+      "name": "Onyx",
+      "description": "Strong and authoritative voice",
+      "gender": "male",
+      "suitable_for": ["host"]
+    },
+    "nova": {
+      "name": "Nova",
+      "description": "Warm and friendly voice",
+      "gender": "female",
+      "suitable_for": ["host", "guest"]
+    },
+    "shimmer": {
+      "name": "Shimmer",
+      "description": "Bright and energetic voice",
+      "gender": "female",
+      "suitable_for": ["guest"]
+    }
+  },
+  "default_voices": {
+    "host": "alloy",
+    "guest": "nova"
+  },
+  "audio_settings": {
+    "format": "mp3",
+    "sample_rate": 24000,
+    "model": "tts-1-hd",
+    "speed": 1.0
+  }
+}
diff --git a/PdfToPodcast/api/tts-service/app/core/__init__.py b/PdfToPodcast/api/tts-service/app/core/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/PdfToPodcast/api/tts-service/app/core/audio_generator.py b/PdfToPodcast/api/tts-service/app/core/audio_generator.py
new file mode 100644
index 0000000000..e45e49c5df
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/core/audio_generator.py
@@ -0,0 +1,246 @@
+from pathlib import Path
+import logging
+import uuid
+from typing import Dict, List, Optional
+import asyncio
+
+from app.core.tts_client import TTSClient
+from app.core.audio_mixer import AudioMixer
+from app.core.voice_manager import VoiceManager
+
+logger = logging.getLogger(__name__)
+
+class AudioGenerator:
+    """
+    Main orchestrator for podcast audio generation
+    """
+
+    def __init__(
+        self,
+        openai_api_key: str,
+        output_dir: Path,
+        tts_model: str = "tts-1-hd"
+    ):
+        """
+        Initialize audio generator
+
+        Args:
+            openai_api_key: OpenAI API key
+            output_dir: Directory for output files
+            tts_model: TTS model to use
+        """
+        self.tts_client = TTSClient(openai_api_key, model=tts_model)
+        self.audio_mixer = AudioMixer()
+        self.voice_manager = VoiceManager()
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    async def generate_podcast(
+        self,
+        script: List[Dict[str, str]],
+        host_voice: str = "alloy",
+        guest_voice: str = "nova",
+        job_id: Optional[str] = None,
+        progress_callback: Optional[callable] = None
+    ) -> Dict:
+        """
+        Generate complete podcast audio from script
+
+        Args:
+            script: List of dialogue objects
+            host_voice: Voice ID for host
+            guest_voice: Voice ID for guest
+            job_id: Optional job ID
+            progress_callback: Optional progress callback
+
+        Returns:
+            Dict with audio_url and metadata
+        """
+        try:
+            if not job_id:
+                job_id = str(uuid.uuid4())
+
+            logger.info(f"Generating podcast for job {job_id}")
+            logger.info(f"Script: {len(script)} turns, host={host_voice}, guest={guest_voice}")
+
+            # Validate voices
+            if not self.voice_manager.validate_voice(host_voice):
+                logger.warning(f"Invalid host voice {host_voice}, using default")
+                host_voice = self.voice_manager.get_default_voice("host")
+
+            if not self.voice_manager.validate_voice(guest_voice):
+                logger.warning(f"Invalid guest voice {guest_voice}, using default")
+                guest_voice = self.voice_manager.get_default_voice("guest")
+
+            # Create job directory
+            job_dir = self.output_dir / job_id
+            job_dir.mkdir(parents=True, exist_ok=True)
+            segments_dir = job_dir / "segments"
+            segments_dir.mkdir(exist_ok=True)
+
+            # Update progress
+            if progress_callback:
+                await progress_callback(job_id, 10, "Generating audio segments...")
+
+            # Prepare texts and voices
+            texts = [item["text"] for item in script]
+            voices = [
+                host_voice if item["speaker"].lower() == "host" else guest_voice
+                for item in script
+            ]
+
+            # Generate segments in parallel
+            segment_paths = await self._generate_segments(
+                texts=texts,
+                voices=voices,
+                output_dir=segments_dir,
+                progress_callback=lambda prog: (
+                    progress_callback(job_id, 10 + int(prog * 0.7), "Generating segments...")
+                    if progress_callback else None
+                )
+            )
+
+            # Update progress
+            if progress_callback:
+                await progress_callback(job_id, 80, "Mixing audio segments...")
+
+            # Mix segments
+            output_path = job_dir / f"podcast_{job_id}.mp3"
+            mixed_path = self.audio_mixer.mix_segments(
+                segment_paths=segment_paths,
+                output_path=output_path,
+                add_silence=True
+            )
+
+            # Add metadata
+            self.audio_mixer.add_metadata(
+                file_path=mixed_path,
+                title=f"Podcast {job_id}",
+                artist="PDF to Podcast",
+                album="Generated Podcasts"
+            )
+
+            # Calculate duration
+            duration = self.audio_mixer.get_audio_duration(mixed_path)
+
+            # Update progress
+            if progress_callback:
+                await progress_callback(job_id, 100, "Podcast generation complete!")
+
+            logger.info(f"Podcast generated: {mixed_path} ({duration:.1f}s)")
+
+            return {
+                "job_id": job_id,
+                "audio_url": f"/static/{job_id}/podcast_{job_id}.mp3",
+                "local_path": str(mixed_path),
+                "metadata": {
+                    "duration_seconds": round(duration, 2),
+                    "duration_minutes": round(duration / 60, 2),
+                    "total_segments": len(script),
+                    "host_voice": host_voice,
+                    "guest_voice": guest_voice,
+                    "file_size_mb": round(mixed_path.stat().st_size / 1024 / 1024, 2)
+                },
+                "status": "completed"
+            }
+
+        except Exception as e:
+            logger.error(f"Podcast generation failed: {str(e)}")
+            raise
+
+    async def _generate_segments(
+        self,
+        texts: List[str],
+        voices: List[str],
+        output_dir: Path,
+        progress_callback: Optional[callable] = None
+    ) -> List[Path]:
+        """
+        Generate all audio segments
+
+        Args:
+            texts: List of texts
+            voices: List of voice IDs
+            output_dir: Output directory
+            progress_callback: Optional progress callback
+
+        Returns:
+            List of segment paths
+        """
+        segment_paths = []
+        total = len(texts)
+
+        # Create tasks for parallel generation
+        tasks = []
+        for i, (text, voice) in enumerate(zip(texts, voices)):
+            output_path = output_dir / f"segment_{i:03d}.mp3"
+            segment_paths.append(output_path)
+
+            task = self.tts_client.generate_speech(
+                text=text,
+                voice=voice,
+                output_path=output_path
+            )
+            tasks.append((i, task))
+
+        # Process with progress tracking
+        completed = 0
+        semaphore = asyncio.Semaphore(5)  # Limit concurrent requests
+
+        async def process_with_progress(index, task):
+            nonlocal completed
+            async with semaphore:
+                await task
+                completed += 1
+                if progress_callback and completed % 5 == 0:
+                    progress = (completed / total) * 100
+                    await progress_callback(progress)
+
+        await asyncio.gather(*[process_with_progress(i, task) for i, task in tasks])
+
+        logger.info(f"Generated {len(segment_paths)} segments")
+        return segment_paths
+
+    def get_available_voices(self) -> Dict:
+        """Get all available voices with metadata"""
+        voices = self.voice_manager.get_all_voices()
+
+        return {
+            "voices": [
+                {
+                    "id": voice_id,
+                    **voice_info
+                }
+                for voice_id, voice_info in voices.items()
+            ],
+            "default_host": self.voice_manager.get_default_voice("host"),
+            "default_guest": self.voice_manager.get_default_voice("guest")
+        }
+
+    async def generate_voice_sample(
+        self,
+        voice_id: str,
+        sample_text: str = "Hello! This is a sample of my voice for the podcast."
+    ) -> Path:
+        """
+        Generate voice sample
+
+        Args:
+            voice_id: Voice ID
+            sample_text: Text to speak
+
+        Returns:
+            Path to sample audio
+        """
+        sample_dir = self.output_dir / "samples"
+        sample_dir.mkdir(parents=True, exist_ok=True)
+
+        output_path = sample_dir / f"sample_{voice_id}.mp3"
+
+        await self.tts_client.generate_speech(
+            text=sample_text,
+            voice=voice_id,
+            output_path=output_path
+        )
+
+        return output_path
diff --git a/PdfToPodcast/api/tts-service/app/core/audio_mixer.py b/PdfToPodcast/api/tts-service/app/core/audio_mixer.py
new file mode 100644
index 0000000000..227a825642
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/core/audio_mixer.py
@@ -0,0 +1,214 @@
+from pydub import AudioSegment
+from pydub.effects import normalize
+from pathlib import Path
+import logging
+from typing import List, Optional
+from mutagen.mp3 import MP3
+from mutagen.id3 import ID3, TIT2, TPE1, TALB
+
+logger = logging.getLogger(__name__)
+
+class AudioMixer:
+    """Mix and process audio segments"""
+
+    def __init__(self):
+        self.silence_duration = 500  # milliseconds between speakers
+
+    def create_silence(self, duration_ms: int) -> AudioSegment:
+        """Create silent audio segment"""
+        return AudioSegment.silent(duration=duration_ms)
+
+    def load_audio(self, file_path: Path) -> AudioSegment:
+        """Load audio file"""
+        try:
+            audio = AudioSegment.from_mp3(str(file_path))
+            logger.info(f"Loaded audio: {file_path} ({len(audio)}ms)")
+            return audio
+        except Exception as e:
+            logger.error(f"Failed to load audio {file_path}: {str(e)}")
+            raise
+
+    def mix_segments(
+        self,
+        segment_paths: List[Path],
+        output_path: Path,
+        add_silence: bool = True
+    ) -> Path:
+        """
+        Mix audio segments sequentially
+
+        Args:
+            segment_paths: List of audio file paths
+            output_path: Output file path
+            add_silence: Add silence between segments
+
+        Returns:
+            Path to mixed audio file
+        """
+        try:
+            logger.info(f"Mixing {len(segment_paths)} segments")
+
+            # Load first segment
+            mixed = self.load_audio(segment_paths[0])
+
+            # Add remaining segments
+            for i, path in enumerate(segment_paths[1:], 1):
+                if add_silence:
+                    mixed += self.create_silence(self.silence_duration)
+
+                segment = self.load_audio(path)
+                mixed += segment
+
+                if i % 10 == 0:
+                    logger.info(f"Mixed {i}/{len(segment_paths)-1} segments")
+
+            logger.info(f"Total duration: {len(mixed)}ms ({len(mixed)/1000/60:.1f} min)")
+
+            # Export
+            self._export_audio(mixed, output_path)
+
+            return output_path
+
+        except Exception as e:
+            logger.error(f"Mixing failed: {str(e)}")
+            raise
+
+    def normalize_audio(self, audio: AudioSegment) -> AudioSegment:
+        """Normalize audio levels"""
+        try:
+            normalized = normalize(audio, headroom=0.1)
+            logger.info("Audio normalized")
+            return normalized
+        except Exception as e:
+            logger.error(f"Normalization failed: {str(e)}")
+            return audio
+
+    def adjust_speed(self, audio: AudioSegment, speed: float) -> AudioSegment:
+        """Adjust playback speed"""
+        if speed == 1.0:
+            return audio
+
+        try:
+            # Change speed by changing frame rate
+            sound_with_altered_frame_rate = audio._spawn(
+                audio.raw_data,
+                overrides={"frame_rate": int(audio.frame_rate * speed)}
+            )
+            # Convert back to original frame rate
+            return sound_with_altered_frame_rate.set_frame_rate(audio.frame_rate)
+        except Exception as e:
+            logger.error(f"Speed adjustment failed: {str(e)}")
+            return audio
+
+    def _export_audio(
+        self,
+        audio: AudioSegment,
+        output_path: Path,
+        format: str = "mp3",
+        bitrate: str = "192k"
+    ):
+        """Export audio with settings"""
+        try:
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Normalize before export
+            audio = self.normalize_audio(audio)
+
+            # Export
+            audio.export(
+                str(output_path),
+                format=format,
+                bitrate=bitrate,
+                parameters=["-q:a", "2"]  # High quality
+            )
+
+            logger.info(f"Exported audio to {output_path}")
+
+        except Exception as e:
+            logger.error(f"Export failed: {str(e)}")
+            raise
+
+    def add_metadata(
+        self,
+        file_path: Path,
+        title: Optional[str] = None,
+        artist: Optional[str] = None,
+        album: Optional[str] = None
+    ):
+        """Add ID3 metadata to MP3 file"""
+        try:
+            audio = MP3(str(file_path), ID3=ID3)
+
+            # Add ID3 tag if doesn't exist
+            try:
+                audio.add_tags()
+            except:
+                pass
+
+            if title:
+                audio.tags["TIT2"] = TIT2(encoding=3, text=title)
+            if artist:
+                audio.tags["TPE1"] = TPE1(encoding=3, text=artist)
+            if album:
+                audio.tags["TALB"] = TALB(encoding=3, text=album)
+
+            audio.save()
+            logger.info(f"Added metadata to {file_path}")
+
+        except Exception as e:
+            logger.error(f"Metadata addition failed: {str(e)}")
+
+    def get_audio_duration(self, file_path: Path) -> float:
+        """Get audio duration in seconds"""
+        try:
+            audio = self.load_audio(file_path)
+            return len(audio) / 1000.0
+        except Exception as e:
+            logger.error(f"Duration calculation failed: {str(e)}")
+            return 0.0
+
+    def trim_silence(
+        self,
+        audio: AudioSegment,
+        silence_thresh: int = -50,
+        chunk_size: int = 10
+    ) -> AudioSegment:
+        """Trim leading and trailing silence"""
+        try:
+            # Detect non-silent parts
+            non_silent_ranges = self._detect_nonsilent(
+                audio,
+                min_silence_len=chunk_size,
+                silence_thresh=silence_thresh
+            )
+
+            if not non_silent_ranges:
+                return audio
+
+            # Get start and end of non-silent audio
+            start = non_silent_ranges[0][0]
+            end = non_silent_ranges[-1][1]
+
+            return audio[start:end]
+
+        except Exception as e:
+            logger.error(f"Silence trimming failed: {str(e)}")
+            return audio
+
+    def _detect_nonsilent(
+        self,
+        audio: AudioSegment,
+        min_silence_len: int = 1000,
+        silence_thresh: int = -16,
+        seek_step: int = 1
+    ) -> List[tuple]:
+        """Detect non-silent chunks"""
+        # Implementation using pydub's silence detection
+        from pydub.silence import detect_nonsilent
+
+        return detect_nonsilent(
+            audio,
+            min_silence_len=min_silence_len,
+            silence_thresh=silence_thresh,
+            seek_step=seek_step
+        )
diff --git a/PdfToPodcast/api/tts-service/app/core/tts_client.py b/PdfToPodcast/api/tts-service/app/core/tts_client.py
new file mode 100644
index 0000000000..5b646016ab
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/core/tts_client.py
@@ -0,0 +1,131 @@
+import openai
+from pathlib import Path
+import logging
+from typing import Optional
+import asyncio
+
+logger = logging.getLogger(__name__)
+
+class TTSClient:
+    """
+    Client for OpenAI Text-to-Speech API
+    """
+
+    def __init__(self, api_key: str, model: str = "tts-1-hd"):
+        """
+        Initialize TTS client
+
+        Args:
+            api_key: OpenAI API key
+            model: TTS model (tts-1 or tts-1-hd)
+        """
+        self.client = openai.OpenAI(api_key=api_key)
+        self.model = model
+
+    async def generate_speech(
+        self,
+        text: str,
+        voice: str = "alloy",
+        speed: float = 1.0,
+        output_path: Optional[Path] = None
+    ) -> bytes:
+        """
+        Generate speech audio from text
+
+        Args:
+            text: Text to convert
+            voice: Voice ID (alloy, echo, fable, onyx, nova, shimmer)
+            speed: Speech speed (0.25 to 4.0)
+            output_path: Optional path to save audio
+
+        Returns:
+            Audio bytes
+        """
+        try:
+            logger.info(f"Generating speech: voice={voice}, length={len(text)} chars")
+
+            # Run in thread pool to avoid blocking
+            loop = asyncio.get_event_loop()
+            response = await loop.run_in_executor(
+                None,
+                lambda: self.client.audio.speech.create(
+                    model=self.model,
+                    voice=voice,
+                    input=text,
+                    speed=speed
+                )
+            )
+
+            # Get audio content
+            audio_bytes = response.content
+
+            # Save if path provided
+            if output_path:
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                with open(output_path, 'wb') as f:
+                    f.write(audio_bytes)
+                logger.info(f"Saved audio to {output_path}")
+
+            logger.info(f"Generated {len(audio_bytes)} bytes of audio")
+            return audio_bytes
+
+        except Exception as e:
+            logger.error(f"Speech generation failed: {str(e)}")
+            raise
+
+    async def generate_speech_batch(
+        self,
+        texts: list[str],
+        voices: list[str],
+        output_dir: Path
+    ) -> list[Path]:
+        """
+        Generate speech for multiple texts in parallel
+
+        Args:
+            texts: List of texts
+            voices: List of voice IDs
+            output_dir: Directory to save audio files
+
+        Returns:
+            List of output paths
+        """
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        tasks = []
+        output_paths = []
+
+        for i, (text, voice) in enumerate(zip(texts, voices)):
+            output_path = output_dir / f"segment_{i:03d}.mp3"
+            output_paths.append(output_path)
+
+            task = self.generate_speech(
+                text=text,
+                voice=voice,
+                output_path=output_path
+            )
+            tasks.append(task)
+
+        # Run in parallel with concurrency limit
+        semaphore = asyncio.Semaphore(5)  # Max 5 concurrent requests
+
+        async def bounded_task(task):
+            async with semaphore:
+                return await task
+
+        await asyncio.gather(*[bounded_task(task) for task in tasks])
+
+        logger.info(f"Generated {len(output_paths)} audio segments")
+        return output_paths
+
+    def get_available_voices(self) -> list[str]:
+        """Get list of available voices"""
+        return ["alloy", "echo", "fable", "onyx", "nova", "shimmer"]
+
+    def is_available(self) -> bool:
+        """Check if TTS service is available"""
+        try:
+            # Simple check - could be improved with actual API call
+            return self.client is not None
+        except:
+            return False
diff --git a/PdfToPodcast/api/tts-service/app/core/voice_manager.py b/PdfToPodcast/api/tts-service/app/core/voice_manager.py
new file mode 100644
index 0000000000..224f7a16e3
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/core/voice_manager.py
@@ -0,0 +1,66 @@
+import json
+from pathlib import Path
+import logging
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+class VoiceManager:
+    """Manage voice configurations and mappings"""
+
+    def __init__(self, config_path: Optional[Path] = None):
+        """
+        Initialize voice manager
+
+        Args:
+            config_path: Path to voices.json config file
+        """
+        if config_path is None:
+            config_path = Path(__file__).parent.parent / "config" / "voices.json"
+
+        self.config_path = config_path
+        self.config = self._load_config()
+
+    def _load_config(self) -> Dict:
+        """Load voice configuration"""
+        try:
+            with open(self.config_path, 'r') as f:
+                return json.load(f)
+        except Exception as e:
+            logger.error(f"Failed to load voice config: {str(e)}")
+            # Return default config
+            return {
+                "openai_voices": {
+                    "alloy": {"name": "Alloy"},
+                    "nova": {"name": "Nova"}
+                },
+                "default_voices": {"host": "alloy", "guest": "nova"}
+            }
+
+    def get_voice_info(self, voice_id: str) -> Dict:
+        """Get voice information"""
+        voices = self.config.get("openai_voices", {})
+        return voices.get(voice_id, {"name": voice_id})
+
+    def get_default_voice(self, role: str = "host") -> str:
+        """Get default voice for role"""
+        defaults = self.config.get("default_voices", {})
+        return defaults.get(role, "alloy")
+
+    def get_all_voices(self) -> Dict:
+        """Get all available voices"""
+        return self.config.get("openai_voices", {})
+
+    def validate_voice(self, voice_id: str) -> bool:
+        """Check if voice ID is valid"""
+        voices = self.config.get("openai_voices", {})
+        return voice_id in voices
+
+    def get_audio_settings(self) -> Dict:
+        """Get audio generation settings"""
+        return self.config.get("audio_settings", {
+            "format": "mp3",
+            "sample_rate": 24000,
+            "model": "tts-1-hd",
+            "speed": 1.0
+        })
diff --git a/PdfToPodcast/api/tts-service/app/main.py b/PdfToPodcast/api/tts-service/app/main.py
new file mode 100644
index 0000000000..b7b5a974e8
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/app/main.py
@@ -0,0 +1,90 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pathlib import Path
+import logging
+import sys
+import os
+
+from app.api.routes import router
+from app.config import settings
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+
+logger = logging.getLogger(__name__)
+
+# Create FastAPI app
+app = FastAPI(
+    title="TTS Audio Generation Service",
+    description="Generate podcast audio from scripts using OpenAI TTS",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount static files
+static_dir = Path(settings.OUTPUT_DIR)
+static_dir.mkdir(parents=True, exist_ok=True)
+app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+# Include routers
+app.include_router(router, tags=["Audio Generation"])
+
+@app.on_event("startup")
+async def startup_event():
+    """Run on application startup"""
+    logger.info("TTS Audio Generation Service starting up...")
+    logger.info(f"Service running on port {settings.SERVICE_PORT}")
+
+    # Check API key
+    if settings.OPENAI_API_KEY:
+        logger.info("OpenAI API key configured")
+    else:
+        logger.warning("OpenAI API key not found - service will not function properly")
+
+    # Create output directory
+    static_dir.mkdir(parents=True, exist_ok=True)
+    logger.info(f"Output directory: {static_dir.absolute()}")
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    """Run on application shutdown"""
+    logger.info("TTS Audio Generation Service shutting down...")
+
+@app.get("/")
+async def root():
+    """Root endpoint"""
+    return {
+        "service": "TTS Audio Generation Service",
+        "version": "1.0.0",
+        "description": "Generate podcast audio from scripts using OpenAI TTS",
+        "endpoints": {
+            "generate_audio": "POST /generate-audio - Generate podcast audio",
+            "status": "GET /status/{job_id} - Check generation status",
+            "download": "GET /download/{job_id} - Download audio file",
+            "voices": "GET /voices - List available voices",
+            "voice_sample": "GET /voice-sample/{voice_id} - Get voice sample",
+            "health": "GET /health - Health check",
+            "docs": "GET /docs - API documentation"
+        }
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=settings.SERVICE_PORT)
diff --git a/PdfToPodcast/api/tts-service/requirements.txt b/PdfToPodcast/api/tts-service/requirements.txt
new file mode 100644
index 0000000000..1f6aa3ec30
--- /dev/null
+++ b/PdfToPodcast/api/tts-service/requirements.txt
@@ -0,0 +1,12 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+python-multipart>=0.0.12
+openai>=1.57.0
+pydantic>=2.10.0
+pydantic-settings>=2.7.0
+python-dotenv>=1.0.0
+pydub>=0.25.1
+ffmpeg-python>=0.2.0
+aiofiles>=24.1.0
+httpx>=0.28.0
+mutagen>=1.47.0
diff --git a/PdfToPodcast/docker-compose.yml b/PdfToPodcast/docker-compose.yml
new file mode 100644
index 0000000000..3f14c3fadf
--- /dev/null
+++ b/PdfToPodcast/docker-compose.yml
@@ -0,0 +1,93 @@
+services:
+  pdf-service:
+    build:
+      context: ./api/pdf-service
+      dockerfile: Dockerfile
+    container_name: pdf-service
+    ports:
+      - "8001:8001"
+    volumes:
+      - ./api/pdf-service:/app
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  llm-service:
+    build:
+      context: ./api/llm-service
+      dockerfile: Dockerfile
+    container_name: llm-service
+    ports:
+      - "8002:8002"
+    env_file:
+      - ./api/llm-service/.env
+    volumes:
+      - ./api/llm-service:/app
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  tts-service:
+    build:
+      context: ./api/tts-service
+      dockerfile: Dockerfile
+    container_name: tts-service
+    ports:
+      - "8003:8003"
+    env_file:
+      - ./api/tts-service/.env
+    volumes:
+      - ./api/tts-service:/app
+      - ./api/tts-service/static:/app/static
+    networks:
+      - app_network
+    restart: unless-stopped
+
+  # backend Gateway (Python)
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: backend
+    ports:
+      - "8000:8000"
+    env_file:
+      - ./.env
+    depends_on:
+      - pdf-service
+      - llm-service
+      - tts-service
+    volumes:
+      - .:/app
+    networks:
+      - app_network
+    restart: unless-stopped
+
+
+  # Frontend (React)
+  frontend:
+    build:
+      context: ./ui
+      dockerfile: Dockerfile
+    container_name: frontend
+    ports:
+      - "3000:3000"
+    environment:
+      - REACT_APP_BACKEND_URL=http://localhost:8000
+      - VITE_API_URL=http://localhost:8000
+    depends_on:
+      - backend
+    networks:
+      - app_network
+    restart: unless-stopped
+
+##################################
+# 🔗 Shared Network
+##################################
+networks:
+  app_network:
+    driver: bridge
+
+volumes:
+  audio-files:
+    driver: local
diff --git a/PdfToPodcast/requirements.txt b/PdfToPodcast/requirements.txt
new file mode 100644
index 0000000000..8560460a29
--- /dev/null
+++ b/PdfToPodcast/requirements.txt
@@ -0,0 +1,6 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+pydantic==2.5.0
+pydantic-settings==2.1.0
+httpx==0.25.2
\ No newline at end of file
diff --git a/PdfToPodcast/sample-input-files/podcast topic-1.pdf b/PdfToPodcast/sample-input-files/podcast topic-1.pdf
new file mode 100644
index 0000000000..de11ef2cd6
Binary files /dev/null and b/PdfToPodcast/sample-input-files/podcast topic-1.pdf differ
diff --git a/PdfToPodcast/sample-input-files/podcast topic-2.pdf b/PdfToPodcast/sample-input-files/podcast topic-2.pdf
new file mode 100644
index 0000000000..81c81793fa
Binary files /dev/null and b/PdfToPodcast/sample-input-files/podcast topic-2.pdf differ
diff --git a/PdfToPodcast/sample-input-files/podcast topic-3.pdf b/PdfToPodcast/sample-input-files/podcast topic-3.pdf
new file mode 100644
index 0000000000..ce6c2a7aba
Binary files /dev/null and b/PdfToPodcast/sample-input-files/podcast topic-3.pdf differ
diff --git a/PdfToPodcast/simple_backend.py b/PdfToPodcast/simple_backend.py
new file mode 100644
index 0000000000..ff42f2df46
--- /dev/null
+++ b/PdfToPodcast/simple_backend.py
@@ -0,0 +1,396 @@
+"""
+Simple Backend Gateway for Testing
+Routes requests from frontend to microservices directly
+"""
+from fastapi import FastAPI, File, UploadFile, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+from typing import Optional, List, Dict
+import httpx
+import logging
+import sys
+import asyncio
+import os
+
+# Suppress Windows asyncio errors
+if sys.platform == 'win32':
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="Simple Backend Gateway")
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Service URLs
+PDF_SERVICE = os.getenv("PDF_SERVICE_URL", os.getenv("PDF_SERVICE", "http://localhost:8001"))
+LLM_SERVICE = os.getenv("LLM_SERVICE_URL", os.getenv("LLM_SERVICE", "http://localhost:8002"))
+TTS_SERVICE = os.getenv("TTS_SERVICE_URL", os.getenv("TTS_SERVICE", "http://localhost:8003"))
+
+class GenerateScriptRequest(BaseModel):
+    text: str
+    host_name: Optional[str] = "Host"
+    guest_name: Optional[str] = "Guest"
+    tone: Optional[str] = "conversational"
+    max_length: Optional[int] = 500
+
+class GenerateScriptFromJobRequest(BaseModel):
+    job_id: str
+    host_voice: Optional[str] = "alloy"
+    guest_voice: Optional[str] = "echo"
+
+# Simple in-memory storage for job data
+job_storage = {}
+
+@app.get("/")
+async def root():
+    return {
+        "service": "Simple Backend Gateway",
+        "status": "running",
+        "endpoints": {
+            "upload": "POST /api/upload",
+            "generate_script": "POST /api/generate-script",
+            "health": "GET /health"
+        }
+    }
+
+@app.get("/health")
+async def health():
+    """Health check"""
+    return {"status": "healthy", "services": {
+        "pdf": PDF_SERVICE,
+        "llm": LLM_SERVICE,
+        "tts": TTS_SERVICE
+    }}
+
+@app.post("/api/upload")
+async def upload_pdf(file: UploadFile = File(...)):
+    """Upload PDF and extract text"""
+    logger.info(f"Received PDF upload: {file.filename}")
+
+    try:
+        # Read file content
+        pdf_content = await file.read()
+        logger.info(f"PDF size: {len(pdf_content)} bytes")
+
+        # Send to PDF service
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            files = {"file": (file.filename, pdf_content, "application/pdf")}
+            response = await client.post(f"{PDF_SERVICE}/extract", files=files)
+
+            if response.status_code == 200:
+                result = response.json()
+                logger.info(f"Extracted {len(result.get('text', ''))} characters")
+
+                # Generate a simple job ID from filename
+                import time
+                job_id = f"{file.filename}_{int(time.time())}"
+
+                # Store the extracted text for later use
+                job_storage[job_id] = {
+                    "text": result.get("text", ""),
+                    "metadata": result.get("metadata", {}),
+                    "filename": file.filename
+                }
+
+                return JSONResponse({
+                    "status": "success",
+                    "job_id": job_id,
+                    "text": result.get("text", ""),
+                    "metadata": result.get("metadata", {}),
+                    "filename": file.filename
+                })
+            else:
+                logger.error(f"PDF service error: {response.text}")
+                raise HTTPException(status_code=500, detail="PDF extraction failed")
+
+    except Exception as e:
+        logger.error(f"Upload error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.post("/api/generate-script")
+async def generate_script(request: GenerateScriptFromJobRequest):
+    """Generate podcast script from job"""
+    logger.info(f"Generating script for job: {request.job_id}")
+
+    # Retrieve stored text from job_id
+    if request.job_id not in job_storage:
+        raise HTTPException(status_code=404, detail=f"Job {request.job_id} not found")
+
+    job_data = job_storage[request.job_id]
+    text = job_data["text"]
+
+    try:
+        async with httpx.AsyncClient(timeout=120.0) as client:
+            payload = {
+                "text": text,
+                "host_name": "Host",
+                "guest_name": "Guest",
+                "tone": "conversational",
+                "max_length": 500
+            }
+
+            response = await client.post(
+                f"{LLM_SERVICE}/generate-script",
+                json=payload
+            )
+
+            if response.status_code == 200:
+                result = response.json()
+                logger.info(f"Generated {len(result.get('script', []))} dialogue turns")
+
+                # Store the script in job storage
+                job_storage[request.job_id]["script"] = result.get("script", [])
+                job_storage[request.job_id]["host_voice"] = request.host_voice
+                job_storage[request.job_id]["guest_voice"] = request.guest_voice
+
+                return result
+            else:
+                logger.error(f"LLM service error: {response.text}")
+                raise HTTPException(status_code=500, detail="Script generation failed")
+
+    except Exception as e:
+        logger.error(f"Script generation error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/api/voices")
+async def get_voices():
+    """Get available TTS voices"""
+    # Return default voices (TTS service not implemented yet)
+    return {
+        "alloy": {"name": "Alloy", "description": "Neutral and balanced", "gender": "neutral"},
+        "echo": {"name": "Echo", "description": "Deep and resonant", "gender": "male"},
+        "fable": {"name": "Fable", "description": "Expressive and dynamic", "gender": "neutral"},
+        "onyx": {"name": "Onyx", "description": "Strong and authoritative", "gender": "male"},
+        "nova": {"name": "Nova", "description": "Warm and friendly", "gender": "female"},
+        "shimmer": {"name": "Shimmer", "description": "Bright and energetic", "gender": "female"}
+    }
+
+@app.get("/api/job/{job_id}")
+async def get_job_status(job_id: str):
+    """Get job status"""
+    logger.info(f"Job status requested: {job_id}")
+
+    if job_id not in job_storage:
+        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+
+    job_data = job_storage[job_id]
+
+    # Check if script and audio have been generated
+    has_script = "script" in job_data and job_data["script"]
+    has_audio = job_data.get("audio_generated", False)
+    is_generating_audio = job_data.get("audio_generating", False)
+
+    # If audio is being generated, poll TTS service for status
+    if is_generating_audio and not has_audio:
+        try:
+            tts_job_id = job_data.get("tts_job_id", job_id)
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.get(f"{TTS_SERVICE}/status/{tts_job_id}")
+
+                if response.status_code == 200:
+                    tts_status = response.json()
+                    logger.info(f"TTS status for {job_id}: {tts_status.get('status')}")
+
+                    # Update job storage with TTS status
+                    if tts_status.get("status") == "completed":
+                        job_data["audio_generated"] = True
+                        job_data["audio_generating"] = False
+                        job_data["audio_url"] = f"/api/download/{job_id}"
+                        job_data["audio_status"] = "completed"
+                        has_audio = True
+                        is_generating_audio = False
+                    elif tts_status.get("status") == "failed":
+                        job_data["audio_generating"] = False
+                        job_data["audio_status"] = tts_status.get("message", "Audio generation failed")
+
+        except Exception as e:
+            logger.error(f"Error checking TTS status: {str(e)}")
+
+    # Determine status
+    if has_audio:
+        status = "completed"
+        progress = 100
+    elif has_script:
+        status = "script_generated"
+        progress = 75
+    else:
+        status = "processing"
+        progress = 50
+
+    return JSONResponse({
+        "job_id": job_id,
+        "status": status,
+        "progress": progress,
+        "script": job_data.get("script"),
+        "audio_url": job_data.get("audio_url"),
+        "audio_status": job_data.get("audio_status"),
+        "metadata": {
+            "filename": job_data.get("filename"),
+            "host_voice": job_data.get("host_voice"),
+            "guest_voice": job_data.get("guest_voice")
+        }
+    })
+
+@app.post("/api/generate-audio")
+async def generate_audio(request: dict):
+    """Generate audio from script"""
+    job_id = request.get("job_id")
+    edited_script = request.get("script")  # Get edited script if provided
+    logger.info(f"Audio generation requested for job: {job_id}")
+
+    if not job_id or job_id not in job_storage:
+        raise HTTPException(status_code=404, detail=f"Job {job_id} not found")
+
+    job_data = job_storage[job_id]
+
+    # Check if audio is already generated or being generated
+    if job_data.get("audio_generated", False):
+        logger.info(f"Audio already generated for job: {job_id}")
+        return JSONResponse({
+            "status": "success",
+            "message": "Audio already generated",
+            "job_id": job_id
+        })
+
+    if job_data.get("audio_generating", False):
+        logger.info(f"Audio generation already in progress for job: {job_id}")
+        return JSONResponse({
+            "status": "success",
+            "message": "Audio generation in progress",
+            "job_id": job_id
+        })
+
+    # Use edited script if provided, otherwise use stored script
+    script_to_use = edited_script if edited_script else job_data.get("script")
+
+    # Check if script exists
+    if not script_to_use:
+        raise HTTPException(status_code=400, detail="No script available for this job")
+
+    # Update job_data with edited script if provided
+    if edited_script:
+        job_data["script"] = edited_script
+        job_storage[job_id] = job_data
+        logger.info(f"Using edited script for job {job_id}: {len(edited_script)} dialogue turns")
+
+    try:
+        # Send to TTS service
+        async with httpx.AsyncClient(timeout=300.0) as client:
+            payload = {
+                "script": script_to_use,
+                "host_voice": job_data.get("host_voice", "alloy"),
+                "guest_voice": job_data.get("guest_voice", "echo"),
+                "job_id": job_id
+            }
+
+            logger.info(f"Sending to TTS service: {len(job_data['script'])} dialogue turns")
+
+            response = await client.post(
+                f"{TTS_SERVICE}/generate-audio",
+                json=payload
+            )
+
+            if response.status_code == 200:
+                result = response.json()
+                logger.info(f"TTS service accepted job: {job_id}")
+
+                # Mark as generating
+                job_storage[job_id]["audio_generating"] = True
+                job_storage[job_id]["tts_job_id"] = result.get("job_id", job_id)
+
+                return JSONResponse({
+                    "status": "success",
+                    "message": "Audio generation started",
+                    "job_id": job_id
+                })
+            else:
+                logger.error(f"TTS service error: {response.text}")
+                # Fallback to mock if TTS service fails
+                job_storage[job_id]["audio_generated"] = True
+                job_storage[job_id]["audio_url"] = None
+                job_storage[job_id]["audio_status"] = "TTS service unavailable"
+
+                return JSONResponse({
+                    "status": "success",
+                    "message": "Audio generation requires TTS service",
+                    "job_id": job_id
+                })
+
+    except httpx.ConnectError:
+        logger.warning(f"TTS service not available, using fallback")
+        # Fallback if TTS service not running
+        job_storage[job_id]["audio_generated"] = True
+        job_storage[job_id]["audio_url"] = None
+        job_storage[job_id]["audio_status"] = "TTS service not available"
+
+        return JSONResponse({
+            "status": "success",
+            "message": "Audio generation requires TTS service (Python 3.11)",
+            "job_id": job_id
+        })
+
+    except Exception as e:
+        logger.error(f"Audio generation error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/api/download/{job_id}")
+async def download_audio(job_id: str):
+    """Download audio file"""
+    logger.info(f"Download requested for job: {job_id}")
+
+    try:
+        # Proxy the download request to TTS service
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            response = await client.get(f"{TTS_SERVICE}/download/{job_id}")
+
+            if response.status_code == 200:
+                from fastapi.responses import StreamingResponse
+                import io
+
+                # Stream the audio file back to the client
+                audio_content = response.content
+                return StreamingResponse(
+                    io.BytesIO(audio_content),
+                    media_type="audio/mpeg",
+                    headers={
+                        "Content-Disposition": f'attachment; filename="podcast_{job_id}.mp3"'
+                    }
+                )
+            else:
+                logger.error(f"TTS service download error: {response.text}")
+                raise HTTPException(status_code=404, detail="Audio file not found")
+
+    except Exception as e:
+        logger.error(f"Download error: {str(e)}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/api/voice/sample/{voice_id}")
+async def get_voice_sample(voice_id: str):
+    """Get voice sample audio"""
+    logger.info(f"Voice sample requested: {voice_id}")
+
+    # Return URL to the static audio file
+    return JSONResponse({
+        "voice_id": voice_id,
+        "status": "available",
+        "audio_url": f"/voice-samples/{voice_id}.mp3"
+    })
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Starting Simple Backend Gateway on http://localhost:8000")
+    print("Forwarding to:")
+    print(f"  - PDF Service: {PDF_SERVICE}")
+    print(f"  - LLM Service: {LLM_SERVICE}")
+    print(f"  - TTS Service: {TTS_SERVICE}")
+    uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/PdfToPodcast/tests/full_workflow_test.py b/PdfToPodcast/tests/full_workflow_test.py
new file mode 100644
index 0000000000..3c76aed6a4
--- /dev/null
+++ b/PdfToPodcast/tests/full_workflow_test.py
@@ -0,0 +1,217 @@
+"""
+Full Workflow Test - PDF to Podcast
+Tests the complete pipeline: PDF -> Text -> Script -> (Audio when TTS is ready)
+"""
+import requests
+import json
+import time
+from pathlib import Path
+
+print("=" * 80)
+print("PDF TO PODCAST - FULL WORKFLOW TEST")
+print("=" * 80)
+
+# Service URLs
+PDF_SERVICE = "http://localhost:8001"
+LLM_SERVICE = "http://localhost:8002"
+FRONTEND = "http://localhost:3001"
+
+# Colors for terminal output (Windows compatible)
+def success(msg):
+    print(f"[SUCCESS] {msg}")
+
+def info(msg):
+    print(f"[INFO] {msg}")
+
+def error(msg):
+    print(f"[ERROR] {msg}")
+
+# Step 1: Check all services
+print("\n" + "=" * 80)
+print("STEP 1: Checking Service Health")
+print("=" * 80)
+
+services_ok = True
+
+try:
+    response = requests.get(f"{PDF_SERVICE}/health", timeout=5)
+    health = response.json()
+    success(f"PDF Service: {health['status']}")
+except Exception as e:
+    error(f"PDF Service: {e}")
+    services_ok = False
+
+try:
+    response = requests.get(f"{LLM_SERVICE}/health", timeout=5)
+    health = response.json()
+    success(f"LLM Service: {health['status']}")
+    info(f"  - OpenAI API: {'Ready' if health.get('openai_available') else 'Not configured'}")
+except Exception as e:
+    error(f"LLM Service: {e}")
+    services_ok = False
+
+try:
+    response = requests.get(FRONTEND, timeout=5)
+    success(f"Frontend: Accessible at {FRONTEND}")
+except Exception as e:
+    error(f"Frontend: {e}")
+
+if not services_ok:
+    print("\nSome services are not running. Please start them first.")
+    exit(1)
+
+# Step 2: Create sample PDF content (simulated)
+print("\n" + "=" * 80)
+print("STEP 2: Preparing Sample Content")
+print("=" * 80)
+
+sample_text = """
+The Future of Renewable Energy
+
+Solar and wind power have become increasingly cost-effective alternatives to fossil fuels.
+Over the past decade, the cost of solar panels has dropped by more than 80%, making solar
+energy competitive with traditional power sources in many regions.
+
+Wind energy has also seen remarkable growth, with offshore wind farms becoming particularly
+popular in Europe and Asia. These massive turbines can generate enormous amounts of clean
+electricity, even in areas where land-based wind farms aren't practical.
+
+Battery storage technology is advancing rapidly, addressing one of the biggest challenges
+of renewable energy: intermittency. Modern lithium-ion batteries and emerging technologies
+like solid-state batteries can store excess energy generated during peak production times
+for use when the sun isn't shining or the wind isn't blowing.
+
+Governments worldwide are setting ambitious targets for renewable energy adoption. Many
+countries aim to achieve net-zero carbon emissions by 2050, with renewable energy playing
+a central role in this transition. Investment in green energy infrastructure is creating
+millions of new jobs and driving economic growth.
+
+The integration of smart grid technology allows for more efficient distribution of
+renewable energy. AI-powered systems can predict energy demand and optimize the mix of
+power sources in real-time, ensuring stable and reliable electricity supply.
+"""
+
+info(f"Sample content prepared: {len(sample_text)} characters")
+info(f"Topic: The Future of Renewable Energy")
+
+# Step 3: Generate podcast script
+print("\n" + "=" * 80)
+print("STEP 3: Generating Podcast Script with AI")
+print("=" * 80)
+
+info("Calling LLM service to generate conversational script...")
+info("This may take 10-15 seconds...")
+
+try:
+    start_time = time.time()
+
+    response = requests.post(
+        f"{LLM_SERVICE}/generate-script",
+        json={
+            "text": sample_text,
+            "host_name": "Sarah",
+            "guest_name": "Dr. Chen",
+            "tone": "conversational",
+            "max_length": 600,
+            "provider": "openai"
+        },
+        timeout=60
+    )
+
+    generation_time = time.time() - start_time
+
+    if response.status_code == 200:
+        result = response.json()
+        script = result.get("script", [])
+        metadata = result.get("metadata", {})
+
+        success(f"Script generated in {generation_time:.1f} seconds!")
+        print("\n" + "-" * 80)
+        print("SCRIPT METADATA:")
+        print("-" * 80)
+        print(f"  Total dialogue turns: {metadata.get('total_turns', 0)}")
+        print(f"  Host turns: {metadata.get('host_turns', 0)}")
+        print(f"  Guest turns: {metadata.get('guest_turns', 0)}")
+        print(f"  Total words: {metadata.get('total_words', 0)}")
+        print(f"  Estimated duration: {metadata.get('estimated_duration_minutes', 0)} minutes")
+        print(f"  Tone: {metadata.get('tone', 'N/A')}")
+
+        print("\n" + "-" * 80)
+        print("SAMPLE DIALOGUE (First 5 turns):")
+        print("-" * 80)
+
+        for i, turn in enumerate(script[:5]):
+            speaker = turn.get('speaker', 'Unknown').upper()
+            text = turn.get('text', '')
+
+            # Truncate long text for display
+            display_text = text if len(text) <= 150 else text[:147] + "..."
+
+            print(f"\n{speaker}:")
+            print(f"  {display_text}")
+
+        if len(script) > 5:
+            print(f"\n... and {len(script) - 5} more turns")
+
+        # Save full script to file
+        output_file = Path("generated_script.json")
+        with open(output_file, "w", encoding="utf-8") as f:
+            json.dump(result, f, indent=2, ensure_ascii=False)
+
+        success(f"Full script saved to: {output_file.absolute()}")
+
+    else:
+        error(f"Script generation failed: {response.status_code}")
+        error(f"Error: {response.text}")
+        exit(1)
+
+except Exception as e:
+    error(f"Script generation error: {e}")
+    exit(1)
+
+# Step 4: Summary and next steps
+print("\n" + "=" * 80)
+print("TEST SUMMARY")
+print("=" * 80)
+
+print("\n✓ Services Running:")
+print("  - PDF Service (Port 8001)")
+print("  - LLM Service (Port 8002)")
+print("  - Frontend (Port 3001)")
+
+print("\n✓ Successfully Tested:")
+print("  - Service health checks")
+print("  - AI script generation with OpenAI GPT-4o-mini")
+print("  - Script formatting and validation")
+print("  - Metadata calculation")
+
+print("\n✓ Generated:")
+print(f"  - {metadata.get('total_turns', 0)} dialogue turns")
+print(f"  - {metadata.get('total_words', 0)} word podcast script")
+print(f"  - Estimated {metadata.get('estimated_duration_minutes', 0)} minute podcast")
+
+print("\n" + "=" * 80)
+print("NEXT STEPS TO TEST THE FULL APPLICATION:")
+print("=" * 80)
+
+print("\n1. MANUAL FRONTEND TEST:")
+print(f"   - Open your browser: {FRONTEND}")
+print("   - Go to the 'Generate' page")
+print("   - Upload a PDF or enter text")
+print("   - Select voices and generate podcast")
+
+print("\n2. VIEW GENERATED SCRIPT:")
+print(f"   - Open: {output_file.absolute()}")
+print("   - Review the complete dialogue")
+
+print("\n3. FUTURE ENHANCEMENTS:")
+print("   - TTS Service (needs Python 3.11)")
+print("   - Backend Gateway (needs PostgreSQL/SQLite)")
+print("   - Full audio generation pipeline")
+
+print("\n" + "=" * 80)
+print("APPLICATION IS WORKING! 🎉")
+print("=" * 80)
+print("\nThe core PDF-to-Script pipeline is functional.")
+print("You can now use the frontend to test the complete user experience.")
+print("\n" + "=" * 80)
diff --git a/PdfToPodcast/tests/generate_voice_samples.py b/PdfToPodcast/tests/generate_voice_samples.py
new file mode 100644
index 0000000000..773eeaff03
--- /dev/null
+++ b/PdfToPodcast/tests/generate_voice_samples.py
@@ -0,0 +1,62 @@
+"""
+Generate OpenAI TTS voice sample audio files for voice preview
+"""
+import os
+from pathlib import Path
+from openai import OpenAI
+from dotenv import load_dotenv
+
+# Load environment variables from LLM service
+load_dotenv("microservices/llm-service/.env")
+
+# Get API key
+api_key = os.getenv("OPENAI_API_KEY")
+if not api_key:
+    raise ValueError("OPENAI_API_KEY not found in environment")
+
+# Initialize OpenAI client
+client = OpenAI(api_key=api_key)
+
+# Voice configurations
+voices = {
+    "alloy": {"name": "Alloy", "description": "Neutral and balanced"},
+    "echo": {"name": "Echo", "description": "Clear and expressive"},
+    "fable": {"name": "Fable", "description": "Warm and engaging"},
+    "onyx": {"name": "Onyx", "description": "Deep and authoritative"},
+    "nova": {"name": "Nova", "description": "Friendly and conversational"},
+    "shimmer": {"name": "Shimmer", "description": "Bright and energetic"},
+}
+
+# Create output directory
+output_dir = Path("frontend/public/voice-samples")
+output_dir.mkdir(parents=True, exist_ok=True)
+
+print("Generating OpenAI TTS voice samples...\n")
+
+for voice_id, voice_info in voices.items():
+    print(f"Generating sample for {voice_info['name']}...")
+
+    # Create speech sample
+    text = f"Hello, I'm {voice_info['name']}. {voice_info['description']}. I'll be your podcast voice."
+
+    try:
+        response = client.audio.speech.create(
+            model="tts-1",
+            voice=voice_id,
+            input=text,
+            speed=1.0
+        )
+
+        # Save audio file
+        output_path = output_dir / f"{voice_id}.mp3"
+        response.stream_to_file(str(output_path))
+
+        print(f"Generated: {output_path}")
+
+    except Exception as e:
+        print(f"Error generating {voice_id}: {e}")
+
+print(f"\nVoice samples generated successfully in {output_dir}")
+print("\nNext steps:")
+print("1. Update simple_backend.py to serve these audio files")
+print("2. Modify VoiceSelector.jsx to play the audio files")
diff --git a/PdfToPodcast/tests/test_end_to_end.py b/PdfToPodcast/tests/test_end_to_end.py
new file mode 100644
index 0000000000..4aa784e508
--- /dev/null
+++ b/PdfToPodcast/tests/test_end_to_end.py
@@ -0,0 +1,113 @@
+"""
+End-to-end test of the PDF to Podcast services
+"""
+import requests
+import json
+import time
+
+print("=" * 70)
+print("PDF to Podcast - End-to-End Test")
+print("=" * 70)
+
+# Service URLs
+PDF_SERVICE = "http://localhost:8001"
+LLM_SERVICE = "http://localhost:8002"
+TTS_SERVICE = "http://localhost:8003"
+
+# Test 1: Check service health
+print("\n1. Checking service health...")
+try:
+    pdf_health = requests.get(f"{PDF_SERVICE}/health", timeout=5).json()
+    print(f"   [OK] PDF Service: {pdf_health['status']}")
+except Exception as e:
+    print(f"   [FAILED] PDF Service: {e}")
+
+try:
+    llm_health = requests.get(f"{LLM_SERVICE}/health", timeout=5).json()
+    print(f"   [OK] LLM Service: {llm_health['status']}")
+    print(f"        OpenAI API: {'Available' if llm_health.get('openai_available') else 'Not configured'}")
+except Exception as e:
+    print(f"   [FAILED] LLM Service: {e}")
+
+try:
+    tts_health = requests.get(f"{TTS_SERVICE}/health", timeout=5).json()
+    print(f"   [OK] TTS Service: {tts_health['status']}")
+except Exception as e:
+    print(f"   [FAILED] TTS Service: {e}")
+
+# Test 2: Generate script from sample text
+print("\n2. Testing LLM script generation...")
+sample_text = """
+Artificial Intelligence has revolutionized the way we interact with technology.
+Machine learning algorithms can now recognize patterns in data that would be
+impossible for humans to detect. Deep learning, a subset of machine learning,
+uses neural networks with multiple layers to process information in ways that
+mimic the human brain. These technologies are being applied in fields ranging
+from healthcare to autonomous vehicles, promising to transform our daily lives.
+"""
+
+try:
+    response = requests.post(
+        f"{LLM_SERVICE}/generate-script",
+        json={
+            "text": sample_text,
+            "host_name": "Alex",
+            "guest_name": "Sam",
+            "tone": "conversational",
+            "max_length": 500,
+            "provider": "openai"
+        },
+        timeout=60
+    )
+
+    if response.status_code == 200:
+        result = response.json()
+        script = result.get("script", [])
+        metadata = result.get("metadata", {})
+
+        print(f"   [OK] Script generated successfully!")
+        print(f"        Dialogue turns: {len(script)}")
+        print(f"        Total words: {metadata.get('total_words', 0)}")
+        print(f"        Estimated duration: {metadata.get('estimated_duration_minutes', 0)} minutes")
+
+        # Show first 2 dialogue turns
+        print("\n   Sample dialogue:")
+        for i, turn in enumerate(script[:2]):
+            speaker = turn.get('speaker', 'Unknown').upper()
+            text = turn.get('text', '')[:100]
+            print(f"      {speaker}: {text}...")
+
+        # Save script for audio generation test
+        with open("test_script.json", "w") as f:
+            json.dump(script, f, indent=2)
+        print("\n   Script saved to test_script.json")
+
+    else:
+        print(f"   [FAILED] Status code: {response.status_code}")
+        print(f"        Error: {response.text}")
+
+except Exception as e:
+    print(f"   [FAILED] Error: {e}")
+
+# Test 3: List available voices
+print("\n3. Testing TTS voice listing...")
+try:
+    response = requests.get(f"{TTS_SERVICE}/voices", timeout=5)
+    if response.status_code == 200:
+        voices = response.json()
+        print(f"   [OK] Available voices: {len(voices)}")
+        for voice_id, info in list(voices.items())[:3]:
+            print(f"        - {voice_id}: {info.get('name', 'N/A')}")
+    else:
+        print(f"   [FAILED] Could not fetch voices")
+except Exception as e:
+    print(f"   [FAILED] TTS Service not running: {e}")
+
+print("\n" + "=" * 70)
+print("Test Complete!")
+print("=" * 70)
+print("\nNext steps:")
+print("1. If script generation worked, the services are functioning!")
+print("2. To test audio generation, you would upload the script to TTS service")
+print("3. Frontend at http://localhost:3001 can be used for full workflow")
+print("\n" + "=" * 70)
diff --git a/PdfToPodcast/tests/test_modules.py b/PdfToPodcast/tests/test_modules.py
new file mode 100644
index 0000000000..7e7286c320
--- /dev/null
+++ b/PdfToPodcast/tests/test_modules.py
@@ -0,0 +1,94 @@
+"""
+Simple module verification test
+"""
+import sys
+from pathlib import Path
+
+print("=" * 60)
+print("PDF to Podcast - Module Verification Test")
+print("=" * 60)
+
+# Test 1: PDF Service
+print("\n1. Testing PDF Service modules...")
+try:
+    sys.path.insert(0, str(Path(__file__).parent / "microservices" / "pdf-service"))
+    from app.core.pdf_extractor import PDFExtractor
+    from app.core.text_cleaner import TextCleaner
+
+    pdf_extractor = PDFExtractor()
+    text_cleaner = TextCleaner()
+
+    # Test text cleaning
+    sample_text = "This   is  a   test.\n\nIt has  multiple   spaces."
+    cleaned = text_cleaner.clean(sample_text)
+    stats = text_cleaner.get_statistics(cleaned)
+
+    print("[OK] PDF Service modules loaded successfully")
+    print(f"     Text cleaner working: {stats['word_count']} words")
+
+except Exception as e:
+    print(f"[FAILED] PDF Service error: {str(e)}")
+    import traceback
+    traceback.print_exc()
+
+# Test 2: LLM Service
+print("\n2. Testing LLM Service modules...")
+try:
+    sys.path.insert(0, str(Path(__file__).parent / "microservices" / "llm-service"))
+    from app.core.prompt_builder import PromptBuilder
+    from app.core.script_formatter import ScriptFormatter
+
+    prompt_builder = PromptBuilder()
+    script_formatter = ScriptFormatter()
+
+    # Test script validation
+    test_script = [
+        {"speaker": "host", "text": "Welcome to the show!"},
+        {"speaker": "guest", "text": "Thanks for having me!"}
+    ]
+
+    is_valid = script_formatter.validate_script(test_script)
+    metadata = script_formatter.calculate_metadata(test_script)
+
+    print("[OK] LLM Service modules loaded successfully")
+    print(f"     Script validation: {is_valid}")
+    print(f"     Estimated duration: {metadata['estimated_duration_minutes']} min")
+
+except Exception as e:
+    print(f"[FAILED] LLM Service error: {str(e)}")
+    import traceback
+    traceback.print_exc()
+
+# Test 3: TTS Service
+print("\n3. Testing TTS Service modules...")
+try:
+    sys.path.insert(0, str(Path(__file__).parent / "microservices" / "tts-service"))
+    from app.core.voice_manager import VoiceManager
+    from app.core.audio_mixer import AudioMixer
+
+    voice_manager = VoiceManager()
+    audio_mixer = AudioMixer()
+
+    # Test voice manager
+    voices = voice_manager.get_all_voices()
+    default_host = voice_manager.get_default_voice("host")
+
+    print("[OK] TTS Service modules loaded successfully")
+    print(f"     Available voices: {len(voices)}")
+    print(f"     Default host voice: {default_host}")
+
+except Exception as e:
+    print(f"[FAILED] TTS Service error: {str(e)}")
+    import traceback
+    traceback.print_exc()
+
+# Summary
+print("\n" + "=" * 60)
+print("Test Summary")
+print("=" * 60)
+print("\n[SUCCESS] All core modules loaded and working!")
+print("\nNext steps:")
+print("1. Set environment variable: OPENAI_API_KEY")
+print("2. Start each service individually or use Docker Compose")
+print("3. Frontend already running on http://localhost:3001")
+print("\n" + "=" * 60)
diff --git a/PdfToPodcast/tests/test_services.py b/PdfToPodcast/tests/test_services.py
new file mode 100644
index 0000000000..430198974b
--- /dev/null
+++ b/PdfToPodcast/tests/test_services.py
@@ -0,0 +1,108 @@
+"""
+Simple test script to verify the microservices are working
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+# Add paths
+sys.path.append(str(Path(__file__).parent / "microservices" / "pdf-service"))
+sys.path.append(str(Path(__file__).parent / "microservices" / "llm-service"))
+sys.path.append(str(Path(__file__).parent / "microservices" / "tts-service"))
+
+print("=" * 60)
+print("Testing PDF to Podcast Microservices")
+print("=" * 60)
+
+# Test 1: PDF Service
+print("\n1. Testing PDF Service...")
+try:
+    from app.core.pdf_extractor import PDFExtractor
+    from app.core.text_cleaner import TextCleaner
+
+    pdf_extractor = PDFExtractor()
+    text_cleaner = TextCleaner()
+
+    # Test text cleaning
+    sample_text = "This   is  a   test.\n\nIt has  multiple   spaces."
+    cleaned = text_cleaner.clean(sample_text)
+    stats = text_cleaner.get_statistics(cleaned)
+
+    print("✅ PDF Service modules loaded successfully")
+    print(f"   - Text cleaner working: {stats['word_count']} words")
+
+except Exception as e:
+    print(f"❌ PDF Service error: {str(e)}")
+
+# Test 2: LLM Service
+print("\n2. Testing LLM Service...")
+try:
+    sys.path.insert(0, str(Path(__file__).parent / "microservices" / "llm-service"))
+    from app.core.prompt_builder import PromptBuilder
+    from app.core.script_formatter import ScriptFormatter
+
+    prompt_builder = PromptBuilder()
+    script_formatter = ScriptFormatter()
+
+    # Test script validation
+    test_script = [
+        {"speaker": "host", "text": "Welcome to the show!"},
+        {"speaker": "guest", "text": "Thanks for having me!"}
+    ]
+
+    is_valid = script_formatter.validate_script(test_script)
+    metadata = script_formatter.calculate_metadata(test_script)
+
+    print("✅ LLM Service modules loaded successfully")
+    print(f"   - Script validation working: {is_valid}")
+    print(f"   - Estimated duration: {metadata['estimated_duration_minutes']} min")
+
+except Exception as e:
+    print(f"❌ LLM Service error: {str(e)}")
+
+# Test 3: TTS Service
+print("\n3. Testing TTS Service...")
+try:
+    sys.path.insert(0, str(Path(__file__).parent / "microservices" / "tts-service"))
+    from app.core.voice_manager import VoiceManager
+    from app.core.audio_mixer import AudioMixer
+
+    voice_manager = VoiceManager()
+    audio_mixer = AudioMixer()
+
+    # Test voice manager
+    voices = voice_manager.get_all_voices()
+    default_host = voice_manager.get_default_voice("host")
+
+    print("✅ TTS Service modules loaded successfully")
+    print(f"   - Available voices: {len(voices)}")
+    print(f"   - Default host voice: {default_host}")
+
+except Exception as e:
+    print(f"❌ TTS Service error: {str(e)}")
+
+# Test 4: Frontend
+print("\n4. Testing Frontend...")
+try:
+    frontend_dir = Path(__file__).parent / "frontend"
+    package_json = frontend_dir / "package.json"
+
+    if package_json.exists():
+        print("✅ Frontend structure exists")
+        print(f"   - Location: {frontend_dir}")
+    else:
+        print("❌ Frontend package.json not found")
+
+except Exception as e:
+    print(f"❌ Frontend check error: {str(e)}")
+
+# Summary
+print("\n" + "=" * 60)
+print("Test Summary")
+print("=" * 60)
+print("\n✅ All core modules are working!")
+print("\nNext steps:")
+print("1. Set up environment variables (OPENAI_API_KEY)")
+print("2. Start services with Docker Compose or individually")
+print("3. Frontend is already running on http://localhost:3001")
+print("\n" + "=" * 60)
diff --git a/PdfToPodcast/ui/.eslintrc.cjs b/PdfToPodcast/ui/.eslintrc.cjs
new file mode 100644
index 0000000000..4dcb43901a
--- /dev/null
+++ b/PdfToPodcast/ui/.eslintrc.cjs
@@ -0,0 +1,20 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:react/recommended',
+    'plugin:react/jsx-runtime',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+  settings: { react: { version: '18.2' } },
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+}
diff --git a/PdfToPodcast/ui/Dockerfile b/PdfToPodcast/ui/Dockerfile
new file mode 100644
index 0000000000..c90932fe94
--- /dev/null
+++ b/PdfToPodcast/ui/Dockerfile
@@ -0,0 +1,20 @@
+FROM node:18
+
+# Set the working directory
+WORKDIR /app
+
+# Copy package.json and package-lock.json
+COPY package.json ./
+COPY package-lock.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy the rest of the application files
+COPY . .
+
+# Expose the port the app runs on
+EXPOSE 3000
+
+# Command to run the application
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
diff --git a/PdfToPodcast/ui/QUICKSTART.md b/PdfToPodcast/ui/QUICKSTART.md
new file mode 100644
index 0000000000..ac674fd3f7
--- /dev/null
+++ b/PdfToPodcast/ui/QUICKSTART.md
@@ -0,0 +1,240 @@
+# Frontend Quick Start Guide
+
+Get the React frontend running in 3 minutes!
+
+## Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+cd frontend
+npm install
+```
+
+This will install all required packages including:
+- React, React DOM, React Router
+- Redux Toolkit, React Redux
+- Axios, React Dropzone
+- WaveSurfer.js
+- Tailwind CSS
+- And more...
+
+### 2. Start Development Server
+
+```bash
+npm run dev
+```
+
+The app will start at: **http://localhost:5173**
+
+### 3. Open in Browser
+
+Navigate to http://localhost:5173 and you should see the landing page!
+
+---
+
+## Available Scripts
+
+```bash
+# Development
+npm run dev          # Start dev server with hot reload
+
+# Build
+npm run build        # Build for production
+
+# Preview
+npm run preview      # Preview production build
+
+# Lint
+npm run lint         # Run ESLint
+```
+
+---
+
+## Project Structure Overview
+
+```
+src/
+├── components/      # Reusable components
+│   ├── ui/         # UI components (Button, Card, etc.)
+│   ├── layout/     # Layout components (Header, Footer)
+│   └── features/   # Feature components (PDFUploader, etc.)
+├── pages/          # Page components (Home, Generate, etc.)
+├── store/          # Redux store and slices
+├── services/       # API integration
+├── hooks/          # Custom React hooks
+└── utils/          # Helper functions
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the frontend directory:
+
+```env
+VITE_API_URL=http://localhost:8000
+```
+
+### Path Aliases
+
+The following path aliases are configured in `vite.config.js`:
+
+```javascript
+import Component from '@components/ui/Button'
+import { uploadPDF } from '@services/api'
+import { usePolling } from '@hooks/usePolling'
+import store from '@store/store'
+```
+
+---
+
+## Testing the Application
+
+### 1. Home Page
+- Should display landing page with features
+- Click "Get Started Free" to navigate to Generate page
+
+### 2. Generate Page
+- **Step 1:** Upload a PDF file (drag-drop or click)
+- **Step 2:** Select host and guest voices
+- **Step 3:** Review and edit the generated script
+- **Step 4:** Download the podcast audio
+
+### 3. Projects Page
+- View list of past projects
+- Download or delete projects
+
+### 4. Settings Page
+- Configure API key
+- Set voice preferences
+
+---
+
+## Common Issues
+
+### Port 5173 Already in Use
+```bash
+# Change port in vite.config.js
+server: {
+  port: 3000  // Change to any available port
+}
+```
+
+### Module Not Found
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### API Connection Issues
+- Make sure backend is running on port 8000
+- Check `VITE_API_URL` in .env file
+- Verify CORS is configured on backend
+
+---
+
+## Development Tips
+
+### Hot Reload
+- Save any file to see changes instantly
+- No need to refresh browser
+
+### Redux DevTools
+- Install Redux DevTools browser extension
+- Open DevTools to inspect state changes
+
+### Network Tab
+- Open browser DevTools → Network tab
+- Monitor all API calls in real-time
+
+### Console
+- Check browser console for errors
+- All API responses are logged during development
+
+---
+
+## Building for Production
+
+### Create Production Build
+
+```bash
+npm run build
+```
+
+Output will be in `dist/` folder.
+
+### Preview Production Build
+
+```bash
+npm run preview
+```
+
+### Deploy
+
+The `dist/` folder can be deployed to:
+- Vercel: `vercel deploy`
+- Netlify: Drag & drop dist folder
+- AWS S3: `aws s3 sync dist/ s3://bucket-name`
+- GitHub Pages: Push dist to gh-pages branch
+
+---
+
+## Customization
+
+### Change Colors
+
+Edit `tailwind.config.js`:
+
+```javascript
+colors: {
+  primary: {
+    500: '#YOUR_COLOR',  // Change primary color
+  }
+}
+```
+
+### Add New Page
+
+1. Create `src/pages/NewPage.jsx`
+2. Add route in `src/App.jsx`:
+   ```jsx
+   <Route path="new-page" element={<NewPage />} />
+   ```
+
+### Add New Component
+
+1. Create component in appropriate folder
+2. Export from index.js
+3. Import where needed
+
+---
+
+## Next Steps
+
+1. ✅ Install dependencies
+2. ✅ Start dev server
+3. ✅ Test all features
+4. 📖 Read full documentation in `README.md`
+5. 🎨 Customize to your needs
+6. 🚀 Deploy to production
+
+---
+
+## Support
+
+- 📚 Full docs: `frontend/README.md`
+- 🐛 Issues: Create GitHub issue
+- 💬 Questions: Check documentation
+
+---
+
+**Happy coding!** 🎉
diff --git a/PdfToPodcast/ui/README.md b/PdfToPodcast/ui/README.md
new file mode 100644
index 0000000000..3bd4038c7f
--- /dev/null
+++ b/PdfToPodcast/ui/README.md
@@ -0,0 +1,339 @@
+# PDF to Podcast - Frontend Application
+
+A modern, feature-rich React application for generating podcast-style audio from PDF documents.
+
+## Features
+
+- 📤 **PDF Upload** - Drag-and-drop PDF upload with validation
+- 🎙️ **Voice Selection** - Choose from 6 professional AI voices
+- ✏️ **Script Editor** - Review and edit generated scripts
+- 🎵 **Audio Player** - Play and download podcast audio with waveform visualization
+- 📊 **Progress Tracking** - Real-time status updates
+- 💾 **Project Management** - View and manage past projects
+- ⚙️ **Settings** - Configure preferences and API keys
+
+## Technology Stack
+
+- **React 18** - UI library
+- **Vite** - Build tool
+- **Redux Toolkit** - State management
+- **React Router** - Navigation
+- **Tailwind CSS** - Styling
+- **Axios** - HTTP client
+- **React Dropzone** - File uploads
+- **WaveSurfer.js** - Audio visualization
+- **Framer Motion** - Animations
+- **Lucide React** - Icons
+- **React Hot Toast** - Notifications
+
+## Project Structure
+
+```
+frontend/
+├── src/
+│   ├── components/
+│   │   ├── ui/              # Reusable UI components
+│   │   │   ├── Button.jsx
+│   │   │   ├── Card.jsx
+│   │   │   ├── Input.jsx
+│   │   │   ├── Modal.jsx
+│   │   │   ├── Progress.jsx
+│   │   │   ├── Spinner.jsx
+│   │   │   ├── Alert.jsx
+│   │   │   └── StepIndicator.jsx
+│   │   ├── layout/          # Layout components
+│   │   │   ├── Header.jsx
+│   │   │   ├── Footer.jsx
+│   │   │   └── Layout.jsx
+│   │   └── features/        # Feature-specific components
+│   │       ├── PDFUploader.jsx
+│   │       ├── VoiceSelector.jsx
+│   │       ├── ScriptEditor.jsx
+│   │       ├── AudioPlayer.jsx
+│   │       └── ProgressTracker.jsx
+│   ├── pages/               # Page components
+│   │   ├── Home.jsx
+│   │   ├── Generate.jsx
+│   │   ├── Projects.jsx
+│   │   └── Settings.jsx
+│   ├── store/               # Redux store
+│   │   ├── store.js
+│   │   └── slices/
+│   │       ├── projectSlice.js
+│   │       ├── uploadSlice.js
+│   │       ├── scriptSlice.js
+│   │       ├── audioSlice.js
+│   │       └── uiSlice.js
+│   ├── services/            # API services
+│   │   └── api.js
+│   ├── hooks/               # Custom hooks
+│   │   ├── usePolling.js
+│   │   ├── useAudioPlayer.js
+│   │   ├── useWaveSurfer.js
+│   │   └── useDebounce.js
+│   ├── utils/               # Utility functions
+│   │   └── helpers.js
+│   ├── App.jsx              # Root component
+│   ├── main.jsx             # Entry point
+│   └── index.css            # Global styles
+├── public/
+├── index.html
+├── package.json
+├── vite.config.js
+├── tailwind.config.js
+└── postcss.config.js
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+### Environment Variables
+
+Create a `.env` file in the frontend directory:
+
+```env
+VITE_API_URL=http://localhost:8000
+```
+
+## Components
+
+### UI Components
+
+**Button** - Versatile button component with variants, sizes, and loading states
+```jsx
+<Button variant="primary" size="lg" loading={false} icon={Upload}>
+  Upload File
+</Button>
+```
+
+**Card** - Container component with header, body, and footer sections
+```jsx
+<Card>
+  <CardHeader>Title</CardHeader>
+  <CardBody>Content</CardBody>
+  <CardFooter>Actions</CardFooter>
+</Card>
+```
+
+**Progress** - Progress bar with percentage display
+```jsx
+<Progress value={75} max={100} showLabel />
+```
+
+**Modal** - Customizable modal dialog
+```jsx
+<Modal isOpen={true} onClose={handleClose} title="Modal Title">
+  Content
+</Modal>
+```
+
+**Alert** - Notification messages with variants
+```jsx
+<Alert variant="success" title="Success" message="Operation completed" />
+```
+
+**StepIndicator** - Multi-step progress indicator
+```jsx
+<StepIndicator steps={steps} currentStep={2} />
+```
+
+### Feature Components
+
+**PDFUploader** - Drag-and-drop PDF upload with validation
+- File type validation (PDF only)
+- File size validation (max 10MB)
+- Upload progress tracking
+- Error handling
+
+**VoiceSelector** - Voice selection interface
+- 6 AI voice options
+- Voice preview/sample playback
+- Visual selection state
+- Host and guest voice selection
+
+**ScriptEditor** - Interactive script editing
+- Add/remove dialogue lines
+- Edit speaker assignments
+- Edit dialogue text
+- Save changes to backend
+
+**AudioPlayer** - Full-featured audio player
+- WaveSurfer.js waveform visualization
+- Play/pause controls
+- Skip forward/backward (10s)
+- Time display
+- Download functionality
+
+**ProgressTracker** - Real-time progress display
+- Animated progress bar
+- Step-by-step status
+- Progress percentage
+- Status messages
+
+## State Management
+
+Redux Toolkit slices:
+
+- **project** - Project list and management
+- **upload** - PDF upload state
+- **script** - Script generation and editing
+- **audio** - Audio generation and playback
+- **ui** - UI state (current step, sidebar, theme)
+
+## Custom Hooks
+
+- **usePolling** - Poll async functions at intervals
+- **useAudioPlayer** - Audio playback functionality
+- **useWaveSurfer** - WaveSurfer.js integration
+- **useDebounce** - Debounce values
+
+## API Integration
+
+All API calls are handled through the `services/api.js` module:
+
+```javascript
+import { uploadAPI, scriptAPI, audioAPI, voiceAPI } from '@services/api';
+
+// Upload PDF
+await uploadAPI.uploadFile(file, (progress) => console.log(progress));
+
+// Generate script
+await scriptAPI.generate(jobId, hostVoice, guestVoice);
+
+// Generate audio
+await audioAPI.generate(jobId);
+
+// Download audio
+await audioAPI.download(jobId);
+```
+
+## Pages
+
+### Home (`/`)
+- Landing page with features
+- Call-to-action buttons
+- How it works section
+
+### Generate (`/generate`)
+- Main workflow page
+- 4-step process:
+  1. PDF Upload
+  2. Voice Selection
+  3. Script Review
+  4. Audio Generation
+- Real-time progress tracking
+- State persistence
+
+### Projects (`/projects`)
+- List of all projects
+- Project cards with status
+- Download/delete actions
+- Empty state handling
+
+### Settings (`/settings`)
+- API key configuration
+- Voice preferences
+- App information
+
+## Styling
+
+Tailwind CSS is used for all styling with custom configuration:
+
+- Custom color palette (primary, secondary, success, warning, error)
+- Custom animations (fade-in, slide-up, slide-down)
+- Responsive design
+- Dark mode ready (future feature)
+
+## Error Handling
+
+- Global error boundary
+- API error handling with user-friendly messages
+- Form validation
+- Network error recovery
+- Toast notifications for user feedback
+
+## Performance Optimizations
+
+- Code splitting with React.lazy
+- Memoized components with React.memo
+- Optimized re-renders with useCallback/useMemo
+- Virtualized lists for large datasets
+- Debounced input handlers
+- Lazy loading of images and components
+
+## Testing
+
+```bash
+# Run tests
+npm run test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## Build & Deployment
+
+```bash
+# Build for production
+npm run build
+
+# The dist/ folder contains the production build
+# Deploy to any static hosting service:
+# - Vercel
+# - Netlify
+# - AWS S3 + CloudFront
+# - GitHub Pages
+```
+
+## Deployment Checklist
+
+- [ ] Update `VITE_API_URL` for production
+- [ ] Enable production error tracking (Sentry, etc.)
+- [ ] Configure CDN for static assets
+- [ ] Enable gzip/brotli compression
+- [ ] Set up SSL certificate
+- [ ] Configure CORS on backend
+- [ ] Test all features in production environment
+
+## Browser Support
+
+- Chrome/Edge (latest 2 versions)
+- Firefox (latest 2 versions)
+- Safari (latest 2 versions)
+- Mobile browsers (iOS Safari, Chrome Android)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run linting and tests
+5. Submit a pull request
+
+## License
+
+MIT License
+
+## Support
+
+For issues and questions, please open an issue on GitHub.
diff --git a/PdfToPodcast/ui/index.html b/PdfToPodcast/ui/index.html
new file mode 100644
index 0000000000..32daad0b2d
--- /dev/null
+++ b/PdfToPodcast/ui/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>PDF to Podcast Generator</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
diff --git a/PdfToPodcast/ui/nginx.conf b/PdfToPodcast/ui/nginx.conf
new file mode 100644
index 0000000000..d731fb2254
--- /dev/null
+++ b/PdfToPodcast/ui/nginx.conf
@@ -0,0 +1,22 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api {
+        proxy_pass http://backend:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+}
diff --git a/PdfToPodcast/ui/package.json b/PdfToPodcast/ui/package.json
new file mode 100644
index 0000000000..543e69057d
--- /dev/null
+++ b/PdfToPodcast/ui/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "pdf-podcast-frontend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "vite build",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.20.1",
+    "@reduxjs/toolkit": "^2.0.1",
+    "react-redux": "^9.0.4",
+    "axios": "^1.6.2",
+    "react-dropzone": "^14.2.3",
+    "wavesurfer.js": "^7.4.4",
+    "lucide-react": "^0.294.0",
+    "react-hot-toast": "^2.4.1",
+    "clsx": "^2.0.0",
+    "framer-motion": "^10.16.16",
+    "date-fns": "^3.0.6"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.4.0",
+    "vite": "^5.0.8"
+  }
+}
diff --git a/PdfToPodcast/ui/postcss.config.js b/PdfToPodcast/ui/postcss.config.js
new file mode 100644
index 0000000000..2e7af2b7f1
--- /dev/null
+++ b/PdfToPodcast/ui/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
diff --git a/PdfToPodcast/ui/public/app-logo.png b/PdfToPodcast/ui/public/app-logo.png
new file mode 100644
index 0000000000..e3c1dead7b
Binary files /dev/null and b/PdfToPodcast/ui/public/app-logo.png differ
diff --git a/PdfToPodcast/ui/public/cloud2labs-logo.png b/PdfToPodcast/ui/public/cloud2labs-logo.png
new file mode 100644
index 0000000000..2a0ef60222
Binary files /dev/null and b/PdfToPodcast/ui/public/cloud2labs-logo.png differ
diff --git a/PdfToPodcast/ui/public/final_podcast_page.png b/PdfToPodcast/ui/public/final_podcast_page.png
new file mode 100644
index 0000000000..508647ac86
Binary files /dev/null and b/PdfToPodcast/ui/public/final_podcast_page.png differ
diff --git a/PdfToPodcast/ui/public/hero-image.png b/PdfToPodcast/ui/public/hero-image.png
new file mode 100644
index 0000000000..e3c1dead7b
Binary files /dev/null and b/PdfToPodcast/ui/public/hero-image.png differ
diff --git a/PdfToPodcast/ui/public/homepage.png b/PdfToPodcast/ui/public/homepage.png
new file mode 100644
index 0000000000..239ffc3477
Binary files /dev/null and b/PdfToPodcast/ui/public/homepage.png differ
diff --git a/PdfToPodcast/ui/public/homepage2.png b/PdfToPodcast/ui/public/homepage2.png
new file mode 100644
index 0000000000..0465fd6af7
Binary files /dev/null and b/PdfToPodcast/ui/public/homepage2.png differ
diff --git a/PdfToPodcast/ui/public/projects_page.png b/PdfToPodcast/ui/public/projects_page.png
new file mode 100644
index 0000000000..6429ad37c8
Binary files /dev/null and b/PdfToPodcast/ui/public/projects_page.png differ
diff --git a/PdfToPodcast/ui/public/script_edit.png b/PdfToPodcast/ui/public/script_edit.png
new file mode 100644
index 0000000000..9444a69751
Binary files /dev/null and b/PdfToPodcast/ui/public/script_edit.png differ
diff --git a/PdfToPodcast/ui/public/script_preview.png b/PdfToPodcast/ui/public/script_preview.png
new file mode 100644
index 0000000000..a38ab23647
Binary files /dev/null and b/PdfToPodcast/ui/public/script_preview.png differ
diff --git a/PdfToPodcast/ui/public/select_voices.png b/PdfToPodcast/ui/public/select_voices.png
new file mode 100644
index 0000000000..bb4aa6fd07
Binary files /dev/null and b/PdfToPodcast/ui/public/select_voices.png differ
diff --git a/PdfToPodcast/ui/public/ui_loading_component.png b/PdfToPodcast/ui/public/ui_loading_component.png
new file mode 100644
index 0000000000..905f0d178d
Binary files /dev/null and b/PdfToPodcast/ui/public/ui_loading_component.png differ
diff --git a/PdfToPodcast/ui/public/upload_pdf.png b/PdfToPodcast/ui/public/upload_pdf.png
new file mode 100644
index 0000000000..7b06b528fa
Binary files /dev/null and b/PdfToPodcast/ui/public/upload_pdf.png differ
diff --git a/PdfToPodcast/ui/public/voice-samples/alloy.mp3 b/PdfToPodcast/ui/public/voice-samples/alloy.mp3
new file mode 100644
index 0000000000..b122347696
Binary files /dev/null and b/PdfToPodcast/ui/public/voice-samples/alloy.mp3 differ
diff --git a/PdfToPodcast/ui/public/voice-samples/echo.mp3 b/PdfToPodcast/ui/public/voice-samples/echo.mp3
new file mode 100644
index 0000000000..f1f796e677
Binary files /dev/null and b/PdfToPodcast/ui/public/voice-samples/echo.mp3 differ
diff --git a/PdfToPodcast/ui/public/voice-samples/fable.mp3 b/PdfToPodcast/ui/public/voice-samples/fable.mp3
new file mode 100644
index 0000000000..9d1e4948d7
Binary files /dev/null and b/PdfToPodcast/ui/public/voice-samples/fable.mp3 differ
diff --git a/PdfToPodcast/ui/public/voice-samples/nova.mp3 b/PdfToPodcast/ui/public/voice-samples/nova.mp3
new file mode 100644
index 0000000000..2dc0fa624b
Binary files /dev/null and b/PdfToPodcast/ui/public/voice-samples/nova.mp3 differ
diff --git a/PdfToPodcast/ui/public/voice-samples/onyx.mp3 b/PdfToPodcast/ui/public/voice-samples/onyx.mp3
new file mode 100644
index 0000000000..8d35b3358c
Binary files /dev/null and b/PdfToPodcast/ui/public/voice-samples/onyx.mp3 differ
diff --git a/PdfToPodcast/ui/public/voice-samples/shimmer.mp3 b/PdfToPodcast/ui/public/voice-samples/shimmer.mp3
new file mode 100644
index 0000000000..83ac3b54e2
Binary files /dev/null and b/PdfToPodcast/ui/public/voice-samples/shimmer.mp3 differ
diff --git a/PdfToPodcast/ui/src/App.css b/PdfToPodcast/ui/src/App.css
new file mode 100644
index 0000000000..75f52b6d76
--- /dev/null
+++ b/PdfToPodcast/ui/src/App.css
@@ -0,0 +1,4 @@
+#root {
+  margin: 0 auto;
+  text-align: center;
+}
diff --git a/PdfToPodcast/ui/src/App.jsx b/PdfToPodcast/ui/src/App.jsx
new file mode 100644
index 0000000000..92b4376905
--- /dev/null
+++ b/PdfToPodcast/ui/src/App.jsx
@@ -0,0 +1,47 @@
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { Toaster } from 'react-hot-toast';
+import Layout from '@components/layout/Layout';
+import Home from '@pages/Home';
+import PodcastGenerator from '@pages/PodcastGenerator';
+import Projects from '@pages/Projects';
+import Settings from '@pages/Settings';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Toaster
+        position="top-right"
+        toastOptions={{
+          duration: 4000,
+          style: {
+            background: '#fff',
+            color: '#374151',
+            boxShadow: '0 10px 15px -3px rgba(0, 0, 0, 0.1)',
+          },
+          success: {
+            iconTheme: {
+              primary: '#22c55e',
+              secondary: '#fff',
+            },
+          },
+          error: {
+            iconTheme: {
+              primary: '#ef4444',
+              secondary: '#fff',
+            },
+          },
+        }}
+      />
+      <Routes>
+        <Route path="/" element={<Layout />}>
+          <Route index element={<Home />} />
+          <Route path="generate" element={<PodcastGenerator />} />
+          <Route path="projects" element={<Projects />} />
+          <Route path="settings" element={<Settings />} />
+        </Route>
+      </Routes>
+    </BrowserRouter>
+  );
+}
+
+export default App;
diff --git a/PdfToPodcast/ui/src/components/AudioPlayer.jsx b/PdfToPodcast/ui/src/components/AudioPlayer.jsx
new file mode 100644
index 0000000000..f242f1f694
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/AudioPlayer.jsx
@@ -0,0 +1,193 @@
+import { useState, useRef } from 'react';
+import { Play, Pause, Download, RotateCcw, Volume2, Save } from 'lucide-react';
+import toast from 'react-hot-toast';
+import { downloadAudio } from '../services/api';
+
+const AudioPlayer = ({ audioUrl, jobId, onReset, pdfName, hostVoice, guestVoice }) => {
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const audioRef = useRef(null);
+
+  const togglePlay = () => {
+    if (audioRef.current) {
+      if (isPlaying) {
+        audioRef.current.pause();
+      } else {
+        audioRef.current.play();
+      }
+      setIsPlaying(!isPlaying);
+    }
+  };
+
+  const handleTimeUpdate = () => {
+    if (audioRef.current) {
+      setCurrentTime(audioRef.current.currentTime);
+    }
+  };
+
+  const handleLoadedMetadata = () => {
+    if (audioRef.current) {
+      setDuration(audioRef.current.duration);
+    }
+  };
+
+  const handleSeek = (e) => {
+    const seekTime = (e.target.value / 100) * duration;
+    if (audioRef.current) {
+      audioRef.current.currentTime = seekTime;
+      setCurrentTime(seekTime);
+    }
+  };
+
+  const handleDownload = () => {
+    // Create download link using the audioUrl
+    const a = document.createElement('a');
+    a.href = audioUrl;
+    a.download = `podcast-${jobId}.mp3`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+
+    // Save to projects after downloading
+    handleSaveProject();
+  };
+
+  const handleSaveProject = () => {
+    try {
+      const project = {
+        id: jobId,
+        pdfName: pdfName || 'Untitled',
+        audioUrl: audioUrl,
+        hostVoice,
+        guestVoice,
+        createdAt: new Date().toISOString(),
+        status: 'completed'
+      };
+
+      const projects = JSON.parse(localStorage.getItem('podcastProjects') || '[]');
+
+      // Check if project already exists
+      const existingIndex = projects.findIndex(p => p.id === jobId);
+      if (existingIndex !== -1) {
+        // Update existing project
+        projects[existingIndex] = project;
+      } else {
+        // Add new project
+        projects.unshift(project);
+      }
+
+      localStorage.setItem('podcastProjects', JSON.stringify(projects.slice(0, 20)));
+      toast.success('Project saved to Projects!');
+    } catch (error) {
+      console.error('Error saving project:', error);
+      toast.error('Failed to save project');
+    }
+  };
+
+  const formatTime = (time) => {
+    if (isNaN(time)) return '0:00';
+    const minutes = Math.floor(time / 60);
+    const seconds = Math.floor(time % 60);
+    return `${minutes}:${seconds.toString().padStart(2, '0')}`;
+  };
+
+  return (
+    <div className="card">
+      <div className="text-center mb-8">
+        <div className="w-24 h-24 bg-gradient-to-br from-primary-500 to-primary-700 rounded-full mx-auto mb-4 flex items-center justify-center">
+          <Volume2 className="w-12 h-12 text-white" />
+        </div>
+        <h2 className="text-2xl font-bold text-gray-800 mb-2">
+          Your Podcast is Ready!
+        </h2>
+        <p className="text-gray-600">
+          Listen to your AI-generated podcast below
+        </p>
+      </div>
+
+      <audio
+        ref={audioRef}
+        src={audioUrl}
+        onTimeUpdate={handleTimeUpdate}
+        onLoadedMetadata={handleLoadedMetadata}
+        onEnded={() => setIsPlaying(false)}
+      />
+
+      <div className="bg-gray-50 rounded-lg p-6 mb-6">
+        <div className="flex items-center justify-between mb-4">
+          <span className="text-sm text-gray-600">{formatTime(currentTime)}</span>
+          <span className="text-sm text-gray-600">{formatTime(duration)}</span>
+        </div>
+
+        <input
+          type="range"
+          min="0"
+          max="100"
+          value={duration ? (currentTime / duration) * 100 : 0}
+          onChange={handleSeek}
+          className="w-full h-2 bg-gray-300 rounded-lg appearance-none cursor-pointer slider"
+        />
+
+        <div className="flex justify-center mt-6">
+          <button
+            onClick={togglePlay}
+            className="w-16 h-16 bg-primary-600 hover:bg-primary-700 text-white rounded-full flex items-center justify-center transition-colors"
+          >
+            {isPlaying ? (
+              <Pause className="w-8 h-8" />
+            ) : (
+              <Play className="w-8 h-8 ml-1" />
+            )}
+          </button>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-3 gap-4">
+        <button
+          onClick={handleDownload}
+          className="btn-primary flex items-center justify-center"
+        >
+          <Download className="w-5 h-5 mr-2" />
+          Download
+        </button>
+        <button
+          onClick={handleSaveProject}
+          className="btn-primary flex items-center justify-center"
+        >
+          <Save className="w-5 h-5 mr-2" />
+          Save Project
+        </button>
+        <button
+          onClick={onReset}
+          className="btn-secondary flex items-center justify-center"
+        >
+          <RotateCcw className="w-5 h-5 mr-2" />
+          New Podcast
+        </button>
+      </div>
+
+      <style jsx>{`
+        .slider::-webkit-slider-thumb {
+          appearance: none;
+          width: 16px;
+          height: 16px;
+          background: #0284c7;
+          cursor: pointer;
+          border-radius: 50%;
+        }
+
+        .slider::-moz-range-thumb {
+          width: 16px;
+          height: 16px;
+          background: #0284c7;
+          cursor: pointer;
+          border-radius: 50%;
+          border: none;
+        }
+      `}</style>
+    </div>
+  );
+};
+
+export default AudioPlayer;
diff --git a/PdfToPodcast/ui/src/components/FileUpload.jsx b/PdfToPodcast/ui/src/components/FileUpload.jsx
new file mode 100644
index 0000000000..b8a18bf838
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/FileUpload.jsx
@@ -0,0 +1,130 @@
+import { useState, useRef } from 'react';
+import { Upload, FileText } from 'lucide-react';
+
+const FileUpload = ({ onFileUpload, isLoading }) => {
+  const [dragActive, setDragActive] = useState(false);
+  const [selectedFile, setSelectedFile] = useState(null);
+  const fileInputRef = useRef(null);
+
+  const handleDrag = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.type === 'dragenter' || e.type === 'dragover') {
+      setDragActive(true);
+    } else if (e.type === 'dragleave') {
+      setDragActive(false);
+    }
+  };
+
+  const handleDrop = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragActive(false);
+
+    if (e.dataTransfer.files && e.dataTransfer.files[0]) {
+      handleFile(e.dataTransfer.files[0]);
+    }
+  };
+
+  const handleChange = (e) => {
+    e.preventDefault();
+    if (e.target.files && e.target.files[0]) {
+      handleFile(e.target.files[0]);
+    }
+  };
+
+  const handleFile = (file) => {
+    if (file.type !== 'application/pdf') {
+      alert('Please upload a PDF file');
+      return;
+    }
+
+    if (file.size > 10 * 1024 * 1024) {
+      alert('File size must be less than 10MB');
+      return;
+    }
+
+    setSelectedFile(file);
+  };
+
+  const handleUpload = () => {
+    if (selectedFile) {
+      onFileUpload(selectedFile);
+    }
+  };
+
+  const handleButtonClick = () => {
+    fileInputRef.current?.click();
+  };
+
+  return (
+    <div className="card">
+      <div
+        className={`border-2 border-dashed rounded-lg p-12 text-center transition-colors ${
+          dragActive
+            ? 'border-primary-500 bg-primary-50'
+            : 'border-gray-300 bg-gray-50'
+        }`}
+        onDragEnter={handleDrag}
+        onDragLeave={handleDrag}
+        onDragOver={handleDrag}
+        onDrop={handleDrop}
+      >
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept=".pdf"
+          onChange={handleChange}
+          className="hidden"
+        />
+
+        {!selectedFile ? (
+          <>
+            <Upload className="mx-auto h-16 w-16 text-gray-400 mb-4" />
+            <p className="text-lg font-medium text-gray-700 mb-2">
+              Drop your PDF here or click to browse
+            </p>
+            <p className="text-sm text-gray-500 mb-4">
+              Maximum file size: 10MB
+            </p>
+            <button
+              onClick={handleButtonClick}
+              className="btn-primary"
+              disabled={isLoading}
+            >
+              Choose File
+            </button>
+          </>
+        ) : (
+          <>
+            <FileText className="mx-auto h-16 w-16 text-primary-500 mb-4" />
+            <p className="text-lg font-medium text-gray-700 mb-2">
+              {selectedFile.name}
+            </p>
+            <p className="text-sm text-gray-500 mb-4">
+              {(selectedFile.size / 1024 / 1024).toFixed(2)} MB
+            </p>
+            <div className="flex gap-3 justify-center">
+              <button
+                onClick={handleButtonClick}
+                className="btn-secondary"
+                disabled={isLoading}
+              >
+                Change File
+              </button>
+              <button
+                onClick={handleUpload}
+                className="btn-primary"
+                disabled={isLoading}
+              >
+                {isLoading ? 'Uploading...' : 'Upload & Continue'}
+              </button>
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default FileUpload;
diff --git a/PdfToPodcast/ui/src/components/ProgressTracker.jsx b/PdfToPodcast/ui/src/components/ProgressTracker.jsx
new file mode 100644
index 0000000000..d59cab40b4
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ProgressTracker.jsx
@@ -0,0 +1,84 @@
+import { Loader2, CheckCircle2 } from 'lucide-react';
+
+const ProgressTracker = ({ progress, message }) => {
+  // Determine steps based on message content
+  const getSteps = () => {
+    const msg = message.toLowerCase();
+
+    if (msg.includes('audio') || msg.includes('generating podcast') || msg.includes('creating podcast')) {
+      // Audio generation phase
+      return [
+        { label: 'Processing script', threshold: 20 },
+        { label: 'Generating host audio', threshold: 40 },
+        { label: 'Generating guest audio', threshold: 60 },
+        { label: 'Combining audio segments', threshold: 80 },
+        { label: 'Finalizing podcast', threshold: 95 }
+      ];
+    } else {
+      // Script generation phase
+      return [
+        { label: 'Analyzing PDF content', threshold: 20 },
+        { label: 'Extracting key concepts', threshold: 40 },
+        { label: 'Creating dialogue flow', threshold: 60 },
+        { label: 'Generating conversation', threshold: 80 },
+        { label: 'Finalizing script', threshold: 95 }
+      ];
+    }
+  };
+
+  const steps = getSteps();
+
+  return (
+    <div className="card">
+      <div className="text-center">
+        <Loader2 className="w-16 h-16 text-primary-500 mx-auto mb-6 animate-spin" />
+
+        <h2 className="text-2xl font-bold text-gray-800 mb-4">
+          {message || 'Processing...'}
+        </h2>
+
+        <div className="w-full bg-gray-200 rounded-full h-4 mb-4">
+          <div
+            className="bg-primary-600 h-4 rounded-full transition-all duration-500 ease-out"
+            style={{ width: `${progress}%` }}
+          />
+        </div>
+
+        <p className="text-lg font-medium text-gray-600">
+          {progress}% Complete
+        </p>
+
+        <div className="mt-8 space-y-3 text-left max-w-md mx-auto">
+          {steps.map((step, index) => {
+            const isCompleted = progress >= step.threshold;
+            const isActive = progress >= (index > 0 ? steps[index - 1].threshold : 0) && progress < step.threshold;
+
+            return (
+              <div
+                key={index}
+                className={`flex items-center transition-colors ${
+                  isCompleted ? 'text-green-600' :
+                  isActive ? 'text-primary-600 font-medium' :
+                  'text-gray-400'
+                }`}
+              >
+                {isCompleted ? (
+                  <CheckCircle2 className="w-4 h-4 mr-3 flex-shrink-0" />
+                ) : (
+                  <div className={`w-2 h-2 rounded-full mr-3 flex-shrink-0 ${
+                    isCompleted ? 'bg-green-600' :
+                    isActive ? 'bg-primary-600 animate-pulse' :
+                    'bg-gray-400'
+                  }`} />
+                )}
+                <span>{step.label}</span>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default ProgressTracker;
diff --git a/PdfToPodcast/ui/src/components/ScriptEditor.jsx b/PdfToPodcast/ui/src/components/ScriptEditor.jsx
new file mode 100644
index 0000000000..4f57773a01
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ScriptEditor.jsx
@@ -0,0 +1,122 @@
+import { useState } from 'react';
+import { ChevronLeft, Edit2, Save } from 'lucide-react';
+
+const ScriptEditor = ({ script, onScriptChange, onGenerate, isLoading, onBack }) => {
+  const [isEditing, setIsEditing] = useState(false);
+  const [editedScript, setEditedScript] = useState(script);
+
+  const handleSave = () => {
+    onScriptChange(editedScript);
+    setIsEditing(false);
+  };
+
+  const handleCancel = () => {
+    setEditedScript(script);
+    setIsEditing(false);
+  };
+
+  const handleDialogueChange = (index, field, value) => {
+    const newScript = [...editedScript];
+    newScript[index][field] = value;
+    setEditedScript(newScript);
+  };
+
+  return (
+    <div className="card">
+      <button
+        onClick={onBack}
+        className="flex items-center text-gray-600 hover:text-gray-800 mb-6"
+      >
+        <ChevronLeft className="w-5 h-5 mr-1" />
+        Back
+      </button>
+
+      <div className="flex justify-between items-center mb-6">
+        <h2 className="text-2xl font-bold text-gray-800">
+          Podcast Script
+        </h2>
+        {!isEditing && (
+          <button
+            onClick={() => setIsEditing(true)}
+            className="flex items-center btn-secondary"
+          >
+            <Edit2 className="w-4 h-4 mr-2" />
+            Edit Script
+          </button>
+        )}
+      </div>
+
+      <div className="space-y-4 mb-6 max-h-96 overflow-y-auto">
+        {(isEditing ? editedScript : script).map((dialogue, index) => (
+          <div
+            key={index}
+            className={`p-4 rounded-lg ${
+              dialogue.speaker === 'host'
+                ? 'bg-blue-50 border-l-4 border-blue-500'
+                : 'bg-green-50 border-l-4 border-green-500'
+            }`}
+          >
+            <div className="flex items-start justify-between mb-2">
+              <span className="font-semibold text-gray-700 capitalize">
+                {dialogue.speaker}
+              </span>
+              {isEditing && (
+                <select
+                  value={dialogue.speaker}
+                  onChange={(e) =>
+                    handleDialogueChange(index, 'speaker', e.target.value)
+                  }
+                  className="text-sm border border-gray-300 rounded px-2 py-1"
+                >
+                  <option value="host">Host</option>
+                  <option value="guest">Guest</option>
+                </select>
+              )}
+            </div>
+            {isEditing ? (
+              <textarea
+                value={dialogue.text}
+                onChange={(e) =>
+                  handleDialogueChange(index, 'text', e.target.value)
+                }
+                className="w-full p-2 border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-primary-500"
+                rows={3}
+              />
+            ) : (
+              <p className="text-gray-800">{dialogue.text}</p>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {isEditing && (
+        <div className="flex gap-3 mb-6">
+          <button onClick={handleCancel} className="btn-secondary flex-1">
+            Cancel
+          </button>
+          <button onClick={handleSave} className="btn-primary flex-1">
+            <Save className="w-4 h-4 mr-2 inline" />
+            Save Changes
+          </button>
+        </div>
+      )}
+
+      <div className="bg-yellow-50 border border-yellow-200 rounded-lg p-4 mb-6">
+        <p className="text-sm text-yellow-800">
+          <strong>Tip:</strong> Review and edit the script to ensure accuracy before generating audio.
+          This is your last chance to make changes!
+        </p>
+      </div>
+
+      <button
+        onClick={onGenerate}
+        className="btn-primary w-full text-lg py-3"
+        disabled={isLoading || isEditing}
+      >
+        {isLoading ? 'Generating Audio...' : 'Generate Podcast Audio'}
+      </button>
+    </div>
+  );
+};
+
+export default ScriptEditor;
diff --git a/PdfToPodcast/ui/src/components/VoiceSelector.jsx b/PdfToPodcast/ui/src/components/VoiceSelector.jsx
new file mode 100644
index 0000000000..e82556f083
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/VoiceSelector.jsx
@@ -0,0 +1,170 @@
+import { useState } from 'react';
+import { Volume2, ChevronLeft } from 'lucide-react';
+
+const VoiceSelector = ({
+  voices,
+  hostVoice,
+  guestVoice,
+  onHostVoiceChange,
+  onGuestVoiceChange,
+  onGenerate,
+  isLoading,
+  onBack,
+}) => {
+  const [playingVoice, setPlayingVoice] = useState(null);
+
+  const playSample = async (voiceId) => {
+    try {
+      setPlayingVoice(voiceId);
+
+      // Access voice samples directly from public folder
+      const audio = new Audio(`/voice-samples/${voiceId}.mp3`);
+
+      audio.onended = () => {
+        setPlayingVoice(null);
+      };
+
+      audio.onerror = () => {
+        console.error(`Failed to play voice sample for ${voiceId}`);
+        setPlayingVoice(null);
+      };
+
+      await audio.play();
+    } catch (error) {
+      console.error('Error playing voice sample:', error);
+      setPlayingVoice(null);
+    }
+  };
+
+  const voiceOptions = [
+    { id: 'alloy', name: 'Alloy', description: 'Neutral and balanced' },
+    { id: 'echo', name: 'Echo', description: 'Clear and expressive' },
+    { id: 'fable', name: 'Fable', description: 'Warm and engaging' },
+    { id: 'onyx', name: 'Onyx', description: 'Deep and authoritative' },
+    { id: 'nova', name: 'Nova', description: 'Friendly and conversational' },
+    { id: 'shimmer', name: 'Shimmer', description: 'Bright and energetic' },
+  ];
+
+  return (
+    <div className="card">
+      <button
+        onClick={onBack}
+        className="flex items-center text-gray-600 hover:text-gray-800 mb-6"
+      >
+        <ChevronLeft className="w-5 h-5 mr-1" />
+        Back
+      </button>
+
+      <h2 className="text-2xl font-bold text-gray-800 mb-6">
+        Select Voice Actors
+      </h2>
+
+      <div className="grid md:grid-cols-2 gap-6 mb-8">
+        {/* Host Voice */}
+        <div>
+          <label className="block text-sm font-medium text-gray-700 mb-3">
+            Host Voice
+          </label>
+          <div className="space-y-2">
+            {voiceOptions.map((voice) => (
+              <div
+                key={`host-${voice.id}`}
+                className={`p-4 border rounded-lg cursor-pointer transition-all ${
+                  hostVoice === voice.id
+                    ? 'border-primary-500 bg-primary-50'
+                    : 'border-gray-200 hover:border-gray-300'
+                }`}
+                onClick={() => onHostVoiceChange(voice.id)}
+              >
+                <div className="flex items-center justify-between">
+                  <div>
+                    <p className="font-medium text-gray-800">{voice.name}</p>
+                    <p className="text-sm text-gray-500">{voice.description}</p>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      playSample(voice.id);
+                    }}
+                    className="p-2 hover:bg-gray-100 rounded-full"
+                    disabled={playingVoice === voice.id}
+                  >
+                    <Volume2
+                      className={`w-5 h-5 ${
+                        playingVoice === voice.id
+                          ? 'text-primary-500 animate-pulse'
+                          : 'text-gray-400'
+                      }`}
+                    />
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+
+        {/* Guest Voice */}
+        <div>
+          <label className="block text-sm font-medium text-gray-700 mb-3">
+            Guest Voice
+          </label>
+          <div className="space-y-2">
+            {voiceOptions.map((voice) => (
+              <div
+                key={`guest-${voice.id}`}
+                className={`p-4 border rounded-lg cursor-pointer transition-all ${
+                  guestVoice === voice.id
+                    ? 'border-primary-500 bg-primary-50'
+                    : 'border-gray-200 hover:border-gray-300'
+                }`}
+                onClick={() => onGuestVoiceChange(voice.id)}
+              >
+                <div className="flex items-center justify-between">
+                  <div>
+                    <p className="font-medium text-gray-800">{voice.name}</p>
+                    <p className="text-sm text-gray-500">{voice.description}</p>
+                  </div>
+                  <button
+                    type="button"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      playSample(voice.id);
+                    }}
+                    className="p-2 hover:bg-gray-100 rounded-full"
+                    disabled={playingVoice === voice.id}
+                  >
+                    <Volume2
+                      className={`w-5 h-5 ${
+                        playingVoice === voice.id
+                          ? 'text-primary-500 animate-pulse'
+                          : 'text-gray-400'
+                      }`}
+                    />
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      <div className="bg-blue-50 border border-blue-200 rounded-lg p-4 mb-6">
+        <p className="text-sm text-blue-800">
+          <strong>Selected:</strong> Host - {voiceOptions.find(v => v.id === hostVoice)?.name} |
+          Guest - {voiceOptions.find(v => v.id === guestVoice)?.name}
+        </p>
+      </div>
+
+      <button
+        onClick={onGenerate}
+        className="btn-primary w-full text-lg py-3"
+        disabled={isLoading || !hostVoice || !guestVoice}
+      >
+        {isLoading ? 'Generating Script...' : 'Generate Podcast Script'}
+      </button>
+    </div>
+  );
+};
+
+export default VoiceSelector;
diff --git a/PdfToPodcast/ui/src/components/features/AudioPlayer.jsx b/PdfToPodcast/ui/src/components/features/AudioPlayer.jsx
new file mode 100644
index 0000000000..258f9a99f1
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/features/AudioPlayer.jsx
@@ -0,0 +1,269 @@
+import { useRef, useEffect } from 'react';
+import { useDispatch, useSelector } from 'react-redux';
+import {
+  Play,
+  Pause,
+  Download,
+  RotateCcw,
+  SkipBack,
+  SkipForward,
+} from 'lucide-react';
+import { useWaveSurfer } from '@hooks/useWaveSurfer';
+import { downloadAudio } from '@store/slices/audioSlice';
+import { Button, Card, CardBody, Spinner } from '@components/ui';
+import { formatTime, downloadBlob } from '@utils/helpers';
+import { cn } from '@utils/helpers';
+
+export const AudioPlayer = ({ onReset }) => {
+  const dispatch = useDispatch();
+  const { audioUrl, audioBlob } = useSelector((state) => state.audio);
+  const { jobId } = useSelector((state) => state.upload);
+  const waveformRef = useRef(null);
+
+  const {
+    wavesurfer,
+    isPlaying,
+    currentTime,
+    duration,
+    playPause,
+    seekTo,
+    load,
+  } = useWaveSurfer(waveformRef, {
+    height: 100,
+    waveColor: '#ddd',
+    progressColor: '#0284c7',
+  });
+
+  useEffect(() => {
+    if (audioUrl && wavesurfer) {
+      const fullUrl = audioUrl.startsWith('http')
+        ? audioUrl
+        : `http://localhost:8000${audioUrl}`;
+      load(fullUrl);
+    }
+  }, [audioUrl, wavesurfer, load]);
+
+  const handleDownload = async () => {
+    if (jobId) {
+      let blob = audioBlob;
+
+      if (!blob) {
+        const result = await dispatch(downloadAudio(jobId));
+        if (result.type.endsWith('/fulfilled')) {
+          blob = result.payload;
+        }
+      }
+
+      if (blob) {
+        downloadBlob(blob, `podcast-${jobId}.mp3`);
+      }
+    }
+  };
+
+  const handleSkip = (seconds) => {
+    if (wavesurfer) {
+      const newTime = Math.max(
+        0,
+        Math.min(duration, currentTime + seconds)
+      );
+      seekTo(newTime / duration);
+    }
+  };
+
+  if (!audioUrl) {
+    return (
+      <Card>
+        <CardBody>
+          <div className="text-center py-12">
+            <Spinner size="lg" />
+            <p className="mt-4 text-gray-600">
+              Generating your podcast audio...
+            </p>
+          </div>
+        </CardBody>
+      </Card>
+    );
+  }
+
+  // Check if TTS service is not available (placeholder URL)
+  const isTTSAvailable = audioUrl && audioUrl !== 'placeholder' && !audioUrl.startsWith('http://localhost:8000/voice-samples');
+
+  return (
+    <Card>
+      <CardBody>
+        <div className="space-y-6">
+          <div className="text-center">
+            {/* Custom Success Image - Replace src with your actual image */}
+            <img
+              src="/success-icon.png"
+              alt="Success"
+              className="w-24 h-24 mx-auto mb-4 object-contain"
+              onError={(e) => {
+                // Fallback to gradient circle if image not found
+                e.target.style.display = 'none';
+                e.target.nextSibling.style.display = 'flex';
+              }}
+            />
+            <div
+              className="w-24 h-24 bg-gradient-to-br from-primary-500 to-primary-700 rounded-full mx-auto mb-4 items-center justify-center shadow-lg hidden"
+              style={{ display: 'none' }}
+            >
+              <div className="w-12 h-12 bg-white rounded-full" />
+            </div>
+            <h2 className="text-2xl font-bold text-gray-900 mb-2">
+              {isTTSAvailable ? 'Your Podcast is Ready!' : 'Script Generation Complete!'}
+            </h2>
+            {isTTSAvailable ? (
+              <p className="text-gray-600">
+                Listen to your AI-generated podcast below
+              </p>
+            ) : (
+              <p className="text-gray-600">
+                Your podcast script has been successfully created
+              </p>
+            )}
+          </div>
+
+          {isTTSAvailable ? (
+            <>
+              {/* Waveform */}
+              <div className="bg-gray-50 rounded-lg p-6">
+                <div ref={waveformRef} className="mb-4" />
+
+                {/* Time Display */}
+                <div className="flex justify-between text-sm text-gray-600 mb-4">
+                  <span>{formatTime(currentTime)}</span>
+                  <span>{formatTime(duration)}</span>
+                </div>
+
+                {/* Controls */}
+                <div className="flex items-center justify-center gap-4">
+                  <button
+                    onClick={() => handleSkip(-10)}
+                    className="p-2 hover:bg-gray-200 rounded-full transition-colors"
+                    title="Skip back 10s"
+                  >
+                    <SkipBack className="w-5 h-5" />
+                  </button>
+
+                  <button
+                    onClick={playPause}
+                    className="w-16 h-16 bg-primary-600 hover:bg-primary-700 text-white rounded-full flex items-center justify-center transition-colors shadow-lg"
+                  >
+                    {isPlaying ? (
+                      <Pause className="w-8 h-8" />
+                    ) : (
+                      <Play className="w-8 h-8 ml-1" />
+                    )}
+                  </button>
+
+                  <button
+                    onClick={() => handleSkip(10)}
+                    className="p-2 hover:bg-gray-200 rounded-full transition-colors"
+                    title="Skip forward 10s"
+                  >
+                    <SkipForward className="w-5 h-5" />
+                  </button>
+                </div>
+              </div>
+
+              {/* Stats */}
+              <div className="grid grid-cols-2 gap-4">
+                <div className="bg-blue-50 rounded-lg p-4 text-center">
+                  <p className="text-sm text-gray-600 mb-1">Duration</p>
+                  <p className="text-2xl font-bold text-gray-900">
+                    {formatTime(duration)}
+                  </p>
+                </div>
+                <div className="bg-green-50 rounded-lg p-4 text-center">
+                  <p className="text-sm text-gray-600 mb-1">Format</p>
+                  <p className="text-2xl font-bold text-gray-900">MP3</p>
+                </div>
+              </div>
+
+              {/* Actions */}
+              <div className="grid grid-cols-2 gap-4">
+                <Button
+                  onClick={handleDownload}
+                  variant="primary"
+                  size="lg"
+                  icon={Download}
+                  fullWidth
+                >
+                  Download Audio
+                </Button>
+                <Button
+                  onClick={onReset}
+                  variant="outline"
+                  size="lg"
+                  icon={RotateCcw}
+                  fullWidth
+                >
+                  Create New Podcast
+                </Button>
+              </div>
+            </>
+          ) : (
+            <>
+              {/* Success Summary */}
+              <div className="bg-green-50 border border-green-200 rounded-lg p-6">
+                <h3 className="text-lg font-semibold text-green-900 mb-3">
+                  What's Been Created
+                </h3>
+                <div className="space-y-2 text-green-800">
+                  <div className="flex items-center gap-2">
+                    <svg className="w-5 h-5 text-green-600" fill="currentColor" viewBox="0 0 20 20">
+                      <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clipRule="evenodd" />
+                    </svg>
+                    <span>PDF text successfully extracted</span>
+                  </div>
+                  <div className="flex items-center gap-2">
+                    <svg className="w-5 h-5 text-green-600" fill="currentColor" viewBox="0 0 20 20">
+                      <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clipRule="evenodd" />
+                    </svg>
+                    <span>Podcast script generated with AI</span>
+                  </div>
+                  <div className="flex items-center gap-2">
+                    <svg className="w-5 h-5 text-green-600" fill="currentColor" viewBox="0 0 20 20">
+                      <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clipRule="evenodd" />
+                    </svg>
+                    <span>Voice actors selected</span>
+                  </div>
+                </div>
+              </div>
+
+              {/* TTS Info */}
+              <div className="bg-blue-50 border border-blue-200 rounded-lg p-6">
+                <h3 className="text-lg font-semibold text-blue-900 mb-2">
+                  Audio Generation
+                </h3>
+                <p className="text-blue-800 mb-3">
+                  To generate the final podcast audio, you'll need to start the TTS (Text-to-Speech) service.
+                </p>
+                <div className="bg-white rounded-lg p-3 text-sm font-mono text-gray-700">
+                  <p className="text-blue-900 font-semibold mb-2">Setup Instructions:</p>
+                  <p>1. Install Python 3.11</p>
+                  <p>2. Start TTS service on port 8003</p>
+                  <p>3. Re-run the generation process</p>
+                </div>
+              </div>
+
+              {/* Action */}
+              <Button
+                onClick={onReset}
+                variant="primary"
+                size="lg"
+                icon={RotateCcw}
+                fullWidth
+              >
+                Create New Podcast
+              </Button>
+            </>
+          )}
+        </div>
+      </CardBody>
+    </Card>
+  );
+};
+
+export default AudioPlayer;
diff --git a/PdfToPodcast/ui/src/components/features/PDFUploader.jsx b/PdfToPodcast/ui/src/components/features/PDFUploader.jsx
new file mode 100644
index 0000000000..6117064dfb
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/features/PDFUploader.jsx
@@ -0,0 +1,174 @@
+import { useCallback } from 'react';
+import { useDropzone } from 'react-dropzone';
+import { useDispatch, useSelector } from 'react-redux';
+import { Upload, FileText, X, AlertCircle } from 'lucide-react';
+import { setFile, uploadPDF } from '@store/slices/uploadSlice';
+import { validatePDFFile, formatFileSize } from '@utils/helpers';
+import { Button, Card, CardBody, Progress, Alert } from '@components/ui';
+import { cn } from '@utils/helpers';
+
+export const PDFUploader = ({ onSuccess }) => {
+  const dispatch = useDispatch();
+  const { file, uploading, uploadProgress, uploadComplete, error } = useSelector(
+    (state) => state.upload
+  );
+
+  const onDrop = useCallback(
+    (acceptedFiles) => {
+      const selectedFile = acceptedFiles[0];
+      const errors = validatePDFFile(selectedFile);
+
+      if (errors.length > 0) {
+        // Handle validation errors
+        return;
+      }
+
+      dispatch(setFile(selectedFile));
+    },
+    [dispatch]
+  );
+
+  const { getRootProps, getInputProps, isDragActive } = useDropzone({
+    onDrop,
+    accept: {
+      'application/pdf': ['.pdf'],
+    },
+    maxFiles: 1,
+    maxSize: 10 * 1024 * 1024, // 10MB
+  });
+
+  const handleUpload = async () => {
+    if (file) {
+      const result = await dispatch(uploadPDF(file));
+      if (result.type.endsWith('/fulfilled') && onSuccess) {
+        onSuccess(result.payload);
+      }
+    }
+  };
+
+  const handleRemove = () => {
+    dispatch(setFile(null));
+  };
+
+  return (
+    <Card>
+      <CardBody>
+        <div className="space-y-6">
+          <div>
+            <h2 className="text-2xl font-bold text-gray-900 mb-2">
+              Upload Your PDF
+            </h2>
+            <p className="text-gray-600">
+              Upload a PDF document to transform it into an engaging podcast conversation.
+            </p>
+          </div>
+
+          {error && (
+            <Alert variant="error" message={error} />
+          )}
+
+          {!file && (
+            <div
+              {...getRootProps()}
+              className={cn(
+                'border-2 border-dashed rounded-lg p-12 text-center cursor-pointer transition-all',
+                isDragActive
+                  ? 'border-primary-500 bg-primary-50'
+                  : 'border-gray-300 hover:border-primary-400 hover:bg-gray-50'
+              )}
+            >
+              <input {...getInputProps()} />
+              <Upload
+                className={cn(
+                  'w-16 h-16 mx-auto mb-4',
+                  isDragActive ? 'text-primary-500' : 'text-gray-400'
+                )}
+              />
+              <p className="text-lg font-medium text-gray-700 mb-2">
+                {isDragActive
+                  ? 'Drop your PDF here'
+                  : 'Drag & drop your PDF here'}
+              </p>
+              <p className="text-sm text-gray-500 mb-4">
+                or click to browse files
+              </p>
+              <p className="text-xs text-gray-400">
+                Maximum file size: 10MB | PDF format only
+              </p>
+            </div>
+          )}
+
+          {file && !uploadComplete && (
+            <div className="border-2 border-primary-200 bg-primary-50 rounded-lg p-6">
+              <div className="flex items-start justify-between mb-4">
+                <div className="flex items-start gap-3 flex-1">
+                  <FileText className="w-10 h-10 text-primary-600 flex-shrink-0" />
+                  <div className="flex-1 min-w-0">
+                    <p className="font-medium text-gray-900 truncate">
+                      {file.name}
+                    </p>
+                    <p className="text-sm text-gray-600">
+                      {formatFileSize(file.size)}
+                    </p>
+                  </div>
+                </div>
+                {!uploading && (
+                  <button
+                    onClick={handleRemove}
+                    className="text-gray-400 hover:text-gray-600 p-1"
+                  >
+                    <X className="w-5 h-5" />
+                  </button>
+                )}
+              </div>
+
+              {uploading && (
+                <div className="space-y-2">
+                  <Progress value={uploadProgress} showLabel />
+                  <p className="text-sm text-gray-600 text-center">
+                    Uploading... {uploadProgress}%
+                  </p>
+                </div>
+              )}
+
+              {!uploading && !uploadComplete && (
+                <Button
+                  onClick={handleUpload}
+                  fullWidth
+                  size="lg"
+                  icon={Upload}
+                >
+                  Upload & Continue
+                </Button>
+              )}
+            </div>
+          )}
+
+          {uploadComplete && (
+            <Alert
+              variant="success"
+              title="Upload Successful!"
+              message="Your PDF has been uploaded and processed successfully."
+            />
+          )}
+
+          <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+            <div className="flex gap-2">
+              <AlertCircle className="w-5 h-5 text-blue-600 flex-shrink-0 mt-0.5" />
+              <div className="text-sm text-blue-800">
+                <p className="font-medium mb-1">Tips for best results:</p>
+                <ul className="list-disc list-inside space-y-1 text-blue-700">
+                  <li>Use PDFs with selectable text (not scanned images)</li>
+                  <li>Documents between 2-10 pages work best</li>
+                  <li>Clear formatting improves conversation quality</li>
+                </ul>
+              </div>
+            </div>
+          </div>
+        </div>
+      </CardBody>
+    </Card>
+  );
+};
+
+export default PDFUploader;
diff --git a/PdfToPodcast/ui/src/components/features/ProgressTracker.jsx b/PdfToPodcast/ui/src/components/features/ProgressTracker.jsx
new file mode 100644
index 0000000000..cfa5a5f857
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/features/ProgressTracker.jsx
@@ -0,0 +1,97 @@
+import { Loader2, CheckCircle } from 'lucide-react';
+import { Card, CardBody, Progress } from '@components/ui';
+import { cn } from '@utils/helpers';
+
+const steps = [
+  { id: 1, label: 'Uploading PDF', threshold: 10 },
+  { id: 2, label: 'Extracting content', threshold: 30 },
+  { id: 3, label: 'Analyzing structure', threshold: 50 },
+  { id: 4, label: 'Generating dialogue', threshold: 70 },
+  { id: 5, label: 'Finalizing script', threshold: 90 },
+];
+
+export const ProgressTracker = ({ progress = 0, message = 'Processing...' }) => {
+  return (
+    <Card>
+      <CardBody>
+        <div className="text-center space-y-6">
+          {/* Animated Icon */}
+          <div className="relative">
+            <Loader2 className="w-16 h-16 text-primary-500 mx-auto animate-spin" />
+            <div className="absolute inset-0 flex items-center justify-center">
+              <div className="w-12 h-12 bg-primary-100 rounded-full animate-pulse" />
+            </div>
+          </div>
+
+          {/* Message */}
+          <div>
+            <h2 className="text-2xl font-bold text-gray-900 mb-2">
+              {message}
+            </h2>
+            <p className="text-gray-600">
+              This may take a few minutes. Please don't close this page.
+            </p>
+          </div>
+
+          {/* Progress Bar */}
+          <div className="max-w-md mx-auto">
+            <Progress value={progress} size="lg" showLabel />
+          </div>
+
+          {/* Step List */}
+          <div className="max-w-md mx-auto space-y-2 text-left">
+            {steps.map((step) => {
+              const isCompleted = progress >= step.threshold;
+              const isCurrent =
+                progress >= (steps[step.id - 2]?.threshold || 0) &&
+                progress < step.threshold;
+
+              return (
+                <div
+                  key={step.id}
+                  className={cn(
+                    'flex items-center gap-3 p-3 rounded-lg transition-all',
+                    isCompleted && 'bg-success-50',
+                    isCurrent && 'bg-primary-50',
+                    !isCompleted && !isCurrent && 'bg-gray-50'
+                  )}
+                >
+                  <div
+                    className={cn(
+                      'w-6 h-6 rounded-full flex items-center justify-center flex-shrink-0',
+                      isCompleted &&
+                        'bg-success-500 text-white',
+                      isCurrent &&
+                        'bg-primary-500 text-white animate-pulse',
+                      !isCompleted &&
+                        !isCurrent &&
+                        'bg-gray-300 text-gray-500'
+                    )}
+                  >
+                    {isCompleted ? (
+                      <CheckCircle className="w-4 h-4" />
+                    ) : (
+                      <span className="text-xs font-bold">{step.id}</span>
+                    )}
+                  </div>
+                  <span
+                    className={cn(
+                      'text-sm font-medium',
+                      isCompleted && 'text-success-700',
+                      isCurrent && 'text-primary-700',
+                      !isCompleted && !isCurrent && 'text-gray-500'
+                    )}
+                  >
+                    {step.label}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </CardBody>
+    </Card>
+  );
+};
+
+export default ProgressTracker;
diff --git a/PdfToPodcast/ui/src/components/features/ScriptEditor.jsx b/PdfToPodcast/ui/src/components/features/ScriptEditor.jsx
new file mode 100644
index 0000000000..875d7ce8b4
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/features/ScriptEditor.jsx
@@ -0,0 +1,210 @@
+import { useState } from 'react';
+import { useDispatch, useSelector } from 'react-redux';
+import { Edit2, Save, X, ChevronLeft, Trash2, Plus } from 'lucide-react';
+import { setScript, updateScript } from '@store/slices/scriptSlice';
+import { Button, Card, CardBody, Alert, Input } from '@components/ui';
+import { cn } from '@utils/helpers';
+
+export const ScriptEditor = ({ onBack, onNext }) => {
+  const dispatch = useDispatch();
+  const { script, updating, error } = useSelector((state) => state.script);
+  const { jobId } = useSelector((state) => state.upload);
+  const [isEditing, setIsEditing] = useState(false);
+  const [editedScript, setEditedScript] = useState(script || []);
+
+  const handleEdit = () => {
+    setEditedScript(JSON.parse(JSON.stringify(script)));
+    setIsEditing(true);
+  };
+
+  const handleCancel = () => {
+    setEditedScript(script);
+    setIsEditing(false);
+  };
+
+  const handleSave = async () => {
+    if (jobId) {
+      dispatch(setScript(editedScript));
+      const result = await dispatch(
+        updateScript({ jobId, script: editedScript })
+      );
+      if (result.type.endsWith('/fulfilled')) {
+        setIsEditing(false);
+      }
+    }
+  };
+
+  const handleDialogueChange = (index, field, value) => {
+    const newScript = [...editedScript];
+    newScript[index] = { ...newScript[index], [field]: value };
+    setEditedScript(newScript);
+  };
+
+  const handleAddDialogue = (index) => {
+    const newScript = [...editedScript];
+    newScript.splice(index + 1, 0, {
+      speaker: 'host',
+      text: '',
+    });
+    setEditedScript(newScript);
+  };
+
+  const handleDeleteDialogue = (index) => {
+    if (editedScript.length > 1) {
+      const newScript = editedScript.filter((_, i) => i !== index);
+      setEditedScript(newScript);
+    }
+  };
+
+  const currentScript = isEditing ? editedScript : script;
+
+  if (!script) {
+    return (
+      <Card>
+        <CardBody>
+          <Alert
+            variant="warning"
+            message="No script available. Please generate a script first."
+          />
+        </CardBody>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <CardBody>
+        <div className="space-y-6">
+          <div className="flex items-center justify-between">
+            <div className="flex items-center gap-4">
+              <button
+                onClick={onBack}
+                className="p-2 hover:bg-gray-100 rounded-lg transition-colors"
+              >
+                <ChevronLeft className="w-5 h-5" />
+              </button>
+              <div>
+                <h2 className="text-2xl font-bold text-gray-900">
+                  Review & Edit Script
+                </h2>
+                <p className="text-gray-600">
+                  Review the generated conversation and make any changes
+                </p>
+              </div>
+            </div>
+
+            {!isEditing ? (
+              <Button onClick={handleEdit} variant="outline" icon={Edit2}>
+                Edit Script
+              </Button>
+            ) : (
+              <div className="flex gap-2">
+                <Button onClick={handleCancel} variant="ghost" icon={X}>
+                  Cancel
+                </Button>
+                <Button
+                  onClick={handleSave}
+                  loading={updating}
+                  icon={Save}
+                >
+                  Save Changes
+                </Button>
+              </div>
+            )}
+          </div>
+
+          {error && <Alert variant="error" message={error} />}
+
+          <div className="space-y-3 max-h-96 overflow-y-auto pr-2">
+            {currentScript.map((dialogue, index) => (
+              <div
+                key={index}
+                className={cn(
+                  'p-4 rounded-lg border-l-4 transition-all',
+                  dialogue.speaker === 'host'
+                    ? 'bg-blue-50 border-blue-500'
+                    : 'bg-green-50 border-green-500',
+                  isEditing && 'ring-2 ring-gray-200'
+                )}
+              >
+                <div className="flex items-start gap-3">
+                  <div className="flex-1">
+                    {isEditing ? (
+                      <div className="space-y-2">
+                        <select
+                          value={dialogue.speaker}
+                          onChange={(e) =>
+                            handleDialogueChange(index, 'speaker', e.target.value)
+                          }
+                          className="text-sm font-semibold text-gray-700 border-none bg-transparent focus:outline-none capitalize"
+                        >
+                          <option value="host">Host</option>
+                          <option value="guest">Guest</option>
+                        </select>
+                        <textarea
+                          value={dialogue.text}
+                          onChange={(e) =>
+                            handleDialogueChange(index, 'text', e.target.value)
+                          }
+                          className="w-full p-2 border border-gray-300 rounded focus:outline-none focus:ring-2 focus:ring-primary-500 resize-none"
+                          rows={3}
+                        />
+                      </div>
+                    ) : (
+                      <>
+                        <div className="text-sm font-semibold text-gray-700 mb-1 capitalize">
+                          {dialogue.speaker}
+                        </div>
+                        <p className="text-gray-800">{dialogue.text}</p>
+                      </>
+                    )}
+                  </div>
+
+                  {isEditing && (
+                    <div className="flex flex-col gap-1">
+                      <button
+                        onClick={() => handleAddDialogue(index)}
+                        className="p-1.5 text-green-600 hover:bg-green-100 rounded transition-colors"
+                        title="Add dialogue after this"
+                      >
+                        <Plus className="w-4 h-4" />
+                      </button>
+                      {currentScript.length > 1 && (
+                        <button
+                          onClick={() => handleDeleteDialogue(index)}
+                          className="p-1.5 text-red-600 hover:bg-red-100 rounded transition-colors"
+                          title="Delete this dialogue"
+                        >
+                          <Trash2 className="w-4 h-4" />
+                        </button>
+                      )}
+                    </div>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+
+          <div className="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
+            <p className="text-sm text-yellow-800">
+              <strong>Tip:</strong> Review the script carefully and make any
+              necessary edits before generating the audio. This is your last
+              chance to perfect the conversation!
+            </p>
+          </div>
+
+          <Button
+            onClick={onNext}
+            fullWidth
+            size="lg"
+            disabled={isEditing}
+          >
+            Continue to Audio Generation
+          </Button>
+        </div>
+      </CardBody>
+    </Card>
+  );
+};
+
+export default ScriptEditor;
diff --git a/PdfToPodcast/ui/src/components/features/VoiceSelector.jsx b/PdfToPodcast/ui/src/components/features/VoiceSelector.jsx
new file mode 100644
index 0000000000..4ffed09e0e
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/features/VoiceSelector.jsx
@@ -0,0 +1,220 @@
+import { useState, useEffect } from 'react';
+import { useDispatch, useSelector } from 'react-redux';
+import { Volume2, ChevronLeft } from 'lucide-react';
+import { setHostVoice, setGuestVoice, generateScript } from '@store/slices/scriptSlice';
+import { voiceAPI } from '@services/api';
+import { Button, Card, CardBody, Alert } from '@components/ui';
+import { cn } from '@utils/helpers';
+
+const voiceOptions = [
+  { id: 'alloy', name: 'Alloy', description: 'Neutral and balanced', gender: 'neutral' },
+  { id: 'echo', name: 'Echo', description: 'Clear and expressive', gender: 'male' },
+  { id: 'fable', name: 'Fable', description: 'Warm and engaging', gender: 'neutral' },
+  { id: 'onyx', name: 'Onyx', description: 'Deep and authoritative', gender: 'male' },
+  { id: 'nova', name: 'Nova', description: 'Friendly and conversational', gender: 'female' },
+  { id: 'shimmer', name: 'Shimmer', description: 'Bright and energetic', gender: 'female' },
+];
+
+export const VoiceSelector = ({ onBack, onNext }) => {
+  const dispatch = useDispatch();
+  const { hostVoice, guestVoice, generating, error } = useSelector((state) => state.script);
+  const { jobId } = useSelector((state) => state.upload);
+  const [playingVoice, setPlayingVoice] = useState(null);
+  const [previewMessage, setPreviewMessage] = useState(null);
+
+  // No cleanup needed anymore since we're using HTML5 audio
+
+  const playSample = async (voiceId) => {
+    const voice = voiceOptions.find(v => v.id === voiceId);
+
+    try {
+      setPlayingVoice(voiceId);
+      setPreviewMessage(`Playing ${voice.name}...`);
+
+      // Get audio URL from backend
+      const response = await fetch(`http://localhost:8000/api/voice/sample/${voiceId}`);
+      const data = await response.json();
+
+      if (data.status === 'available' && data.audio_url) {
+        // Play actual OpenAI TTS audio sample
+        const audio = new Audio(data.audio_url);
+
+        audio.onended = () => {
+          setPlayingVoice(null);
+          setPreviewMessage(null);
+        };
+
+        audio.onerror = () => {
+          setPlayingVoice(null);
+          setPreviewMessage('Error playing audio sample');
+          setTimeout(() => setPreviewMessage(null), 3000);
+        };
+
+        await audio.play();
+      } else {
+        // Fallback if audio not available
+        setPreviewMessage(`${voice.name}: ${voice.description}`);
+        setTimeout(() => {
+          setPlayingVoice(null);
+          setPreviewMessage(null);
+        }, 3000);
+      }
+    } catch (error) {
+      console.error('Failed to play sample:', error);
+      setPlayingVoice(null);
+      setPreviewMessage('Error loading audio sample');
+      setTimeout(() => setPreviewMessage(null), 3000);
+    }
+  };
+
+  const handleGenerate = async () => {
+    if (jobId) {
+      const result = await dispatch(
+        generateScript({ jobId, hostVoice, guestVoice })
+      );
+      if (result.type.endsWith('/fulfilled') && onNext) {
+        onNext();
+      }
+    }
+  };
+
+  const VoiceCard = ({ voice, selected, onSelect, label }) => (
+    <div
+      onClick={() => onSelect(voice.id)}
+      className={cn(
+        'p-4 border-2 rounded-lg cursor-pointer transition-all',
+        selected
+          ? 'border-primary-500 bg-primary-50 shadow-md'
+          : 'border-gray-200 hover:border-primary-300 hover:shadow-sm'
+      )}
+    >
+      <div className="flex items-center justify-between">
+        <div className="flex-1">
+          <div className="flex items-center gap-2">
+            <h4 className="font-semibold text-gray-900">{voice.name}</h4>
+            <span className="text-xs px-2 py-0.5 bg-gray-200 text-gray-600 rounded-full">
+              {voice.gender}
+            </span>
+          </div>
+          <p className="text-sm text-gray-600 mt-1">{voice.description}</p>
+        </div>
+        <button
+          onClick={(e) => {
+            e.stopPropagation();
+            playSample(voice.id);
+          }}
+          className={cn(
+            'p-2 rounded-full transition-colors ml-4',
+            playingVoice === voice.id
+              ? 'bg-primary-500 text-white'
+              : 'bg-gray-200 text-gray-600 hover:bg-gray-300'
+          )}
+          disabled={playingVoice !== null}
+        >
+          <Volume2
+            className={cn(
+              'w-5 h-5',
+              playingVoice === voice.id && 'animate-pulse'
+            )}
+          />
+        </button>
+      </div>
+    </div>
+  );
+
+  return (
+    <Card>
+      <CardBody>
+        <div className="space-y-6">
+          <div className="flex items-center gap-4">
+            <button
+              onClick={onBack}
+              className="p-2 hover:bg-gray-100 rounded-lg transition-colors"
+            >
+              <ChevronLeft className="w-5 h-5" />
+            </button>
+            <div>
+              <h2 className="text-2xl font-bold text-gray-900">
+                Select Voice Actors
+              </h2>
+              <p className="text-gray-600">
+                Choose voices for your podcast host and guest
+              </p>
+            </div>
+          </div>
+
+          {error && (
+            <Alert variant="error" message={error} />
+          )}
+
+          {previewMessage && (
+            <div className="bg-blue-50 border border-blue-200 rounded-lg p-3">
+              <p className="text-sm text-blue-800 flex items-center gap-2">
+                <Volume2 className="w-4 h-4 animate-pulse" />
+                <span>{previewMessage}</span>
+              </p>
+            </div>
+          )}
+
+          <div className="grid md:grid-cols-2 gap-6">
+            {/* Host Voice */}
+            <div>
+              <label className="block text-sm font-medium text-gray-700 mb-3">
+                Host Voice
+              </label>
+              <div className="space-y-2">
+                {voiceOptions.map((voice) => (
+                  <VoiceCard
+                    key={`host-${voice.id}`}
+                    voice={voice}
+                    selected={hostVoice === voice.id}
+                    onSelect={(id) => dispatch(setHostVoice(id))}
+                    label="host"
+                  />
+                ))}
+              </div>
+            </div>
+
+            {/* Guest Voice */}
+            <div>
+              <label className="block text-sm font-medium text-gray-700 mb-3">
+                Guest Voice
+              </label>
+              <div className="space-y-2">
+                {voiceOptions.map((voice) => (
+                  <VoiceCard
+                    key={`guest-${voice.id}`}
+                    voice={voice}
+                    selected={guestVoice === voice.id}
+                    onSelect={(id) => dispatch(setGuestVoice(id))}
+                    label="guest"
+                  />
+                ))}
+              </div>
+            </div>
+          </div>
+
+          <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+            <p className="text-sm text-blue-800">
+              <strong>Selected:</strong> Host -{' '}
+              {voiceOptions.find((v) => v.id === hostVoice)?.name} | Guest -{' '}
+              {voiceOptions.find((v) => v.id === guestVoice)?.name}
+            </p>
+          </div>
+
+          <Button
+            onClick={handleGenerate}
+            fullWidth
+            size="lg"
+            loading={generating}
+            disabled={!jobId || generating}
+          >
+            Generate Podcast Script
+          </Button>
+        </div>
+      </CardBody>
+    </Card>
+  );
+};
+
+export default VoiceSelector;
diff --git a/PdfToPodcast/ui/src/components/layout/Footer.jsx b/PdfToPodcast/ui/src/components/layout/Footer.jsx
new file mode 100644
index 0000000000..a6185c737d
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/layout/Footer.jsx
@@ -0,0 +1,51 @@
+export const Footer = () => {
+  return (
+    <footer className="bg-gray-50 border-t border-gray-200 mt-auto">
+      <div className="container mx-auto px-4 sm:px-6 lg:px-8 py-8">
+        <div className="flex flex-col md:flex-row justify-between items-center gap-4">
+          <div className="flex items-center gap-3">
+            <span className="text-base text-gray-700 font-medium">Powered by</span>
+            <div className="flex items-center gap-2">
+              {/* Cloud2Labs Logo - Replace src with your actual logo */}
+              <img
+                src="/cloud2labs-logo.png"
+                alt="Cloud2Labs"
+                className="h-12 w-auto"
+                onError={(e) => {
+                  // Fallback to text if image not found
+                  e.target.style.display = 'none';
+                  e.target.nextSibling.style.display = 'block';
+                }}
+              />
+              <span
+                className="text-2xl font-bold bg-gradient-to-r from-primary-600 to-secondary-600 bg-clip-text text-transparent hidden"
+                style={{ display: 'none' }}
+              >
+                Cloud2Labs
+              </span>
+            </div>
+          </div>
+
+          <div className="flex items-center gap-6">
+            <a
+              href="https://github.com"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-sm text-gray-600 hover:text-primary-600 transition-colors"
+            >
+              Documentation
+            </a>
+            <a
+              href="/privacy"
+              className="text-sm text-gray-600 hover:text-primary-600 transition-colors"
+            >
+              Privacy
+            </a>
+          </div>
+        </div>
+      </div>
+    </footer>
+  );
+};
+
+export default Footer;
diff --git a/PdfToPodcast/ui/src/components/layout/Header.jsx b/PdfToPodcast/ui/src/components/layout/Header.jsx
new file mode 100644
index 0000000000..fe71fbf172
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/layout/Header.jsx
@@ -0,0 +1,93 @@
+import { Link } from 'react-router-dom';
+import { Menu, X } from 'lucide-react';
+import { useState } from 'react';
+import { cn } from '@utils/helpers';
+
+export const Header = () => {
+  const [mobileMenuOpen, setMobileMenuOpen] = useState(false);
+
+  const navigation = [
+    { name: 'Home', href: '/' },
+    { name: 'Generate', href: '/generate' },
+    { name: 'Projects', href: '/projects' },
+    { name: 'Settings', href: '/settings' },
+  ];
+
+  return (
+    <header className="bg-white border-b border-gray-200 sticky top-0 z-40">
+      <nav className="container mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex justify-between items-center h-16">
+          {/* Logo */}
+          <Link to="/" className="flex items-center gap-2 hover:opacity-80 transition-opacity">
+            {/* Custom Logo - Replace src with your actual logo */}
+            <img
+              src="/app-logo.png"
+              alt="PDF to Podcast"
+              className="h-10 w-10 object-contain"
+              onError={(e) => {
+                // Fallback to gradient box if image not found
+                e.target.style.display = 'none';
+                e.target.nextSibling.style.display = 'flex';
+              }}
+            />
+            <div
+              className="bg-gradient-to-br from-primary-600 to-secondary-600 p-2 rounded-lg hidden"
+              style={{ display: 'none' }}
+            >
+              <div className="w-6 h-6 bg-white rounded" />
+            </div>
+            <span className="text-xl font-bold bg-gradient-to-r from-primary-600 to-secondary-600 bg-clip-text text-transparent">
+              PDF to Podcast
+            </span>
+          </Link>
+
+          {/* Desktop Navigation */}
+          <div className="hidden md:flex items-center gap-6">
+            {navigation.map((item) => (
+              <Link
+                key={item.name}
+                to={item.href}
+                className="text-gray-700 hover:text-primary-600 font-medium transition-colors"
+              >
+                {item.name}
+              </Link>
+            ))}
+          </div>
+
+          {/* Mobile menu button */}
+          <button
+            onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+            className="md:hidden p-2 rounded-lg hover:bg-gray-100"
+          >
+            {mobileMenuOpen ? (
+              <X className="w-6 h-6" />
+            ) : (
+              <Menu className="w-6 h-6" />
+            )}
+          </button>
+        </div>
+
+        {/* Mobile Navigation */}
+        <div
+          className={cn(
+            'md:hidden overflow-hidden transition-all duration-300',
+            mobileMenuOpen ? 'max-h-64 pb-4' : 'max-h-0'
+          )}
+        >
+          {navigation.map((item) => (
+            <Link
+              key={item.name}
+              to={item.href}
+              className="block py-2 text-gray-700 hover:text-primary-600 font-medium"
+              onClick={() => setMobileMenuOpen(false)}
+            >
+              {item.name}
+            </Link>
+          ))}
+        </div>
+      </nav>
+    </header>
+  );
+};
+
+export default Header;
diff --git a/PdfToPodcast/ui/src/components/layout/Layout.jsx b/PdfToPodcast/ui/src/components/layout/Layout.jsx
new file mode 100644
index 0000000000..55e0fe0cef
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/layout/Layout.jsx
@@ -0,0 +1,17 @@
+import { Outlet } from 'react-router-dom';
+import Header from './Header';
+import Footer from './Footer';
+
+export const Layout = () => {
+  return (
+    <div className="flex flex-col min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100">
+      <Header />
+      <main className="flex-1 container mx-auto px-4 sm:px-6 lg:px-8 py-8">
+        <Outlet />
+      </main>
+      <Footer />
+    </div>
+  );
+};
+
+export default Layout;
diff --git a/PdfToPodcast/ui/src/components/ui/Alert.jsx b/PdfToPodcast/ui/src/components/ui/Alert.jsx
new file mode 100644
index 0000000000..2d7413bc35
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Alert.jsx
@@ -0,0 +1,68 @@
+import { AlertCircle, CheckCircle, Info, XCircle, X } from 'lucide-react';
+import { cn } from '@utils/helpers';
+
+const variants = {
+  info: {
+    bg: 'bg-blue-50 border-blue-200',
+    icon: 'text-blue-600',
+    text: 'text-blue-800',
+    Icon: Info,
+  },
+  success: {
+    bg: 'bg-success-50 border-success-200',
+    icon: 'text-success-600',
+    text: 'text-success-800',
+    Icon: CheckCircle,
+  },
+  warning: {
+    bg: 'bg-warning-50 border-warning-200',
+    icon: 'text-warning-600',
+    text: 'text-warning-800',
+    Icon: AlertCircle,
+  },
+  error: {
+    bg: 'bg-error-50 border-error-200',
+    icon: 'text-error-600',
+    text: 'text-error-800',
+    Icon: XCircle,
+  },
+};
+
+export const Alert = ({
+  variant = 'info',
+  title,
+  message,
+  onClose,
+  className = '',
+}) => {
+  const config = variants[variant];
+  const Icon = config.Icon;
+
+  return (
+    <div
+      className={cn(
+        'p-4 rounded-lg border flex items-start gap-3',
+        config.bg,
+        className
+      )}
+    >
+      <Icon className={cn('w-5 h-5 flex-shrink-0 mt-0.5', config.icon)} />
+      <div className="flex-1">
+        {title && (
+          <h4 className={cn('font-medium mb-1', config.text)}>{title}</h4>
+        )}
+        {message && <p className={cn('text-sm', config.text)}>{message}</p>}
+      </div>
+      {onClose && (
+        <button
+          onClick={onClose}
+          className={cn('flex-shrink-0 hover:opacity-70', config.icon)}
+        >
+          <X className="w-4 h-4" />
+        </button>
+      )}
+    </div>
+  );
+};
+
+export default Alert;
diff --git a/PdfToPodcast/ui/src/components/ui/Button.jsx b/PdfToPodcast/ui/src/components/ui/Button.jsx
new file mode 100644
index 0000000000..56219a5010
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Button.jsx
@@ -0,0 +1,57 @@
+import { cn } from '@utils/helpers';
+import { Loader2 } from 'lucide-react';
+
+const variants = {
+  primary: 'bg-primary-600 hover:bg-primary-700 text-white',
+  secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-800',
+  outline: 'border-2 border-primary-600 text-primary-600 hover:bg-primary-50',
+  ghost: 'hover:bg-gray-100 text-gray-700',
+  danger: 'bg-error-500 hover:bg-error-600 text-white',
+  success: 'bg-success-500 hover:bg-success-600 text-white',
+};
+
+const sizes = {
+  sm: 'px-3 py-1.5 text-sm',
+  md: 'px-4 py-2',
+  lg: 'px-6 py-3 text-lg',
+  xl: 'px-8 py-4 text-xl',
+};
+
+export const Button = ({
+  children,
+  variant = 'primary',
+  size = 'md',
+  loading = false,
+  disabled = false,
+  icon = null,
+  iconPosition = 'left',
+  fullWidth = false,
+  className = '',
+  ...props
+}) => {
+  const Icon = icon;
+
+  return (
+    <button
+      className={cn(
+        'font-medium rounded-lg transition-all duration-200',
+        'focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-2',
+        'disabled:opacity-50 disabled:cursor-not-allowed',
+        'inline-flex items-center justify-center gap-2',
+        variants[variant],
+        sizes[size],
+        fullWidth && 'w-full',
+        className
+      )}
+      disabled={disabled || loading}
+      {...props}
+    >
+      {loading && <Loader2 className="w-4 h-4 animate-spin" />}
+      {!loading && Icon && iconPosition === 'left' && <Icon className="w-4 h-4" />}
+      {children}
+      {!loading && Icon && iconPosition === 'right' && <Icon className="w-4 h-4" />}
+    </button>
+  );
+};
+
+export default Button;
diff --git a/PdfToPodcast/ui/src/components/ui/Card.jsx b/PdfToPodcast/ui/src/components/ui/Card.jsx
new file mode 100644
index 0000000000..3d6940b0aa
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Card.jsx
@@ -0,0 +1,47 @@
+import { cn } from '@utils/helpers';
+
+export const Card = ({ children, className = '', ...props }) => {
+  return (
+    <div
+      className={cn(
+        'bg-white rounded-xl shadow-lg border border-gray-200',
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export const CardHeader = ({ children, className = '', ...props }) => {
+  return (
+    <div
+      className={cn('p-6 border-b border-gray-200', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export const CardBody = ({ children, className = '', ...props }) => {
+  return (
+    <div className={cn('p-6', className)} {...props}>
+      {children}
+    </div>
+  );
+};
+
+export const CardFooter = ({ children, className = '', ...props }) => {
+  return (
+    <div
+      className={cn('p-6 border-t border-gray-200 bg-gray-50', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};
+
+export default Card;
diff --git a/PdfToPodcast/ui/src/components/ui/Input.jsx b/PdfToPodcast/ui/src/components/ui/Input.jsx
new file mode 100644
index 0000000000..5a854bed1f
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Input.jsx
@@ -0,0 +1,55 @@
+import { cn } from '@utils/helpers';
+import { forwardRef } from 'react';
+
+export const Input = forwardRef(
+  (
+    {
+      label,
+      error,
+      helperText,
+      icon: Icon,
+      className = '',
+      containerClassName = '',
+      ...props
+    },
+    ref
+  ) => {
+    return (
+      <div className={cn('w-full', containerClassName)}>
+        {label && (
+          <label className="block text-sm font-medium text-gray-700 mb-2">
+            {label}
+          </label>
+        )}
+        <div className="relative">
+          {Icon && (
+            <div className="absolute left-3 top-1/2 transform -translate-y-1/2 text-gray-400">
+              <Icon className="w-5 h-5" />
+            </div>
+          )}
+          <input
+            ref={ref}
+            className={cn(
+              'w-full px-4 py-2 border rounded-lg',
+              'focus:outline-none focus:ring-2 focus:ring-primary-500 focus:border-transparent',
+              'disabled:bg-gray-100 disabled:cursor-not-allowed',
+              error && 'border-error-500 focus:ring-error-500',
+              !error && 'border-gray-300',
+              Icon && 'pl-10',
+              className
+            )}
+            {...props}
+          />
+        </div>
+        {error && <p className="mt-1 text-sm text-error-500">{error}</p>}
+        {!error && helperText && (
+          <p className="mt-1 text-sm text-gray-500">{helperText}</p>
+        )}
+      </div>
+    );
+  }
+);
+
+Input.displayName = 'Input';
+
+export default Input;
diff --git a/PdfToPodcast/ui/src/components/ui/Modal.jsx b/PdfToPodcast/ui/src/components/ui/Modal.jsx
new file mode 100644
index 0000000000..4d759471eb
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Modal.jsx
@@ -0,0 +1,80 @@
+import { useEffect } from 'react';
+import { X } from 'lucide-react';
+import { cn } from '@utils/helpers';
+import Button from './Button';
+
+export const Modal = ({
+  isOpen,
+  onClose,
+  title,
+  children,
+  footer,
+  size = 'md',
+  closeOnOverlayClick = true,
+}) => {
+  const sizes = {
+    sm: 'max-w-md',
+    md: 'max-w-2xl',
+    lg: 'max-w-4xl',
+    xl: 'max-w-6xl',
+    full: 'max-w-full mx-4',
+  };
+
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = 'hidden';
+    } else {
+      document.body.style.overflow = 'unset';
+    }
+
+    return () => {
+      document.body.style.overflow = 'unset';
+    };
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 overflow-y-auto">
+      <div className="flex min-h-screen items-center justify-center p-4">
+        {/* Overlay */}
+        <div
+          className="fixed inset-0 bg-black bg-opacity-50 transition-opacity"
+          onClick={closeOnOverlayClick ? onClose : undefined}
+        />
+
+        {/* Modal */}
+        <div
+          className={cn(
+            'relative bg-white rounded-xl shadow-xl w-full',
+            'transform transition-all',
+            sizes[size]
+          )}
+        >
+          {/* Header */}
+          <div className="flex items-center justify-between p-6 border-b border-gray-200">
+            <h3 className="text-xl font-semibold text-gray-900">{title}</h3>
+            <button
+              onClick={onClose}
+              className="text-gray-400 hover:text-gray-600 transition-colors"
+            >
+              <X className="w-6 h-6" />
+            </button>
+          </div>
+
+          {/* Body */}
+          <div className="p-6">{children}</div>
+
+          {/* Footer */}
+          {footer && (
+            <div className="flex items-center justify-end gap-3 p-6 border-t border-gray-200 bg-gray-50">
+              {footer}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default Modal;
diff --git a/PdfToPodcast/ui/src/components/ui/Progress.jsx b/PdfToPodcast/ui/src/components/ui/Progress.jsx
new file mode 100644
index 0000000000..0bc35b49e8
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Progress.jsx
@@ -0,0 +1,55 @@
+import { cn } from '@utils/helpers';
+
+export const Progress = ({
+  value = 0,
+  max = 100,
+  size = 'md',
+  color = 'primary',
+  showLabel = false,
+  className = '',
+}) => {
+  const percentage = Math.min(100, Math.max(0, (value / max) * 100));
+
+  const sizes = {
+    sm: 'h-2',
+    md: 'h-4',
+    lg: 'h-6',
+  };
+
+  const colors = {
+    primary: 'bg-primary-600',
+    success: 'bg-success-500',
+    warning: 'bg-warning-500',
+    error: 'bg-error-500',
+  };
+
+  return (
+    <div className="w-full">
+      {showLabel && (
+        <div className="flex justify-between items-center mb-2">
+          <span className="text-sm font-medium text-gray-700">Progress</span>
+          <span className="text-sm font-medium text-gray-700">
+            {Math.round(percentage)}%
+          </span>
+        </div>
+      )}
+      <div
+        className={cn(
+          'w-full bg-gray-200 rounded-full overflow-hidden',
+          sizes[size],
+          className
+        )}
+      >
+        <div
+          className={cn(
+            'h-full transition-all duration-500 ease-out rounded-full',
+            colors[color]
+          )}
+          style={{ width: `${percentage}%` }}
+        />
+      </div>
+    </div>
+  );
+};
+
+export default Progress;
diff --git a/PdfToPodcast/ui/src/components/ui/Spinner.jsx b/PdfToPodcast/ui/src/components/ui/Spinner.jsx
new file mode 100644
index 0000000000..78635ca527
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/Spinner.jsx
@@ -0,0 +1,34 @@
+import { Loader2 } from 'lucide-react';
+import { cn } from '@utils/helpers';
+
+export const Spinner = ({ size = 'md', className = '' }) => {
+  const sizes = {
+    sm: 'w-4 h-4',
+    md: 'w-8 h-8',
+    lg: 'w-12 h-12',
+    xl: 'w-16 h-16',
+  };
+
+  return (
+    <Loader2
+      className={cn(
+        'animate-spin text-primary-600',
+        sizes[size],
+        className
+      )}
+    />
+  );
+};
+
+export const SpinnerOverlay = ({ message = 'Loading...' }) => {
+  return (
+    <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50">
+      <div className="bg-white rounded-lg p-8 flex flex-col items-center gap-4">
+        <Spinner size="lg" />
+        <p className="text-gray-700 font-medium">{message}</p>
+      </div>
+    </div>
+  );
+};
+
+export default Spinner;
diff --git a/PdfToPodcast/ui/src/components/ui/StepIndicator.jsx b/PdfToPodcast/ui/src/components/ui/StepIndicator.jsx
new file mode 100644
index 0000000000..8a98f3115d
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/StepIndicator.jsx
@@ -0,0 +1,69 @@
+import { Check } from 'lucide-react';
+import { cn } from '@utils/helpers';
+
+export const StepIndicator = ({ steps, currentStep }) => {
+  return (
+    <div className="w-full py-8">
+      <div className="flex items-center justify-between">
+        {steps.map((step, index) => {
+          const stepNumber = index + 1;
+          const isCompleted = stepNumber < currentStep;
+          const isCurrent = stepNumber === currentStep;
+
+          return (
+            <div key={step.id} className="flex items-center flex-1">
+              {/* Step circle */}
+              <div className="flex flex-col items-center">
+                <div
+                  className={cn(
+                    'w-12 h-12 rounded-full flex items-center justify-center font-semibold transition-all',
+                    isCompleted &&
+                      'bg-success-500 text-white',
+                    isCurrent &&
+                      'bg-primary-600 text-white ring-4 ring-primary-100',
+                    !isCompleted &&
+                      !isCurrent &&
+                      'bg-gray-200 text-gray-600'
+                  )}
+                >
+                  {isCompleted ? (
+                    <Check className="w-6 h-6" />
+                  ) : (
+                    stepNumber
+                  )}
+                </div>
+                <div className="mt-2 text-center">
+                  <p
+                    className={cn(
+                      'text-sm font-medium',
+                      isCurrent ? 'text-primary-600' : 'text-gray-600'
+                    )}
+                  >
+                    {step.title}
+                  </p>
+                  {step.subtitle && (
+                    <p className="text-xs text-gray-500 mt-1">
+                      {step.subtitle}
+                    </p>
+                  )}
+                </div>
+              </div>
+
+              {/* Connector line */}
+              {index < steps.length - 1 && (
+                <div
+                  className={cn(
+                    'flex-1 h-1 mx-4 rounded transition-all',
+                    isCompleted ? 'bg-success-500' : 'bg-gray-200'
+                  )}
+                />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
+
+export default StepIndicator;
diff --git a/PdfToPodcast/ui/src/components/ui/index.js b/PdfToPodcast/ui/src/components/ui/index.js
new file mode 100644
index 0000000000..42ca41efd7
--- /dev/null
+++ b/PdfToPodcast/ui/src/components/ui/index.js
@@ -0,0 +1,8 @@
+export { Button } from './Button';
+export { Card, CardHeader, CardBody, CardFooter } from './Card';
+export { Input } from './Input';
+export { Progress } from './Progress';
+export { Spinner, SpinnerOverlay } from './Spinner';
+export { Modal } from './Modal';
+export { Alert } from './Alert';
+export { StepIndicator } from './StepIndicator';
diff --git a/PdfToPodcast/ui/src/hooks/index.js b/PdfToPodcast/ui/src/hooks/index.js
new file mode 100644
index 0000000000..7ee6ec995f
--- /dev/null
+++ b/PdfToPodcast/ui/src/hooks/index.js
@@ -0,0 +1,4 @@
+export { usePolling } from './usePolling';
+export { useAudioPlayer } from './useAudioPlayer';
+export { useWaveSurfer } from './useWaveSurfer';
+export { useDebounce } from './useDebounce';
diff --git a/PdfToPodcast/ui/src/hooks/useAudioPlayer.js b/PdfToPodcast/ui/src/hooks/useAudioPlayer.js
new file mode 100644
index 0000000000..6cfbc819d9
--- /dev/null
+++ b/PdfToPodcast/ui/src/hooks/useAudioPlayer.js
@@ -0,0 +1,122 @@
+import { useState, useRef, useEffect } from 'react';
+
+/**
+ * Custom hook for audio player functionality
+ * @param {string} audioUrl - URL of the audio file
+ */
+export const useAudioPlayer = (audioUrl) => {
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [volume, setVolume] = useState(1);
+  const [loading, setLoading] = useState(false);
+  const audioRef = useRef(null);
+
+  useEffect(() => {
+    if (!audioRef.current) {
+      audioRef.current = new Audio();
+    }
+
+    const audio = audioRef.current;
+
+    const handleLoadStart = () => setLoading(true);
+    const handleCanPlay = () => setLoading(false);
+    const handleLoadedMetadata = () => {
+      setDuration(audio.duration);
+    };
+    const handleTimeUpdate = () => {
+      setCurrentTime(audio.currentTime);
+    };
+    const handleEnded = () => {
+      setIsPlaying(false);
+      setCurrentTime(0);
+    };
+    const handleError = (e) => {
+      console.error('Audio error:', e);
+      setLoading(false);
+    };
+
+    audio.addEventListener('loadstart', handleLoadStart);
+    audio.addEventListener('canplay', handleCanPlay);
+    audio.addEventListener('loadedmetadata', handleLoadedMetadata);
+    audio.addEventListener('timeupdate', handleTimeUpdate);
+    audio.addEventListener('ended', handleEnded);
+    audio.addEventListener('error', handleError);
+
+    return () => {
+      audio.removeEventListener('loadstart', handleLoadStart);
+      audio.removeEventListener('canplay', handleCanPlay);
+      audio.removeEventListener('loadedmetadata', handleLoadedMetadata);
+      audio.removeEventListener('timeupdate', handleTimeUpdate);
+      audio.removeEventListener('ended', handleEnded);
+      audio.removeEventListener('error', handleError);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (audioRef.current && audioUrl) {
+      audioRef.current.src = audioUrl;
+      audioRef.current.load();
+    }
+  }, [audioUrl]);
+
+  const play = () => {
+    if (audioRef.current) {
+      audioRef.current.play();
+      setIsPlaying(true);
+    }
+  };
+
+  const pause = () => {
+    if (audioRef.current) {
+      audioRef.current.pause();
+      setIsPlaying(false);
+    }
+  };
+
+  const togglePlay = () => {
+    if (isPlaying) {
+      pause();
+    } else {
+      play();
+    }
+  };
+
+  const seek = (time) => {
+    if (audioRef.current) {
+      audioRef.current.currentTime = time;
+      setCurrentTime(time);
+    }
+  };
+
+  const changeVolume = (newVolume) => {
+    if (audioRef.current) {
+      const vol = Math.max(0, Math.min(1, newVolume));
+      audioRef.current.volume = vol;
+      setVolume(vol);
+    }
+  };
+
+  const skip = (seconds) => {
+    if (audioRef.current) {
+      const newTime = Math.max(0, Math.min(duration, currentTime + seconds));
+      seek(newTime);
+    }
+  };
+
+  return {
+    isPlaying,
+    currentTime,
+    duration,
+    volume,
+    loading,
+    play,
+    pause,
+    togglePlay,
+    seek,
+    changeVolume,
+    skip,
+  };
+};
+
+export default useAudioPlayer;
diff --git a/PdfToPodcast/ui/src/hooks/useDebounce.js b/PdfToPodcast/ui/src/hooks/useDebounce.js
new file mode 100644
index 0000000000..85160e69fa
--- /dev/null
+++ b/PdfToPodcast/ui/src/hooks/useDebounce.js
@@ -0,0 +1,24 @@
+import { useState, useEffect } from 'react';
+
+/**
+ * Custom hook for debouncing values
+ * @param {any} value - Value to debounce
+ * @param {number} delay - Delay in milliseconds
+ */
+export const useDebounce = (value, delay = 500) => {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+};
+
+export default useDebounce;
diff --git a/PdfToPodcast/ui/src/hooks/usePolling.js b/PdfToPodcast/ui/src/hooks/usePolling.js
new file mode 100644
index 0000000000..3687708ae1
--- /dev/null
+++ b/PdfToPodcast/ui/src/hooks/usePolling.js
@@ -0,0 +1,61 @@
+import { useEffect, useRef, useCallback } from 'react';
+
+/**
+ * Custom hook for polling an async function at regular intervals
+ * @param {Function} callback - Async function to poll
+ * @param {number} interval - Polling interval in milliseconds
+ * @param {boolean} enabled - Whether polling is enabled
+ * @param {Array} dependencies - Dependencies that should restart polling
+ */
+export const usePolling = (callback, interval = 2000, enabled = false, dependencies = []) => {
+  const savedCallback = useRef();
+  const timeoutId = useRef(null);
+
+  // Remember the latest callback
+  useEffect(() => {
+    savedCallback.current = callback;
+  }, [callback]);
+
+  // Set up the polling
+  useEffect(() => {
+    const tick = async () => {
+      if (savedCallback.current) {
+        try {
+          await savedCallback.current();
+        } catch (error) {
+          console.error('Polling error:', error);
+        }
+      }
+    };
+
+    if (enabled) {
+      // Execute immediately
+      tick();
+
+      // Then poll at interval
+      const id = setInterval(tick, interval);
+      timeoutId.current = id;
+
+      return () => {
+        if (timeoutId.current) {
+          clearInterval(timeoutId.current);
+        }
+      };
+    } else {
+      if (timeoutId.current) {
+        clearInterval(timeoutId.current);
+      }
+    }
+  }, [enabled, interval, ...dependencies]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutId.current) {
+        clearInterval(timeoutId.current);
+      }
+    };
+  }, []);
+};
+
+export default usePolling;
diff --git a/PdfToPodcast/ui/src/hooks/useWaveSurfer.js b/PdfToPodcast/ui/src/hooks/useWaveSurfer.js
new file mode 100644
index 0000000000..f57df120a8
--- /dev/null
+++ b/PdfToPodcast/ui/src/hooks/useWaveSurfer.js
@@ -0,0 +1,100 @@
+import { useEffect, useRef, useState } from 'react';
+import WaveSurfer from 'wavesurfer.js';
+
+/**
+ * Custom hook for WaveSurfer.js integration
+ * @param {string} containerRef - Ref to the container element
+ * @param {Object} options - WaveSurfer options
+ */
+export const useWaveSurfer = (containerRef, options = {}) => {
+  const wavesurferRef = useRef(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const wavesurfer = WaveSurfer.create({
+      container: containerRef.current,
+      waveColor: '#ddd',
+      progressColor: '#0284c7',
+      cursorColor: '#0ea5e9',
+      barWidth: 2,
+      barRadius: 3,
+      cursorWidth: 1,
+      height: 80,
+      barGap: 2,
+      ...options,
+    });
+
+    wavesurferRef.current = wavesurfer;
+
+    wavesurfer.on('ready', () => {
+      setDuration(wavesurfer.getDuration());
+    });
+
+    wavesurfer.on('audioprocess', () => {
+      setCurrentTime(wavesurfer.getCurrentTime());
+    });
+
+    wavesurfer.on('play', () => {
+      setIsPlaying(true);
+    });
+
+    wavesurfer.on('pause', () => {
+      setIsPlaying(false);
+    });
+
+    wavesurfer.on('finish', () => {
+      setIsPlaying(false);
+      setCurrentTime(0);
+    });
+
+    return () => {
+      wavesurfer.destroy();
+    };
+  }, [containerRef, options]);
+
+  const play = () => {
+    wavesurferRef.current?.play();
+  };
+
+  const pause = () => {
+    wavesurferRef.current?.pause();
+  };
+
+  const playPause = () => {
+    wavesurferRef.current?.playPause();
+  };
+
+  const seekTo = (progress) => {
+    wavesurferRef.current?.seekTo(progress);
+  };
+
+  const load = (url) => {
+    wavesurferRef.current?.load(url);
+  };
+
+  const loadBlob = (blob) => {
+    if (wavesurferRef.current) {
+      const url = URL.createObjectURL(blob);
+      wavesurferRef.current.load(url);
+    }
+  };
+
+  return {
+    wavesurfer: wavesurferRef.current,
+    isPlaying,
+    currentTime,
+    duration,
+    play,
+    pause,
+    playPause,
+    seekTo,
+    load,
+    loadBlob,
+  };
+};
+
+export default useWaveSurfer;
diff --git a/PdfToPodcast/ui/src/index.css b/PdfToPodcast/ui/src/index.css
new file mode 100644
index 0000000000..77162cfb75
--- /dev/null
+++ b/PdfToPodcast/ui/src/index.css
@@ -0,0 +1,117 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-text-size-adjust: 100%;
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+}
+
+#root {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: #f1f1f1;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #888;
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #555;
+}
+
+/* Animations */
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes slideUp {
+  from {
+    transform: translateY(20px);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+
+@keyframes slideDown {
+  from {
+    transform: translateY(-20px);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+
+.animate-fade-in {
+  animation: fadeIn 0.5s ease-in-out;
+}
+
+.animate-slide-up {
+  animation: slideUp 0.5s ease-out;
+}
+
+.animate-slide-down {
+  animation: slideDown 0.5s ease-out;
+}
+
+/* React Hot Toast Customization */
+.react-hot-toast {
+  font-family: inherit;
+}
+
+/* Component Styles */
+@layer components {
+  .card {
+    @apply bg-white rounded-xl p-6 shadow-lg;
+  }
+
+  .btn-primary {
+    @apply bg-primary-600 hover:bg-primary-700 text-white font-medium px-6 py-2.5 rounded-lg transition-colors duration-200 disabled:opacity-50 disabled:cursor-not-allowed;
+  }
+
+  .btn-secondary {
+    @apply bg-gray-100 hover:bg-gray-200 text-gray-700 font-medium px-6 py-2.5 rounded-lg transition-colors duration-200 disabled:opacity-50 disabled:cursor-not-allowed;
+  }
+}
diff --git a/PdfToPodcast/ui/src/main.jsx b/PdfToPodcast/ui/src/main.jsx
new file mode 100644
index 0000000000..7497ae8653
--- /dev/null
+++ b/PdfToPodcast/ui/src/main.jsx
@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App.jsx';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
diff --git a/PdfToPodcast/ui/src/pages/Generate.jsx b/PdfToPodcast/ui/src/pages/Generate.jsx
new file mode 100644
index 0000000000..9438946dbb
--- /dev/null
+++ b/PdfToPodcast/ui/src/pages/Generate.jsx
@@ -0,0 +1,157 @@
+import { useEffect } from 'react';
+import { useDispatch, useSelector } from 'react-redux';
+import { setCurrentStep, nextStep, previousStep } from '@store/slices/uiSlice';
+import { pollScriptStatus } from '@store/slices/scriptSlice';
+import { pollAudioStatus, generateAudio } from '@store/slices/audioSlice';
+import { resetUpload } from '@store/slices/uploadSlice';
+import { resetScript } from '@store/slices/scriptSlice';
+import { resetAudio } from '@store/slices/audioSlice';
+import { resetUI } from '@store/slices/uiSlice';
+import { usePolling } from '@hooks/usePolling';
+
+import { StepIndicator } from '@components/ui';
+import PDFUploader from '@components/features/PDFUploader';
+import VoiceSelector from '@components/features/VoiceSelector';
+import ProgressTracker from '@components/features/ProgressTracker';
+import ScriptEditor from '@components/features/ScriptEditor';
+import AudioPlayer from '@components/features/AudioPlayer';
+
+const steps = [
+  { id: 1, title: 'Upload PDF', subtitle: 'Select your document' },
+  { id: 2, title: 'Choose Voices', subtitle: 'Pick AI voices' },
+  { id: 3, title: 'Review Script', subtitle: 'Edit conversation' },
+  { id: 4, title: 'Generate Audio', subtitle: 'Download podcast' },
+];
+
+export const Generate = () => {
+  const dispatch = useDispatch();
+  const currentStep = useSelector((state) => state.ui.currentStep);
+  const { jobId } = useSelector((state) => state.upload);
+  const {
+    script,
+    generating: scriptGenerating,
+    generationProgress: scriptProgress,
+    statusMessage: scriptMessage,
+  } = useSelector((state) => state.script);
+  const {
+    audioUrl,
+    generating: audioGenerating,
+    generationProgress: audioProgress,
+    statusMessage: audioMessage,
+  } = useSelector((state) => state.audio);
+
+  // Poll for script status
+  usePolling(
+    () => {
+      if (jobId) {
+        return dispatch(pollScriptStatus(jobId));
+      }
+    },
+    2000,
+    scriptGenerating && !script,
+    [jobId, scriptGenerating, script]
+  );
+
+  // Poll for audio status
+  usePolling(
+    () => {
+      if (jobId) {
+        return dispatch(pollAudioStatus(jobId));
+      }
+    },
+    2000,
+    audioGenerating && !audioUrl,
+    [jobId, audioGenerating, audioUrl]
+  );
+
+  // Move to next step when script is generated
+  useEffect(() => {
+    if (script && scriptGenerating === false && currentStep === 2) {
+      dispatch(setCurrentStep(3));
+    }
+  }, [script, scriptGenerating, currentStep, dispatch]);
+
+  // Move to next step when audio is generated
+  useEffect(() => {
+    if (audioUrl && audioGenerating === false && currentStep === 3) {
+      dispatch(setCurrentStep(4));
+    }
+  }, [audioUrl, audioGenerating, currentStep, dispatch]);
+
+  const handleUploadSuccess = () => {
+    dispatch(nextStep());
+  };
+
+  const handleVoiceNext = () => {
+    // Script generation will be triggered by VoiceSelector component
+    // Progress tracker will be shown automatically
+  };
+
+  const handleScriptNext = async () => {
+    if (jobId) {
+      await dispatch(generateAudio(jobId));
+    }
+  };
+
+  const handleReset = () => {
+    dispatch(resetUpload());
+    dispatch(resetScript());
+    dispatch(resetAudio());
+    dispatch(resetUI());
+  };
+
+  return (
+    <div className="max-w-4xl mx-auto space-y-8">
+      <div>
+        <h1 className="text-3xl font-bold text-gray-900 mb-2">
+          Generate Your Podcast
+        </h1>
+        <p className="text-gray-600">
+          Follow the steps below to create your AI-powered podcast
+        </p>
+      </div>
+
+      <StepIndicator steps={steps} currentStep={currentStep} />
+
+      <div className="animate-fade-in">
+        {currentStep === 1 && (
+          <PDFUploader onSuccess={handleUploadSuccess} />
+        )}
+
+        {currentStep === 2 && !scriptGenerating && (
+          <VoiceSelector
+            onBack={() => dispatch(previousStep())}
+            onNext={handleVoiceNext}
+          />
+        )}
+
+        {scriptGenerating && !script && (
+          <ProgressTracker
+            progress={scriptProgress}
+            message={scriptMessage || 'Generating podcast script...'}
+          />
+        )}
+
+        {currentStep === 3 && script && !audioGenerating && (
+          <ScriptEditor
+            onBack={() => dispatch(setCurrentStep(2))}
+            onNext={handleScriptNext}
+          />
+        )}
+
+        {audioGenerating && !audioUrl && (
+          <ProgressTracker
+            progress={audioProgress}
+            message={audioMessage || 'Generating podcast audio...'}
+          />
+        )}
+
+        {currentStep === 4 && audioUrl && (
+          <AudioPlayer onReset={handleReset} />
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default Generate;
diff --git a/PdfToPodcast/ui/src/pages/Home.jsx b/PdfToPodcast/ui/src/pages/Home.jsx
new file mode 100644
index 0000000000..659340a1a7
--- /dev/null
+++ b/PdfToPodcast/ui/src/pages/Home.jsx
@@ -0,0 +1,169 @@
+import { Link } from 'react-router-dom';
+import { Upload, Sparkles, Download, ArrowRight } from 'lucide-react';
+import { Button } from '@components/ui';
+
+export const Home = () => {
+  const features = [
+    {
+      icon: Upload,
+      title: 'Easy Upload',
+      description: 'Simply drag and drop your PDF document to get started',
+    },
+    {
+      icon: Sparkles,
+      title: 'AI-Powered',
+      description: 'Advanced AI creates natural, engaging podcast conversations',
+    },
+    {
+      icon: Download,
+      title: 'Multiple Voices',
+      description: 'Choose from 6 professional AI voices for host and guest',
+    },
+    {
+      icon: Download,
+      title: 'Download & Share',
+      description: 'Get high-quality MP3 audio ready to share anywhere',
+    },
+  ];
+
+  const steps = [
+    {
+      number: 1,
+      title: 'Upload PDF',
+      description: 'Upload your PDF document (max 10MB)',
+    },
+    {
+      number: 2,
+      title: 'Select Voices',
+      description: 'Choose AI voices for host and guest',
+    },
+    {
+      number: 3,
+      title: 'Review Script',
+      description: 'Edit the generated conversation if needed',
+    },
+    {
+      number: 4,
+      title: 'Download',
+      description: 'Get your podcast audio file',
+    },
+  ];
+
+  return (
+    <div className="space-y-16">
+      {/* Hero Section */}
+      <section className="text-center space-y-6 py-12">
+        <div className="inline-block">
+          {/* Custom Hero Image - Replace src with your actual image */}
+          <img
+            src="/hero-image.png"
+            alt="PDF to Podcast"
+            className="w-48 h-48 object-contain mx-auto mb-6"
+            onError={(e) => {
+              // Fallback to gradient box if image not found
+              e.target.style.display = 'none';
+              e.target.nextSibling.style.display = 'inline-block';
+            }}
+          />
+          <div
+            className="bg-gradient-to-br from-primary-600 to-secondary-600 p-4 rounded-2xl mb-6 shadow-xl"
+            style={{ display: 'none' }}
+          >
+            <div className="w-40 h-40 bg-white rounded-lg" />
+          </div>
+        </div>
+
+        <h1 className="text-5xl md:text-6xl font-bold text-gray-900 leading-tight">
+          Transform PDFs into
+          <br />
+          <span className="bg-gradient-to-r from-primary-600 to-secondary-600 bg-clip-text text-transparent">
+            Engaging Podcasts
+          </span>
+        </h1>
+
+        <p className="text-xl text-gray-600 max-w-2xl mx-auto">
+          Turn any PDF document into a natural, AI-powered podcast conversation
+          in minutes. Perfect for learning, content creation, and accessibility.
+        </p>
+
+        <div className="flex flex-col sm:flex-row gap-4 justify-center pt-4">
+          <Link to="/generate">
+            <Button size="xl" icon={ArrowRight} iconPosition="right">
+              Get Started
+            </Button>
+          </Link>
+          <Link to="/projects">
+            <Button size="xl" variant="outline">
+              View Projects
+            </Button>
+          </Link>
+        </div>
+      </section>
+
+      {/* Features */}
+      <section>
+        <h2 className="text-3xl font-bold text-center text-gray-900 mb-12">
+          Why Choose PDF to Podcast?
+        </h2>
+        <div className="grid md:grid-cols-2 lg:grid-cols-4 gap-8">
+          {features.map((feature, index) => (
+            <div
+              key={index}
+              className="bg-white rounded-xl p-6 shadow-lg hover:shadow-xl transition-shadow"
+            >
+              <div className="bg-primary-100 w-12 h-12 rounded-lg flex items-center justify-center mb-4">
+                <feature.icon className="w-6 h-6 text-primary-600" />
+              </div>
+              <h3 className="text-xl font-semibold text-gray-900 mb-2">
+                {feature.title}
+              </h3>
+              <p className="text-gray-600">{feature.description}</p>
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* How It Works */}
+      <section>
+        <h2 className="text-3xl font-bold text-center text-gray-900 mb-12">
+          How It Works
+        </h2>
+        <div className="grid md:grid-cols-4 gap-8">
+          {steps.map((step, index) => (
+            <div key={index} className="relative">
+              <div className="flex flex-col items-center text-center">
+                <div className="w-16 h-16 bg-gradient-to-br from-primary-600 to-secondary-600 rounded-full flex items-center justify-center text-white text-2xl font-bold mb-4 shadow-lg">
+                  {step.number}
+                </div>
+                <h3 className="text-xl font-semibold text-gray-900 mb-2">
+                  {step.title}
+                </h3>
+                <p className="text-gray-600">{step.description}</p>
+              </div>
+              {index < steps.length - 1 && (
+                <div className="hidden md:block absolute top-8 left-1/2 w-full h-0.5 bg-gradient-to-r from-primary-600 to-secondary-600 opacity-30" />
+              )}
+            </div>
+          ))}
+        </div>
+      </section>
+
+      {/* CTA */}
+      <section className="bg-gradient-to-r from-primary-600 to-secondary-600 rounded-2xl p-12 text-center text-white shadow-xl">
+        <h2 className="text-3xl font-bold mb-4">
+          Ready to Create Your First Podcast?
+        </h2>
+        <p className="text-xl mb-8 opacity-90">
+          Get started in less than 5 minutes. No sign-up required.
+        </p>
+        <Link to="/generate">
+          <Button size="xl" variant="secondary">
+            Start Generating Now
+          </Button>
+        </Link>
+      </section>
+    </div>
+  );
+};
+
+export default Home;
diff --git a/PdfToPodcast/ui/src/pages/PodcastGenerator.jsx b/PdfToPodcast/ui/src/pages/PodcastGenerator.jsx
new file mode 100644
index 0000000000..a668ab555f
--- /dev/null
+++ b/PdfToPodcast/ui/src/pages/PodcastGenerator.jsx
@@ -0,0 +1,273 @@
+import { useState, useEffect } from 'react';
+import toast from 'react-hot-toast';
+import FileUpload from '../components/FileUpload';
+import VoiceSelector from '../components/VoiceSelector';
+import ProgressTracker from '../components/ProgressTracker';
+import ScriptEditor from '../components/ScriptEditor';
+import AudioPlayer from '../components/AudioPlayer';
+import { uploadPDF, getVoices, generateScript, generateAudio, getJobStatus } from '../services/api';
+
+const PodcastGenerator = () => {
+  const [step, setStep] = useState(1); // 1: Upload, 2: Voice Selection, 3: Generating, 4: Script Edit, 5: Audio
+  const [jobId, setJobId] = useState(null);
+  const [pdfFile, setPdfFile] = useState(null);
+  const [voices, setVoices] = useState([]);
+  const [hostVoice, setHostVoice] = useState('alloy');
+  const [guestVoice, setGuestVoice] = useState('echo');
+  const [script, setScript] = useState(null);
+  const [progress, setProgress] = useState(0);
+  const [progressMessage, setProgressMessage] = useState('');
+  const [audioUrl, setAudioUrl] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
+
+  useEffect(() => {
+    fetchVoices();
+  }, []);
+
+  const fetchVoices = async () => {
+    try {
+      const voicesData = await getVoices();
+      setVoices(voicesData.voices);
+    } catch (error) {
+      toast.error('Failed to load voices');
+      console.error(error);
+    }
+  };
+
+  const handleFileUpload = async (file) => {
+    try {
+      setIsLoading(true);
+      setPdfFile(file);
+      const response = await uploadPDF(file);
+      setJobId(response.job_id);
+      setStep(2);
+      toast.success('PDF uploaded successfully!');
+    } catch (error) {
+      toast.error(error.response?.data?.detail || 'Failed to upload PDF');
+      console.error(error);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  const handleGenerateScript = async () => {
+    // Prevent duplicate calls
+    if (isLoading) {
+      console.log('Script generation already in progress, ignoring duplicate call');
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setStep(3);
+      setProgress(10);
+      setProgressMessage('Analyzing PDF content...');
+
+      await generateScript(jobId, hostVoice, guestVoice);
+
+      // Poll for script generation status with error tolerance
+      let errorCount = 0;
+      const MAX_ERRORS = 3;
+      const pollInterval = setInterval(async () => {
+        try {
+          const status = await getJobStatus(jobId);
+          console.log('Script generation status:', status);
+          console.log('Status value:', status.status);
+          console.log('Script present:', !!status.script);
+
+          // Reset error count on successful poll
+          errorCount = 0;
+
+          setProgress(status.progress || 0);
+          setProgressMessage(status.status_message || 'Generating script...');
+
+          if (status.status === 'script_generated') {
+            console.log('Moving to step 4 - Script Editor');
+            clearInterval(pollInterval);
+            setScript(status.script);
+            setStep(4);
+            setIsLoading(false);
+            toast.success('Script generated successfully!');
+          } else if (status.status === 'failed') {
+            clearInterval(pollInterval);
+            setIsLoading(false);
+            toast.error(status.error_message || 'Script generation failed');
+            setStep(2);
+          }
+        } catch (error) {
+          console.error('Polling error:', error);
+          errorCount++;
+
+          // Only stop polling after multiple consecutive errors
+          if (errorCount >= MAX_ERRORS) {
+            console.error('Max polling errors reached, stopping');
+            clearInterval(pollInterval);
+            setIsLoading(false);
+            toast.error('Failed to check status');
+            setStep(2);
+          }
+        }
+      }, 2000);
+    } catch (error) {
+      setIsLoading(false);
+      toast.error(error.response?.data?.detail || 'Failed to generate script');
+      console.error(error);
+      setStep(2);
+    }
+  };
+
+  const handleGenerateAudio = async () => {
+    // Prevent duplicate calls
+    if (isLoading) {
+      console.log('Audio generation already in progress, ignoring duplicate call');
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setStep(3);
+      setProgress(10);
+      setProgressMessage('Generating audio...');
+
+      // Send the current (possibly edited) script to backend
+      await generateAudio(jobId, script);
+
+      // Poll for audio generation status with error tolerance
+      let errorCount = 0;
+      const MAX_ERRORS = 3;
+      const pollInterval = setInterval(async () => {
+        try {
+          const status = await getJobStatus(jobId);
+          console.log('Audio generation status:', status);
+
+          // Reset error count on successful poll
+          errorCount = 0;
+
+          setProgress(status.progress || 0);
+          setProgressMessage(status.status_message || 'Creating podcast audio...');
+
+          if (status.status === 'completed' || status.status === 'audio_generated') {
+            clearInterval(pollInterval);
+
+            // Check if audio URL exists
+            if (!status.audio_url) {
+              console.error('Audio completed but no audio_url provided:', status);
+              setIsLoading(false);
+              toast.error('Audio generation completed but no audio file available');
+              setStep(4);
+              return;
+            }
+
+            // Convert relative URL to absolute URL
+            const apiBaseUrl = import.meta.env.VITE_API_URL || 'http://localhost:8000';
+            const fullAudioUrl = status.audio_url.startsWith('http')
+              ? status.audio_url
+              : `${apiBaseUrl}${status.audio_url}`;
+            console.log('Setting audio URL:', fullAudioUrl);
+
+            setAudioUrl(fullAudioUrl);
+            setStep(5);
+            setIsLoading(false);
+            toast.success('Podcast generated successfully!');
+          } else if (status.status === 'failed') {
+            clearInterval(pollInterval);
+            setIsLoading(false);
+            toast.error(status.error_message || 'Audio generation failed');
+            setStep(4);
+          }
+        } catch (error) {
+          console.error('Polling error:', error);
+          errorCount++;
+
+          // Only stop polling after multiple consecutive errors
+          if (errorCount >= MAX_ERRORS) {
+            console.error('Max polling errors reached, stopping');
+            clearInterval(pollInterval);
+            setIsLoading(false);
+            toast.error('Failed to check status');
+            setStep(4);
+          }
+        }
+      }, 2000);
+    } catch (error) {
+      setIsLoading(false);
+      toast.error(error.response?.data?.detail || 'Failed to generate audio');
+      console.error(error);
+      setStep(4);
+    }
+  };
+
+  const handleReset = () => {
+    setStep(1);
+    setJobId(null);
+    setPdfFile(null);
+    setScript(null);
+    setProgress(0);
+    setProgressMessage('');
+    setAudioUrl(null);
+    setHostVoice('alloy');
+    setGuestVoice('echo');
+  };
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <div className="max-w-4xl mx-auto">
+        <header className="text-center mb-8">
+          <h1 className="text-4xl font-bold text-gray-800 mb-2">
+            PDF to Podcast Generator
+          </h1>
+          <p className="text-gray-600">
+            Transform your PDF documents into engaging podcast conversations
+          </p>
+        </header>
+
+        {step === 1 && (
+          <FileUpload onFileUpload={handleFileUpload} isLoading={isLoading} />
+        )}
+
+        {step === 2 && (
+          <VoiceSelector
+            voices={voices}
+            hostVoice={hostVoice}
+            guestVoice={guestVoice}
+            onHostVoiceChange={setHostVoice}
+            onGuestVoiceChange={setGuestVoice}
+            onGenerate={handleGenerateScript}
+            isLoading={isLoading}
+            onBack={() => setStep(1)}
+          />
+        )}
+
+        {step === 3 && (
+          <ProgressTracker
+            progress={progress}
+            message={progressMessage}
+          />
+        )}
+
+        {step === 4 && script && (
+          <ScriptEditor
+            script={script}
+            onScriptChange={setScript}
+            onGenerate={handleGenerateAudio}
+            isLoading={isLoading}
+            onBack={() => setStep(2)}
+          />
+        )}
+
+        {step === 5 && audioUrl && (
+          <AudioPlayer
+            audioUrl={audioUrl}
+            jobId={jobId}
+            onReset={handleReset}
+            pdfName={pdfFile?.name}
+            hostVoice={hostVoice}
+            guestVoice={guestVoice}
+          />
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default PodcastGenerator;
diff --git a/PdfToPodcast/ui/src/pages/Projects.jsx b/PdfToPodcast/ui/src/pages/Projects.jsx
new file mode 100644
index 0000000000..96a13d8ba7
--- /dev/null
+++ b/PdfToPodcast/ui/src/pages/Projects.jsx
@@ -0,0 +1,141 @@
+import { useState, useEffect } from 'react';
+import { Link } from 'react-router-dom';
+import { FileAudio, Clock, Download, Trash2, Plus, FolderOpen } from 'lucide-react';
+
+const Projects = () => {
+  const [projects, setProjects] = useState([]);
+
+  useEffect(() => {
+    loadProjects();
+  }, []);
+
+  const loadProjects = () => {
+    const saved = JSON.parse(localStorage.getItem('podcastProjects') || '[]');
+    setProjects(saved);
+  };
+
+  const handleDelete = (id) => {
+    if (window.confirm('Are you sure you want to delete this project?')) {
+      const updated = projects.filter(p => p.id !== id);
+      localStorage.setItem('podcastProjects', JSON.stringify(updated));
+      setProjects(updated);
+    }
+  };
+
+  const formatDate = (dateString) => {
+    const date = new Date(dateString);
+    const now = new Date();
+    const diffMs = now - date;
+    const diffMins = Math.floor(diffMs / 60000);
+    const diffHours = Math.floor(diffMs / 3600000);
+    const diffDays = Math.floor(diffMs / 86400000);
+
+    if (diffMins < 1) return 'Just now';
+    if (diffMins < 60) return `${diffMins} minute${diffMins !== 1 ? 's' : ''} ago`;
+    if (diffHours < 24) return `${diffHours} hour${diffHours !== 1 ? 's' : ''} ago`;
+    if (diffDays < 7) return `${diffDays} day${diffDays !== 1 ? 's' : ''} ago`;
+
+    return date.toLocaleDateString('en-US', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric'
+    });
+  };
+
+  return (
+    <div className="max-w-6xl mx-auto space-y-8">
+      <div className="flex justify-between items-center">
+        <div>
+          <h1 className="text-3xl font-bold text-gray-900 mb-2">
+            My Projects
+          </h1>
+          <p className="text-gray-600">
+            View and manage your recent podcast projects
+          </p>
+        </div>
+        <Link to="/generate">
+          <button className="btn-primary flex items-center gap-2">
+            <Plus className="w-5 h-5" />
+            New Project
+          </button>
+        </Link>
+      </div>
+
+      {projects.length === 0 ? (
+        <div className="card text-center py-16">
+          <FolderOpen className="w-20 h-20 text-gray-300 mx-auto mb-4" />
+          <h3 className="text-xl font-semibold text-gray-700 mb-2">
+            No projects yet
+          </h3>
+          <p className="text-gray-500 mb-6">
+            Create your first podcast project to get started
+          </p>
+          <Link to="/generate">
+            <button className="btn-primary inline-flex items-center gap-2">
+              <Plus className="w-5 h-5" />
+              Create Project
+            </button>
+          </Link>
+        </div>
+      ) : (
+        <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6">
+          {projects.map((project) => (
+            <div
+              key={project.id}
+              className="card hover:shadow-xl transition-shadow"
+            >
+              <div className="flex items-start justify-between mb-4">
+                <div className="bg-primary-100 p-3 rounded-lg">
+                  <FileAudio className="w-8 h-8 text-primary-600" />
+                </div>
+                <span className="px-3 py-1 text-xs font-medium rounded-full bg-success-100 text-success-700">
+                  {project.status}
+                </span>
+              </div>
+
+              <h3 className="font-semibold text-gray-900 mb-2 truncate text-lg">
+                {project.pdfName}
+              </h3>
+
+              <div className="flex items-center gap-2 text-sm text-gray-500 mb-4">
+                <Clock className="w-4 h-4" />
+                {formatDate(project.createdAt)}
+              </div>
+
+              <div className="text-sm text-gray-600 mb-4">
+                <div className="flex justify-between">
+                  <span>Host:</span>
+                  <span className="font-medium capitalize">{project.hostVoice}</span>
+                </div>
+                <div className="flex justify-between">
+                  <span>Guest:</span>
+                  <span className="font-medium capitalize">{project.guestVoice}</span>
+                </div>
+              </div>
+
+              <div className="flex gap-2 pt-4 border-t border-gray-100">
+                <a
+                  href={project.audioUrl}
+                  download
+                  className="btn-primary flex-1 flex items-center justify-center gap-2"
+                >
+                  <Download className="w-4 h-4" />
+                  Download
+                </a>
+                <button
+                  onClick={() => handleDelete(project.id)}
+                  className="btn-secondary p-3"
+                  title="Delete project"
+                >
+                  <Trash2 className="w-4 h-4 text-error-600" />
+                </button>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default Projects;
diff --git a/PdfToPodcast/ui/src/pages/Settings.jsx b/PdfToPodcast/ui/src/pages/Settings.jsx
new file mode 100644
index 0000000000..fe7a08fd4b
--- /dev/null
+++ b/PdfToPodcast/ui/src/pages/Settings.jsx
@@ -0,0 +1,125 @@
+import { useState } from 'react';
+import { Save, Info } from 'lucide-react';
+
+const Settings = () => {
+  const [apiKey, setApiKey] = useState('');
+  const [saved, setSaved] = useState(false);
+
+  const handleSave = () => {
+    localStorage.setItem('openai_api_key', apiKey);
+    setSaved(true);
+    setTimeout(() => setSaved(false), 3000);
+  };
+
+  return (
+    <div className="max-w-4xl mx-auto space-y-8">
+      <div>
+        <h1 className="text-3xl font-bold text-gray-900 mb-2">Settings</h1>
+        <p className="text-gray-600">Configure your podcast generator settings</p>
+      </div>
+
+      <div className="card space-y-6">
+        <h2 className="text-xl font-semibold text-gray-900">API Configuration</h2>
+
+        <div className="bg-blue-50 border border-blue-200 rounded-lg p-4 flex gap-3">
+          <Info className="w-5 h-5 text-blue-600 flex-shrink-0 mt-0.5" />
+          <div>
+            <p className="font-medium text-blue-900">OpenAI API Key</p>
+            <p className="text-sm text-blue-700">
+              Your API key is used to generate scripts and audio. It's stored locally in your browser.
+            </p>
+          </div>
+        </div>
+
+        <div className="space-y-2">
+          <label htmlFor="apiKey" className="block text-sm font-medium text-gray-700">
+            OpenAI API Key
+          </label>
+          <input
+            id="apiKey"
+            type="password"
+            value={apiKey}
+            onChange={(e) => setApiKey(e.target.value)}
+            placeholder="sk-..."
+            className="w-full px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-primary-500"
+          />
+          <p className="text-sm text-gray-500">
+            Get your API key from{' '}
+            <a
+              href="https://platform.openai.com"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-primary-600 hover:underline"
+            >
+              platform.openai.com
+            </a>
+          </p>
+        </div>
+
+        {saved && (
+          <div className="bg-success-50 border border-success-200 rounded-lg p-4 text-success-800">
+            Settings saved successfully!
+          </div>
+        )}
+
+        <button onClick={handleSave} className="btn-primary inline-flex items-center gap-2">
+          <Save className="w-4 h-4" />
+          Save Settings
+        </button>
+      </div>
+
+      <div className="card space-y-6">
+        <h2 className="text-xl font-semibold text-gray-900">Preferences</h2>
+
+        <div className="space-y-4">
+          <div className="flex items-center justify-between p-4 bg-gray-50 rounded-lg">
+            <div>
+              <p className="font-medium text-gray-900">Default Host Voice</p>
+              <p className="text-sm text-gray-600">Choose your preferred host voice</p>
+            </div>
+            <select className="border border-gray-300 rounded-lg px-4 py-2 focus:outline-none focus:ring-2 focus:ring-primary-500">
+              <option>Alloy</option>
+              <option>Echo</option>
+              <option>Fable</option>
+              <option>Onyx</option>
+              <option>Nova</option>
+              <option>Shimmer</option>
+            </select>
+          </div>
+
+          <div className="flex items-center justify-between p-4 bg-gray-50 rounded-lg">
+            <div>
+              <p className="font-medium text-gray-900">Default Guest Voice</p>
+              <p className="text-sm text-gray-600">Choose your preferred guest voice</p>
+            </div>
+            <select className="border border-gray-300 rounded-lg px-4 py-2 focus:outline-none focus:ring-2 focus:ring-primary-500">
+              <option>Echo</option>
+              <option>Alloy</option>
+              <option>Fable</option>
+              <option>Onyx</option>
+              <option>Nova</option>
+              <option>Shimmer</option>
+            </select>
+          </div>
+        </div>
+      </div>
+
+      <div className="card space-y-4">
+        <h2 className="text-xl font-semibold text-gray-900">About</h2>
+
+        <div className="space-y-3 text-gray-600">
+          <p>
+            <strong className="text-gray-900">Version:</strong> 1.0.0
+          </p>
+
+          <p>
+            <strong className="text-gray-900">Description:</strong> Transform your PDF documents
+            into engaging podcast conversations using AI
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default Settings;
diff --git a/PdfToPodcast/ui/src/services/api.js b/PdfToPodcast/ui/src/services/api.js
new file mode 100644
index 0000000000..01de0ce23c
--- /dev/null
+++ b/PdfToPodcast/ui/src/services/api.js
@@ -0,0 +1,174 @@
+import axios from 'axios';
+
+const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000';
+
+// Create axios instance
+const apiClient = axios.create({
+  baseURL: API_BASE_URL,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  timeout: 300000, // 5 minutes for long-running operations
+});
+
+// Request interceptor
+apiClient.interceptors.request.use(
+  (config) => {
+    // Add auth token if available
+    const token = localStorage.getItem('auth_token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  },
+  (error) => Promise.reject(error)
+);
+
+// Response interceptor
+apiClient.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      // Handle unauthorized
+      localStorage.removeItem('auth_token');
+      window.location.href = '/';
+    }
+    return Promise.reject(error);
+  }
+);
+
+// Upload API
+export const uploadAPI = {
+  uploadFile: (file, onProgress) => {
+    const formData = new FormData();
+    formData.append('file', file);
+
+    return apiClient.post('/api/upload', formData, {
+      headers: {
+        'Content-Type': 'multipart/form-data',
+      },
+      onUploadProgress: (progressEvent) => {
+        const percentCompleted = Math.round(
+          (progressEvent.loaded * 100) / progressEvent.total
+        );
+        if (onProgress) onProgress(percentCompleted);
+      },
+    });
+  },
+};
+
+// Script API
+export const scriptAPI = {
+  generate: (jobId, hostVoice, guestVoice) => {
+    return apiClient.post('/api/generate-script', {
+      job_id: jobId,
+      host_voice: hostVoice,
+      guest_voice: guestVoice,
+    });
+  },
+
+  update: (jobId, script) => {
+    return apiClient.put(`/api/script/${jobId}`, {
+      script,
+    });
+  },
+
+  getStatus: (jobId) => {
+    return apiClient.get(`/api/job/${jobId}`);
+  },
+};
+
+// Audio API
+export const audioAPI = {
+  generate: (jobId, script) => {
+    return apiClient.post('/api/generate-audio', {
+      job_id: jobId,
+      script: script,
+    });
+  },
+
+  getStatus: (jobId) => {
+    return apiClient.get(`/api/job/${jobId}`);
+  },
+
+  download: async (jobId) => {
+    const response = await apiClient.get(`/api/download/${jobId}`, {
+      responseType: 'blob',
+    });
+    return response.data;
+  },
+};
+
+// Voice API
+export const voiceAPI = {
+  getAll: () => {
+    return apiClient.get('/api/voices');
+  },
+
+  getSample: (voiceId) => {
+    return apiClient.get(`/api/voice/sample/${voiceId}`, {
+      responseType: 'blob',
+    });
+  },
+};
+
+// Project API (for future use)
+export const projectAPI = {
+  getAll: () => {
+    return apiClient.get('/api/projects');
+  },
+
+  getById: (id) => {
+    return apiClient.get(`/api/projects/${id}`);
+  },
+
+  create: (data) => {
+    return apiClient.post('/api/projects', data);
+  },
+
+  update: (id, data) => {
+    return apiClient.put(`/api/projects/${id}`, data);
+  },
+
+  delete: (id) => {
+    return apiClient.delete(`/api/projects/${id}`);
+  },
+};
+
+// Job API
+export const jobAPI = {
+  getStatus: (jobId) => {
+    return apiClient.get(`/api/job/${jobId}`);
+  },
+
+  cancel: (jobId) => {
+    return apiClient.post(`/api/job/${jobId}/cancel`);
+  },
+};
+
+// Convenience exports for backward compatibility
+export const uploadPDF = (file, onProgress) => {
+  return uploadAPI.uploadFile(file, onProgress).then(res => res.data);
+};
+
+export const getVoices = () => {
+  return voiceAPI.getAll().then(res => res.data);
+};
+
+export const generateScript = (jobId, hostVoice, guestVoice) => {
+  return scriptAPI.generate(jobId, hostVoice, guestVoice).then(res => res.data);
+};
+
+export const generateAudio = (jobId, script) => {
+  return audioAPI.generate(jobId, script).then(res => res.data);
+};
+
+export const getJobStatus = (jobId) => {
+  return jobAPI.getStatus(jobId).then(res => res.data);
+};
+
+export const downloadAudio = (jobId) => {
+  return audioAPI.download(jobId);
+};
+
+export default apiClient;
diff --git a/PdfToPodcast/ui/src/store/slices/audioSlice.js b/PdfToPodcast/ui/src/store/slices/audioSlice.js
new file mode 100644
index 0000000000..e6d18a26f3
--- /dev/null
+++ b/PdfToPodcast/ui/src/store/slices/audioSlice.js
@@ -0,0 +1,133 @@
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+import { audioAPI } from '@services/api';
+
+const initialState = {
+  audioUrl: null,
+  audioBlob: null,
+  generating: false,
+  generationProgress: 0,
+  statusMessage: '',
+  error: null,
+};
+
+// Async thunks
+export const generateAudio = createAsyncThunk(
+  'audio/generateAudio',
+  async (jobId, { rejectWithValue }) => {
+    try {
+      const response = await audioAPI.generate(jobId);
+      return response.data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to generate audio');
+    }
+  }
+);
+
+export const pollAudioStatus = createAsyncThunk(
+  'audio/pollAudioStatus',
+  async (jobId, { rejectWithValue, dispatch }) => {
+    try {
+      const response = await audioAPI.getStatus(jobId);
+      const data = response.data;
+
+      dispatch(setGenerationProgress(data.progress || 0));
+      dispatch(setStatusMessage(data.status_message || ''));
+
+      return data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to get status');
+    }
+  }
+);
+
+export const downloadAudio = createAsyncThunk(
+  'audio/downloadAudio',
+  async (jobId, { rejectWithValue }) => {
+    try {
+      const blob = await audioAPI.download(jobId);
+      return blob;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to download audio');
+    }
+  }
+);
+
+const audioSlice = createSlice({
+  name: 'audio',
+  initialState,
+  reducers: {
+    setGenerationProgress: (state, action) => {
+      state.generationProgress = action.payload;
+    },
+    setStatusMessage: (state, action) => {
+      state.statusMessage = action.payload;
+    },
+    resetAudio: (state) => {
+      state.audioUrl = null;
+      state.audioBlob = null;
+      state.generating = false;
+      state.generationProgress = 0;
+      state.statusMessage = '';
+      state.error = null;
+    },
+    clearError: (state) => {
+      state.error = null;
+    },
+  },
+  extraReducers: (builder) => {
+    builder
+      // Generate audio
+      .addCase(generateAudio.pending, (state) => {
+        state.generating = true;
+        state.generationProgress = 0;
+        state.error = null;
+      })
+      .addCase(generateAudio.fulfilled, (state, action) => {
+        state.generating = false;
+        state.generationProgress = 10;
+        state.statusMessage = 'Audio generation started';
+      })
+      .addCase(generateAudio.rejected, (state, action) => {
+        state.generating = false;
+        state.error = action.payload;
+      })
+      // Poll status
+      .addCase(pollAudioStatus.fulfilled, (state, action) => {
+        const data = action.payload;
+        if (data.status === 'completed' && data.audio_url) {
+          state.audioUrl = data.audio_url;
+          state.generating = false;
+          state.generationProgress = 100;
+        } else if (data.status === 'audio_generated') {
+          // Audio generation complete (even if URL is null for TTS not available)
+          state.audioUrl = data.audio_url || 'placeholder';
+          state.generating = false;
+          state.generationProgress = 100;
+          state.statusMessage = data.audio_status || 'Audio generation complete';
+        } else if (data.status === 'failed') {
+          state.generating = false;
+          state.error = data.error_message || 'Audio generation failed';
+        }
+      })
+      .addCase(pollAudioStatus.rejected, (state, action) => {
+        state.generating = false;
+        state.error = action.payload;
+      })
+      // Download audio
+      .addCase(downloadAudio.fulfilled, (state, action) => {
+        state.audioBlob = action.payload;
+      })
+      .addCase(downloadAudio.rejected, (state, action) => {
+        state.error = action.payload;
+      });
+  },
+});
+
+export const {
+  setGenerationProgress,
+  setStatusMessage,
+  resetAudio,
+  clearError,
+} = audioSlice.actions;
+
+export default audioSlice.reducer;
diff --git a/PdfToPodcast/ui/src/store/slices/projectSlice.js b/PdfToPodcast/ui/src/store/slices/projectSlice.js
new file mode 100644
index 0000000000..d769797784
--- /dev/null
+++ b/PdfToPodcast/ui/src/store/slices/projectSlice.js
@@ -0,0 +1,98 @@
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+import { projectAPI } from '@services/api';
+
+const initialState = {
+  projects: [],
+  currentProject: null,
+  loading: false,
+  error: null,
+};
+
+// Async thunks
+export const fetchProjects = createAsyncThunk(
+  'project/fetchProjects',
+  async (_, { rejectWithValue }) => {
+    try {
+      const response = await projectAPI.getAll();
+      return response.data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to fetch projects');
+    }
+  }
+);
+
+export const fetchProjectById = createAsyncThunk(
+  'project/fetchProjectById',
+  async (id, { rejectWithValue }) => {
+    try {
+      const response = await projectAPI.getById(id);
+      return response.data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to fetch project');
+    }
+  }
+);
+
+export const deleteProject = createAsyncThunk(
+  'project/deleteProject',
+  async (id, { rejectWithValue }) => {
+    try {
+      await projectAPI.delete(id);
+      return id;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to delete project');
+    }
+  }
+);
+
+const projectSlice = createSlice({
+  name: 'project',
+  initialState,
+  reducers: {
+    setCurrentProject: (state, action) => {
+      state.currentProject = action.payload;
+    },
+    clearCurrentProject: (state) => {
+      state.currentProject = null;
+    },
+    clearError: (state) => {
+      state.error = null;
+    },
+  },
+  extraReducers: (builder) => {
+    builder
+      // Fetch projects
+      .addCase(fetchProjects.pending, (state) => {
+        state.loading = true;
+        state.error = null;
+      })
+      .addCase(fetchProjects.fulfilled, (state, action) => {
+        state.loading = false;
+        state.projects = action.payload;
+      })
+      .addCase(fetchProjects.rejected, (state, action) => {
+        state.loading = false;
+        state.error = action.payload;
+      })
+      // Fetch project by ID
+      .addCase(fetchProjectById.pending, (state) => {
+        state.loading = true;
+        state.error = null;
+      })
+      .addCase(fetchProjectById.fulfilled, (state, action) => {
+        state.loading = false;
+        state.currentProject = action.payload;
+      })
+      .addCase(fetchProjectById.rejected, (state, action) => {
+        state.loading = false;
+        state.error = action.payload;
+      })
+      // Delete project
+      .addCase(deleteProject.fulfilled, (state, action) => {
+        state.projects = state.projects.filter(p => p.id !== action.payload);
+      });
+  },
+});
+
+export const { setCurrentProject, clearCurrentProject, clearError } = projectSlice.actions;
+export default projectSlice.reducer;
diff --git a/PdfToPodcast/ui/src/store/slices/scriptSlice.js b/PdfToPodcast/ui/src/store/slices/scriptSlice.js
new file mode 100644
index 0000000000..5feb265ba9
--- /dev/null
+++ b/PdfToPodcast/ui/src/store/slices/scriptSlice.js
@@ -0,0 +1,150 @@
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+import { scriptAPI } from '@services/api';
+
+const initialState = {
+  script: null,
+  originalScript: null,
+  hostVoice: 'alloy',
+  guestVoice: 'echo',
+  generating: false,
+  updating: false,
+  generationProgress: 0,
+  statusMessage: '',
+  error: null,
+};
+
+// Async thunks
+export const generateScript = createAsyncThunk(
+  'script/generateScript',
+  async ({ jobId, hostVoice, guestVoice }, { rejectWithValue }) => {
+    try {
+      const response = await scriptAPI.generate(jobId, hostVoice, guestVoice);
+      return response.data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to generate script');
+    }
+  }
+);
+
+export const pollScriptStatus = createAsyncThunk(
+  'script/pollScriptStatus',
+  async (jobId, { rejectWithValue, dispatch }) => {
+    try {
+      const response = await scriptAPI.getStatus(jobId);
+      const data = response.data;
+
+      dispatch(setGenerationProgress(data.progress || 0));
+      dispatch(setStatusMessage(data.status_message || ''));
+
+      return data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to get status');
+    }
+  }
+);
+
+export const updateScript = createAsyncThunk(
+  'script/updateScript',
+  async ({ jobId, script }, { rejectWithValue }) => {
+    try {
+      const response = await scriptAPI.update(jobId, script);
+      return response.data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to update script');
+    }
+  }
+);
+
+const scriptSlice = createSlice({
+  name: 'script',
+  initialState,
+  reducers: {
+    setHostVoice: (state, action) => {
+      state.hostVoice = action.payload;
+    },
+    setGuestVoice: (state, action) => {
+      state.guestVoice = action.payload;
+    },
+    setScript: (state, action) => {
+      state.script = action.payload;
+    },
+    setGenerationProgress: (state, action) => {
+      state.generationProgress = action.payload;
+    },
+    setStatusMessage: (state, action) => {
+      state.statusMessage = action.payload;
+    },
+    resetScript: (state) => {
+      state.script = null;
+      state.originalScript = null;
+      state.generating = false;
+      state.updating = false;
+      state.generationProgress = 0;
+      state.statusMessage = '';
+      state.error = null;
+    },
+    clearError: (state) => {
+      state.error = null;
+    },
+  },
+  extraReducers: (builder) => {
+    builder
+      // Generate script
+      .addCase(generateScript.pending, (state) => {
+        state.generating = true;
+        state.generationProgress = 0;
+        state.error = null;
+      })
+      .addCase(generateScript.fulfilled, (state, action) => {
+        state.generating = false;
+        state.generationProgress = 10;
+        state.statusMessage = 'Script generation started';
+      })
+      .addCase(generateScript.rejected, (state, action) => {
+        state.generating = false;
+        state.error = action.payload;
+      })
+      // Poll status
+      .addCase(pollScriptStatus.fulfilled, (state, action) => {
+        const data = action.payload;
+        if (data.status === 'script_generated' && data.script) {
+          state.script = data.script;
+          state.originalScript = JSON.parse(JSON.stringify(data.script));
+          state.generating = false;
+          state.generationProgress = 100;
+        } else if (data.status === 'failed') {
+          state.generating = false;
+          state.error = data.error_message || 'Script generation failed';
+        }
+      })
+      .addCase(pollScriptStatus.rejected, (state, action) => {
+        state.generating = false;
+        state.error = action.payload;
+      })
+      // Update script
+      .addCase(updateScript.pending, (state) => {
+        state.updating = true;
+        state.error = null;
+      })
+      .addCase(updateScript.fulfilled, (state, action) => {
+        state.updating = false;
+        state.originalScript = JSON.parse(JSON.stringify(state.script));
+      })
+      .addCase(updateScript.rejected, (state, action) => {
+        state.updating = false;
+        state.error = action.payload;
+      });
+  },
+});
+
+export const {
+  setHostVoice,
+  setGuestVoice,
+  setScript,
+  setGenerationProgress,
+  setStatusMessage,
+  resetScript,
+  clearError,
+} = scriptSlice.actions;
+
+export default scriptSlice.reducer;
diff --git a/PdfToPodcast/ui/src/store/slices/uiSlice.js b/PdfToPodcast/ui/src/store/slices/uiSlice.js
new file mode 100644
index 0000000000..ad49ea5bdd
--- /dev/null
+++ b/PdfToPodcast/ui/src/store/slices/uiSlice.js
@@ -0,0 +1,66 @@
+import { createSlice } from '@reduxjs/toolkit';
+
+const initialState = {
+  currentStep: 1, // 1: Upload, 2: Voice Selection, 3: Script Review, 4: Audio Generation
+  sidebarOpen: true,
+  theme: 'light',
+  notifications: [],
+};
+
+const uiSlice = createSlice({
+  name: 'ui',
+  initialState,
+  reducers: {
+    setCurrentStep: (state, action) => {
+      state.currentStep = action.payload;
+    },
+    nextStep: (state) => {
+      if (state.currentStep < 4) {
+        state.currentStep += 1;
+      }
+    },
+    previousStep: (state) => {
+      if (state.currentStep > 1) {
+        state.currentStep -= 1;
+      }
+    },
+    toggleSidebar: (state) => {
+      state.sidebarOpen = !state.sidebarOpen;
+    },
+    setSidebarOpen: (state, action) => {
+      state.sidebarOpen = action.payload;
+    },
+    setTheme: (state, action) => {
+      state.theme = action.payload;
+    },
+    addNotification: (state, action) => {
+      state.notifications.push({
+        id: Date.now(),
+        ...action.payload,
+      });
+    },
+    removeNotification: (state, action) => {
+      state.notifications = state.notifications.filter(
+        (n) => n.id !== action.payload
+      );
+    },
+    resetUI: (state) => {
+      state.currentStep = 1;
+      state.notifications = [];
+    },
+  },
+});
+
+export const {
+  setCurrentStep,
+  nextStep,
+  previousStep,
+  toggleSidebar,
+  setSidebarOpen,
+  setTheme,
+  addNotification,
+  removeNotification,
+  resetUI,
+} = uiSlice.actions;
+
+export default uiSlice.reducer;
diff --git a/PdfToPodcast/ui/src/store/slices/uploadSlice.js b/PdfToPodcast/ui/src/store/slices/uploadSlice.js
new file mode 100644
index 0000000000..b7d4b53b2c
--- /dev/null
+++ b/PdfToPodcast/ui/src/store/slices/uploadSlice.js
@@ -0,0 +1,74 @@
+import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
+import { uploadAPI } from '@services/api';
+
+const initialState = {
+  file: null,
+  jobId: null,
+  uploadProgress: 0,
+  uploading: false,
+  uploadComplete: false,
+  error: null,
+};
+
+// Async thunks
+export const uploadPDF = createAsyncThunk(
+  'upload/uploadPDF',
+  async (file, { rejectWithValue, dispatch }) => {
+    try {
+      const response = await uploadAPI.uploadFile(file, (progress) => {
+        dispatch(setUploadProgress(progress));
+      });
+      return response.data;
+    } catch (error) {
+      return rejectWithValue(error.response?.data?.detail || 'Failed to upload PDF');
+    }
+  }
+);
+
+const uploadSlice = createSlice({
+  name: 'upload',
+  initialState,
+  reducers: {
+    setFile: (state, action) => {
+      state.file = action.payload;
+      state.error = null;
+    },
+    setUploadProgress: (state, action) => {
+      state.uploadProgress = action.payload;
+    },
+    resetUpload: (state) => {
+      state.file = null;
+      state.jobId = null;
+      state.uploadProgress = 0;
+      state.uploading = false;
+      state.uploadComplete = false;
+      state.error = null;
+    },
+    clearError: (state) => {
+      state.error = null;
+    },
+  },
+  extraReducers: (builder) => {
+    builder
+      .addCase(uploadPDF.pending, (state) => {
+        state.uploading = true;
+        state.uploadComplete = false;
+        state.error = null;
+      })
+      .addCase(uploadPDF.fulfilled, (state, action) => {
+        state.uploading = false;
+        state.uploadComplete = true;
+        state.jobId = action.payload.job_id;
+        state.uploadProgress = 100;
+      })
+      .addCase(uploadPDF.rejected, (state, action) => {
+        state.uploading = false;
+        state.uploadComplete = false;
+        state.error = action.payload;
+        state.uploadProgress = 0;
+      });
+  },
+});
+
+export const { setFile, setUploadProgress, resetUpload, clearError } = uploadSlice.actions;
+export default uploadSlice.reducer;
diff --git a/PdfToPodcast/ui/src/store/store.js b/PdfToPodcast/ui/src/store/store.js
new file mode 100644
index 0000000000..21dea242d1
--- /dev/null
+++ b/PdfToPodcast/ui/src/store/store.js
@@ -0,0 +1,29 @@
+import { configureStore } from '@reduxjs/toolkit';
+import projectReducer from './slices/projectSlice';
+import uploadReducer from './slices/uploadSlice';
+import scriptReducer from './slices/scriptSlice';
+import audioReducer from './slices/audioSlice';
+import uiReducer from './slices/uiSlice';
+
+export const store = configureStore({
+  reducer: {
+    project: projectReducer,
+    upload: uploadReducer,
+    script: scriptReducer,
+    audio: audioReducer,
+    ui: uiReducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware({
+      serializableCheck: {
+        // Ignore these action types
+        ignoredActions: ['upload/setFile'],
+        // Ignore these field paths in all actions
+        ignoredActionPaths: ['payload.file'],
+        // Ignore these paths in the state
+        ignoredPaths: ['upload.file'],
+      },
+    }),
+});
+
+export default store;
diff --git a/PdfToPodcast/ui/src/utils/helpers.js b/PdfToPodcast/ui/src/utils/helpers.js
new file mode 100644
index 0000000000..8c8cdc41ca
--- /dev/null
+++ b/PdfToPodcast/ui/src/utils/helpers.js
@@ -0,0 +1,83 @@
+/**
+ * Format seconds to MM:SS or HH:MM:SS
+ */
+export const formatTime = (seconds) => {
+  if (isNaN(seconds) || seconds === null) return '0:00';
+
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = Math.floor(seconds % 60);
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, '0')}:${secs
+      .toString()
+      .padStart(2, '0')}`;
+  }
+
+  return `${minutes}:${secs.toString().padStart(2, '0')}`;
+};
+
+/**
+ * Format file size to human readable format
+ */
+export const formatFileSize = (bytes) => {
+  if (bytes === 0) return '0 Bytes';
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + ' ' + sizes[i];
+};
+
+/**
+ * Validate PDF file
+ */
+export const validatePDFFile = (file) => {
+  const errors = [];
+
+  if (!file) {
+    errors.push('No file selected');
+    return errors;
+  }
+
+  if (file.type !== 'application/pdf') {
+    errors.push('File must be a PDF');
+  }
+
+  const maxSize = 10 * 1024 * 1024; // 10MB
+  if (file.size > maxSize) {
+    errors.push('File size must be less than 10MB');
+  }
+
+  return errors;
+};
+
+/**
+ * Download file from blob
+ */
+export const downloadBlob = (blob, filename) => {
+  const url = window.URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  window.URL.revokeObjectURL(url);
+};
+
+/**
+ * Truncate text with ellipsis
+ */
+export const truncateText = (text, maxLength = 50) => {
+  if (text.length <= maxLength) return text;
+  return text.substring(0, maxLength) + '...';
+};
+
+/**
+ * Combine class names
+ */
+export const cn = (...classes) => {
+  return classes.filter(Boolean).join(' ');
+};
diff --git a/PdfToPodcast/ui/tailwind.config.js b/PdfToPodcast/ui/tailwind.config.js
new file mode 100644
index 0000000000..846c750a01
--- /dev/null
+++ b/PdfToPodcast/ui/tailwind.config.js
@@ -0,0 +1,77 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: '#f0f9ff',
+          100: '#e0f2fe',
+          200: '#bae6fd',
+          300: '#7dd3fc',
+          400: '#38bdf8',
+          500: '#0ea5e9',
+          600: '#0284c7',
+          700: '#0369a1',
+          800: '#075985',
+          900: '#0c4a6e',
+          950: '#082f49',
+        },
+        secondary: {
+          50: '#fdf4ff',
+          100: '#fae8ff',
+          200: '#f5d0fe',
+          300: '#f0abfc',
+          400: '#e879f9',
+          500: '#d946ef',
+          600: '#c026d3',
+          700: '#a21caf',
+          800: '#86198f',
+          900: '#701a75',
+        },
+        success: {
+          50: '#f0fdf4',
+          100: '#dcfce7',
+          500: '#22c55e',
+          600: '#16a34a',
+        },
+        warning: {
+          50: '#fffbeb',
+          100: '#fef3c7',
+          500: '#f59e0b',
+          600: '#d97706',
+        },
+        error: {
+          50: '#fef2f2',
+          100: '#fee2e2',
+          500: '#ef4444',
+          600: '#dc2626',
+        },
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.5s ease-in-out',
+        'slide-up': 'slideUp 0.5s ease-out',
+        'slide-down': 'slideDown 0.5s ease-out',
+        'pulse-slow': 'pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite',
+      },
+      keyframes: {
+        fadeIn: {
+          '0%': { opacity: '0' },
+          '100%': { opacity: '1' },
+        },
+        slideUp: {
+          '0%': { transform: 'translateY(20px)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+        slideDown: {
+          '0%': { transform: 'translateY(-20px)', opacity: '0' },
+          '100%': { transform: 'translateY(0)', opacity: '1' },
+        },
+      },
+    },
+  },
+  plugins: [],
+}
diff --git a/PdfToPodcast/ui/vite.config.js b/PdfToPodcast/ui/vite.config.js
new file mode 100644
index 0000000000..7b14357ea7
--- /dev/null
+++ b/PdfToPodcast/ui/vite.config.js
@@ -0,0 +1,33 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      '@components': path.resolve(__dirname, './src/components'),
+      '@pages': path.resolve(__dirname, './src/pages'),
+      '@services': path.resolve(__dirname, './src/services'),
+      '@store': path.resolve(__dirname, './src/store'),
+      '@hooks': path.resolve(__dirname, './src/hooks'),
+      '@utils': path.resolve(__dirname, './src/utils'),
+    }
+  },
+  server: {
+    port: 3000,
+    strictPort: false,
+    open: false,
+    host: true,
+    watch: {
+      usePolling: true
+    },
+    proxy: {
+      '/api': {
+        target: 'http://localhost:8000',
+        changeOrigin: true,
+      }
+    }
+  }
+})
diff --git a/RAGChatbot/.gitignore b/RAGChatbot/.gitignore
new file mode 100644
index 0000000000..1972fc44d8
--- /dev/null
+++ b/RAGChatbot/.gitignore
@@ -0,0 +1,2 @@
+**/.env
+**/test.txt
\ No newline at end of file
diff --git a/RAGChatbot/README.md b/RAGChatbot/README.md
new file mode 100644
index 0000000000..a4e774009f
--- /dev/null
+++ b/RAGChatbot/README.md
@@ -0,0 +1,227 @@
+## RAG Chatbot
+
+A full-stack Retrieval-Augmented Generation (RAG) application that enables intelligent, document-based question answering.
+The system integrates a FastAPI backend powered by LangChain, FAISS, and AI models, alongside a modern React + Vite + Tailwind CSS frontend for an intuitive chat experience.
+
+## Table of Contents
+
+- [Project Overview](#project-overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Quick Start Deployment](#quick-start-deployment)
+- [User Interface](#user-interface)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Project Overview
+
+The **RAG Chatbot** demonstrates how retrieval-augmented generation can be used to build intelligent, document-grounded conversational systems. It retrieves relevant information from a knowledge base, passes it to a large language model, and generates a concise and reliable answer to the user’s query. This project integrates seamlessly with cloud-hosted APIs or local model endpoints, offering flexibility for research, enterprise, or educational use.
+
+---
+
+## Features
+
+**Backend**
+
+- Clean PDF upload with validation
+- LangChain-powered document processing
+- FAISS-CPU vector store for efficient similarity search
+- Enterprise inference endpoints for embeddings and LLM
+- Keycloak authentication for secure API access
+- Comprehensive error handling and logging
+- File validation and size limits
+- CORS enabled for web integration
+- Health check endpoints
+- Modular architecture (routes + services)
+
+**Frontend**
+
+- PDF file upload with drag-and-drop support
+- Real-time chat interface
+- Modern, responsive design with Tailwind CSS
+- Built with Vite for fast development
+- Live status updates
+- Mobile-friendly
+
+---
+
+## Architecture
+
+Below is the architecture as it consists of a server that waits for documents to embed and index into a vector database. Once documents have been uploaded, the server will wait for user queries which initiates a similarity search in the vector database before calling the LLM service to summarize the findings.
+
+![Architecture Diagram](./images/RAG%20Model%20System%20Design.png)
+
+**Service Components:**
+
+1. **React Web UI (Port 3000)** - Provides intuitive chat interface with drag-and-drop PDF upload, real-time messaging, and document-grounded Q&A interaction
+
+2. **FastAPI Backend (Port 5001)** - Handles document processing, FAISS vector storage, LangChain integration, and orchestrates retrieval-augmented generation for accurate responses
+
+**Typical Flow:**
+
+1. User uploads a document through the web UI.
+2. The backend processes the document by splitting it and transforming it into embeddings before storing it in the vector database.
+3. User sends a question through the web UI.
+4. The backend retrieves relevant content from stored documents.
+5. The model generates a response based on retrieved context.
+6. The answer is displayed to the user via the UI.
+
+---
+
+## Prerequisites
+
+### System Requirements
+
+Before you begin, ensure you have the following installed:
+
+- **Docker and Docker Compose**
+- **Enterprise inference endpoint access** (Keycloak authentication)
+
+### Verify Docker Installation
+
+```bash
+# Check Docker version
+docker --version
+
+# Check Docker Compose version
+docker compose version
+
+# Verify Docker is running
+docker ps
+```
+
+## Quick Start Deployment
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/opea-project/GenAIExamples.git
+cd GenAIExamples/RAGChatbot
+```
+
+### Set up the Environment
+
+This application requires an `.env` file in the `api` directory for proper configuration. Create it with the commands below:
+
+```bash
+# Create the .env file in the api directory
+mkdir -p api
+cat > api/.env << EOF
+# Backend API URL (accessible from frontend)
+VITE_API_URL=https://backend:5000
+
+# Required - Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Required - Model Configuration
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+EOF
+```
+
+Or manually create `api/.env` with:
+
+```bash
+# Backend API URL (accessible from frontend)
+VITE_API_URL=https://backend:5000
+
+# Required - Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Required - Model Configuration
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+```
+
+**Note**: The docker-compose.yml file automatically loads environment variables from `./api/.env` for the backend service.
+
+### Running the Application
+
+Start both API and UI services together with Docker Compose:
+
+```bash
+# From the rag-chatbot directory
+docker compose up --build
+
+# Or run in detached mode (background)
+docker compose up -d --build
+```
+
+The API will be available at: `http://localhost:5001`  
+The UI will be available at: `http://localhost:3000`
+
+**View logs**:
+
+```bash
+# All services
+docker compose logs -f
+
+# Backend only
+docker compose logs -f backend
+
+# Frontend only
+docker compose logs -f frontend
+```
+
+**Verify the services are running**:
+
+```bash
+# Check API health
+curl http://localhost:5001/health
+
+# Check if containers are running
+docker compose ps
+```
+
+## User Interface
+
+**Using the Application**
+
+Make sure you are at the localhost:3000 url
+
+You will be directed to the main page which has each feature
+
+![User Interface](images/ui.png)
+
+Upload a PDF:
+
+- Drag and drop a PDF file, or
+- Click "Browse Files" to select a file
+- Wait for processing to complete
+
+Start chatting:
+
+- Type your question in the input field
+- Press Enter or click Send
+- Get AI-powered answers based on your document
+
+**UI Configuration**
+
+When running with Docker Compose, the UI automatically connects to the backend API. The frontend is available at `http://localhost:3000` and the API at `http://localhost:5001`.
+
+For production deployments, you may want to configure a reverse proxy or update the API URL in the frontend configuration.
+
+### Stopping the Application
+
+
+```bash
+docker compose down
+```
+
+## Troubleshooting
+
+For comprehensive troubleshooting guidance, common issues, and solutions, refer to:
+
+[Troubleshooting Guide - TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
diff --git a/RAGChatbot/TROUBLESHOOTING.md b/RAGChatbot/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..34b352991e
--- /dev/null
+++ b/RAGChatbot/TROUBLESHOOTING.md
@@ -0,0 +1,103 @@
+# Troubleshooting Guide
+
+This document contains all common issues encountered during development and their solutions.
+
+## Table of Contents
+
+- [API Common Issues](#api-common-issues)
+- [UI Common Issues](#ui-common-issues)
+
+### API Common Issues
+
+#### "OPENAI_API_KEY not found in environment variables"
+
+**Solution**:
+
+1. Create a `.env` file in the `api` directory
+2. Add your OpenAI API key: `OPENAI_API_KEY=your_key_here`
+3. Restart the server
+
+#### "No documents uploaded"
+
+**Solution**:
+
+- Upload a PDF first using the `/upload-pdf` endpoint
+- Check server logs for any upload errors
+- Verify the PDF is not corrupted or empty
+
+#### "Could not load vector store"
+
+**Solution**:
+
+- The vector store is created when you upload your first PDF
+- Check that the application has write permissions in the directory
+- Verify `dmv_index/` directory exists and is accessible
+
+#### Import errors
+
+**Solution**:
+
+1. Ensure all dependencies are installed: `pip install -r requirements.txt`
+2. Verify you're using Python 3.10 or higher: `python --version`
+3. Activate your virtual environment if using one
+
+#### Server won't start
+
+**Solution**:
+
+1. Check if port 5000 is already in use: `lsof -i :5000` (Unix) or `netstat -ano | findstr :5000` (Windows)
+2. Use a different port: `uvicorn server:app --port 5001`
+3. Check the logs for specific error messages
+
+#### PDF upload fails
+
+**Solution**:
+
+1. Verify the file is a valid PDF
+2. Check file size (must be under 50MB by default)
+3. Ensure the PDF contains extractable text (not just images)
+4. Check server logs for detailed error messages
+
+#### Query returns no answer
+
+**Solution**:
+
+1. Verify a document has been uploaded successfully
+2. Try rephrasing your question
+3. Check if the document contains relevant information
+4. Increase `TOP_K_DOCUMENTS` in `config.py` for broader search
+
+## UI Common Issues
+
+### API Connection Issues
+
+**Problem**: "Failed to upload PDF" or "Failed to get response"
+
+**Solution**:
+
+1. Ensure the API server is running on `http://localhost:5000`
+2. Check browser console for detailed errors
+3. Verify CORS is enabled in the API
+
+### Build Issues
+
+**Problem**: Build fails with dependency errors
+
+**Solution**:
+
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Styling Issues
+
+**Problem**: Styles not applying
+
+**Solution**:
+
+```bash
+# Rebuild Tailwind CSS
+npm run dev
+```
diff --git a/RAGChatbot/api/Dockerfile b/RAGChatbot/api/Dockerfile
new file mode 100644
index 0000000000..4424ff4c43
--- /dev/null
+++ b/RAGChatbot/api/Dockerfile
@@ -0,0 +1,19 @@
+FROM python:3.9-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+COPY requirements.txt .
+
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application files into the container
+COPY server.py .
+
+# Expose the port the service runs on
+EXPOSE 5001
+
+# Command to run the application
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "5001", "--reload"]
\ No newline at end of file
diff --git a/RAGChatbot/api/README.md b/RAGChatbot/api/README.md
new file mode 100644
index 0000000000..7434f91397
--- /dev/null
+++ b/RAGChatbot/api/README.md
@@ -0,0 +1,693 @@
+# RAG Chatbot API
+
+A production-ready RAG (Retrieval-Augmented Generation) chatbot API built with FastAPI, LangChain, and FAISS for document-based question answering.
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Running the Server](#running-the-server)
+- [API Endpoints](#api-endpoints)
+- [Project Structure](#project-structure)
+- [Testing](#testing)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+
+## Features
+
+- Clean PDF upload with validation
+- LangChain-powered document processing
+- FAISS-CPU vector store for efficient similarity search
+- Enterprise inference endpoints for embeddings and LLM
+- Keycloak authentication for secure API access
+- Comprehensive error handling and logging
+- File validation and size limits
+- CORS enabled for web integration
+- Health check endpoints
+- Modular architecture (routes + services)
+
+## Quick Start
+
+Get up and running in 3 minutes using Docker Compose:
+
+```bash
+# 1. Navigate to the rag-chatbot directory
+cd /path/to/rag-chatbot
+
+# 2. Create .env file in the api directory with enterprise configuration
+mkdir -p api
+cat > api/.env << EOF
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+EOF
+
+# 3. Start both API and UI services with Docker Compose
+docker compose up --build
+
+# 4. Access the application
+# API: http://localhost:5001/docs
+# UI: http://localhost:3000
+```
+
+The application will automatically start both the backend API and frontend UI. Visit http://localhost:5001/docs for interactive API documentation.
+
+## Installation
+
+### Prerequisites
+
+- Docker and Docker Compose installed
+- Enterprise inference endpoint access (Keycloak authentication)
+
+### Docker Compose Setup
+
+Docker Compose will start both the API and UI services together.
+
+1. **Set up environment variables**:
+
+Create a `.env` file in the `api` directory (relative to `rag-chatbot/`):
+
+```bash
+cd rag-chatbot
+mkdir -p api
+cat > api/.env << EOF
+# Backend API URL (accessible from frontend)
+VITE_API_URL=https://backend:5000
+
+# Required - Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Required - Model Configuration
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+EOF
+```
+
+2. **Start the services**:
+
+```bash
+# From the rag-chatbot directory
+docker compose up --build
+```
+
+This will:
+- Build the backend API container
+- Build the frontend UI container
+- Start both services automatically
+- Make API available at http://localhost:5001
+- Make UI available at http://localhost:3000
+
+### Dependencies
+
+The main dependencies include:
+
+- `fastapi==0.109.0` - Web framework
+- `uvicorn[standard]==0.27.0` - ASGI server
+- `langchain==0.1.0` - LLM framework
+- `faiss-cpu==1.7.4` - Vector similarity search
+- `pypdf==4.0.1` - PDF processing
+
+See `requirements.txt` for complete list.
+
+## Configuration
+
+All configuration is centralized in `config.py`. You can modify settings by editing this file or using environment variables.
+
+### Environment Variables
+
+For Docker Compose, create a `.env` file in the `api/` directory (relative to `rag-chatbot/`):
+
+```bash
+# Backend API URL (accessible from frontend)
+VITE_API_URL=https://backend:5000
+
+# Required - Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_client_secret
+
+# Required - Model Configuration
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+
+# Optional (with defaults shown)
+# VECTOR_STORE_PATH=./dmv_index
+# MAX_FILE_SIZE_MB=50
+```
+
+**Note**: The docker-compose.yml file automatically loads environment variables from `./api/.env` for the backend service.
+
+### Configuration Settings
+
+Edit `config.py` to customize:
+
+#### File Upload Settings
+
+```python
+MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB
+ALLOWED_EXTENSIONS = {".pdf"}
+```
+
+#### Text Processing Settings
+
+```python
+CHUNK_SIZE = 1000           # Characters per chunk
+CHUNK_OVERLAP = 200         # Overlap between chunks
+SEPARATORS = ["\n\n", "\n", " ", ""]  # Text splitting separators
+```
+
+#### Vector Store Settings
+
+```python
+VECTOR_STORE_PATH = "./dmv_index"  # Where to store FAISS index
+```
+
+#### LLM Settings
+
+```python
+LLM_TEMPERATURE = 0                      # Response randomness (0-1)
+TOP_K_DOCUMENTS = 4                      # Documents to retrieve
+# Model endpoints and names are configured via environment variables:
+# EMBEDDING_MODEL_ENDPOINT, INFERENCE_MODEL_ENDPOINT
+# EMBEDDING_MODEL_NAME, INFERENCE_MODEL_NAME
+```
+
+#### CORS Settings
+
+```python
+CORS_ALLOW_ORIGINS = ["*"]  # Update with specific origins in production
+CORS_ALLOW_CREDENTIALS = True
+CORS_ALLOW_METHODS = ["*"]
+CORS_ALLOW_HEADERS = ["*"]
+```
+
+## Running the Server
+
+**Start both API and UI together**:
+
+```bash
+# From the rag-chatbot directory
+docker compose up --build
+
+# Or run in detached mode (background)
+docker compose up -d --build
+```
+
+**Stop the services**:
+
+```bash
+docker compose down
+```
+
+The API will be available at: `http://localhost:5001`  
+The UI will be available at: `http://localhost:3000`
+
+**View logs**:
+
+```bash
+# All services
+docker compose logs -f
+
+# Backend only
+docker compose logs -f backend
+
+# Frontend only
+docker compose logs -f frontend
+```
+
+### Verifying the Server
+
+```bash
+# Check if API server is running
+curl http://localhost:5001/
+
+# Check health status
+curl http://localhost:5001/health
+
+# Check if containers are running
+docker compose ps
+```
+
+## API Endpoints
+
+### Health Check
+
+**GET /** - Basic health check
+
+```bash
+curl http://localhost:5001/
+```
+
+Response:
+
+```json
+{
+  "message": "RAG Chatbot API is running",
+  "version": "2.0.0",
+  "status": "healthy",
+  "vectorstore_loaded": true
+}
+```
+
+**GET /health** - Detailed health status
+
+```bash
+curl http://localhost:5001/health
+```
+
+Response:
+
+```json
+{
+  "status": "healthy",
+  "vectorstore_available": true,
+  "enterprise_inference_configured": true
+}
+```
+
+### Upload PDF
+
+**POST /upload-pdf** - Upload and process a PDF document
+
+```bash
+curl -X POST "http://localhost:5001/upload-pdf" \
+  -H "Content-Type: multipart/form-data" \
+  -F "file=@/path/to/document.pdf"
+```
+
+Response:
+
+```json
+{
+  "message": "Successfully uploaded and processed 'document.pdf'",
+  "num_chunks": 45,
+  "status": "success"
+}
+```
+
+**Validation Rules**:
+
+- File must be PDF format
+- Maximum size: 50MB (configurable)
+- File must not be empty
+- Content must be extractable
+
+### Query Documents
+
+**POST /query** - Ask questions about uploaded documents
+
+```bash
+curl -X POST "http://localhost:5001/query" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What are the main topics in the document?"}'
+```
+
+Response:
+
+```json
+{
+  "answer": "The main topics covered in the document are...",
+  "query": "What are the main topics in the document?"
+}
+```
+
+### Delete Vector Store
+
+**DELETE /vectorstore** - Delete the current vector store
+
+```bash
+curl -X DELETE "http://localhost:5001/vectorstore"
+```
+
+Response:
+
+```json
+{
+  "message": "Vector store deleted successfully",
+  "status": "success"
+}
+```
+
+### Interactive API Documentation
+
+FastAPI provides automatic interactive documentation:
+
+- **Swagger UI**: http://localhost:5001/docs
+- **ReDoc**: http://localhost:5001/redoc
+
+## Project Structure
+
+The application follows a modular architecture with clear separation of concerns:
+
+```
+api/
+├── server.py               # FastAPI app with routes (main entry point)
+├── config.py               # Configuration settings
+├── models.py               # Pydantic models for request/response validation
+├── services/               # Business logic layer
+│   ├── __init__.py
+│   ├── pdf_service.py      # PDF processing and validation
+│   ├── vector_service.py   # Vector store operations (FAISS)
+│   └── retrieval_service.py # Query processing and LLM integration
+├── requirements.txt        # Python dependencies
+├── test_api.py            # Automated test suite
+├── .env                   # Environment variables (create this)
+└── dmv_index/             # FAISS vector store (auto-generated)
+```
+
+### Architecture Overview
+
+```
+Client Request
+     ↓
+server.py (Routes)
+     ↓
+models.py (Validation)
+     ↓
+services/ (Business Logic)
+     ├── pdf_service.py
+     ├── vector_service.py
+     └── retrieval_service.py
+     ↓
+External Services (Enterprise Inference Endpoints, FAISS)
+```
+
+**Layered Architecture**:
+
+- **Routes Layer** (`server.py`): HTTP handling, routing, error responses
+- **Validation Layer** (`models.py`): Request/response validation
+- **Business Logic Layer** (`services/`): Core functionality
+- **Configuration Layer** (`config.py`): Settings management
+
+## Testing
+
+### Automated Test Suite
+
+Run the included test suite:
+
+```bash
+# Basic tests (no PDF required)
+python test_api.py
+
+# Full tests with PDF upload
+python test_api.py /path/to/your/document.pdf
+```
+
+The test suite includes:
+
+- Health check tests
+- Upload validation tests
+- Query functionality tests
+- Error handling tests
+- Colored output for easy reading
+
+### Manual Testing
+
+1. **Start the services**:
+
+```bash
+docker compose up
+```
+
+2. **Upload a PDF**:
+
+```bash
+curl -X POST "http://localhost:5001/upload-pdf" \
+  -F "file=@sample.pdf"
+```
+
+3. **Query the document**:
+
+```bash
+curl -X POST "http://localhost:5001/query" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is this document about?"}'
+```
+
+4. **Check health**:
+
+```bash
+curl http://localhost:5001/health
+```
+
+## Development
+
+### Project Setup for Development
+
+1. Fork/clone the repository
+2. Set up your `.env` file in the `api` directory
+3. Run with Docker Compose for development: `docker compose up --build`
+4. Make changes to code (changes are reflected with volume mounts in docker-compose.yml)
+
+### Adding New Features
+
+#### Add a New Service
+
+1. Create new file in `services/` directory:
+
+```python
+# services/new_service.py
+def new_function(param):
+    """Your business logic"""
+    return result
+```
+
+2. Export from `services/__init__.py`:
+
+```python
+from .new_service import new_function
+```
+
+3. Use in routes:
+
+```python
+# server.py
+from services import new_function
+
+@app.post("/new-endpoint")
+def new_endpoint():
+    result = new_function(data)
+    return result
+```
+
+#### Add a New Endpoint
+
+1. Define model in `models.py`:
+
+```python
+class NewRequest(BaseModel):
+    field: str
+```
+
+2. Add route in `server.py`:
+
+```python
+@app.post("/new-endpoint")
+def new_endpoint(request: NewRequest):
+    # Your logic here
+    return {"result": "success"}
+```
+
+### Modifying Configuration
+
+Edit `config.py` to change default settings:
+
+```python
+# Example: Increase file size limit
+MAX_FILE_SIZE = 100 * 1024 * 1024  # 100MB
+
+# Example: Change chunk size
+CHUNK_SIZE = 1500
+
+# Example: Use different model
+LLM_MODEL = "gpt-4"
+```
+
+### Code Style
+
+- Use type hints for all functions
+- Add docstrings to all public functions
+- Follow PEP 8 style guide
+- Keep functions focused (single responsibility)
+- Log important operations
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Keycloak authentication or model endpoints not configured"
+
+**Solution**:
+
+1. Create a `.env` file in the `api` directory (relative to `rag-chatbot/`)
+2. Add required configuration:
+   ```bash
+   BASE_URL=https://api.example.com
+   KEYCLOAK_REALM=master
+   KEYCLOAK_CLIENT_ID=api
+   KEYCLOAK_CLIENT_SECRET=your_client_secret
+   EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+   INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+   EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+   INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+   ```
+3. Restart the services with `docker compose restart backend` or `docker compose down && docker compose up`
+
+#### "No documents uploaded"
+
+**Solution**:
+
+- Upload a PDF first using the `/upload-pdf` endpoint
+- Check server logs for any upload errors
+- Verify the PDF is not corrupted or empty
+
+#### "Could not load vector store"
+
+**Solution**:
+
+- The vector store is created when you upload your first PDF
+- Check that the application has write permissions in the directory
+- Verify `dmv_index/` directory exists and is accessible
+
+#### Import errors
+
+**Solution**:
+
+1. Rebuild the Docker containers: `docker compose down && docker compose build --no-cache && docker compose up`
+2. Check container logs: `docker compose logs backend`
+
+#### Server won't start
+
+**Solution**:
+
+1. Check if ports 5001 or 3000 are already in use: `lsof -i :5001` or `lsof -i :3000` (Unix) or `netstat -ano | findstr :5001` (Windows)
+2. Check container logs: `docker compose logs backend`
+3. Try rebuilding containers: `docker compose down && docker compose build --no-cache && docker compose up`
+4. Check the logs for specific error messages
+
+#### PDF upload fails
+
+**Solution**:
+
+1. Verify the file is a valid PDF
+2. Check file size (must be under 50MB by default)
+3. Ensure the PDF contains extractable text (not just images)
+4. Check server logs for detailed error messages
+
+#### Query returns no answer
+
+**Solution**:
+
+1. Verify a document has been uploaded successfully
+2. Try rephrasing your question
+3. Check if the document contains relevant information
+4. Increase `TOP_K_DOCUMENTS` in `config.py` for broader search
+
+### Logging
+
+The application logs important events to the console:
+
+- **INFO**: Normal operations (PDF processing, queries)
+- **WARNING**: Non-critical issues
+- **ERROR**: Critical errors with stack traces
+
+To view logs:
+
+```bash
+# View all logs
+docker compose logs -f
+
+# View backend logs only
+docker compose logs -f backend
+```
+
+### Getting Help
+
+1. View logs with `docker compose logs -f`
+2. Visit the health endpoint: `http://localhost:5001/health`
+3. Review the error messages in API responses
+4. Check the interactive documentation: `http://localhost:5001/docs`
+
+## Production Deployment
+
+### Checklist
+
+Before deploying to production:
+
+- [ ] Configure secure `KEYCLOAK_CLIENT_SECRET`
+- [ ] Set up proper `BASE_URL` for enterprise endpoints
+- [ ] Configure specific CORS origins (not `["*"]`)
+- [ ] Enable HTTPS
+- [ ] Set up monitoring and alerting
+- [ ] Configure logging to files
+- [ ] Implement rate limiting
+- [ ] Verify Keycloak authentication is working
+- [ ] Set up backup for vector stores
+- [ ] Configure firewall rules
+- [ ] Use environment-specific configuration
+
+### Docker Compose Production Deployment
+
+The provided `docker-compose.yml` already includes both API and UI services. For production:
+
+1. **Set up environment variables** in `api/.env`:
+
+```bash
+# Enterprise/Keycloak Configuration
+BASE_URL=https://api.example.com
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=api
+KEYCLOAK_CLIENT_SECRET=your_production_client_secret
+
+# Model Configuration
+EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
+INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
+EMBEDDING_MODEL_NAME=bge-base-en-v1.5
+INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
+```
+
+2. **Run in detached mode**:
+
+```bash
+docker compose up -d --build
+```
+
+3. **Monitor logs**:
+
+```bash
+docker compose logs -f
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues, questions, or contributions:
+
+1. Check this README for solutions
+2. Review the troubleshooting section
+3. Check container logs: `docker compose logs -f`
+4. Visit the interactive docs at `http://localhost:5001/docs`
+
+---
+
+**Version**: 2.0.0  
+**Last Updated**: 2025  
+**API Documentation**: http://localhost:5001/docs
diff --git a/RAGChatbot/api/config.py b/RAGChatbot/api/config.py
new file mode 100644
index 0000000000..190375c0f3
--- /dev/null
+++ b/RAGChatbot/api/config.py
@@ -0,0 +1,58 @@
+"""
+Configuration settings for RAG Chatbot API
+"""
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# API Configuration
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+
+# Custom API Configuration
+BASE_URL = os.getenv("BASE_URL", "https://api.example.com")
+KEYCLOAK_REALM = os.getenv("KEYCLOAK_REALM", "master")
+KEYCLOAK_CLIENT_ID = os.getenv("KEYCLOAK_CLIENT_ID", "api")
+KEYCLOAK_CLIENT_SECRET = os.getenv("KEYCLOAK_CLIENT_SECRET")
+
+# Model Configuration
+EMBEDDING_MODEL_ENDPOINT = os.getenv("EMBEDDING_MODEL_ENDPOINT", "bge-base-en-v1.5")
+INFERENCE_MODEL_ENDPOINT = os.getenv("INFERENCE_MODEL_ENDPOINT", "Llama-3.1-8B-Instruct")
+EMBEDDING_MODEL_NAME = os.getenv("EMBEDDING_MODEL_NAME", "bge-base-en-v1.5")
+INFERENCE_MODEL_NAME = os.getenv("INFERENCE_MODEL_NAME", "meta-llama/Llama-3.1-8B-Instruct")
+
+# Validate required configuration
+if not OPENAI_API_KEY and not KEYCLOAK_CLIENT_SECRET:
+    raise ValueError("Either OPENAI_API_KEY or KEYCLOAK_CLIENT_SECRET must be set in environment variables")
+
+# Application Settings
+APP_TITLE = "RAG QnA Chatbot"
+APP_DESCRIPTION = "A RAG-based chatbot API using LangChain and FAISS"
+APP_VERSION = "2.0.0"
+
+# File Upload Settings
+MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB
+ALLOWED_EXTENSIONS = {".pdf"}
+
+# Vector Store Settings
+VECTOR_STORE_PATH = "./dmv_index"
+
+# Text Splitting Settings
+CHUNK_SIZE = 1000
+CHUNK_OVERLAP = 200
+SEPARATORS = ["\n\n", "\n", " ", ""]
+
+# Retrieval Settings
+TOP_K_DOCUMENTS = 4
+LLM_MODEL = "gpt-3.5-turbo"
+LLM_TEMPERATURE = 0
+EMBEDDING_MODEL = "text-embedding-ada-002"
+
+# CORS Settings
+CORS_ALLOW_ORIGINS = ["*"]  # Update with specific origins in production
+CORS_ALLOW_CREDENTIALS = True
+CORS_ALLOW_METHODS = ["*"]
+CORS_ALLOW_HEADERS = ["*"]
+
diff --git a/RAGChatbot/api/models.py b/RAGChatbot/api/models.py
new file mode 100644
index 0000000000..1daafe9e89
--- /dev/null
+++ b/RAGChatbot/api/models.py
@@ -0,0 +1,61 @@
+"""
+Pydantic models for request/response validation
+"""
+
+from pydantic import BaseModel, Field
+
+
+class QueryRequest(BaseModel):
+    """Request model for querying documents"""
+    query: str = Field(..., min_length=1, description="Natural language question")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "query": "What are the main topics covered in the document?"
+            }
+        }
+
+
+class UploadResponse(BaseModel):
+    """Response model for PDF upload"""
+    message: str = Field(..., description="Success message")
+    num_chunks: int = Field(..., description="Number of chunks created")
+    status: str = Field(..., description="Operation status")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "message": "Successfully uploaded and processed 'document.pdf'",
+                "num_chunks": 45,
+                "status": "success"
+            }
+        }
+
+
+class QueryResponse(BaseModel):
+    """Response model for document queries"""
+    answer: str = Field(..., description="Answer to the query")
+    query: str = Field(..., description="Original query")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "answer": "The main topics covered in the document are...",
+                "query": "What are the main topics covered in the document?"
+            }
+        }
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check"""
+    status: str = Field(..., description="Health status")
+    vectorstore_available: bool = Field(..., description="Whether vectorstore is loaded")
+    openai_key_configured: bool = Field(..., description="Whether OpenAI key is configured")
+
+
+class DeleteResponse(BaseModel):
+    """Response model for delete operations"""
+    message: str = Field(..., description="Result message")
+    status: str = Field(..., description="Operation status")
+
diff --git a/RAGChatbot/api/requirements.txt b/RAGChatbot/api/requirements.txt
new file mode 100644
index 0000000000..8a77040e54
--- /dev/null
+++ b/RAGChatbot/api/requirements.txt
@@ -0,0 +1,15 @@
+fastapi>=0.109.0
+uvicorn[standard]>=0.27.0
+python-dotenv>=1.0.0
+langchain>=0.1.0
+langchain-community>=0.0.10
+langchain-openai>=0.0.5
+faiss-cpu>=1.7.4
+pypdf>=4.0.0
+openai>=1.10.0
+python-multipart>=0.0.6
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+cryptography>=3.1.0
+httpx>=0.24.0
+requests>=2.31.0
\ No newline at end of file
diff --git a/RAGChatbot/api/server.py b/RAGChatbot/api/server.py
new file mode 100644
index 0000000000..1aac509da1
--- /dev/null
+++ b/RAGChatbot/api/server.py
@@ -0,0 +1,229 @@
+"""
+FastAPI server with routes for RAG Chatbot API
+"""
+
+import os
+import tempfile
+import logging
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, File, UploadFile, HTTPException, status
+from fastapi.middleware.cors import CORSMiddleware
+
+import config
+from models import (
+    QueryRequest, UploadResponse, QueryResponse,
+    HealthResponse, DeleteResponse
+)
+from services import (
+    validate_pdf_file, load_and_split_pdf,
+    store_in_vector_storage, load_vector_store, delete_vector_store,
+    query_documents
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Lifespan context manager for FastAPI app"""
+    # Startup
+    app.state.vectorstore = load_vector_store(config.OPENAI_API_KEY)
+    if app.state.vectorstore:
+        logger.info("✓ FAISS vector store loaded successfully")
+    else:
+        logger.info("! No existing vector store found. Please upload a PDF document.")
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down RAG Chatbot API")
+
+
+# Initialize FastAPI app
+app = FastAPI(
+    title=config.APP_TITLE,
+    description=config.APP_DESCRIPTION,
+    version=config.APP_VERSION,
+    lifespan=lifespan
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=config.CORS_ALLOW_ORIGINS,
+    allow_credentials=config.CORS_ALLOW_CREDENTIALS,
+    allow_methods=config.CORS_ALLOW_METHODS,
+    allow_headers=config.CORS_ALLOW_HEADERS,
+)
+
+
+# ==================== Routes ====================
+
+@app.get("/")
+def root():
+    """Health check endpoint"""
+    return {
+        "message": "RAG Chatbot API is running",
+        "version": config.APP_VERSION,
+        "status": "healthy",
+        "vectorstore_loaded": app.state.vectorstore is not None
+    }
+
+
+@app.get("/health", response_model=HealthResponse)
+def health_check():
+    """Detailed health check"""
+    return HealthResponse(
+        status="healthy",
+        vectorstore_available=app.state.vectorstore is not None,
+        openai_key_configured=bool(config.OPENAI_API_KEY)
+    )
+
+
+@app.post("/upload-pdf", response_model=UploadResponse)
+async def upload_pdf(file: UploadFile = File(...)):
+    """
+    Upload a PDF file, process it, create embeddings, and store in FAISS
+    
+    - **file**: PDF file to upload (max 50MB)
+    """
+    # Validate file
+    validate_pdf_file(file)
+    
+    tmp_path = None
+    try:
+        # Read file content
+        content = await file.read()
+        file_size = len(content)
+        
+        # Check file size
+        if file_size > config.MAX_FILE_SIZE:
+            raise HTTPException(
+                status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+                detail=f"File too large. Maximum size is {config.MAX_FILE_SIZE / (1024*1024)}MB"
+            )
+        
+        if file_size == 0:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Empty file uploaded"
+            )
+        
+        logger.info(f"Processing PDF: {file.filename} ({file_size / 1024:.2f} KB)")
+        
+        # Save to temporary file
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as tmp:
+            tmp.write(content)
+            tmp_path = tmp.name
+            logger.info(f"Saved to temporary path: {tmp_path}")
+        
+        # Load and split PDF
+        chunks = load_and_split_pdf(tmp_path)
+        
+        if not chunks:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="No text content could be extracted from the PDF"
+            )
+        
+        # Create embeddings and store in FAISS
+        vectorstore = store_in_vector_storage(chunks, config.OPENAI_API_KEY)
+        
+        # Update app state
+        app.state.vectorstore = vectorstore
+        
+        logger.info(f"✓ Successfully processed PDF: {file.filename}")
+        
+        return UploadResponse(
+            message=f"Successfully uploaded and processed '{file.filename}'",
+            num_chunks=len(chunks),
+            status="success"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error processing PDF: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing PDF: {str(e)}"
+        )
+    finally:
+        # Clean up temporary file
+        if tmp_path and os.path.exists(tmp_path):
+            try:
+                os.remove(tmp_path)
+                logger.info(f"Cleaned up temporary file: {tmp_path}")
+            except Exception as e:
+                logger.warning(f"Could not remove temporary file: {str(e)}")
+
+
+@app.post("/query", response_model=QueryResponse)
+def query_endpoint(request: QueryRequest):
+    """
+    Query the uploaded documents using RAG
+    
+    - **query**: Natural language question about the documents
+    """
+    if not app.state.vectorstore:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No documents uploaded. Please upload a PDF first using /upload-pdf endpoint."
+        )
+    
+    if not request.query or not request.query.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Query cannot be empty"
+        )
+    
+    try:
+        result = query_documents(
+            request.query,
+            app.state.vectorstore,
+            config.OPENAI_API_KEY
+        )
+        return QueryResponse(**result)
+    except Exception as e:
+        logger.error(f"Error processing query: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing query: {str(e)}"
+        )
+
+
+@app.delete("/vectorstore", response_model=DeleteResponse)
+def delete_vectorstore_endpoint():
+    """Delete the current vector store"""
+    try:
+        deleted = delete_vector_store()
+        app.state.vectorstore = None
+        
+        if deleted:
+            return DeleteResponse(
+                message="Vector store deleted successfully",
+                status="success"
+            )
+        else:
+            return DeleteResponse(
+                message="No vector store found to delete",
+                status="success"
+            )
+    except Exception as e:
+        logger.error(f"Error deleting vector store: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error deleting vector store: {str(e)}"
+        )
+
+
+# Entry point for running with uvicorn
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=5001)
+
diff --git a/RAGChatbot/api/services/__init__.py b/RAGChatbot/api/services/__init__.py
new file mode 100644
index 0000000000..2802bf9895
--- /dev/null
+++ b/RAGChatbot/api/services/__init__.py
@@ -0,0 +1,21 @@
+"""
+Services package for RAG Chatbot API
+"""
+
+from .pdf_service import load_and_split_pdf, validate_pdf_file
+from .vector_service import store_in_vector_storage, load_vector_store, delete_vector_store
+from .retrieval_service import build_retrieval_chain, query_documents
+from .api_client import APIClient, get_api_client
+
+__all__ = [
+    'load_and_split_pdf',
+    'validate_pdf_file',
+    'store_in_vector_storage',
+    'load_vector_store',
+    'delete_vector_store',
+    'build_retrieval_chain',
+    'query_documents',
+    'APIClient',
+    'get_api_client'
+]
+
diff --git a/RAGChatbot/api/services/api_client.py b/RAGChatbot/api/services/api_client.py
new file mode 100644
index 0000000000..111c737a9a
--- /dev/null
+++ b/RAGChatbot/api/services/api_client.py
@@ -0,0 +1,252 @@
+"""
+API Client for authentication and API calls
+Similar to simple-client/main.py implementation
+"""
+
+import logging
+import requests
+import httpx
+from typing import Optional
+import config
+
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+    """
+    Client for handling authentication and API calls
+    """
+    
+    def __init__(self):
+        self.base_url = config.BASE_URL
+        self.token = None
+        self.http_client = None
+        self._authenticate()
+    
+    def _authenticate(self) -> None:
+        """
+        Authenticate and obtain access token from Keycloak
+        """
+        token_url = f"{self.base_url}/token"
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": config.KEYCLOAK_CLIENT_ID,
+            "client_secret": config.KEYCLOAK_CLIENT_SECRET,
+        }
+        
+        try:
+            response = requests.post(token_url, data=payload, verify=False)
+            
+            if response.status_code == 200:
+                self.token = response.json().get("access_token")
+                logger.info(f"✓ Access token obtained: {self.token[:20]}..." if self.token else "Failed to get token")
+                
+                # Create httpx client with SSL verification disabled (like -k in curl)
+                self.http_client = httpx.Client(verify=False)
+                
+            else:
+                logger.error(f"Error obtaining token: {response.status_code} - {response.text}")
+                raise Exception(f"Authentication failed: {response.status_code}")
+                
+        except Exception as e:
+            logger.error(f"Error during authentication: {str(e)}")
+            raise
+    
+    def get_embedding_client(self):
+        """
+        Get OpenAI-style client for embeddings
+        Uses bge-base-en-v1.5 endpoint
+        """
+        from openai import OpenAI
+        
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{config.EMBEDDING_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+    
+    def get_inference_client(self):
+        """
+        Get OpenAI-style client for inference/completions
+        Uses Llama-3.1-8B-Instruct endpoint
+        """
+        from openai import OpenAI
+        
+        return OpenAI(
+            api_key=self.token,
+            base_url=f"{self.base_url}/{config.INFERENCE_MODEL_ENDPOINT}/v1",
+            http_client=self.http_client
+        )
+    
+    def embed_text(self, text: str) -> list:
+        """
+        Get embedding for text
+        Uses the bge-base-en-v1.5 embedding model
+        
+        Args:
+            text: Text to embed
+            
+        Returns:
+            List of embedding values
+        """
+        try:
+            client = self.get_embedding_client()
+            # Call the embeddings endpoint
+            response = client.embeddings.create(
+                model=config.EMBEDDING_MODEL_NAME,
+                input=text
+            )
+            return response.data[0].embedding
+        except Exception as e:
+            logger.error(f"Error generating embedding: {str(e)}")
+            raise
+    
+    def embed_texts(self, texts: list) -> list:
+        """
+        Get embeddings for multiple texts
+        Batches requests to avoid exceeding API limits (max batch size: 32)
+        
+        Args:
+            texts: List of texts to embed
+            
+        Returns:
+            List of embedding vectors
+        """
+        try:
+            BATCH_SIZE = 32  # Maximum allowed batch size
+            all_embeddings = []
+            client = self.get_embedding_client()
+            
+            # Process in batches of 32
+            for i in range(0, len(texts), BATCH_SIZE):
+                batch = texts[i:i + BATCH_SIZE]
+                logger.info(f"Processing embedding batch {i//BATCH_SIZE + 1}/{(len(texts) + BATCH_SIZE - 1)//BATCH_SIZE} ({len(batch)} texts)")
+                
+                response = client.embeddings.create(
+                    model=config.EMBEDDING_MODEL_NAME,
+                    input=batch
+                )
+                batch_embeddings = [data.embedding for data in response.data]
+                all_embeddings.extend(batch_embeddings)
+            
+            return all_embeddings
+        except Exception as e:
+            logger.error(f"Error generating embeddings: {str(e)}")
+            raise
+    
+    def complete(self, prompt: str, max_tokens: int = 50, temperature: float = 0) -> str:
+        """
+        Get completion from the inference model
+        Uses Llama-3.1-8B-Instruct for inference
+        
+        Args:
+            prompt: Input prompt
+            max_tokens: Maximum tokens to generate
+            temperature: Temperature for generation
+            
+        Returns:
+            Generated text
+        """
+        try:
+            client = self.get_inference_client()
+            logger.info(f"Calling inference client with model: {config.INFERENCE_MODEL_NAME}")
+            response = client.completions.create(
+                model=config.INFERENCE_MODEL_NAME,
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature
+            )
+            
+            # Handle response structure
+            if hasattr(response, 'choices') and len(response.choices) > 0:
+                choice = response.choices[0]
+                if hasattr(choice, 'text'):
+                    return choice.text
+                else:
+                    logger.error(f"Unexpected choice structure: {type(choice)}, {choice}")
+                    return str(choice)
+            else:
+                logger.error(f"Unexpected response: {type(response)}, {response}")
+                return ""
+        except Exception as e:
+            logger.error(f"Error generating completion: {str(e)}", exc_info=True)
+            raise
+    
+    def chat_complete(self, messages: list, max_tokens: int = 150, temperature: float = 0) -> str:
+        """
+        Get chat completion from the inference model
+        
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            max_tokens: Maximum tokens to generate
+            temperature: Temperature for generation
+            
+        Returns:
+            Generated text
+        """
+        try:
+            client = self.get_inference_client()
+            # Convert messages to a prompt for the completions endpoint
+            # (since Llama models use completions, not chat.completions)
+            prompt = ""
+            for msg in messages:
+                role = msg.get('role', 'user')
+                content = msg.get('content', '')
+                if role == 'system':
+                    prompt += f"System: {content}\n\n"
+                elif role == 'user':
+                    prompt += f"User: {content}\n\n"
+                elif role == 'assistant':
+                    prompt += f"Assistant: {content}\n\n"
+            prompt += "Assistant:"
+            
+            logger.info(f"Calling inference with prompt length: {len(prompt)}")
+            
+            response = client.completions.create(
+                model=config.INFERENCE_MODEL_NAME,
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature
+            )
+            
+            # Handle response structure
+            if hasattr(response, 'choices') and len(response.choices) > 0:
+                choice = response.choices[0]
+                if hasattr(choice, 'text'):
+                    return choice.text
+                elif hasattr(choice, 'message') and hasattr(choice.message, 'content'):
+                    return choice.message.content
+                else:
+                    logger.error(f"Unexpected response structure: {type(choice)}, {choice}")
+                    return str(choice)
+            else:
+                logger.error(f"Unexpected response: {type(response)}, {response}")
+                return ""
+        except Exception as e:
+            logger.error(f"Error generating chat completion: {str(e)}", exc_info=True)
+            raise
+    
+    def __del__(self):
+        """
+        Cleanup: close httpx client
+        """
+        if self.http_client:
+            self.http_client.close()
+
+
+# Global API client instance
+_api_client: Optional[APIClient] = None
+
+
+def get_api_client() -> APIClient:
+    """
+    Get or create the global API client instance
+    
+    Returns:
+        APIClient instance
+    """
+    global _api_client
+    if _api_client is None:
+        _api_client = APIClient()
+    return _api_client
+
diff --git a/RAGChatbot/api/services/pdf_service.py b/RAGChatbot/api/services/pdf_service.py
new file mode 100644
index 0000000000..9fbc2032af
--- /dev/null
+++ b/RAGChatbot/api/services/pdf_service.py
@@ -0,0 +1,86 @@
+"""
+PDF processing service
+Handles PDF validation, loading, and text splitting
+"""
+
+import logging
+from pathlib import Path
+from fastapi import UploadFile, HTTPException, status
+from langchain_community.document_loaders import PyPDFLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+logger = logging.getLogger(__name__)
+
+# Constants
+ALLOWED_EXTENSIONS = {".pdf"}
+MAX_FILE_SIZE = 50 * 1024 * 1024  # 50MB
+
+
+def validate_pdf_file(file: UploadFile) -> None:
+    """
+    Validate uploaded PDF file
+    
+    Args:
+        file: UploadFile object from FastAPI
+        
+    Raises:
+        HTTPException: If file validation fails
+    """
+    if not file.filename:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No filename provided"
+        )
+    
+    file_ext = Path(file.filename).suffix.lower()
+    if file_ext not in ALLOWED_EXTENSIONS:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid file type. Only PDF files are allowed. Got: {file_ext}"
+        )
+    
+    if not file.content_type or "pdf" not in file.content_type.lower():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid content type. Expected PDF, got: {file.content_type}"
+        )
+
+
+def load_and_split_pdf(path: str) -> list:
+    """
+    Load PDF and split into chunks using RecursiveCharacterTextSplitter
+    
+    Args:
+        path: Path to the PDF file
+        
+    Returns:
+        List of document chunks
+        
+    Raises:
+        ValueError: If no content can be extracted
+        Exception: For other processing errors
+    """
+    try:
+        # Load PDF documents
+        loader = PyPDFLoader(file_path=path)
+        documents = loader.load()
+        logger.info(f"Loaded {len(documents)} pages from PDF")
+        
+        if not documents:
+            raise ValueError("No content extracted from PDF")
+        
+        # Split text into chunks with better strategy
+        text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=1000,
+            chunk_overlap=200,
+            length_function=len,
+            separators=["\n\n", "\n", " ", ""]
+        )
+        chunks = text_splitter.split_documents(documents)
+        logger.info(f"Split into {len(chunks)} chunks")
+        
+        return chunks
+    except Exception as e:
+        logger.error(f"Error loading and splitting PDF: {str(e)}")
+        raise
+
diff --git a/RAGChatbot/api/services/retrieval_service.py b/RAGChatbot/api/services/retrieval_service.py
new file mode 100644
index 0000000000..a5efe82252
--- /dev/null
+++ b/RAGChatbot/api/services/retrieval_service.py
@@ -0,0 +1,231 @@
+"""
+Retrieval service
+Handles query processing and retrieval chain operations
+"""
+
+import logging
+from langchain_openai import ChatOpenAI
+from langchain_community.vectorstores import FAISS
+from langchain.chains.retrieval import create_retrieval_chain
+from langchain.chains.combine_documents import create_stuff_documents_chain
+from langchain import hub
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.language_models.llms import LLM
+from langchain_core.outputs import LLMResult, Generation
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage, BaseMessage
+from typing import List, Optional, Any
+import config
+
+logger = logging.getLogger(__name__)
+
+
+class CustomLLM(LLM):
+    """
+    Custom LLM class that uses the Llama-3.1-8B-Instruct endpoint
+    """
+    
+    @property
+    def _llm_type(self) -> str:
+        """Return type of LLM."""
+        return "custom_llm"
+    
+    def _call(
+        self,
+        prompt: str,
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Call the LLM on the given prompt."""
+        from .api_client import get_api_client
+        api_client = get_api_client()
+        return api_client.complete(prompt, max_tokens=kwargs.get('max_tokens', 150), temperature=kwargs.get('temperature', 0))
+
+
+class CustomChatModel(BaseChatModel):
+    """
+    Custom Chat Model that uses the Llama-3.1-8B-Instruct endpoint
+    """
+    
+    @property
+    def _llm_type(self) -> str:
+        """Return type of LLM."""
+        return "custom_chat"
+    
+    def _generate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> LLMResult:
+        """Generate response from messages."""
+        from .api_client import get_api_client
+        api_client = get_api_client()
+        
+        # Convert messages to a prompt string
+        # Build the prompt from all messages
+        prompt_parts = []
+        
+        for msg in messages:
+            if isinstance(msg, SystemMessage):
+                prompt_parts.append(f"System: {msg.content}")
+            elif isinstance(msg, HumanMessage):
+                prompt_parts.append(f"User: {msg.content}")
+            elif isinstance(msg, AIMessage):
+                prompt_parts.append(f"Assistant: {msg.content}")
+        
+        # Join all parts and add assistant prompt suffix
+        full_prompt = "\n\n".join(prompt_parts)
+        if not full_prompt.endswith("Assistant:"):
+            full_prompt += "\n\nAssistant:"
+        
+        logger.info(f"Sending prompt to LLM (length: {len(full_prompt)} chars)")
+        
+        # Use the complete method which directly sends the prompt
+        # This calls: Llama-3.1-8B-Instruct/v1/completions with prompt
+        response_text = api_client.complete(
+            full_prompt,
+            max_tokens=kwargs.get('max_tokens', 150),
+            temperature=kwargs.get('temperature', 0)
+        )
+        
+        generations = [Generation(text=response_text)]
+        return LLMResult(generations=[generations])
+
+
+def get_llm(api_key: str) -> BaseChatModel:
+    """
+    Get LLM instance (ChatOpenAI or CustomChatModel based on config)
+    
+    Args:
+        api_key: API key
+        
+    Returns:
+        LLM instance
+    """
+    # Check if using custom API
+    if hasattr(config, 'KEYCLOAK_CLIENT_SECRET') and config.KEYCLOAK_CLIENT_SECRET:
+        return CustomChatModel()
+    else:
+        # Fallback to OpenAI ChatOpenAI
+        return ChatOpenAI(
+            model="gpt-3.5-turbo",
+            temperature=0,
+            openai_api_key=api_key
+        )
+
+
+def build_retrieval_chain(vectorstore: FAISS, api_key: str):
+    """
+    Build retrieval chain with LLM (ChatOpenAI or CustomChatModel)
+    
+    Args:
+        vectorstore: FAISS vectorstore instance
+        api_key: API key
+        
+    Returns:
+        Configured retrieval chain
+        
+    Raises:
+        Exception: If chain building fails
+    """
+    try:
+        retrieval_qa_chat_prompt = hub.pull("langchain-ai/retrieval-qa-chat")
+        llm = get_llm(api_key)
+        combine_docs_chain = create_stuff_documents_chain(llm, retrieval_qa_chat_prompt)
+        retrieval_chain = create_retrieval_chain(
+            vectorstore.as_retriever(search_kwargs={"k": 4}),
+            combine_docs_chain
+        )
+        return retrieval_chain
+    except Exception as e:
+        logger.error(f"Error building retrieval chain: {str(e)}")
+        raise
+
+
+def query_documents(query: str, vectorstore: FAISS, api_key: str) -> dict:
+    """
+    Query the documents using RAG with custom embedding and inference
+    
+    Simple workflow:
+    1. Create embedding for the query
+    2. Search for similar documents in the vectorstore
+    3. Format the retrieved context
+    4. Summarize using Llama inference endpoint
+    
+    Args:
+        query: User's question
+        vectorstore: FAISS vectorstore instance
+        api_key: API key
+        
+    Returns:
+        Dictionary with answer and query
+        
+    Raises:
+        Exception: If query processing fails
+    """
+    try:
+        logger.info(f"Processing query: {query}")
+        
+        # Step 1: Create embedding for the query
+        logger.info("Creating query embedding...")
+        from .api_client import get_api_client
+        api_client = get_api_client()
+        
+        query_embedding = api_client.embed_text(query)
+        logger.info(f"Query embedding created (dimension: {len(query_embedding)})")
+        
+        # Step 2: Search for similar documents (similarity search)
+        logger.info("Searching for similar documents...")
+        similar_docs = vectorstore.similarity_search_by_vector(query_embedding, k=4)
+        logger.info(f"Found {len(similar_docs)} similar documents")
+        
+        if not similar_docs:
+            return {
+                "answer": "I couldn't find any relevant documents to answer your question.",
+                "query": query
+            }
+        
+        # Step 3: Format the retrieved context
+        context_parts = []
+        for i, doc in enumerate(similar_docs):
+            context_parts.append(f"Document {i+1}:\n{doc.page_content}")
+        
+        context = "\n\n".join(context_parts)
+        logger.info(f"Context length: {len(context)} characters")
+        
+        # Step 4: Create prompt for summarization using Llama
+        prompt = f"""Based on the following documents, provide a comprehensive summary that addresses the question.
+
+Documents:
+{context}
+
+Question: {query}
+
+Summary:"""
+        
+        logger.info(f"Calling Llama inference with prompt length: {len(prompt)}")
+        
+        # Call Llama inference endpoint for summarization
+        answer = api_client.complete(
+            prompt=prompt,
+            max_tokens=200,
+            temperature=0
+        )
+        
+        answer = answer.strip()
+        
+        if not answer:
+            answer = "I couldn't find a relevant answer in the documents."
+        
+        logger.info("✓ Query completed successfully")
+        
+        return {
+            "answer": answer,
+            "query": query
+        }
+    except Exception as e:
+        logger.error(f"Error processing query: {str(e)}", exc_info=True)
+        raise
+
diff --git a/RAGChatbot/api/services/vector_service.py b/RAGChatbot/api/services/vector_service.py
new file mode 100644
index 0000000000..516c969bd0
--- /dev/null
+++ b/RAGChatbot/api/services/vector_service.py
@@ -0,0 +1,152 @@
+"""
+Vector store service
+Handles FAISS vector store operations
+"""
+
+import os
+import logging
+import shutil
+from typing import Optional
+from langchain_openai import OpenAIEmbeddings
+from langchain_community.vectorstores import FAISS
+from langchain_core.embeddings import Embeddings
+import config
+
+logger = logging.getLogger(__name__)
+
+# Constants
+VECTOR_STORE_PATH = "./dmv_index"
+
+
+class CustomEmbeddings(Embeddings):
+    """
+    Custom embeddings class that uses the bge-base-en-v1.5 endpoint
+    """
+    
+    def __init__(self):
+        from .api_client import get_api_client
+        self.api_client = get_api_client()
+    
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        """
+        Embed multiple documents
+        Note: Batches are handled automatically by api_client (max batch size: 32)
+        
+        Args:
+            texts: List of texts to embed
+            
+        Returns:
+            List of embedding vectors
+        """
+        return self.api_client.embed_texts(texts)
+    
+    def embed_query(self, text: str) -> list[float]:
+        """
+        Embed a single query
+        
+        Args:
+            text: Text to embed
+            
+        Returns:
+            Embedding vector
+        """
+        return self.api_client.embed_text(text)
+
+
+def get_embeddings(api_key: str) -> Embeddings:
+    """
+    Create embeddings instance
+    
+    Args:
+        api_key: API key (for compatibility, not used with custom endpoint)
+        
+    Returns:
+        Embeddings instance (CustomEmbeddings if using custom API, OpenAIEmbeddings otherwise)
+    """
+    # Check if using custom API
+    if hasattr(config, 'KEYCLOAK_CLIENT_SECRET') and config.KEYCLOAK_CLIENT_SECRET:
+        return CustomEmbeddings()
+    else:
+        # Fallback to OpenAI
+        return OpenAIEmbeddings(
+            model="text-embedding-ada-002",
+            openai_api_key=api_key
+        )
+
+
+def store_in_vector_storage(chunks: list, api_key: str) -> FAISS:
+    """
+    Create embeddings and store in FAISS vector store
+    
+    Args:
+        chunks: List of document chunks
+        api_key: OpenAI API key
+        
+    Returns:
+        FAISS vectorstore instance
+        
+    Raises:
+        Exception: If storage operation fails
+    """
+    try:
+        embeddings = get_embeddings(api_key)
+        vectorstore = FAISS.from_documents(chunks, embeddings)
+        
+        # Ensure directory exists
+        os.makedirs(
+            os.path.dirname(VECTOR_STORE_PATH) if os.path.dirname(VECTOR_STORE_PATH) else ".",
+            exist_ok=True
+        )
+        vectorstore.save_local(VECTOR_STORE_PATH)
+        logger.info(f"Saved vector store to {VECTOR_STORE_PATH}")
+        
+        return vectorstore
+    except Exception as e:
+        logger.error(f"Error storing vectors: {str(e)}")
+        raise
+
+
+def load_vector_store(api_key: str) -> Optional[FAISS]:
+    """
+    Load existing FAISS vector store
+    
+    Args:
+        api_key: OpenAI API key
+        
+    Returns:
+        FAISS vectorstore instance or None if not found
+    """
+    try:
+        embeddings = get_embeddings(api_key)
+        vectorstore = FAISS.load_local(
+            VECTOR_STORE_PATH,
+            embeddings,
+            allow_dangerous_deserialization=True
+        )
+        logger.info("Loaded existing FAISS vector store")
+        return vectorstore
+    except Exception as e:
+        logger.warning(f"Could not load vector store: {str(e)}")
+        return None
+
+
+def delete_vector_store() -> bool:
+    """
+    Delete the vector store from disk
+    
+    Returns:
+        True if deleted successfully, False otherwise
+        
+    Raises:
+        Exception: If deletion fails
+    """
+    try:
+        if os.path.exists(VECTOR_STORE_PATH):
+            shutil.rmtree(VECTOR_STORE_PATH)
+            logger.info("Deleted vector store")
+            return True
+        return False
+    except Exception as e:
+        logger.error(f"Error deleting vector store: {str(e)}")
+        raise
+
diff --git a/RAGChatbot/api/test_api.py b/RAGChatbot/api/test_api.py
new file mode 100644
index 0000000000..ac4baf6be5
--- /dev/null
+++ b/RAGChatbot/api/test_api.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+Test script for RAG Chatbot API
+Tests PDF upload and query functionality
+
+Usage:
+    python test_api.py                    # Run basic tests
+    python test_api.py /path/to/file.pdf  # Run full tests with PDF upload
+"""
+
+import requests
+import sys
+import time
+from pathlib import Path
+
+BASE_URL = "http://localhost:5000"
+
+def print_status(message, status="info"):
+    """Print colored status messages"""
+    colors = {
+        "info": "\033[94m",  # Blue
+        "success": "\033[92m",  # Green
+        "error": "\033[91m",  # Red
+        "warning": "\033[93m"  # Yellow
+    }
+    reset = "\033[0m"
+    print(f"{colors.get(status, '')}{message}{reset}")
+
+
+def test_health_check():
+    """Test health check endpoint"""
+    print_status("\n1. Testing health check endpoint...", "info")
+    try:
+        response = requests.get(f"{BASE_URL}/")
+        response.raise_for_status()
+        data = response.json()
+        print_status(f"✓ Health check passed: {data['message']}", "success")
+        print(f"  Version: {data.get('version', 'N/A')}")
+        print(f"  Vectorstore loaded: {data.get('vectorstore_loaded', False)}")
+        return True
+    except Exception as e:
+        print_status(f"✗ Health check failed: {str(e)}", "error")
+        return False
+
+
+def test_detailed_health():
+    """Test detailed health endpoint"""
+    print_status("\n2. Testing detailed health endpoint...", "info")
+    try:
+        response = requests.get(f"{BASE_URL}/health")
+        response.raise_for_status()
+        data = response.json()
+        print_status("✓ Detailed health check passed", "success")
+        print(f"  Status: {data.get('status')}")
+        print(f"  Vectorstore available: {data.get('vectorstore_available')}")
+        print(f"  OpenAI key configured: {data.get('openai_key_configured')}")
+        return True
+    except Exception as e:
+        print_status(f"✗ Detailed health check failed: {str(e)}", "error")
+        return False
+
+
+def test_upload_pdf(pdf_path=None):
+    """Test PDF upload endpoint"""
+    print_status("\n3. Testing PDF upload...", "info")
+    
+    if pdf_path and Path(pdf_path).exists():
+        file_path = pdf_path
+    else:
+        print_status("  No PDF file provided. Skipping upload test.", "warning")
+        print_status("  To test upload, run: python test_api.py /path/to/file.pdf", "warning")
+        return None
+    
+    try:
+        print(f"  Uploading: {file_path}")
+        with open(file_path, 'rb') as f:
+            files = {'file': (Path(file_path).name, f, 'application/pdf')}
+            response = requests.post(f"{BASE_URL}/upload-pdf", files=files)
+            response.raise_for_status()
+            data = response.json()
+            
+        print_status(f"✓ Upload successful!", "success")
+        print(f"  Message: {data['message']}")
+        print(f"  Number of chunks: {data['num_chunks']}")
+        print(f"  Status: {data['status']}")
+        return True
+    except requests.exceptions.HTTPError as e:
+        print_status(f"✗ Upload failed: {e}", "error")
+        try:
+            error_detail = e.response.json()
+            print(f"  Error details: {error_detail}")
+        except:
+            pass
+        return False
+    except Exception as e:
+        print_status(f"✗ Upload failed: {str(e)}", "error")
+        return False
+
+
+def test_query(query="What is this document about?"):
+    """Test query endpoint"""
+    print_status("\n4. Testing query endpoint...", "info")
+    print(f"  Query: '{query}'")
+    
+    try:
+        response = requests.post(
+            f"{BASE_URL}/query",
+            json={"query": query}
+        )
+        response.raise_for_status()
+        data = response.json()
+        
+        print_status("✓ Query successful!", "success")
+        print(f"  Answer: {data['answer'][:200]}{'...' if len(data['answer']) > 200 else ''}")
+        return True
+    except requests.exceptions.HTTPError as e:
+        if e.response.status_code == 400:
+            print_status("✗ No documents uploaded yet. Upload a PDF first.", "warning")
+        else:
+            print_status(f"✗ Query failed: {e}", "error")
+            try:
+                error_detail = e.response.json()
+                print(f"  Error details: {error_detail}")
+            except:
+                pass
+        return False
+    except Exception as e:
+        print_status(f"✗ Query failed: {str(e)}", "error")
+        return False
+
+
+def test_invalid_upload():
+    """Test upload validation with invalid file"""
+    print_status("\n5. Testing upload validation...", "info")
+    
+    try:
+        # Try uploading a text file
+        files = {'file': ('test.txt', b'This is not a PDF', 'text/plain')}
+        response = requests.post(f"{BASE_URL}/upload-pdf", files=files)
+        
+        if response.status_code == 400:
+            print_status("✓ Validation working: Invalid file rejected correctly", "success")
+            return True
+        else:
+            print_status("✗ Validation issue: Invalid file was accepted", "error")
+            return False
+    except Exception as e:
+        print_status(f"✗ Validation test failed: {str(e)}", "error")
+        return False
+
+
+def main():
+    """Run all tests"""
+    print_status("=" * 60)
+    print_status("RAG Chatbot API Test Suite", "info")
+    print_status("=" * 60)
+    
+    # Check if server is running
+    print_status("\nChecking if server is running...", "info")
+    try:
+        requests.get(BASE_URL, timeout=2)
+    except requests.exceptions.RequestException:
+        print_status("✗ Server is not running!", "error")
+        print_status(f"Please start the server first:", "warning")
+        print_status(f"  cd /Users/raghavdarisi/projects/GenAISamples/rag-chatbot/api", "warning")
+        print_status(f"  uvicorn server:app --reload", "warning")
+        print_status(f"  OR: python server.py", "warning")
+        sys.exit(1)
+    
+    print_status("✓ Server is running", "success")
+    
+    # Get PDF path from command line if provided
+    pdf_path = sys.argv[1] if len(sys.argv) > 1 else None
+    
+    # Run tests
+    results = []
+    results.append(("Health Check", test_health_check()))
+    results.append(("Detailed Health", test_detailed_health()))
+    
+    upload_result = test_upload_pdf(pdf_path)
+    if upload_result is not None:
+        results.append(("PDF Upload", upload_result))
+        
+        if upload_result:
+            # Wait a moment for processing
+            time.sleep(1)
+            results.append(("Query", test_query()))
+            results.append(("Query 2", test_query("Summarize the main points")))
+    
+    results.append(("Validation", test_invalid_upload()))
+    
+    # Print summary
+    print_status("\n" + "=" * 60)
+    print_status("Test Summary", "info")
+    print_status("=" * 60)
+    
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for test_name, result in results:
+        status = "success" if result else "error"
+        symbol = "✓" if result else "✗"
+        print_status(f"{symbol} {test_name}", status)
+    
+    print_status(f"\nPassed: {passed}/{total}", "success" if passed == total else "warning")
+    
+    if pdf_path is None:
+        print_status("\nNote: PDF upload test was skipped", "warning")
+        print_status("To run full tests with PDF upload:", "info")
+        print_status(f"  python test_api.py /path/to/your/document.pdf", "info")
+
+
+if __name__ == "__main__":
+    main()
+
diff --git a/RAGChatbot/docker-compose.yml b/RAGChatbot/docker-compose.yml
new file mode 100644
index 0000000000..020d0c1656
--- /dev/null
+++ b/RAGChatbot/docker-compose.yml
@@ -0,0 +1,42 @@
+services:
+  # backend Gateway (Python)
+  backend:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+    container_name: backend
+    ports:
+      - "5001:5001"
+    env_file:
+      - ./api/.env
+    volumes:
+      - ./api:/app
+    networks:
+      - app_network
+    restart: unless-stopped
+
+
+  # Frontend (React)
+  frontend:
+    build:
+      context: ./ui
+      dockerfile: Dockerfile
+    container_name: frontend
+    ports:
+      - "3000:3000"
+    depends_on:
+      - backend
+    networks:
+      - app_network
+    restart: unless-stopped
+
+##################################
+# 🔗 Shared Network
+##################################
+networks:
+  app_network:
+    driver: bridge
+
+volumes:
+  audio-files:
+    driver: local
\ No newline at end of file
diff --git a/RAGChatbot/images/RAG Model System Design.png b/RAGChatbot/images/RAG Model System Design.png
new file mode 100644
index 0000000000..7838fe5870
Binary files /dev/null and b/RAGChatbot/images/RAG Model System Design.png differ
diff --git a/RAGChatbot/images/ui.png b/RAGChatbot/images/ui.png
new file mode 100644
index 0000000000..484703ba15
Binary files /dev/null and b/RAGChatbot/images/ui.png differ
diff --git a/RAGChatbot/ui/.gitignore b/RAGChatbot/ui/.gitignore
new file mode 100644
index 0000000000..d600b6c76d
--- /dev/null
+++ b/RAGChatbot/ui/.gitignore
@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
diff --git a/RAGChatbot/ui/Dockerfile b/RAGChatbot/ui/Dockerfile
new file mode 100644
index 0000000000..8a5acb3a82
--- /dev/null
+++ b/RAGChatbot/ui/Dockerfile
@@ -0,0 +1,20 @@
+FROM node:18
+
+# Set the working directory
+WORKDIR /app
+
+# Copy package.json and package-lock.json
+COPY package.json ./
+COPY package-lock.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy the rest of the application files
+COPY . .
+
+# Expose the port the app runs on
+EXPOSE 3000
+
+# Command to run the application
+CMD ["npm", "run", "dev", "--", "--host"]
\ No newline at end of file
diff --git a/RAGChatbot/ui/README.md b/RAGChatbot/ui/README.md
new file mode 100644
index 0000000000..532316281f
--- /dev/null
+++ b/RAGChatbot/ui/README.md
@@ -0,0 +1,189 @@
+# RAG Chatbot UI
+
+A clean and elegant React-based user interface for the RAG Chatbot application.
+
+## Features
+
+- PDF file upload with drag-and-drop support
+- Real-time chat interface
+- Modern, responsive design with Tailwind CSS
+- Built with Vite for fast development
+- Live status updates
+- Mobile-friendly
+
+## Quick Start
+
+The UI runs automatically when using Docker Compose. See the main project README for setup instructions.
+
+The UI will be available at `http://localhost:3000`
+
+## Development
+
+This UI runs as part of the Docker Compose setup. For local development without Docker, you can use the scripts below, but Docker Compose is the recommended approach.
+
+### Available Scripts (Local Development Only)
+
+```bash
+# Start development server with hot reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Preview production build
+npm run preview
+
+# Lint code
+npm run lint
+```
+
+### Project Structure
+
+```
+ui/
+├── src/
+│   ├── components/
+│   │   ├── Header.jsx          # App header
+│   │   ├── StatusBar.jsx       # Document status display
+│   │   ├── PDFUploader.jsx     # PDF upload component
+│   │   └── ChatInterface.jsx   # Chat UI
+│   ├── services/
+│   │   └── api.js              # API client
+│   ├── App.jsx                 # Main app component
+│   ├── main.jsx                # Entry point
+│   └── index.css               # Global styles
+├── public/                     # Static assets
+├── index.html                  # HTML template
+├── vite.config.js             # Vite configuration
+├── tailwind.config.js         # Tailwind CSS config
+└── package.json               # Dependencies
+```
+
+## Configuration
+
+When running with Docker Compose, the UI automatically connects to the backend. Configuration is handled through the docker-compose.yml file.
+
+## Usage
+
+1. **Start the application** using Docker Compose (from the `rag-chatbot` directory):
+
+   ```bash
+   docker compose up --build
+   ```
+
+2. **Upload a PDF**:
+
+   - Drag and drop a PDF file, or
+   - Click "Browse Files" to select a file
+   - Wait for processing to complete
+
+4. **Start chatting**:
+   - Type your question in the input field
+   - Press Enter or click Send
+   - Get AI-powered answers based on your document
+
+## Features in Detail
+
+### PDF Upload
+
+- Drag-and-drop support
+- File validation (PDF only, max 50MB)
+- Upload progress indicator
+- Success/error notifications
+
+### Chat Interface
+
+- Real-time messaging
+- Message history
+- Typing indicators
+- Timestamp display
+- Error handling
+
+### Status Bar
+
+- Document upload status
+- Progress tracking
+- Quick reset functionality
+
+## Building for Production
+
+```bash
+# Build the production bundle
+npm run build
+
+# The built files will be in the dist/ directory
+# Serve with any static file server
+```
+
+### Deploy with Docker Compose
+
+The UI is automatically deployed when using Docker Compose from the root `rag-chatbot` directory. The Dockerfile in this directory is used by the docker-compose.yml configuration.
+
+## Customization
+
+### Styling
+
+The UI uses Tailwind CSS. Customize colors and theme in `tailwind.config.js`:
+
+```javascript
+theme: {
+  extend: {
+    colors: {
+      primary: {
+        // Your custom colors
+      }
+    }
+  }
+}
+```
+
+### Backend Integration
+
+The UI communicates with the backend through `src/services/api.js`. When running with Docker Compose, the backend is automatically available.
+
+## Troubleshooting
+
+### Build Issues
+
+**Problem**: Build fails with dependency errors
+
+**Solution**:
+
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Styling Issues
+
+**Problem**: Styles not applying
+
+**Solution**:
+
+```bash
+# Rebuild Tailwind CSS
+npm run dev
+```
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Performance
+
+- Optimized bundle size with Vite
+- Code splitting for faster loads
+- Lazy loading of components
+- Efficient re-renders with React
+
+## License
+
+MIT
+
+---
+
+**Built with**: React, Vite, Tailwind CSS, Axios, and Lucide Icons
diff --git a/RAGChatbot/ui/index.html b/RAGChatbot/ui/index.html
new file mode 100644
index 0000000000..c6a3e65988
--- /dev/null
+++ b/RAGChatbot/ui/index.html
@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>RAG Chatbot</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>
+
diff --git a/RAGChatbot/ui/package.json b/RAGChatbot/ui/package.json
new file mode 100644
index 0000000000..c4249ab4f3
--- /dev/null
+++ b/RAGChatbot/ui/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "rag-chatbot-ui",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "axios": "^1.6.0",
+    "lucide-react": "^0.294.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.55.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.5",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.3.6",
+    "vite": "^5.0.8"
+  }
+}
+
diff --git a/RAGChatbot/ui/postcss.config.js b/RAGChatbot/ui/postcss.config.js
new file mode 100644
index 0000000000..b4a6220e2d
--- /dev/null
+++ b/RAGChatbot/ui/postcss.config.js
@@ -0,0 +1,7 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
+
diff --git a/RAGChatbot/ui/src/App.jsx b/RAGChatbot/ui/src/App.jsx
new file mode 100644
index 0000000000..42ab09fd23
--- /dev/null
+++ b/RAGChatbot/ui/src/App.jsx
@@ -0,0 +1,77 @@
+import { useState } from 'react'
+import ChatInterface from './components/ChatInterface'
+import PDFUploader from './components/PDFUploader'
+import Header from './components/Header'
+import StatusBar from './components/StatusBar'
+
+function App() {
+  const [documentUploaded, setDocumentUploaded] = useState(false)
+  const [documentName, setDocumentName] = useState('')
+  const [uploadProgress, setUploadProgress] = useState(0)
+  const [isUploading, setIsUploading] = useState(false)
+
+  const handleUploadSuccess = (fileName, numChunks) => {
+    setDocumentUploaded(true)
+    setDocumentName(fileName)
+    setUploadProgress(100)
+    setTimeout(() => {
+      setIsUploading(false)
+      setUploadProgress(0)
+    }, 1000)
+  }
+
+  const handleUploadStart = () => {
+    setIsUploading(true)
+    setUploadProgress(0)
+  }
+
+  const handleUploadProgress = (progress) => {
+    setUploadProgress(progress)
+  }
+
+  const handleReset = () => {
+    setDocumentUploaded(false)
+    setDocumentName('')
+    setUploadProgress(0)
+  }
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-blue-50 via-white to-purple-50">
+      <Header />
+      
+      <main className="container mx-auto px-4 py-8 max-w-6xl">
+        {/* Status Bar */}
+        <StatusBar 
+          documentUploaded={documentUploaded}
+          documentName={documentName}
+          isUploading={isUploading}
+          uploadProgress={uploadProgress}
+          onReset={handleReset}
+        />
+
+        <div className="grid grid-cols-1 lg:grid-cols-3 gap-6 mt-6">
+          {/* Left Panel - PDF Upload */}
+          <div className="lg:col-span-1">
+            <PDFUploader
+              onUploadSuccess={handleUploadSuccess}
+              onUploadStart={handleUploadStart}
+              onUploadProgress={handleUploadProgress}
+              documentUploaded={documentUploaded}
+            />
+          </div>
+
+          {/* Right Panel - Chat Interface */}
+          <div className="lg:col-span-2">
+            <ChatInterface 
+              documentUploaded={documentUploaded}
+              documentName={documentName}
+            />
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}
+
+export default App
+
diff --git a/RAGChatbot/ui/src/components/ChatInterface.jsx b/RAGChatbot/ui/src/components/ChatInterface.jsx
new file mode 100644
index 0000000000..ee26d0a02a
--- /dev/null
+++ b/RAGChatbot/ui/src/components/ChatInterface.jsx
@@ -0,0 +1,184 @@
+import { useState, useRef, useEffect } from 'react'
+import { Send, Bot, User, AlertCircle } from 'lucide-react'
+import { queryDocument } from '../services/api'
+
+export default function ChatInterface({ documentUploaded, documentName }) {
+  const [messages, setMessages] = useState([])
+  const [input, setInput] = useState('')
+  const [isLoading, setIsLoading] = useState(false)
+  const messagesEndRef = useRef(null)
+
+  const scrollToBottom = () => {
+    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" })
+  }
+
+  useEffect(() => {
+    scrollToBottom()
+  }, [messages])
+
+  useEffect(() => {
+    // Reset messages when document changes
+    if (documentUploaded) {
+      setMessages([
+        {
+          type: 'bot',
+          content: `Document "${documentName}" has been uploaded successfully! You can now ask me questions about it.`,
+          timestamp: new Date()
+        }
+      ])
+    } else {
+      setMessages([])
+    }
+  }, [documentUploaded, documentName])
+
+  const handleSubmit = async (e) => {
+    e.preventDefault()
+    
+    if (!input.trim() || !documentUploaded) return
+
+    const userMessage = {
+      type: 'user',
+      content: input,
+      timestamp: new Date()
+    }
+
+    setMessages(prev => [...prev, userMessage])
+    setInput('')
+    setIsLoading(true)
+
+    try {
+      const response = await queryDocument(input)
+      
+      const botMessage = {
+        type: 'bot',
+        content: response.answer,
+        timestamp: new Date()
+      }
+      
+      setMessages(prev => [...prev, botMessage])
+    } catch (error) {
+      const errorMessage = {
+        type: 'error',
+        content: error.message || 'Failed to get response. Please try again.',
+        timestamp: new Date()
+      }
+      setMessages(prev => [...prev, errorMessage])
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 flex flex-col h-[600px]">
+      {/* Chat Header */}
+      <div className="border-b border-gray-200 p-4">
+        <h2 className="text-lg font-semibold text-gray-800 flex items-center space-x-2">
+          <Bot className="w-5 h-5 text-purple-500" />
+          <span>Chat Assistant</span>
+        </h2>
+        <p className="text-sm text-gray-500 mt-1">
+          {documentUploaded 
+            ? 'Ask questions about your document' 
+            : 'Upload a document to start chatting'}
+        </p>
+      </div>
+
+      {/* Messages Container */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-4 scrollbar-hide">
+        {!documentUploaded && messages.length === 0 && (
+          <div className="h-full flex items-center justify-center">
+            <div className="text-center space-y-3">
+              <Bot className="w-16 h-16 text-gray-300 mx-auto" />
+              <p className="text-gray-500">Upload a PDF document to start chatting</p>
+            </div>
+          </div>
+        )}
+
+        {messages.map((message, index) => (
+          <div
+            key={index}
+            className={`flex items-start space-x-3 ${
+              message.type === 'user' ? 'flex-row-reverse space-x-reverse' : ''
+            }`}
+          >
+            <div className={`flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center ${
+              message.type === 'user' 
+                ? 'bg-gradient-to-br from-blue-500 to-purple-600' 
+                : message.type === 'error'
+                ? 'bg-red-500'
+                : 'bg-gray-200'
+            }`}>
+              {message.type === 'user' ? (
+                <User className="w-5 h-5 text-white" />
+              ) : message.type === 'error' ? (
+                <AlertCircle className="w-5 h-5 text-white" />
+              ) : (
+                <Bot className="w-5 h-5 text-gray-600" />
+              )}
+            </div>
+
+            <div className={`flex-1 max-w-[80%] ${
+              message.type === 'user' ? 'items-end' : 'items-start'
+            }`}>
+              <div className={`rounded-lg p-3 ${
+                message.type === 'user'
+                  ? 'bg-gradient-to-br from-blue-500 to-purple-600 text-white'
+                  : message.type === 'error'
+                  ? 'bg-red-50 border border-red-200 text-red-700'
+                  : 'bg-gray-100 text-gray-800'
+              }`}>
+                <p className="text-sm whitespace-pre-wrap">{message.content}</p>
+              </div>
+              <p className="text-xs text-gray-400 mt-1">
+                {message.timestamp.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })}
+              </p>
+            </div>
+          </div>
+        ))}
+
+        {isLoading && (
+          <div className="flex items-start space-x-3">
+            <div className="flex-shrink-0 w-8 h-8 rounded-full bg-gray-200 flex items-center justify-center">
+              <Bot className="w-5 h-5 text-gray-600" />
+            </div>
+            <div className="bg-gray-100 rounded-lg p-3">
+              <div className="flex space-x-2">
+                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style={{ animationDelay: '0ms' }}></div>
+                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style={{ animationDelay: '150ms' }}></div>
+                <div className="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style={{ animationDelay: '300ms' }}></div>
+              </div>
+            </div>
+          </div>
+        )}
+
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Input Form */}
+      <div className="border-t border-gray-200 p-4">
+        <form onSubmit={handleSubmit} className="flex space-x-2">
+          <input
+            type="text"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder={documentUploaded ? "Ask a question..." : "Upload a document first..."}
+            disabled={!documentUploaded || isLoading}
+            className="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100 disabled:cursor-not-allowed"
+          />
+          <button
+            type="submit"
+            disabled={!documentUploaded || !input.trim() || isLoading}
+            className="px-6 py-2 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-lg hover:from-blue-600 hover:to-purple-700 disabled:opacity-50 disabled:cursor-not-allowed transition-all font-medium shadow-sm flex items-center space-x-2"
+          >
+            <Send className="w-4 h-4" />
+            <span>Send</span>
+          </button>
+        </form>
+        <p className="text-xs text-gray-500 mt-2">
+          Press Enter to send • The AI will answer based on your uploaded document
+        </p>
+      </div>
+    </div>
+  )
+}
+
diff --git a/RAGChatbot/ui/src/components/Header.jsx b/RAGChatbot/ui/src/components/Header.jsx
new file mode 100644
index 0000000000..0cfd2b11ce
--- /dev/null
+++ b/RAGChatbot/ui/src/components/Header.jsx
@@ -0,0 +1,28 @@
+import { MessageSquare, FileText } from 'lucide-react'
+
+export default function Header() {
+  return (
+    <header className="bg-white border-b border-gray-200 shadow-sm">
+      <div className="container mx-auto px-4 py-4 max-w-6xl">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center space-x-3">
+            <div className="bg-gradient-to-br from-blue-500 to-purple-600 p-2 rounded-lg">
+              <MessageSquare className="w-6 h-6 text-white" />
+            </div>
+            <div>
+              <h1 className="text-2xl font-bold bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
+                RAG Chatbot
+              </h1>
+              <p className="text-sm text-gray-500">Ask questions about your documents</p>
+            </div>
+          </div>
+          
+          <div className="flex items-center space-x-2 text-sm text-gray-500">
+            <FileText className="w-4 h-4" />
+          </div>
+        </div>
+      </div>
+    </header>
+  )
+}
+
diff --git a/RAGChatbot/ui/src/components/PDFUploader.jsx b/RAGChatbot/ui/src/components/PDFUploader.jsx
new file mode 100644
index 0000000000..e6a549f42e
--- /dev/null
+++ b/RAGChatbot/ui/src/components/PDFUploader.jsx
@@ -0,0 +1,155 @@
+import { useState, useRef } from 'react'
+import { Upload, FileText, CheckCircle, AlertCircle } from 'lucide-react'
+import { uploadPDF } from '../services/api'
+
+export default function PDFUploader({ onUploadSuccess, onUploadStart, onUploadProgress, documentUploaded }) {
+  const [dragActive, setDragActive] = useState(false)
+  const [error, setError] = useState('')
+  const fileInputRef = useRef(null)
+
+  const handleDrag = (e) => {
+    e.preventDefault()
+    e.stopPropagation()
+    if (e.type === "dragenter" || e.type === "dragover") {
+      setDragActive(true)
+    } else if (e.type === "dragleave") {
+      setDragActive(false)
+    }
+  }
+
+  const handleDrop = async (e) => {
+    e.preventDefault()
+    e.stopPropagation()
+    setDragActive(false)
+    
+    if (e.dataTransfer.files && e.dataTransfer.files[0]) {
+      await handleFile(e.dataTransfer.files[0])
+    }
+  }
+
+  const handleChange = async (e) => {
+    e.preventDefault()
+    if (e.target.files && e.target.files[0]) {
+      await handleFile(e.target.files[0])
+    }
+  }
+
+  const handleFile = async (file) => {
+    setError('')
+    
+    // Validate file type
+    if (!file.name.endsWith('.pdf')) {
+      setError('Please upload a PDF file')
+      return
+    }
+
+    // Validate file size (50MB)
+    if (file.size > 50 * 1024 * 1024) {
+      setError('File size must be less than 50MB')
+      return
+    }
+
+    onUploadStart()
+    
+    try {
+      // Simulate progress
+      onUploadProgress(30)
+      
+      const result = await uploadPDF(file)
+      
+      onUploadProgress(90)
+      
+      onUploadSuccess(file.name, result.num_chunks)
+      setError('')
+    } catch (err) {
+      setError(err.message || 'Failed to upload file')
+      onUploadProgress(0)
+    }
+  }
+
+  const handleButtonClick = () => {
+    fileInputRef.current?.click()
+  }
+
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-6">
+      <div className="mb-4">
+        <h2 className="text-lg font-semibold text-gray-800 flex items-center space-x-2">
+          <FileText className="w-5 h-5 text-blue-500" />
+          <span>Upload Document</span>
+        </h2>
+        <p className="text-sm text-gray-500 mt-1">
+          Upload a PDF to start asking questions
+        </p>
+      </div>
+
+      <div
+        className={`relative border-2 border-dashed rounded-lg p-8 text-center transition-all ${
+          dragActive 
+            ? 'border-blue-500 bg-blue-50' 
+            : documentUploaded
+            ? 'border-green-300 bg-green-50'
+            : 'border-gray-300 hover:border-gray-400'
+        }`}
+        onDragEnter={handleDrag}
+        onDragLeave={handleDrag}
+        onDragOver={handleDrag}
+        onDrop={handleDrop}
+      >
+        <input
+          ref={fileInputRef}
+          type="file"
+          className="hidden"
+          accept=".pdf"
+          onChange={handleChange}
+        />
+
+        {documentUploaded ? (
+          <div className="space-y-3">
+            <CheckCircle className="w-12 h-12 text-green-500 mx-auto" />
+            <p className="text-green-700 font-medium">Document uploaded successfully!</p>
+            <button
+              onClick={handleButtonClick}
+              className="mt-2 px-4 py-2 text-sm text-blue-600 hover:bg-blue-50 rounded-lg transition-colors"
+            >
+              Upload another document
+            </button>
+          </div>
+        ) : (
+          <div className="space-y-3">
+            <Upload className="w-12 h-12 text-gray-400 mx-auto" />
+            <div>
+              <p className="text-gray-600 font-medium">Drop your PDF here</p>
+              <p className="text-sm text-gray-500">or</p>
+            </div>
+            <button
+              onClick={handleButtonClick}
+              className="px-6 py-2 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-lg hover:from-blue-600 hover:to-purple-700 transition-all font-medium shadow-sm"
+            >
+              Browse Files
+            </button>
+            <p className="text-xs text-gray-500">PDF files only, max 50MB</p>
+          </div>
+        )}
+      </div>
+
+      {error && (
+        <div className="mt-4 p-3 bg-red-50 border border-red-200 rounded-lg flex items-start space-x-2">
+          <AlertCircle className="w-5 h-5 text-red-500 flex-shrink-0 mt-0.5" />
+          <p className="text-sm text-red-700">{error}</p>
+        </div>
+      )}
+
+      <div className="mt-6 space-y-2">
+        <h3 className="text-sm font-medium text-gray-700">Instructions:</h3>
+        <ul className="text-xs text-gray-600 space-y-1 list-disc list-inside">
+          <li>Upload a PDF document (max 50MB)</li>
+          <li>Wait for processing to complete</li>
+          <li>Start asking questions in the chat</li>
+          <li>Get intelligent answers based on your document</li>
+        </ul>
+      </div>
+    </div>
+  )
+}
+
diff --git a/RAGChatbot/ui/src/components/StatusBar.jsx b/RAGChatbot/ui/src/components/StatusBar.jsx
new file mode 100644
index 0000000000..2957d014c5
--- /dev/null
+++ b/RAGChatbot/ui/src/components/StatusBar.jsx
@@ -0,0 +1,54 @@
+import { CheckCircle, AlertCircle, Loader, Trash2 } from 'lucide-react'
+
+export default function StatusBar({ documentUploaded, documentName, isUploading, uploadProgress, onReset }) {
+  return (
+    <div className="bg-white rounded-lg shadow-sm border border-gray-200 p-4">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center space-x-3">
+          {isUploading && (
+            <>
+              <Loader className="w-5 h-5 text-blue-500 animate-spin" />
+              <div className="flex-1">
+                <p className="text-sm font-medium text-gray-700">Uploading and processing...</p>
+                <div className="w-64 bg-gray-200 rounded-full h-2 mt-1">
+                  <div 
+                    className="bg-blue-500 h-2 rounded-full transition-all duration-300"
+                    style={{ width: `${uploadProgress}%` }}
+                  ></div>
+                </div>
+              </div>
+            </>
+          )}
+          
+          {!isUploading && documentUploaded && (
+            <>
+              <CheckCircle className="w-5 h-5 text-green-500" />
+              <div>
+                <p className="text-sm font-medium text-gray-700">Document Ready</p>
+                <p className="text-xs text-gray-500">{documentName}</p>
+              </div>
+            </>
+          )}
+          
+          {!isUploading && !documentUploaded && (
+            <>
+              <AlertCircle className="w-5 h-5 text-amber-500" />
+              <p className="text-sm font-medium text-gray-700">No document uploaded</p>
+            </>
+          )}
+        </div>
+
+        {documentUploaded && !isUploading && (
+          <button
+            onClick={onReset}
+            className="flex items-center space-x-2 px-3 py-1.5 text-sm text-red-600 hover:bg-red-50 rounded-lg transition-colors"
+          >
+            <Trash2 className="w-4 h-4" />
+            <span>Clear</span>
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
diff --git a/RAGChatbot/ui/src/index.css b/RAGChatbot/ui/src/index.css
new file mode 100644
index 0000000000..a523f51e54
--- /dev/null
+++ b/RAGChatbot/ui/src/index.css
@@ -0,0 +1,34 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+    monospace;
+}
+
+@layer utilities {
+  .scrollbar-hide::-webkit-scrollbar {
+    display: none;
+  }
+  
+  .scrollbar-hide {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+}
+
diff --git a/RAGChatbot/ui/src/main.jsx b/RAGChatbot/ui/src/main.jsx
new file mode 100644
index 0000000000..299bc52310
--- /dev/null
+++ b/RAGChatbot/ui/src/main.jsx
@@ -0,0 +1,11 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.jsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
+
diff --git a/RAGChatbot/ui/src/services/api.js b/RAGChatbot/ui/src/services/api.js
new file mode 100644
index 0000000000..87ffb0667d
--- /dev/null
+++ b/RAGChatbot/ui/src/services/api.js
@@ -0,0 +1,85 @@
+import axios from 'axios'
+
+// API base URL - uses Vite proxy in development (proxies to localhost:5000)
+const API_BASE_URL = import.meta.env.VITE_API_URL || '/api'
+
+const api = axios.create({
+  baseURL: API_BASE_URL,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+})
+
+/**
+ * Upload a PDF file to the API
+ * @param {File} file - The PDF file to upload
+ * @returns {Promise} Response with upload status and chunk count
+ */
+export const uploadPDF = async (file) => {
+  const formData = new FormData()
+  formData.append('file', file)
+
+  try {
+    const response = await api.post('/upload-pdf', formData, {
+      headers: {
+        'Content-Type': 'multipart/form-data',
+      },
+    })
+    return response.data
+  } catch (error) {
+    console.error('Upload error:', error)
+    throw new Error(
+      error.response?.data?.detail || 'Failed to upload PDF. Please try again.'
+    )
+  }
+}
+
+/**
+ * Query the uploaded document
+ * @param {string} query - The question to ask
+ * @returns {Promise} Response with the answer
+ */
+export const queryDocument = async (query) => {
+  try {
+    const response = await api.post('/query', { query })
+    return response.data
+  } catch (error) {
+    console.error('Query error:', error)
+    throw new Error(
+      error.response?.data?.detail || 'Failed to get response. Please try again.'
+    )
+  }
+}
+
+/**
+ * Check API health
+ * @returns {Promise} Health status
+ */
+export const checkHealth = async () => {
+  try {
+    const response = await api.get('/health')
+    return response.data
+  } catch (error) {
+    console.error('Health check error:', error)
+    throw new Error('API is not available')
+  }
+}
+
+/**
+ * Delete the vector store
+ * @returns {Promise} Deletion status
+ */
+export const deleteVectorStore = async () => {
+  try {
+    const response = await api.delete('/vectorstore')
+    return response.data
+  } catch (error) {
+    console.error('Delete error:', error)
+    throw new Error(
+      error.response?.data?.detail || 'Failed to delete vector store'
+    )
+  }
+}
+
+export default api
+
diff --git a/RAGChatbot/ui/tailwind.config.js b/RAGChatbot/ui/tailwind.config.js
new file mode 100644
index 0000000000..037cbd7203
--- /dev/null
+++ b/RAGChatbot/ui/tailwind.config.js
@@ -0,0 +1,27 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: '#f0f9ff',
+          100: '#e0f2fe',
+          200: '#bae6fd',
+          300: '#7dd3fc',
+          400: '#38bdf8',
+          500: '#0ea5e9',
+          600: '#0284c7',
+          700: '#0369a1',
+          800: '#075985',
+          900: '#0c4a6e',
+        }
+      }
+    },
+  },
+  plugins: [],
+}
+
diff --git a/RAGChatbot/ui/vite.config.js b/RAGChatbot/ui/vite.config.js
new file mode 100644
index 0000000000..a20f408af9
--- /dev/null
+++ b/RAGChatbot/ui/vite.config.js
@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: true,
+    port: 3000,
+    proxy: {
+      '/api': {
+        target: 'http://backend:5001',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, '')
+      }
+    }
+  }
+})
+