APP_FLOW.md

# Application Flow Diagram

## User Interface Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    🤖 AI Text Assistant                          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ Mode Selection:                                                  │
│   ○ Text Generation    ○ Text Summarization                     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Input Text (max 500 words):                                      │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Enter your text here...                                     │ │
│ │                                                             │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Max Tokens: [━━━━━━━●━━━━━━━] 100                               │
│             10                                          500      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
                      ┌───────────────┐
                      │  🚀 Process   │
                      └───────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Status: ✅ Generated 42 tokens                                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Result (hover over words for alternatives):                      │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ The [quick] [brown] [fox] [jumps] [over]...                │ │
│ │                                                             │ │
│ │ [Hover shows tooltip]                                       │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Backend Processing Flow

```
User Input
    ↓
┌────────────────────┐
│ Validate Input     │
│ - Check non-empty  │
│ - Count words      │
│ - Max 500 words    │
└────────────────────┘
    ↓
┌────────────────────────────────┐
│ Route Based on Mode            │
├────────────────┬───────────────┤
│ Text Gen       │ Summarization │
└────────────────┴───────────────┘
    ↓                    ↓
┌─────────────────┐  ┌──────────────────┐
│ Qwen Model      │  │ BART Model       │
│ Generate with   │  │ Generate with    │
│ output_scores   │  │ output_scores    │
└─────────────────┘  └──────────────────┘
    ↓                    ↓
┌────────────────────────────────┐
│ Extract Token Alternatives     │
│ - Apply softmax to scores      │
│ - Get top-5 tokens per position│
│ - Format with probabilities    │
└────────────────────────────────┘
    ↓
┌────────────────────────────────┐
│ Create HTML with Tooltips      │
│ - Split text into words        │
│ - Map alternatives to words    │
│ - Generate CSS tooltips        │
└────────────────────────────────┘
    ↓
Display to User
```

## Token Alternative Tooltip Structure

```
Word in Text: "quick"
        ↓
    [Hover]
        ↓
┌─────────────────────────────────┐
│ Top 5 Alternatives:             │
├─────────────────────────────────┤
│ 1. quick          45.23%       │
│ 2. fast           23.15%       │
│ 3. rapid          12.08%       │
│ 4. swift           8.54%       │
│ 5. speedy          4.12%       │
└─────────────────────────────────┘
         ▲
    (Dark themed,
     positioned above word)
```

## Data Flow for Token Generation

```
Input: "Write a story about a cat"
    ↓
┌──────────────────────────────────────┐
│ Tokenization                         │
│ → [Write, a, story, about, a, cat]  │
└──────────────────────────────────────┘
    ↓
┌──────────────────────────────────────┐
│ Model Forward Pass                   │
│ → Logits for each position          │
└──────────────────────────────────────┘
    ↓
┌──────────────────────────────────────┐
│ For Each Generated Token:            │
│                                      │
│ Position 1 Scores:                   │
│ [The: 2.5, A: 1.8, Once: 1.2, ...]  │
│         ↓ Softmax                    │
│ [The: 52%, A: 22%, Once: 11%, ...]  │
│         ↓ Top-K (k=5)                │
│ Store top 5                          │
│                                      │
│ Position 2 Scores:                   │
│ [cat: 3.1, dog: 2.1, story: 1.5 ...] │
│         ↓ Softmax                    │
│ [cat: 45%, dog: 23%, story: 12% ...] │
│         ↓ Top-K (k=5)                │
│ Store top 5                          │
│                                      │
│ ... (repeat for all tokens)          │
└──────────────────────────────────────┘
    ↓
Output: 
- Generated text: "The cat was very curious..."
- Alternatives: List[{token, probability}] for each position
```

## Component Interaction

```
┌─────────────┐      ┌──────────────┐      ┌────────────┐
│   Gradio    │◄────►│   app.py     │◄────►│  PyTorch   │
│  Interface  │      │   Handler    │      │   Models   │
└─────────────┘      └──────────────┘      └────────────┘
       │                    │                      │
       │                    │                      │
       ▼                    ▼                      ▼
┌─────────────┐      ┌──────────────┐      ┌────────────┐
│   Browser   │      │  Processing  │      │Transformers│
│   Renders   │      │   Functions  │      │  Library   │
│   HTML      │      └──────────────┘      └────────────┘
└─────────────┘              │
                             │
                             ▼
                  ┌──────────────────┐
                  │  HTML Generator  │
                  │  with Tooltips   │
                  └──────────────────┘
```

## Error Handling Flow

```
Input Received
    ↓
┌──────────────┐   NO    ┌──────────────────┐
│ Text empty?  │────────→│ Count words      │
└──────────────┘         └──────────────────┘
    │ YES                        │
    ↓                            ↓
┌──────────────┐         ┌──────────────┐   YES
│ Return error │         │ > 500 words? │────────┐
└──────────────┘         └──────────────┘        │
                                │ NO              │
                                ↓                 ↓
                         ┌──────────────┐  ┌──────────────┐
                         │ Try process  │  │ Return error │
                         └──────────────┘  └──────────────┘
                                │
                         ┌──────┴──────┐
                         │ Exception?  │
                         └──────┬──────┘
                         YES ←──┘
                          ↓
                    ┌──────────────┐
                    │ Catch & show │
                    │ error to user│
                    └──────────────┘
```

## Model Loading Sequence

```
App Startup
    ↓
┌──────────────────────────────────┐
│ 1. Detect Device (GPU/CPU)       │
│    print("Using device: cpu")    │
└──────────────────────────────────┘
    ↓
┌──────────────────────────────────┐
│ 2. Load Qwen Tokenizer           │
│    ~50MB download (first time)   │
└──────────────────────────────────┘
    ↓
┌──────────────────────────────────┐
│ 3. Load Qwen Model                │
│    ~988MB download (first time)  │
│    Load to device                │
└──────────────────────────────────┘
    ↓
┌──────────────────────────────────┐
│ 4. Load BART Tokenizer           │
│    ~2MB download (first time)    │
└──────────────────────────────────┘
    ↓
┌──────────────────────────────────┐
│ 5. Load BART Model               │
│    ~1.6GB download (first time)  │
│    Load to device                │
└──────────────────────────────────┘
    ↓
┌──────────────────────────────────┐
│ 6. Launch Gradio Interface       │
│    Ready for user input!         │
└──────────────────────────────────┘
```