# pypcoder/mutantscope architecture

> Architecture diagram of the GitHub repository pypcoder/mutantscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pypcoder/mutantscope
- Repository: https://github.com/pypcoder/mutantscope

## Overview

MutantScope lets a researcher submit a UniProt mutation, then fetches the protein sequence and structure metadata, validates and constructs the mutant sequence, predicts secondary structure for both sequences, and requests a biological explanation. The web client displays the returned sequence, structure predictions, composition, and explanation. The main request orchestration and prediction path are supported by sampled source; the separate protein-info endpoint is documented but no client call to it is shown.

Main entry points: [`server/main.py`](https://github.com/pypcoder/mutantscope/blob/main/server/main.py) (FastAPI routes), [`client/app/page.tsx`](https://github.com/pypcoder/mutantscope/blob/main/client/app/page.tsx) (Web app), [`server/services/alphafold.py`](https://github.com/pypcoder/mutantscope/blob/main/server/services/alphafold.py) (AlphaFold client), [`client/components/LeftPanel.tsx`](https://github.com/pypcoder/mutantscope/blob/main/client/components/LeftPanel.tsx) (Mutation form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_mutation_form["Mutation form<br/>[LeftPanel.tsx]"]
  node_web_app["Web app<br/>[page.tsx]"]
  node_structure_view["Structure view<br/>[Viewer.tsx]"]
  node_result_drawer["Result drawer<br/>[Drawer.tsx]"]
end

subgraph group_api["API orchestration"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_alphafold_client["AlphaFold client<br/>[alphafold.py]"]
end

subgraph group_analysis["Mutation analysis"]
  node_seraph_model["SERAPH predictor<br/>[seraph.py]"]
  node_gemini_client["Explanation service<br/>[gemini.py]"]
end

subgraph group_integrations["External services"]
  node_alphafold_db["AlphaFold DB"]
  node_esm2["ESM2 model"]
  node_gemini["Gemini API"]
end

node_researcher(("Researcher"))

node_researcher -->|"enters mutation"| node_mutation_form
node_mutation_form -->|"submits inputs"| node_web_app
node_web_app -->|"POST /mutate"| node_fastapi
node_fastapi -->|"fetches sequence and structure"| node_alphafold_client
node_alphafold_client -->|"requests protein data"| node_alphafold_db
node_alphafold_db -->|"returns protein data"| node_alphafold_client
node_fastapi -->|"predicts both sequences"| node_seraph_model
node_seraph_model -->|"loads pretrained backbone"| node_esm2
node_fastapi -->|"requests explanation"| node_gemini_client
node_gemini_client -->|"generates explanation"| node_gemini
node_fastapi -->|"returns analysis"| node_web_app
node_web_app -->|"passes predictions"| node_structure_view
node_web_app -->|"passes result"| node_result_drawer

click node_mutation_form "https://github.com/pypcoder/mutantscope/blob/main/client/components/LeftPanel.tsx"
click node_web_app "https://github.com/pypcoder/mutantscope/blob/main/client/app/page.tsx"
click node_structure_view "https://github.com/pypcoder/mutantscope/blob/main/client/components/Viewer.tsx"
click node_result_drawer "https://github.com/pypcoder/mutantscope/blob/main/client/components/Drawer.tsx"
click node_fastapi "https://github.com/pypcoder/mutantscope/blob/main/server/main.py"
click node_alphafold_client "https://github.com/pypcoder/mutantscope/blob/main/server/services/alphafold.py"
click node_seraph_model "https://github.com/pypcoder/mutantscope/blob/main/server/models/seraph.py"
click node_gemini_client "https://github.com/pypcoder/mutantscope/blob/main/server/services/gemini.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mutation_form,node_web_app,node_structure_view,node_result_drawer toneBlue
class node_fastapi,node_alphafold_client toneAmber
class node_seraph_model,node_gemini_client toneMint
class node_alphafold_db,node_esm2,node_gemini toneRose
class node_researcher toneIndigo
```

## Components

### Web client

- [Mutation form](https://github.com/pypcoder/mutantscope/blob/main/client/components/LeftPanel.tsx): `client/components/LeftPanel.tsx`
- [Web app](https://github.com/pypcoder/mutantscope/blob/main/client/app/page.tsx): `client/app/page.tsx`
- [Structure view](https://github.com/pypcoder/mutantscope/blob/main/client/components/Viewer.tsx): `client/components/Viewer.tsx`
- [Result drawer](https://github.com/pypcoder/mutantscope/blob/main/client/components/Drawer.tsx): `client/components/Drawer.tsx`

### API orchestration

- [FastAPI routes](https://github.com/pypcoder/mutantscope/blob/main/server/main.py): `server/main.py`
- [AlphaFold client](https://github.com/pypcoder/mutantscope/blob/main/server/services/alphafold.py): `server/services/alphafold.py`

### Mutation analysis

- [SERAPH predictor](https://github.com/pypcoder/mutantscope/blob/main/server/models/seraph.py): `server/models/seraph.py`
- [Explanation service](https://github.com/pypcoder/mutantscope/blob/main/server/services/gemini.py): `server/services/gemini.py`

### External services

- **AlphaFold DB**
- **ESM2 model**
- **Gemini API**

### Other components

- **Researcher**

## Connections

- Researcher → Mutation form: enters mutation
- Mutation form → Web app: submits inputs
- Web app → FastAPI routes: POST /mutate
- FastAPI routes → AlphaFold client: fetches sequence and structure
- AlphaFold client → AlphaFold DB: requests protein data
- AlphaFold DB → AlphaFold client: returns protein data
- FastAPI routes → SERAPH predictor: predicts both sequences
- SERAPH predictor → ESM2 model: loads pretrained backbone
- FastAPI routes → Explanation service: requests explanation
- Explanation service → Gemini API: generates explanation
- FastAPI routes → Web app: returns analysis
- Web app → Structure view: passes predictions
- Web app → Result drawer: passes result