ARCHITECTURE.md

# Docking@HOME System Architecture

## Complete System Overview

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         USER INTERFACES                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐    │
│  │  Web Browser │    │   Terminal   │    │   Python Scripts     │    │
│  │  localhost:  │    │     CLI      │    │   (API calls)        │    │
│  │     8080     │    │   Commands   │    │                      │    │
│  └──────┬───────┘    └──────┬───────┘    └──────────┬───────────┘    │
│         │                   │                        │                 │
└─────────┼───────────────────┼────────────────────────┼─────────────────┘
          │                   │                        │
          │                   │                        │
┌─────────▼───────────────────▼────────────────────────▼─────────────────┐
│                      APPLICATION LAYER                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                    FastAPI Web Server                            │  │
│  │                     (gui.py)                                     │  │
│  ├─────────────────────────────────────────────────────────────────┤  │
│  │                                                                  │  │
│  │  REST API:           WebSockets:         Static Files:          │  │
│  │  • POST /upload      • /ws               • HTML/CSS/JS          │  │
│  │  • POST /api/jobs    • Real-time         • Embedded GUI         │  │
│  │  • GET  /api/jobs    • Job updates       • Responsive           │  │
│  │  • GET  /api/stats   • Progress          • Dashboard            │  │
│  │                                                                  │  │
│  └────────────────────────────┬────────────────────────────────────┘  │
│                               │                                        │
│  ┌────────────────────────────▼───────────────────────────────────┐  │
│  │                   Job Manager                                   │  │
│  │                   (server.py)                                   │  │
│  ├─────────────────────────────────────────────────────────────────┤  │
│  │                                                                  │  │
│  │  • Job Queue (asyncio.Queue)                                    │  │
│  │  • Worker Tasks (2-4 concurrent)                                │  │
│  │  • Job Status Tracking                                          │  │
│  │  • Statistics & Monitoring                                      │  │
│  │                                                                  │  │
│  └────────────────────────────┬────────────────────────────────────┘  │
│                               │                                        │
└───────────────────────────────┼────────────────────────────────────────┘
                                │
┌───────────────────────────────▼────────────────────────────────────────┐
│                      EXECUTION LAYER                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │               AutoDock Executor                                  │  │
│  │               (server.py)                                        │  │
│  ├─────────────────────────────────────────────────────────────────┤  │
│  │                                                                  │  │
│  │  1. Find AutoDock executable                                    │  │
│  │  2. Generate DPF file                                           │  │
│  │  3. Run docking calculation                                     │  │
│  │  4. Parse DLG results                                           │  │
│  │  5. Extract energies & poses                                    │  │
│  │                                                                  │  │
│  └──────────────────┬──────────────────┬───────────────────────────┘  │
│                     │                  │                               │
│         ┌───────────▼────────┐   ┌────▼────────────────┐             │
│         │ AutoDock Found?    │   │ AutoDock NOT Found? │             │
│         └───────────┬────────┘   └────┬────────────────┘             │
│                     │                  │                               │
└─────────────────────┼──────────────────┼───────────────────────────────┘
                      │                  │
         ┌────────────▼─────┐    ┌───────▼─────────┐
         │   REAL MODE      │    │ SIMULATION MODE │
         └────────────┬─────┘    └───────┬─────────┘
                      │                  │
┌─────────────────────▼──────────────────▼───────────────────────────────┐
│                      COMPUTATION LAYER                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────────────────────┐    ┌─────────────────────────────┐  │
│  │     Real AutoDock            │    │   Simulation Engine         │  │
│  ├──────────────────────────────┤    ├─────────────────────────────┤  │
│  │                              │    │                             │  │
│  │  ┌────────────────────────┐ │    │  • Fast execution (0.01s)   │  │
│  │  │   autodock4 (CPU)      │ │    │  • Realistic energies       │  │
│  │  │   or                   │ │    │  • JSON results             │  │
│  │  │   autodock_gpu (CUDA)  │ │    │  • Perfect for testing      │  │
│  │  └────────────────────────┘ │    │                             │  │
│  │         ↓                    │    └─────────────────────────────┘  │
│  │  ┌────────────────────────┐ │                                      │
│  │  │  GPU Acceleration      │ │                                      │
│  │  │  (CUDPP Primitives)    │ │                                      │
│  │  └────────────────────────┘ │                                      │
│  │         ↓                    │                                      │
│  │  ┌────────────────────────┐ │                                      │
│  │  │  Genetic Algorithm     │ │                                      │
│  │  │  Energy Calculations   │ │                                      │
│  │  │  Pose Clustering       │ │                                      │
│  │  └────────────────────────┘ │                                      │
│  │         ↓                    │                                      │
│  │  ┌────────────────────────┐ │                                      │
│  │  │  DLG Output File       │ │                                      │
│  │  │  • Binding energies    │ │                                      │
│  │  │  • Poses & conformers  │ │                                      │
│  │  │  • Cluster analysis    │ │                                      │
│  │  └────────────────────────┘ │                                      │
│  │                              │                                      │
│  └──────────────────────────────┘                                      │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────────┐
│                        RESULTS STORAGE                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  results/                                                               │
│  ├── job_abc123/                                                        │
│  │   ├── results.json        (Parsed results)                          │
│  │   ├── docking.dpf         (AutoDock parameters)                     │
│  │   ├── docking.dlg         (AutoDock log/results)                    │
│  │   └── docking.glg         (AutoDock general log)                    │
│  │                                                                      │
│  ├── job_def456/                                                        │
│  │   └── ...                                                            │
│  │                                                                      │
│  └── uploads/                                                           │
│      ├── ligand_xxx.pdbqt                                               │
│      └── receptor_yyy.pdbqt                                             │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## Data Flow Diagram

