# 🏗️ Architecture Diagram

## System Overview

```
┌─────────────────────────────────────────────────────────────────────┐
│                         WordPress Site                               │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    Dummy Pack Center UI                        │  │
│  │  ┌──────────────────────────────────────────────────────────┐ │  │
│  │  │  React Component: InstallProcess.jsx                     │ │  │
│  │  │  - Display pack info                                     │ │  │
│  │  │  - Show progress bar                                     │ │  │
│  │  │  - Handle user actions                                   │ │  │
│  │  └─────────────────────┬────────────────────────────────────┘ │  │
│  │                        │                                       │  │
│  │                        ▼                                       │  │
│  │  ┌──────────────────────────────────────────────────────────┐ │  │
│  │  │  JavaScript: dummyPackLib.js                             │ │  │
│  │  │  - downloadDummyPack()                                   │ │  │
│  │  │  - Progress tracking                                     │ │  │
│  │  │  - Error handling                                        │ │  │
│  │  └─────────────────────┬────────────────────────────────────┘ │  │
│  └────────────────────────┼────────────────────────────────────────┘  │
│                           │                                           │
│                           │ AJAX Request                              │
│                           │                                           │
│  ┌────────────────────────▼────────────────────────────────────────┐  │
│  │              PHP: worrprba_ajax_download_dummy_pack()           │  │
│  │              (inc/dummy-center.php)                             │  │
│  │  - Verify nonce                                                 │  │
│  │  - Get signed URL                                               │  │
│  │  - Route download steps                                         │  │
│  └─────────────────────┬───────────────────────────────────────────┘  │
│                        │                                              │
│                        ▼                                              │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │      PHP Class: WORRPB_Dummy_Pack_Downloader                 │    │
│  │      (inc/libs/dummy-pack/download-dummy-pack.php)           │    │
│  │  ┌────────────────────────────────────────────────────────┐  │    │
│  │  │  Public Methods:                                       │  │    │
│  │  │  - __construct($args)                                  │  │    │
│  │  │  - startDownload()                                     │  │    │
│  │  │  - processStep()                                       │  │    │
│  │  │  - getProgress()                                       │  │    │
│  │  │  - cleanup()                                           │  │    │
│  │  │  - isComplete()                                        │  │    │
│  │  │  - getFinalFilePath()                                  │  │    │
│  │  └────────────────────────────────────────────────────────┘  │    │
│  │  ┌────────────────────────────────────────────────────────┐  │    │
│  │  │  Private Methods:                                      │  │    │
│  │  │  - downloadChunk()          ← HTTP Range requests     │  │    │
│  │  │  - mergeChunks()            ← Stream copy             │  │    │
│  │  │  - getRemoteFileSize()      ← HEAD request            │  │    │
│  │  │  - loadProgress()           ← From JSON file          │  │    │
│  │  │  - saveProgress()           ← To JSON file            │  │    │
│  │  │  - removeDirectory()        ← Cleanup                 │  │    │
│  │  └────────────────────────────────────────────────────────┘  │    │
│  └─────────────────────┬────────────────────────────────────────┘    │
│                        │                                              │
│                        ▼                                              │
│  ┌──────────────────────────────────────────────────────────────┐    │
│  │                File System Structure                         │    │
│  │  wp-content/uploads/worry-proof-backup-zip/                 │    │
│  │  ├── chunks/                                                 │    │
│  │  │   └── package-123/                                        │    │
│  │  │       ├── part-0                (Chunk files)            │    │
│  │  │       ├── part-1                                          │    │
│  │  │       ├── part-2                                          │    │
│  │  │       └── __download-progress.json (Progress tracking)   │    │
│  │  └── package-123.zip             (Final merged file)        │    │
│  └──────────────────────────────────────────────────────────────┘    │
└───────────────────────────────────────────────────────────────────────┘
                                 │
                                 │ HTTP Range Request
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        Remote Server                                 │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Dummy Pack CDN/Storage                                       │  │
│  │  - Stores large .zip files                                    │  │
│  │  - Supports Range requests                                    │  │
│  │  - Provides signed URLs                                       │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
```

## Download Flow Sequence

