# 🏗️ System Architecture & Flow Diagrams

## System Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     STREAMLIT WEB UI                        │
│                      (app.py - 450 lines)                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │ Task Selection   │  │ Configuration    │                 │
│  │ - Paper Analysis │  │ - Docker Toggle  │                 │
│  │ - Stock Market   │  │ - Temp Slider    │                 │
│  │ - Web Research   │  │ - Max Retries    │                 │
│  │ - Custom Task    │  │ - Settings Panel │                 │
│  └──────────────────┘  └──────────────────┘                 │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │        Conversation Viewer & History                 │   │
│  │  - Message Display  - JSON Export  - Statistics     │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   BACKEND LAYER                             │
│               (backend.py - 300 lines)                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │    AutoGenAgentManager                               │   │
│  │  - Agent Initialization      - Error Recovery       │   │
│  │  - Chat Orchestration        - Performance Tracking │   │
│  │  - Config Loading            - History Management   │   │
│  └──────────────────────────────────────────────────────┘   │
│                              │                                │
│                              ▼                                │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         TaskExecutor                                 │   │
│  │  - Paper Analysis Task      - Stock Market Task     │   │
│  │  - Web Research Task        - Custom Task           │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              UTILITIES & HELPERS                            │
│                 (utils.py - 350 lines)                      │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ Logger   │  │ Message  │  │Validator │  │ Error    │    │
│  │          │  │Processor │  │          │  │Handler   │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│                                                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
│  │Converter │  │Conversa- │  │Performance
│  │Manager   │  │tion Mgr  │  │Monitor   │                   │
│  └──────────┘  └──────────┘  └──────────┘                   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              CONFIGURATION LAYER                            │
│              (config.py - 120 lines)                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Configuration Class                                  │   │
│  │ - API Settings      - Task Templates                │   │
│  │ - Model Config      - Validation Rules              │   │
│  │ - Logging Config    - Environment Loading           │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│            AUTOGEN AGENTS (Microsoft AutoGen)               │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────────┐      ┌──────────────────────┐    │
│  │  AssistantAgent      │◄────►│  UserProxyAgent      │    │
│  │ (LLM-based)          │      │ (Code Executor)      │    │
│  │ - Conversation       │      │ - Code Execution     │    │
│  │ - Code Generation    │      │ - Result Feedback    │    │
│  │ - Analysis           │      │ - Termination Check  │    │
│  └──────────────────────┘      └──────────────────────┘    │
│                                                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              EXTERNAL SERVICES                              │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ OpenAI API   │  │ Web Search   │  │ Docker       │      │
│  │ - GPT-4      │  │ - Web Pages  │  │ - Isolation  │      │
│  │ - GPT-3.5    │  │ - Parsing    │  │ - Execution  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                                               │
└─────────────────────────────────────────────────────────────┘
```

## Data Flow Diagram

```
USER INPUT
    │
    ▼
┌─────────────────────────────┐
│ Input Validation & Sanitize │
│ - URL/Query validation      │
│ - Dangerous pattern removal │
│ - Length constraints        │
└─────────────────────────────┘
    │
    ▼ (Valid)
┌─────────────────────────────┐
│ Log User Request            │
│ - Message timestamp         │
│ - Request type              │
│ - User input (sanitized)    │
└─────────────────────────────┘
    │
    ▼
┌─────────────────────────────┐
│ Initiate Agent Chat         │
│ - Create task message       │
│ - Start performance timer   │
│ - Call assistant agent      │
└─────────────────────────────┘
    │
    ▼
┌─────────────────────────────┐
│ Agent Conversation          │
│ - Assistant analyzes task   │
│ - Generates code if needed  │
│ - User proxy executes code  │
│ - Multiple turns until done │
└─────────────────────────────┘
    │
    ├─── Success ───▶ ┌──────────────────────┐
    │                 │ Process Response     │
    │                 │ - Extract findings   │
    │                 │ - Format message     │
    │                 │ - Log result         │
    │                 │ - Update stats       │
    │                 └──────────────────────┘
    │
    └─── Error ─────▶ ┌──────────────────────┐
                      │ Handle Error         │
                      │ - Generate message   │
                      │ - Log error          │
                      │ - Update stats       │
                      │ - Suggest fix        │
                      └──────────────────────┘
         │
         ▼
    ┌─────────────────────────────┐
    │ Store in Conversation       │
    │ History                     │
    │ - Timestamp                 │
    │ - Task details              │
    │ - Response/Error            │
    │ - Duration                  │
    └─────────────────────────────┘
         │
         ▼
    ┌─────────────────────────────┐
    │ Return to UI                │
    │ - Display message           │
    │ - Update history            │
    │ - Refresh metrics           │
    │ - Show export options       │
    └─────────────────────────────┘
         │
         ▼
    USER SEES RESULTS
```

## Task Execution Flow

```
Task Selection
    │
    ├─ Paper Analysis ──────┬─ Extract URL
    │                        ├─ Validate format
    │                        ├─ Generate prompt
    │                        └─ Execute analysis
    │
    ├─ Stock Market ────────┬─ Validate query
    │                        ├─ Build search message
    │                        ├─ Execute search
    │                        └─ Return market data
    │
    ├─ Web Research ────────┬─ Validate topic
    │                        ├─ Build research message
    │                        ├─ Perform search
    │                        └─ Synthesize findings
    │
    └─ Custom Task ────────┬─ Validate task
                            ├─ Sanitize input
                            ├─ Execute directly
                            └─ Return results
         │
         ▼
    Agent Processing
         │
         ▼
    Return Results
