<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# BioMCP Architecture Diagrams

This page describes BioMCP's architecture, data flows, and workflows.

## System Architecture Overview

BioMCP consists of three main layers:

### Client Layer

- **CLI Interface**: Command-line tool for direct interaction
- **Claude Desktop**: AI assistant integration via MCP protocol
- **Python SDK**: Programmatic access for custom applications
- **Custom MCP Clients**: Any MCP-compatible client

### BioMCP Core

- **MCP Server**: Handles protocol communication
- **Request Router**: Directs queries to appropriate handlers
- **Cache Layer**: Intelligent caching for API responses
- **Domain Handlers**: Specialized processors for each data type
  - Articles Handler (PubMed/PubTator3)
  - Trials Handler (ClinicalTrials.gov, NCI)
  - Variants Handler (MyVariant.info)
  - Genes Handler (MyGene.info)

### External APIs

- **PubMed/PubTator3**: Biomedical literature
- **ClinicalTrials.gov**: US clinical trials registry
- **NCI CTS API**: National Cancer Institute trials
- **MyVariant.info**: Genetic variant annotations
- **MyGene.info**: Gene information
- **cBioPortal**: Cancer genomics data
- **AlphaGenome**: Variant effect predictions

## Data Flow Architecture

1. **User Request**: Query submitted via CLI, Claude, or SDK
2. **Cache Check**: System checks for cached results
3. **API Request**: If cache miss, fetch from external API
4. **Result Processing**: Normalize and enrich data
5. **Cache Storage**: Store results for future use
6. **Response Delivery**: Return formatted results to user

## Key Workflows

### Search Workflow

1. **Think Tool**: Plan search strategy
2. **Execute Search**: Query relevant data sources
3. **Enrich Results**: Add contextual information
4. **Combine Data**: Merge results from multiple sources
5. **Format Output**: Present in user-friendly format

### Article Search Pipeline

1. **Query Processing**: Parse user input
2. **Entity Recognition**: Normalize gene/disease names
3. **PubTator3 Search**: Query literature database
4. **Preprint Integration**: Include bioRxiv/medRxiv if enabled
5. **cBioPortal Enrichment**: Add cancer genomics data for genes
6. **Result Merging**: Combine all data sources

### Clinical Trial Matching

1. **Patient Profile**: Parse eligibility criteria
2. **Location Filter**: Geographic constraints
3. **Molecular Profile**: Mutation requirements
4. **Prior Treatments**: Treatment history matching
5. **Scoring Algorithm**: Rank trials by relevance
6. **Contact Extraction**: Retrieve site information

### Variant Interpretation

1. **Input Parsing**: Process VCF/MAF files
2. **Batch Processing**: Group variants efficiently
3. **Annotation Gathering**:
   - Clinical significance from MyVariant.info
   - Population frequency data
   - In silico predictions
   - Literature evidence
   - Clinical trial associations
4. **AlphaGenome Integration**: Regulatory predictions (optional)
5. **Tier Classification**: Categorize by clinical relevance
6. **Report Generation**: Create interpretation summary

## Architecture Patterns

### Caching Strategy

- **Multi-tier Cache**: Memory → Disk → External
- **Smart TTL**: Domain-specific expiration times
- **Cache Key Generation**: Include all query parameters
- **Invalidation Logic**: Clear on errors or updates

### Error Handling

- **Retry Logic**: Exponential backoff for transient errors
- **Rate Limiting**: Respect API limits with queuing
- **Graceful Degradation**: Return partial results when possible
- **Clear Error Messages**: Help users troubleshoot issues

### Authentication Flow

1. Check for user-provided API key
2. Fall back to environment variable
3. Use public access if no key available
4. Handle authentication errors gracefully

### Performance Optimization

- **Request Batching**: Combine multiple queries
- **Parallel Execution**: Concurrent API calls
- **Connection Pooling**: Reuse HTTP connections
- **Result Streaming**: Return data as available

## Deployment Options

### Local Development

- Single process with in-memory cache
- Direct file system access
- Simple configuration

### Docker Deployment

- Containerized application
- Volume-mounted cache
- Environment-based configuration

### Cloud Deployment

- Load-balanced instances
- Shared Redis cache
- Auto-scaling capabilities
- Monitoring integration

## Creating Documentation Diagrams

For visual diagrams, we recommend:

1. **ASCII Art**: Universal compatibility

   - Use tools like asciiflow.com
   - Store in `docs/assets/` directory

2. **Screenshots**: For complex UIs

   - Annotate with arrows/labels
   - Save as PNG in `docs/assets/`

3. **External Tools**:
   - draw.io for flowcharts
   - Lucidchart for professional diagrams
   - Export as static images

## ASCII System Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              USER INTERFACES                             │
├────────────────┬───────────────────┬───────────────┬───────────────────┤
│                │                   │               │                   │
│   CLI Tool     │  Claude Desktop   │  Python SDK   │   Custom Client   │
│  (biomcp)      │   (MCP Client)    │   (async)     │    (your app)     │
│                │                   │               │                   │
└────────┬───────┴─────────┬─────────┴───────┬───────┴───────────┬───────┘
         │                 │                 │                   │
         └─────────────────┴─────────────────┴───────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            BioMCP CORE SERVER                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │   Router    │  │ Rate Limiter │  │ Cache Manager│  │   Logger   │  │
│  │             │  │              │  │              │  │            │  │
│  └──────┬──────┘  └──────────────┘  └──────────────┘  └────────────┘  │
│         │                                                               │
│         ▼                                                               │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                      Domain Handlers                             │   │
│  ├─────────────┬─────────────┬─────────────┬──────────────────────┤   │
│  │  Articles   │   Trials    │  Variants   │  Genes/Drugs/Disease │   │
│  │  Handler    │   Handler   │  Handler    │      Handler         │   │
│  └──────┬──────┴──────┬──────┴──────┬──────┴──────────┬───────────┘   │
│         │             │             │                 │                 │
└─────────┼─────────────┼─────────────┼─────────────────┼─────────────────┘
          │             │             │                 │
          ▼             ▼             ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          EXTERNAL DATA SOURCES                           │
├─────────────┬─────────────┬─────────────┬──────────────────────────────┤
│             │             │             │                              │
│  PubMed/    │ Clinical    │ MyVariant   │        BioThings Suite       │
│  PubTator3  │ Trials.gov  │   .info     │  (MyGene/MyDisease/MyChem)  │
│             │    + NCI    │             │                              │
│             │             │             │                              │
├─────────────┴─────────────┴─────────────┴──────────────────────────────┤
│                                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                 │
│  │  cBioPortal  │  │  AlphaGenome │  │  Europe PMC  │                 │
│  │   (Cancer)   │  │ (Predictions)│  │  (Preprints) │                 │
│  └──────────────┘  └──────────────┘  └──────────────┘                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

See also: [Quick Architecture Reference](quick-architecture.md)

## Next Steps

- View the [Quick Architecture Guide](quick-architecture.md) for a concise overview
- Check [Developer Guides](../developer-guides/01-server-deployment.md) for implementation details
- See [API Reference](../apis/overview.md) for detailed specifications


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->