```
User              Frontend           Backend           Downloader         Remote Server
  │                   │                  │                   │                   │
  │ Click Install     │                  │                   │                   │
  ├──────────────────>│                  │                   │                   │
  │                   │                  │                   │                   │
  │                   │ Step 1: Get URL  │                   │                   │
  │                   ├─────────────────>│                   │                   │
  │                   │                  │  Get Signed URL   │                   │
  │                   │                  ├──────────────────────────────────────>│
  │                   │                  │<──────────────────────────────────────┤
  │                   │<─────────────────┤                   │                   │
  │                   │ Return URL       │                   │                   │
  │                   │                  │                   │                   │
  │                   │ Step 2: Start    │                   │                   │
  │                   ├─────────────────>│  new Downloader() │                   │
  │                   │                  ├──────────────────>│                   │
  │                   │                  │  startDownload()  │                   │
  │                   │                  ├──────────────────>│                   │
  │                   │                  │                   │  HEAD (file size) │
  │                   │                  │                   ├──────────────────>│
  │                   │                  │                   │<──────────────────┤
  │                   │                  │                   │ Content-Length    │
  │                   │                  │                   │                   │
  │                   │                  │<──────────────────┤                   │
  │                   │<─────────────────┤ {total_size}      │                   │
  │                   │                  │                   │                   │
  │ Show Progress     │                  │                   │                   │
  │<──────────────────┤                  │                   │                   │
  │ 0%                │                  │                   │                   │
  │                   │                  │                   │                   │
  │                   │ Step 3: Download │                   │                   │
  │                   ├─────────────────>│  processStep()    │                   │
  │                   │                  ├──────────────────>│                   │
  │                   │                  │                   │  GET Range: 0-5MB │
  │                   │                  │                   ├──────────────────>│
  │                   │                  │                   │<──────────────────┤
  │                   │                  │                   │ Chunk data        │
  │                   │                  │                   │ Save to part-0    │
  │                   │                  │<──────────────────┤                   │
  │                   │<─────────────────┤ {progress: 5%}    │                   │
  │ Update Progress   │                  │                   │                   │
  │<──────────────────┤                  │                   │                   │
  │ 5%                │                  │                   │                   │
  │                   │                  │                   │                   │
  │                   │ Repeat...        │                   │                   │
  │                   ├─────────────────>│  processStep()    │                   │
  │                   │                  ├──────────────────>│                   │
  │                   │                  │                   │  GET Range: 5-10MB│
  │                   │                  │                   ├──────────────────>│
  │                   │                  │                   │<──────────────────┤
  │                   │                  │                   │ Save to part-1    │
  │                   │                  │<──────────────────┤                   │
  │                   │<─────────────────┤ {progress: 10%}   │                   │
  │ Update Progress   │                  │                   │                   │
  │<──────────────────┤                  │                   │                   │
  │ 10%               │                  │                   │                   │
  │                   │                  │                   │                   │
  │     ... Continue until 100% ...      │                   │                   │
  │                   │                  │                   │                   │
  │                   │ Final Step       │                   │                   │
  │                   ├─────────────────>│  processStep()    │                   │
  │                   │                  ├──────────────────>│                   │
  │                   │                  │                   │ mergeChunks()     │
  │                   │                  │                   │ Verify size       │
  │                   │                  │<──────────────────┤                   │
  │                   │<─────────────────┤ {done: true}      │                   │
  │ Complete!         │                  │  cleanup()        │                   │
  │<──────────────────┤                  ├──────────────────>│                   │
  │ 100%              │                  │                   │ Delete chunks     │
  │                   │                  │                   │ Keep final.zip    │
```

## State Machine

```
┌──────────┐
│ pending  │ ← Initial state
└─────┬────┘
      │ startDownload()
      ▼
┌──────────────┐
│ downloading  │ ← Downloading chunks
└──────┬───────┘
       │ processStep() × N
       │ (loop until done)
       ▼
┌──────────┐
│ merging  │ ← Combining chunks
└─────┬────┘
      │ finishDownload()
      ▼
┌───────────┐
│ completed │ ← Final state (success)
└───────────┘

       OR
       
┌─────────┐
│ failed  │ ← Error occurred
└─────────┘
```

## Data Flow