```

## Class Hierarchy

```
BaseClass (implicit)
    │
    ├─── Config
    │    └─ Configuration management
    │
    ├─── Logger
    │    └─ Structured logging
    │
    ├─── MessageProcessor
    │    ├─ extract_code()
    │    ├─ clean_message()
    │    └─ extract_key_findings()
    │
    ├─── ConversationManager
    │    ├─ add_message()
    │    ├─ get_history()
    │    ├─ get_summary()
    │    └─ export_to_json()
    │
    ├─── ErrorHandler
    │    ├─ format_error()
    │    ├─ is_retryable()
    │    └─ get_user_friendly_message()
    │
    ├─── TaskValidator
    │    ├─ validate_url()
    │    ├─ validate_query()
    │    └─ sanitize_input()
    │
    ├─── PerformanceMonitor
    │    ├─ record_operation()
    │    └─ get_stats()
    │
    ├─── AutoGenAgentManager
    │    ├─ setup_agents()
    │    ├─ initiate_chat()
    │    ├─ get_conversation_history()
    │    ├─ export_conversation()
    │    ├─ get_performance_stats()
    │    └─ reset()
    │
    └─── TaskExecutor
         ├─ execute_paper_analysis()
         ├─ execute_stock_market_analysis()
         ├─ execute_web_research()
         └─ execute_custom_task()
```

## Configuration Loading Sequence

```
Application Start
    │
    ▼
Load Environment Variables (.env)
    │
    ▼
Initialize Config Class
    │
    ├─ API_TIMEOUT = 600
    ├─ LLM_TEMPERATURE = 0.0
    ├─ MAX_CONSECUTIVE_AUTO_REPLY = 10
    ├─ USE_DOCKER = False
    └─ LOG_LEVEL = INFO
    │
    ▼
Validate Configuration
    │
    ├─ Check OPENAI_API_KEY exists
    ├─ Check OAI_CONFIG_LIST exists
    ├─ Verify Docker (if USE_DOCKER=True)
    └─ Return validation result
    │
    ▼
Build LLM Config Dictionary
    │
    ├─ Load config list from JSON
    ├─ Filter by model names
    ├─ Set timeout and temperature
    └─ Set cache seed
    │
    ▼
Ready for Agent Initialization
```

## Error Handling Flow

```
Exception Occurs
    │
    ▼
ErrorHandler.format_error()
    │
    ├─ Capture exception type
    ├─ Capture error message
    ├─ Capture stack trace
    └─ Format with context
    │
    ▼
Check if Retryable?
    │
    ├─ TimeoutError ───────► Retry
    ├─ ConnectionError ────► Retry
    ├─ RuntimeError ───────► Retry
    └─ Other ──────────────► Don't retry
    │
    ▼
Generate User Message
    │
    ├─ API Error ──────────► "🔌 API Error: Unable to connect..."
    ├─ Timeout ───────────► "⏱️ Timeout: Request took too long..."
    ├─ Auth Error ────────► "🔐 Authentication: Verify credentials..."
    └─ Unknown ──────────► "⚠️ Error: [message]"
    │
    ▼
Log Error
    │
    └─ agent.log + console output
    │
    ▼
Return to User
    │
    └─ Display user-friendly message
```

## Performance Monitoring Sequence

```
Operation Starts
    │
    ▼
Record Start Time
    │
    ├─ t_start = time.time()
    └─ operation_name noted
    │
    ▼
Execute Operation
    │
    ├─ Try operation
    ├─ Measure duration
    └─ Determine success/failure
    │
    ▼
Record Metrics
    │
    ├─ duration = time.time() - t_start
    ├─ Add to performance_monitor.metrics
    │
    └─ Store:
        ├─ operation name
        ├─ duration_ms
        ├─ status
        └─ timestamp
    │
    ▼
Aggregated Statistics
    │
    ├─ Total operations
    ├─ Average duration
    ├─ Total duration
    ├─ Success rate
    └─ Available in dashboard
```

## UI State Management

```
Session State
    │
    ├─ agent_manager ────────► AutoGenAgentManager instance
    ├─ agent_initialized ────► Boolean (True/False)
    ├─ conversation_history ► List of conversations
    ├─ current_task ─────────► Current task dict
    ├─ execution_in_progress► Boolean (executing?)
    └─ performance_stats ────► Stats dictionary
    │
    ▼
State Transitions
    │
    ├─ Initialize ───────► agent_initialized = True
    ├─ Execute Task ─────► execution_in_progress = True
    ├─ Complete Task ────► execution_in_progress = False
    │                     conversation_history updated
    │                     performance_stats updated
    └─ Reset ────────────► All state cleared/reset
```

## Validation Pipeline

```
User Input
    │
    ▼
Input Type Check
    │
    ├─ URL? ─────────┬─ TaskValidator.validate_url()
    │                 │  ├─ Regex pattern match
    │                 │  ├─ Protocol check
    │                 │  └─ Domain validation
    │
    ├─ Query? ───────┬─ TaskValidator.validate_query()
    │                 │  ├─ Length check (5-2000)
    │                 │  ├─ Empty check
    │                 │  └─ Content validation
    │
    └─ Task? ────────┬─ Basic format check
                      └─ Length limits
     │
     ▼
Sanitization
     │
     ├─ Remove dangerous patterns
     │  ├─ __import__
     │  ├─ exec(
     │  ├─ eval(
     │  ├─ os.
     │  └─ subprocess.
     │
     └─ Clean special characters
     │
     ▼
Store or Execute
     │
     └─ Safe to use in agent
```

---

These diagrams provide a comprehensive view of the system architecture, data flow, and component interactions.