```
User Action (Upload files) 
        ↓
GUI sends POST /upload
        ↓
Files saved to uploads/
        ↓
User clicks "Start Docking"
        ↓
GUI sends POST /api/jobs
        ↓
Job Manager creates job
        ↓
Job added to queue
        ↓
Worker picks up job
        ↓
AutoDock Executor runs
        ↓
┌───────────────────┐
│  Is AutoDock      │
│  installed?       │
└────────┬──────────┘
         │
    ┌────┴────┐
    │         │
   Yes       No
    │         │
    │    ┌────▼────────┐
    │    │ Simulation  │
    │    │   Mode      │
    │    └────┬────────┘
    │         │
    │    ┌────▼────────────┐
    │    │ Generate random │
    │    │ realistic data  │
    │    └────┬────────────┘
    │         │
┌───▼─────────▼───┐
│ Progress updates│
│ via WebSocket   │
└────────┬────────┘
         │
    ┌────▼────┐
    │ Results │
    │  ready  │
    └────┬────┘
         │
GUI displays results
         ↓
User sees:
  • Binding energies
  • Poses
  • Clusters
  • Statistics
```

## Technology Stack

```
┌─────────────────────────────────────┐
│         FRONTEND                    │
├─────────────────────────────────────┤
│ HTML5 + CSS3 + JavaScript (Vanilla) │
│ WebSockets for real-time updates    │
│ Responsive design (mobile-ready)    │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│         BACKEND                     │
├─────────────────────────────────────┤
│ FastAPI (Python async framework)    │
│ Uvicorn (ASGI server)               │
│ WebSockets (bidirectional comms)    │
│ Pydantic (data validation)          │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│      COMPUTATION ENGINE             │
├─────────────────────────────────────┤
│ AutoDock Suite 4.2.6                │
│ CUDPP (GPU primitives)              │
│ Python asyncio (concurrency)        │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│      DISTRIBUTED LAYER              │
├─────────────────────────────────────┤
│ BOINC (volunteer computing)         │
│ The Decentralized Internet SDK      │
│ Cloud Agents (AI orchestration)     │
└─────────────────────────────────────┘
```

## Deployment Options

### Option 1: Localhost (Current Implementation)
```
[Your Computer]
    ↓
http://localhost:8080
    ↓
All processing local
```

### Option 2: Single Server
```
[Central Server]
    ↓
http://server-ip:8080
    ↓
Multiple users connect
All jobs on one machine
```

### Option 3: Distributed (Future)
```
     [Master Server]
            ↓
     Task Distribution
      ↙    ↓    ↘
[Worker 1] [Worker 2] [Worker 3]
     ↓         ↓         ↓
  GPU Jobs  GPU Jobs  GPU Jobs
```

### Option 4: Cloud (Future)
```
      [Cloud Load Balancer]
            ↓
   ┌────────┼────────┐
   ↓        ↓        ↓
[Node 1] [Node 2] [Node 3]
   ↓        ↓        ↓
[DB]    [Storage]  [Cache]
```

## File Processing Flow

```
1. User uploads ligand.pdbqt and receptor.pdbqt
        ↓
2. Files saved to uploads/ directory
        ↓
3. Job created with file paths
        ↓
4. AutoDock Executor generates DPF file
        ↓
5. DPF specifies:
   - Ligand/receptor paths
   - Grid box parameters
   - Search parameters
   - Output file path
        ↓
6. AutoDock runs using DPF
        ↓
7. Results written to DLG file
        ↓
8. Parser extracts:
   - Binding energies
   - Conformations
   - RMSD values
   - Cluster information
        ↓
9. Results converted to JSON
        ↓
10. Stored in results/job_id/
        ↓
11. Sent to GUI for display
        ↓
12. User downloads or views results
```

---

## Authors

- OpenPeer AI
- Riemann Computing Inc.
- Bleunomics
- Andrew Magdy Kamal