```
┌─────────────────────────────────────────────────────────────────────┐
│                         Request Flow                                 │
└─────────────────────────────────────────────────────────────────────┘

1. User Action
   └─> Frontend Component (InstallProcess.jsx)
       └─> JavaScript Library (dummyPackLib.js)
           └─> Ajax Request to WordPress
               └─> PHP Handler (inc/dummy-center.php)
                   └─> Downloader Class
                       └─> HTTP Request to Remote Server
                           └─> Save to Disk

┌─────────────────────────────────────────────────────────────────────┐
│                        Response Flow                                 │
└─────────────────────────────────────────────────────────────────────┘

Remote Server (Chunk Data)
   └─> Downloader Class (Save & Update Progress)
       └─> PHP Handler (Format Response)
           └─> Ajax Response
               └─> JavaScript Library (Parse Data)
                   └─> Frontend Component (Update UI)
                       └─> User (See Progress)
```

## Progress Tracking

```
┌─────────────────────────────────────────────────────────────────────┐
│                   Progress Persistence                               │
└─────────────────────────────────────────────────────────────────────┘

Request 1:
  startDownload() → Create progress file
                    {
                      current_offset: 0,
                      total_size: 100MB,
                      status: 'downloading'
                    }

Request 2:
  processStep() → Download chunk 0 (0-5MB)
                → Save progress
                  {
                    current_offset: 5MB,
                    downloaded_size: 5MB,
                    status: 'downloading'
                  }

Request 3:
  processStep() → Download chunk 1 (5-10MB)
                → Save progress
                  {
                    current_offset: 10MB,
                    downloaded_size: 10MB,
                    status: 'downloading'
                  }

... Continue ...

Request N:
  processStep() → Download last chunk
                → mergeChunks()
                → Save progress
                  {
                    current_offset: 100MB,
                    downloaded_size: 100MB,
                    status: 'completed'
                  }
```

## Error Handling Flow

```
┌─────────────────────────────────────────────────────────────────────┐
│                        Error Scenarios                               │
└─────────────────────────────────────────────────────────────────────┘

Scenario 1: Network Error During Chunk Download
  processStep()
    └─> downloadChunk()
        └─> wp_remote_get() fails
            └─> Return WP_Error
                └─> Save status: 'failed'
                    └─> Return error to frontend
                        └─> Display error message
                            └─> User can retry

Scenario 2: Script Timeout
  processStep()
    └─> downloadChunk()
        └─> Script times out mid-download
            └─> Progress saved before timeout
                └─> Next request
                    └─> loadProgress()
                        └─> Resume from last chunk
                            └─> Continue download

Scenario 3: Disk Space Full
  downloadChunk()
    └─> wp_remote_get(stream: true)
        └─> Disk full during write
            └─> Return WP_Error
                └─> Status: 'failed'
                    └─> Inform user
```

## Memory Usage Comparison

```
┌─────────────────────────────────────────────────────────────────────┐
│                   Traditional Method                                 │
└─────────────────────────────────────────────────────────────────────┘

file_get_contents('https://remote.com/100MB.zip')
↓
Load entire 100MB into memory
↓
Memory: 100MB+ (plus overhead)
↓
file_put_contents('local.zip', $data)

┌─────────────────────────────────────────────────────────────────────┐
│                   Chunked Download Method                            │
└─────────────────────────────────────────────────────────────────────┘

Loop {
  wp_remote_get(Range: 0-5MB, stream: true)
  ↓
  Write directly to disk (part-0)
  ↓
  Memory: ~5MB
  
  wp_remote_get(Range: 5-10MB, stream: true)
  ↓
  Write directly to disk (part-1)
  ↓
  Memory: ~5MB
  
  ... continue ...
}
↓
Stream copy parts to final.zip
↓
Memory: ~5MB throughout entire process
```

## Key Advantages

```
┌─────────────────────────────────────────────────────────────────────┐
│                  Why This Architecture Works                         │
└─────────────────────────────────────────────────────────────────────┘

✅ Scalability
   - Handles files of any size
   - Memory usage constant regardless of file size

✅ Reliability
   - Automatic resume on failure
   - Progress persisted to disk
   - Each chunk independent

✅ Performance
   - Parallel potential (future enhancement)
   - Efficient streaming
   - Minimal overhead

✅ User Experience
   - Real-time progress
   - Clear error messages
   - No "frozen" interface

✅ Maintainability
   - Clean separation of concerns
   - Well-documented
   - Comprehensive tests

✅ Security
   - Input validation
   - Signed URLs
   - WordPress standards
```

---

**Architecture designed for production use with 100% reliability** ✨