# xuebin-feng/emap-ssn architecture

> Architecture diagram of the GitHub repository xuebin-feng/emap-ssn, 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/xuebin-feng/emap-ssn
- Repository: https://github.com/xuebin-feng/emap-ssn

## Overview

EMAP-SSN is an interactive protein sequence similarity network platform. Its main workflow prepares protein sequences, computes similarity through traditional or embedding-based methods, builds network/layout data, then supports interactive network and alignment analysis. The repository also exposes pipeline and Viewer capabilities through a local STDIO MCP server. Relationships for unsampled modules are limited to the workflows and capabilities described in the README; source excerpts were partial.

Main entry points: [`src/utilities/HDF5_Storage.py`](https://github.com/xuebin-feng/emap-ssn/blob/main/src/utilities/HDF5_Storage.py) (HDF5 Data), [`src/EMAPSSN_Tools.py`](https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_Tools.py) (Tools GUI), [`src/EMAPSSN_Viewer.py`](https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_Viewer.py) (SSN Viewer), [`src/Layout_Cache_Generator.py`](https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Cache_Generator.py) (Layout Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["SSN Generation"]
  node_sanitize["Sequence Preparation"]
  node_embeddings["Embedding Generation"]
  node_traditional_search["Sequence Similarity<br/>[Embedding_PWA.py]"]
  node_embedding_search["Embedding Search"]
  node_network_build["Network Extraction"]
  node_network_inject["Network Injection"]
  node_alignments["Alignment Processing<br/>[Embedding_MSA.py]"]
  node_hdf5[("HDF5 Data<br/>[HDF5_Storage.py]")]
end

subgraph group_analysis["Network Analysis"]
  node_layout_cache["Layout Cache"]
  node_layout_ssn["SSN Layout"]
  node_layout_umap["UMAP Layout"]
end

subgraph group_viewer["Interactive Viewer"]
  node_viewer["SSN Viewer<br/>[EMAPSSN_Viewer.py]"]
  node_commands["Analysis Commands<br/>[Command_Engine.py]"]
  node_query["Alignment Query<br/>[query.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_tools_gui["Tools GUI<br/>[EMAPSSN_Tools.py]"]
  node_desktop["Desktop Viewer<br/>[Desktop_App.py]"]
  node_web_server["Web Server<br/>[Web_Server.py]"]
  node_plugin_manager["Web Plugins<br/>[Plugin_Manager.py]"]
end

subgraph group_mcp["MCP Access"]
  node_mcp_server["MCP Server"]
  node_workflow["Workflow Dispatch"]
  node_pipeline_ops["Pipeline Operations"]
  node_jobs["Pipeline Jobs<br/>[Pipeline_Jobs.py]"]
  node_inspection["File Inspection"]
  node_viewer_ops["Viewer Operations"]
end

node_user(("Researcher"))
node_mcp_client(("MCP Client"))

node_user -->|"configures and runs"| node_tools_gui
node_tools_gui -->|"runs pipeline tool"| node_sanitize
node_tools_gui -->|"runs pipeline tool"| node_embeddings
node_tools_gui -->|"runs pipeline tool"| node_traditional_search
node_tools_gui -->|"runs pipeline tool"| node_embedding_search
node_sanitize -->|"writes sequence data"| node_hdf5
node_embeddings -->|"writes embeddings"| node_hdf5
node_traditional_search -->|"similarity results"| node_network_build
node_embedding_search -->|"similarity results"| node_network_build
node_network_build -->|"writes network data"| node_hdf5
node_network_inject -->|"updates network data"| node_hdf5
node_alignments -->|"stores alignments"| node_hdf5
node_layout_cache -->|"calculates layout"| node_layout_ssn
node_layout_cache -->|"calculates layout"| node_layout_umap
node_layout_cache -->|"reads network data"| node_hdf5
node_layout_cache -->|"writes layout cache"| node_hdf5
node_user -->|"opens application"| node_desktop
node_desktop -->|"launches"| node_viewer
node_viewer -->|"loads network data"| node_hdf5
node_viewer -->|"dispatches commands"| node_commands
node_commands -->|"dispatches query"| node_query
node_query -->|"reads alignment data"| node_hdf5
node_viewer -->|"serves web interface"| node_web_server
node_web_server -->|"activates plugins"| node_plugin_manager
node_mcp_client -->|"STDIO requests"| node_mcp_server
node_mcp_server -->|"dispatches workflows"| node_workflow
node_workflow -->|"routes pipeline actions"| node_pipeline_ops
node_pipeline_ops -->|"submits and monitors"| node_jobs
node_jobs -->|"runs pipeline programs"| node_tools_gui
node_pipeline_ops -->|"inspects files"| node_inspection
node_workflow -->|"routes Viewer actions"| node_viewer_ops
node_viewer_ops -->|"controls Viewer"| node_viewer

click node_tools_gui "https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_Tools.py"
click node_sanitize "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Sanitize_Sequences.py"
click node_embeddings "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Generate_Embeddings.py"
click node_traditional_search "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Embedding_PWA.py"
click node_embedding_search "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Embedding_SSEARCH.py"
click node_network_build "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Network_Extraction.py"
click node_network_inject "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Network_Injection.py"
click node_alignments "https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Embedding_MSA.py"
click node_hdf5 "https://github.com/xuebin-feng/emap-ssn/blob/main/src/utilities/HDF5_Storage.py"
click node_layout_cache "https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Cache_Generator.py"
click node_layout_ssn "https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Engine_SSN.py"
click node_layout_umap "https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Engine_UMAP.py"
click node_desktop "https://github.com/xuebin-feng/emap-ssn/blob/main/src/desktop/Desktop_App.py"
click node_viewer "https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_Viewer.py"
click node_commands "https://github.com/xuebin-feng/emap-ssn/blob/main/src/Command_Engine.py"
click node_query "https://github.com/xuebin-feng/emap-ssn/blob/main/src/commands/query.py"
click node_web_server "https://github.com/xuebin-feng/emap-ssn/blob/main/src/web_ui/Web_Server.py"
click node_plugin_manager "https://github.com/xuebin-feng/emap-ssn/blob/main/src/web_ui/Plugin_Manager.py"
click node_mcp_server "https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_MCP_Server.py"
click node_workflow "https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/core/Workflow_Dispatch.py"
click node_pipeline_ops "https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/pipeline/Pipeline_Operations.py"
click node_jobs "https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/pipeline/Pipeline_Jobs.py"
click node_inspection "https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/pipeline/Pipeline_File_Inspection.py"
click node_viewer_ops "https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/viewer/Viewer_Operations.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_sanitize,node_embeddings,node_traditional_search,node_embedding_search,node_network_build,node_network_inject,node_alignments,node_hdf5,node_mcp_client toneBlue
class node_layout_cache,node_layout_ssn,node_layout_umap toneAmber
class node_viewer,node_commands,node_query toneMint
class node_tools_gui,node_desktop,node_web_server,node_plugin_manager toneRose
class node_mcp_server,node_workflow,node_pipeline_ops,node_jobs,node_inspection,node_viewer_ops,node_user toneIndigo
```

## Components

### SSN Generation

- [Sequence Preparation](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Sanitize_Sequences.py): `src/tools/Sanitize_Sequences.py`
- [Embedding Generation](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Generate_Embeddings.py): `src/tools/Generate_Embeddings.py`
- [Sequence Similarity](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Embedding_PWA.py): `src/tools/Embedding_PWA.py`
- [Embedding Search](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Embedding_SSEARCH.py): `src/tools/Embedding_SSEARCH.py`
- [Network Extraction](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Network_Extraction.py): `src/tools/Network_Extraction.py`
- [Network Injection](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Network_Injection.py): `src/tools/Network_Injection.py`
- [Alignment Processing](https://github.com/xuebin-feng/emap-ssn/blob/main/src/tools/Embedding_MSA.py): `src/tools/Embedding_MSA.py`
- [HDF5 Data](https://github.com/xuebin-feng/emap-ssn/blob/main/src/utilities/HDF5_Storage.py): `src/utilities/HDF5_Storage.py`

### Network Analysis

- [Layout Cache](https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Cache_Generator.py): `src/Layout_Cache_Generator.py`
- [SSN Layout](https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Engine_SSN.py): `src/Layout_Engine_SSN.py`
- [UMAP Layout](https://github.com/xuebin-feng/emap-ssn/blob/main/src/Layout_Engine_UMAP.py): `src/Layout_Engine_UMAP.py`

### Interactive Viewer

- [SSN Viewer](https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_Viewer.py): `src/EMAPSSN_Viewer.py`
- [Analysis Commands](https://github.com/xuebin-feng/emap-ssn/blob/main/src/Command_Engine.py): `src/Command_Engine.py`
- [Alignment Query](https://github.com/xuebin-feng/emap-ssn/blob/main/src/commands/query.py): `src/commands/query.py`

### User Interfaces

- [Tools GUI](https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_Tools.py): `src/EMAPSSN_Tools.py`
- [Desktop Viewer](https://github.com/xuebin-feng/emap-ssn/blob/main/src/desktop/Desktop_App.py): `src/desktop/Desktop_App.py`
- [Web Server](https://github.com/xuebin-feng/emap-ssn/blob/main/src/web_ui/Web_Server.py): `src/web_ui/Web_Server.py`
- [Web Plugins](https://github.com/xuebin-feng/emap-ssn/blob/main/src/web_ui/Plugin_Manager.py): `src/web_ui/Plugin_Manager.py`

### MCP Access

- [MCP Server](https://github.com/xuebin-feng/emap-ssn/blob/main/src/EMAPSSN_MCP_Server.py): `src/EMAPSSN_MCP_Server.py`
- [Workflow Dispatch](https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/core/Workflow_Dispatch.py): `src/mcp_server/core/Workflow_Dispatch.py`
- [Pipeline Operations](https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/pipeline/Pipeline_Operations.py): `src/mcp_server/pipeline/Pipeline_Operations.py`
- [Pipeline Jobs](https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/pipeline/Pipeline_Jobs.py): `src/mcp_server/pipeline/Pipeline_Jobs.py`
- [File Inspection](https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/pipeline/Pipeline_File_Inspection.py): `src/mcp_server/pipeline/Pipeline_File_Inspection.py`
- [Viewer Operations](https://github.com/xuebin-feng/emap-ssn/blob/main/src/mcp_server/viewer/Viewer_Operations.py): `src/mcp_server/viewer/Viewer_Operations.py`

### Other components

- **Researcher**
- **MCP Client**

## Connections

- Researcher → Tools GUI: configures and runs
- Tools GUI → Sequence Preparation: runs pipeline tool
- Tools GUI → Embedding Generation: runs pipeline tool
- Tools GUI → Sequence Similarity: runs pipeline tool
- Tools GUI → Embedding Search: runs pipeline tool
- Sequence Preparation → HDF5 Data: writes sequence data
- Embedding Generation → HDF5 Data: writes embeddings
- Sequence Similarity → Network Extraction: similarity results
- Embedding Search → Network Extraction: similarity results
- Network Extraction → HDF5 Data: writes network data
- Network Injection → HDF5 Data: updates network data
- Alignment Processing → HDF5 Data: stores alignments
- Layout Cache → SSN Layout: calculates layout
- Layout Cache → UMAP Layout: calculates layout
- Layout Cache → HDF5 Data: reads network data
- Layout Cache → HDF5 Data: writes layout cache
- Researcher → Desktop Viewer: opens application
- Desktop Viewer → SSN Viewer: launches
- SSN Viewer → HDF5 Data: loads network data
- SSN Viewer → Analysis Commands: dispatches commands
- Analysis Commands → Alignment Query: dispatches query
- Alignment Query → HDF5 Data: reads alignment data
- SSN Viewer → Web Server: serves web interface
- Web Server → Web Plugins: activates plugins
- MCP Client → MCP Server: STDIO requests
- MCP Server → Workflow Dispatch: dispatches workflows
- Workflow Dispatch → Pipeline Operations: routes pipeline actions
- Pipeline Operations → Pipeline Jobs: submits and monitors
- Pipeline Jobs → Tools GUI: runs pipeline programs
- Pipeline Operations → File Inspection: inspects files
- Workflow Dispatch → Viewer Operations: routes Viewer actions
- Viewer Operations → SSN Viewer: controls Viewer