ARCHITECTURE.md

# Cancer@Home v2 - Architecture Diagram

## System Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         WEB BROWSER                                      │
│                      http://localhost:5000                               │
└────────────────────────────┬────────────────────────────────────────────┘
                             │
                             │ HTTP/WebSocket
                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    FRONTEND (HTML5/CSS3/JS)                             │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────────────────┐  │
│  │Dashboard │  Neo4j   │  BOINC   │   GDC    │    Pipeline          │  │
│  │  View    │   Viz    │  Tasks   │   Data   │    Tools             │  │
│  └──────────┴──────────┴──────────┴──────────┴──────────────────────┘  │
│                                                                          │
│  Technologies: D3.js, Chart.js, Vanilla JavaScript                      │
└────────────────────────────┬────────────────────────────────────────────┘
                             │
                             │ REST API + GraphQL
                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    BACKEND (FastAPI + Python)                           │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                      API Layer                                   │   │
│  │  • REST Endpoints (/api/*)                                      │   │
│  │  • GraphQL Endpoint (/graphql)                                  │   │
│  │  • WebSocket Support                                            │   │
│  │  • Swagger Documentation (/docs)                                │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                             │                                            │
│                             │ Python Modules                             │
│                             ▼                                            │
│  ┌──────────┬──────────┬──────────┬──────────┬─────────────────────┐   │
│  │  BOINC   │   GDC    │  Neo4j   │ Pipeline │   Utilities         │   │
│  │  Client  │  Client  │   DB     │ Tools    │                     │   │
│  └──────────┴──────────┴──────────┴──────────┴─────────────────────┘   │
└───────┬──────────┬──────────┬──────────┬────────────────────────────────┘
        │          │          │          │
        │          │          │          │
        ▼          ▼          ▼          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        DATA & SERVICES LAYER                            │
│                                                                          │
│  ┌────────────────────┐  ┌────────────────────┐  ┌──────────────────┐ │
│  │    Neo4j Graph     │  │   BOINC Server     │  │   GDC Portal     │ │
│  │     Database       │  │   (Distributed)    │  │   (External)     │ │
│  │                    │  │                    │  │                  │ │
│  │ Port: 7687 (Bolt)  │  │ Local/Remote       │  │ api.gdc.cancer   │
│  │       7474 (HTTP)  │  │ Task Processing    │  │ .gov             │ │
│  │                    │  │                    │  │                  │ │
│  │ • Genes            │  │ • Variant Calling  │  │ • TCGA Data      │ │
│  │ • Mutations        │  │ • BLAST Search     │  │ • TARGET Data    │ │
│  │ • Patients         │  │ • Alignment        │  │ • Clinical Data  │ │
│  │ • Cancer Types     │  │ • Annotation       │  │ • Genomic Files  │ │
│  └────────────────────┘  └────────────────────┘  └──────────────────┘ │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐│
│  │              Bioinformatics Tools (Local)                          ││
│  │                                                                     ││
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐    ││
│  │  │   FASTQ      │  │    BLAST     │  │   Variant Caller     │    ││
│  │  │  Processor   │  │    Runner    │  │                      │    ││
│  │  │              │  │              │  │                      │    ││
│  │  │ • QC         │  │ • BLASTN     │  │ • VCF Generation     │    ││
│  │  │ • Filtering  │  │ • BLASTP     │  │ • Annotation         │    ││
│  │  │ • Trimming   │  │ • Parsing    │  │ • TMB Calculation    │    ││
│  │  └──────────────┘  └──────────────┘  └──────────────────────┘    ││
│  └────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       FILE STORAGE                                       │
│                                                                          │
│  data/                                                                   │
│  ├── gdc/              # Downloaded GDC files                           │
│  ├── boinc/            # BOINC task data                                │
│  ├── processed/        # Analysis results                               │
│  │   ├── fastq/                                                         │
│  │   ├── blast/                                                         │
│  │   └── variants/                                                      │
│  └── cache/            # Temporary files                                │
│                                                                          │
│  logs/                 # Application logs                               │
└─────────────────────────────────────────────────────────────────────────┘
```

## Data Flow Diagram

```
┌──────────────┐
│   User       │
│   Browser    │
└──────┬───────┘
       │ 1. Request
       ▼
┌──────────────────────────────────┐
│   Dashboard                      │
│   (View Gene/Mutation Data)      │
└──────┬───────────────────────────┘
       │ 2. GraphQL Query
       ▼
┌──────────────────────────────────┐
│   FastAPI Backend                │
│   - Parse Query                  │
│   - Validate Request             │
└──────┬───────────────────────────┘
       │ 3. Cypher Query
       ▼
┌──────────────────────────────────┐
│   Neo4j Database                 │
│   - Execute Graph Query          │
│   - Traverse Relationships       │
│   - Aggregate Results            │
└──────┬───────────────────────────┘
       │ 4. Graph Data
       ▼
┌──────────────────────────────────┐
│   GraphQL Resolver               │
│   - Transform Data               │
│   - Format Response              │
└──────┬───────────────────────────┘
       │ 5. JSON Response
       ▼
┌──────────────────────────────────┐
│   Frontend Visualization         │
│   - Render Graph                 │
│   - Display Charts               │
│   - Show Statistics              │
└──────────────────────────────────┘
```

## BOINC Task Processing Flow

```
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Submit     │      │   Queue      │      │   Execute    │
│   Task       │─────▶│   Task       │─────▶│   Analysis   │
│              │      │              │      │              │
└──────────────┘      └──────────────┘      └──────┬───────┘
                                                    │
                                                    ▼
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Store      │      │   Import to  │      │   Generate   │
│   Results    │◀─────│   Neo4j      │◀─────│   Results    │
│              │      │              │      │              │
└──────────────┘      └──────────────┘      └──────────────┘
```

## Neo4j Graph Schema

```
┌─────────────────────────────────────────────────────────────────┐
│                       Neo4j Graph Model                         │
│                                                                  │
│   ┌──────────┐                    ┌──────────┐                 │
│   │   Gene   │                    │ Mutation │                 │
│   ├──────────┤                    ├──────────┤                 │
│   │ gene_id  │◀───────AFFECTS─────│mut_id    │                 │
│   │ symbol   │                    │ chr      │                 │
│   │ name     │                    │ position │                 │
│   │ chr      │                    │ ref      │                 │
│   └──────────┘                    │ alt      │                 │
│                                    └────▲─────┘                 │
│                                         │                        │
│                                         │ HAS_MUTATION           │
│                                         │                        │
│   ┌──────────┐                    ┌────┴─────┐                 │
│   │  Cancer  │                    │ Patient  │                 │
│   │   Type   │                    ├──────────┤                 │
│   ├──────────┤                    │patient_id│                 │
│   │cancer_id │                    │ age      │                 │
│   │ name     │◀──DIAGNOSED_WITH───│ gender   │                 │
│   │ tissue   │                    │ race     │                 │
│   └──────────┘                    │ status   │                 │
│                                    └──────────┘                 │
│                                                                  │
│  Relationships:                                                 │
│  • Gene ← AFFECTS ← Mutation                                   │
│  • Patient → HAS_MUTATION → Mutation                           │
│  • Patient → DIAGNOSED_WITH → CancerType                       │
└─────────────────────────────────────────────────────────────────┘
```

## Technology Stack

```
┌─────────────────────────────────────────────────────────────────┐
│                    Technology Layers                            │
│                                                                  │
│  Frontend:                                                      │
│  • HTML5, CSS3, JavaScript (ES6+)                              │
│  • D3.js (Graph Visualization)                                 │
│  • Chart.js (Charts & Analytics)                               │
│  • Responsive Design                                            │
│                                                                  │
│  Backend:                                                       │
│  • Python 3.8+                                                 │
│  • FastAPI (Web Framework)                                     │
│  • Uvicorn (ASGI Server)                                       │
│  • Strawberry (GraphQL)                                        │
│                                                                  │
│  Database:                                                      │
│  • Neo4j 5.13 (Graph Database)                                │
│  • Bolt Protocol                                               │
│  • APOC & GDS Plugins                                          │
│                                                                  │
│  Data Processing:                                              │
│  • Biopython (Sequence Analysis)                               │
│  • NumPy & Pandas (Data Manipulation)                         │
│  • BLAST+ (Sequence Alignment)                                 │
│                                                                  │
│  Infrastructure:                                               │
│  • Docker & Docker Compose                                     │
│  • YAML Configuration                                          │
│  • Python Virtual Environments                                 │
│                                                                  │
│  External APIs:                                                │
│  • GDC Portal API (Cancer Data)                               │
│  • BOINC RPC (Distributed Computing)                          │
└─────────────────────────────────────────────────────────────────┘
```

## Deployment Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    Local Development                            │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Host Machine                                            │  │
│  │                                                           │  │
│  │  ┌─────────────────┐         ┌──────────────────────┐   │  │
│  │  │  Python venv    │         │  Docker Desktop      │   │  │
│  │  │  Port 5000      │         │                      │   │  │
│  │  │                 │         │  ┌────────────────┐  │   │  │
│  │  │  • FastAPI      │         │  │  Neo4j         │  │   │  │
│  │  │  • Backend API  │◀───────▶│  │  Port 7474     │  │   │  │
│  │  │  • GraphQL      │         │  │  Port 7687     │  │   │  │
│  │  │  • WebSocket    │         │  └────────────────┘  │   │  │
│  │  │                 │         │                      │   │  │
│  │  └─────────────────┘         └──────────────────────┘   │  │
│  │                                                           │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Access URLs:                                                  │
│  • http://localhost:5000      - Main Application              │
│  • http://localhost:5000/docs  - API Documentation            │
│  • http://localhost:5000/graphql - GraphQL Playground         │
│  • http://localhost:7474       - Neo4j Browser                │
└─────────────────────────────────────────────────────────────────┘
```