Deploy MuSProt React and FastAPI application

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.claude
+**/.git
+**/__pycache__
+**/*.pyc
+**/node_modules
+**/build
+**/coverage
+**/.env*
+omaib-be-monorepo
+omaib-fe
+trial.ipynb
+convert_csvtsv_to_db.py

.env.example

@@ -0,0 +1,11 @@
+MUSPROT_DATASET_REPO=wenruifan/<dataset-repository>
+MUSPROT_DATASET_REVISION=main
+MUSPROT_DB_FILENAME=MuSProt.db
+
+# Optional mounted-volume overrides
+# MUSPROT_DB_PATH=/data/MuSProt.db
+# MUSPROT_SUMMARY_PATH=/data/musprot_summary.json
+# MUSPROT_DOCS_PATH=/data/MuSProt_documentation.md
+# MUSPROT_PLOTS_DIR=/data/plots
+
+MUSPROT_PRELOAD_NODE_INDEX=1

.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+.env
+.env.*
+!.env.example
+
+node_modules/
+build/
+dist/
+coverage/
+
+omaib-be-monorepo/
+omaib-fe/node_modules/
+omaib-fe/build/
+
+__pycache__/
+*.py[cod]
+*.db
+backend/data/

Dockerfile

@@ -1,20 +1,28 @@
-FROM python:3.13.5-slim
+# syntax=docker/dockerfile:1.7
 
-WORKDIR /app
+FROM node:20-alpine AS frontend-builder
+WORKDIR /frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
 
-RUN apt-get update && apt-get install -y \
-    build-essential \
-    curl \
-    git \
-    && rm -rf /var/lib/apt/lists/*
+FROM python:3.12-slim AS runtime
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    MUSPROT_FRONTEND_DIR=/app/frontend
 
-COPY requirements.txt ./
-COPY src/ ./src/
+WORKDIR /app
+COPY backend/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
 
-RUN pip3 install -r requirements.txt
+COPY backend/app ./app
+COPY backend/assets ./assets
+COPY backend/space_app.py ./space_app.py
+COPY --from=frontend-builder /frontend/build ./frontend
 
 EXPOSE 8501
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30m --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8501/health')"
 
-HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
-
-ENTRYPOINT ["streamlit", "run", "src/streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"]
+CMD ["uvicorn", "space_app:app", "--host", "0.0.0.0", "--port", "8501", "--workers", "1"]

README.md

@@ -1,20 +1,84 @@
 ---
 title: MuSProt
-emoji: 🚀
-colorFrom: red
-colorTo: red
+emoji: 🧬
+colorFrom: blue
+colorTo: gray
 sdk: docker
 app_port: 8501
-tags:
-- streamlit
 pinned: false
-short_description: A Multistate Multimodal Protein Dataset
+short_description: A multistate multimodal protein structure dataset
 license: mit
 ---
 
-# Welcome to Streamlit!
+# MuSProt
 
-Edit `/src/streamlit_app.py` to customize this app to your heart's desire. :heart:
+MuSProt is a multistate protein structure database with pairwise structural
+comparisons, energy annotations, experimental metadata, and functional
+annotations.
 
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+## Space configuration
+
+The Docker Space serves a React frontend and a MuSProt-only FastAPI backend.
+The SQLite database is always opened in immutable read-only mode.
+
+```text
+frontend/   React/Vite MuSProt explorer
+backend/    MuSProt-only FastAPI API and bundled small assets
+Dockerfile  Hugging Face Docker Space build
+```
+
+Provide the database using one of these approaches:
+
+1. Mount or upload it to `/data/MuSProt.db`.
+2. Set `MUSPROT_DATASET_REPO` to a Hugging Face Dataset repository containing
+   `MuSProt.db`.
+
+Recommended Dataset repository files:
+
+```text
+MuSProt.db
+musprot_summary.json
+MuSProt_documentation.md
+plots/
+```
+
+Optional Space variables:
+
+```text
+MUSPROT_DB_PATH=/data/MuSProt.db
+MUSPROT_SUMMARY_PATH=/data/musprot_summary.json
+MUSPROT_DOCS_PATH=/data/MuSProt_documentation.md
+MUSPROT_PLOTS_DIR=/data/plots
+MUSPROT_DATASET_REPO=wenruifan/<dataset-repository>
+MUSPROT_DATASET_REVISION=main
+MUSPROT_DB_FILENAME=MuSProt.db
+MUSPROT_PRELOAD_NODE_INDEX=1
+```
+
+For a private Dataset repository, add `HF_TOKEN` as a Space secret.
+
+## Updating the database
+
+When publishing a new `MuSProt.db`, regenerate the bundled summary sidecar:
+
+```bash
+cd backend
+python scripts/generate_summary.py /path/to/MuSProt.db -o assets/musprot_summary.json
+```
+
+The deployed application does not create indexes or modify the SQLite file.
+Create any required indexes before uploading the database to the Dataset
+repository.
+
+## Local verification
+
+```bash
+cd frontend
+npm ci
+npm run build
+
+cd ../backend
+MUSPROT_DB_PATH=/path/to/MuSProt.db \
+MUSPROT_FRONTEND_DIR=../frontend/build \
+uvicorn space_app:app --host 0.0.0.0 --port 8501
+```

backend/app/protein/__init__.py

@@ -0,0 +1 @@
+# Empty init file

backend/app/protein/api/__init__.py

@@ -0,0 +1 @@
+"""Protein API package."""

backend/app/protein/api/routes/__init__.py

@@ -0,0 +1 @@
+"""Protein route modules."""

backend/app/protein/api/routes/protein.py

@@ -0,0 +1,263 @@
+"""Protein API routes."""
+import logging
+import math
+from typing import Dict, List
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.protein.chain_resolver import (
+    batch_resolve_chains_async,
+    get_cache,
+    resolve_chain_async,
+)
+from app.protein.data_loader import DataManager
+from app.protein import tsv_loader
+from app.protein.models import (
+    ChainMetadata,
+    DataRecord,
+    DataResponse,
+    FilterOptions,
+    FilterParams,
+    SummaryStats,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+data_manager: DataManager | None = None
+
+
+def set_data_manager(manager: DataManager | None) -> None:
+    """Set the active data manager for route handlers."""
+    global data_manager
+    data_manager = manager
+
+
+def _require_data_manager() -> DataManager:
+    """Return data manager or raise if not initialized."""
+    if data_manager is None:
+        raise HTTPException(
+            status_code=503,
+            detail="Protein data is not initialized yet"
+        )
+    return data_manager
+
+
+@router.get("/")
+async def root():
+    """Root endpoint."""
+    return {
+        "message": "Protein Visualisation API",
+        "version": "1.0.0",
+        "endpoints": {
+            "/filters": "Get available filter options",
+            "/data": "Get filtered protein data",
+            "/summary": "Get aggregate statistics"
+        }
+    }
+
+
+@router.get("/filters", response_model=FilterOptions)
+async def get_filters():
+    """Get available filter options and ranges."""
+    try:
+        manager = _require_data_manager()
+        chains = sorted(list(manager.get_all_chains()))
+        fd = manager.get_filters_data()
+
+        return FilterOptions(
+            chain_ids=chains[:100],
+            rmsd_range={"min": float(fd["rmsd_min"]), "max": float(fd["rmsd_max"])},
+            tm_score_range={"min": float(fd["tm_min"]), "max": float(fd["tm_max"])},
+            length_range={"min": int(fd["length_min"]), "max": int(fd["length_max"])},
+            clusters=[
+                "cluster_ultra_high", "cluster_very_high", "cluster_high",
+                "cluster_medium", "cluster_low",
+            ],
+            total_records=fd["total_records"],
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting filters: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/data", response_model=DataResponse)
+async def get_data(filters: FilterParams):
+    """Get filtered protein data. Searches only by pdb_id_A and auth_asym_id_A."""
+    try:
+        manager = _require_data_manager()
+        limit = filters.limit or 1000
+        fetch_limit = limit * 10 if filters.cluster_id else limit
+
+        df = manager.query_edge(
+            pdb_id_a=filters.pdb_id,
+            auth_asym_id_a=filters.auth_asym_id,
+            chain_ids=filters.chain_ids,
+            rmsd_min=filters.rmsd_min,
+            rmsd_max=filters.rmsd_max,
+            tm_min=filters.tm_score_min,
+            tm_max=filters.tm_score_max,
+            limit=fetch_limit,
+        )
+
+        if filters.cluster_id:
+            df = df[df["cluster_id"] == filters.cluster_id]
+
+        filtered_total = len(df)
+        df = df.head(limit)
+
+        def _safe_float(val):
+            try:
+                v = float(val)
+                return None if math.isnan(v) else round(v, 6)
+            except (TypeError, ValueError):
+                return None
+
+        records = []
+        for row in df.itertuples(index=False):
+            raw_ph = getattr(row, "pH", None)
+            raw_temp = getattr(row, "temp_K", None)
+            records.append(DataRecord(
+                pdb_id_a=row.pdb_id_A,
+                auth_asym_id_a=row.auth_asym_id_A,
+                pdb_id_b=row.pdb_id_B,
+                auth_asym_id_b=row.auth_asym_id_B,
+                tm_score=float(row.TM1) if row.TM1 is not None else 0.0,
+                rmsd=float(row.RMSD) if row.RMSD is not None else 0.0,
+                structure_sim=_safe_float(row.structure_sim),
+                length_a=int(row.length_a) if row.length_a is not None else None,
+                length_b=int(row.length_b) if row.length_b is not None else None,
+                cluster_id=row.cluster_id,
+                exptl_method=getattr(row, "experimental_method", None) or None,
+                pH=_safe_float(raw_ph) if raw_ph else None,
+                temp=_safe_float(raw_temp) if raw_temp else None,
+                delta_rosetta=_safe_float(getattr(row, "delta_Rosetta", None)),
+                delta_foldx=_safe_float(getattr(row, "delta_FoldX", None)),
+                delta_evoef2=_safe_float(getattr(row, "delta_EvoEF2", None)),
+                delta_rm=_safe_float(getattr(row, "delta_RM", None)),
+                delta_rm_plus=_safe_float(getattr(row, "delta_RM_plus", None)),
+                state_id_b=getattr(row, "state_id_B", None) or None,
+                state_fidelity=getattr(row, "state_fidelity", None) or None,
+                avg_sim=getattr(row, "avg_sim", None) or None,
+                pair_fidelity=getattr(row, "pair_fidelity", None) or None,
+            ))
+
+        return DataResponse(
+            data=records,
+            total=manager.get_total(),
+            filtered=filtered_total,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error filtering data: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/summary", response_model=SummaryStats)
+async def get_summary(
+    chain_ids: List[str] = Query(default=None),
+    rmsd_min: float = Query(default=None),
+    rmsd_max: float = Query(default=None),
+    tm_score_min: float = Query(default=None),
+    tm_score_max: float = Query(default=None),
+):
+    """Get aggregate statistics for the dataset or filtered subset."""
+    try:
+        manager = _require_data_manager()
+        stats = manager.get_summary_stats(
+            chain_ids=chain_ids,
+            rmsd_min=rmsd_min,
+            rmsd_max=rmsd_max,
+            tm_min=tm_score_min,
+            tm_max=tm_score_max,
+        )
+        return SummaryStats(
+            total_records=stats["total_records"],
+            unique_chains=stats["unique_chains"],
+            avg_rmsd=float(stats["avg_rmsd"]),
+            avg_tm_score=float(stats["avg_tm_score"]),
+            avg_sequence_length=float(stats["avg_sequence_length"]),
+            rmsd_distribution={str(k): int(v) for k, v in stats["rmsd_distribution"].items()},
+            tm_score_distribution={str(k): int(v) for k, v in stats["tm_score_distribution"].items()},
+            length_distribution={str(k): int(v) for k, v in stats["length_distribution"].items()},
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error computing summary: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/chain/resolve", response_model=ChainMetadata)
+async def resolve_chain_endpoint(
+    pdb_id: str = Query(..., description="4-character PDB ID"),
+    auth_asym_id: str = Query(..., description="Chain identifier (e.g., 'A')"),
+    use_cache: bool = Query(True, description="Use cached data if available")
+):
+    """Resolve chain metadata from RCSB web API."""
+    metadata = await resolve_chain_async(pdb_id, auth_asym_id, use_cache=use_cache)
+    return metadata.model_copy(update={
+        "binding_status": tsv_loader.get_binding_status(pdb_id, auth_asym_id),
+        "cath_id": tsv_loader.get_cath_id(pdb_id, auth_asym_id),
+        "cath_superfamily": tsv_loader.get_cath_superfamily(pdb_id, auth_asym_id),
+        "state_id": tsv_loader.get_state_id(pdb_id, auth_asym_id),
+    })
+
+
+@router.post("/chain/batch-resolve")
+async def batch_resolve_chains_endpoint(
+    chains: List[Dict[str, str]],
+    use_cache: bool = Query(True, description="Use cached data if available")
+):
+    """Batch resolve multiple chains at once."""
+    chain_tuples = []
+    for chain in chains:
+        pdb_id = chain.get("pdb_id")
+        auth_asym_id = chain.get("auth_asym_id")
+        if pdb_id and auth_asym_id:
+            chain_tuples.append((pdb_id, auth_asym_id))
+
+    result = await batch_resolve_chains_async(chain_tuples, use_cache=use_cache)
+    return {
+        key: metadata.model_copy(update={
+            "binding_status": tsv_loader.get_binding_status(*key.split("|")),
+            "cath_id": tsv_loader.get_cath_id(*key.split("|")),
+            "cath_superfamily": tsv_loader.get_cath_superfamily(*key.split("|")),
+            "state_id": tsv_loader.get_state_id(*key.split("|")),
+        })
+        for key, metadata in result.items()
+    }
+
+
+@router.get("/chain/cache/stats")
+async def cache_stats():
+    """Get cache statistics."""
+    cache = get_cache()
+    return {
+        "cached_chains": len(cache.cache),
+        "ttl_hours": cache.ttl.total_seconds() / 3600
+    }
+
+
+@router.get("/chain/functions")
+async def get_chain_functions(
+    pdb_id: str = Query(..., description="4-character PDB ID"),
+    auth_asym_id: str = Query(..., description="Chain identifier (e.g., 'A')"),
+):
+    """Return ranked functional annotations for a chain from node table."""
+    functions = tsv_loader.get_functions(pdb_id, auth_asym_id)
+    if functions is None:
+        raise HTTPException(status_code=404, detail=f"No annotation found for {pdb_id}:{auth_asym_id}")
+    return {"pdb_id": pdb_id.lower(), "chain_id": auth_asym_id.upper(), "functions": functions}
+
+
+@router.post("/chain/cache/clear")
+async def clear_cache():
+    """Clear the chain metadata cache."""
+    cache = get_cache()
+    cache.clear()
+    return {"message": "Cache cleared successfully"}

backend/app/protein/chain_resolver.py

@@ -0,0 +1,519 @@
+"""
+Chain metadata resolution service with caching.
+"""
+import asyncio
+import logging
+import sys
+from pathlib import Path
+from typing import Dict, Tuple, Optional, List
+from datetime import datetime, timedelta
+from fastapi import HTTPException
+
+# Add parent directory to path to import fetch_chain_info_from_pdb
+sys.path.insert(0, str(Path(__file__).parent))
+
+try:
+    from app.protein.fetch_chain_info_from_pdb import build_query, _safe_get, extract_ph_from_details
+    from rcsbapi.data import DataQuery
+    HAS_RCSB_API = True
+except ImportError:
+    logging.warning("fetch_chain_info_from_pdb or rcsbapi not found, using mock implementation")
+    HAS_RCSB_API = False
+
+from app.protein.models import ChainMetadata, EntryInfo, CrystalGrow, PolymerEntity, PolymerEntityInstance, NonpolymerEntity
+from app.protein import tsv_loader
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_chain_record_async(pdb_id: str, auth_asym_id: str) -> dict:
+    """
+    Async version of fetch_chain_record that safely executes DataQuery.exec()
+    in a separate thread to avoid asyncio.run() conflicts.
+    
+    Args:
+        pdb_id: 4-character PDB ID
+        auth_asym_id: Chain identifier
+    
+    Returns:
+        dict with entry, polymer_entity, polymer_entity_instance, meta
+    
+    Raises:
+        ValueError: if chain not found or ambiguous
+    """
+    if not HAS_RCSB_API:
+        # Mock implementation for testing
+        return {
+            "entry": {
+                "rcsb_id": pdb_id,
+                "title": f"Mock entry for {pdb_id}",
+                "exptl_method": "X-RAY DIFFRACTION",
+                "resolution_combined": [1.5],
+                "crystal_grow": {
+                    "pH": 7.0,
+                    "temp": 298.0,
+                    "pdbx_details": "Mock crystal growth conditions"
+                }
+            },
+            "polymer_entity": {
+                "rcsb_id": f"{pdb_id}_1",
+                "entity_id": "1",
+                "sequence_length": 300,
+            },
+            "polymer_entity_instance": {
+                "rcsb_id": f"{pdb_id}.{auth_asym_id}",
+                "auth_asym_id": auth_asym_id,
+            },
+            "meta": {
+                "pdb_id": pdb_id,
+                "auth_asym_id": auth_asym_id,
+            }
+        }
+    
+    # Build query
+    dq = build_query(pdb_id)
+    
+    # Execute in separate thread to avoid asyncio.run() conflict
+    # DataQuery.exec() internally uses asyncio.run() which can't be called
+    # from within FastAPI's event loop
+    def _exec_query():
+        return dq.exec()
+    
+    result = await asyncio.to_thread(_exec_query)
+    data = result["data"]["entries"][0]
+    
+    if not data:
+        raise ValueError(f"No data returned for entry {pdb_id}")
+    
+    # Parse entry-level data (same logic as fetch_chain_record)
+    ph_struct = _safe_get(data, "exptl_crystal_grow.pH")
+    pdbx_details = _safe_get(data, "exptl_crystal_grow.pdbx_details")
+    xray_temp = _safe_get(data, "exptl_crystal_grow.temp")
+
+    # Cryo-EM fallbacks (used when crystal grow fields are absent)
+    em_temp = _safe_get(data, "em_vitrification.temp")
+    em_cryogen = _safe_get(data, "em_vitrification.cryogen_name")
+    em_assembly_details = _safe_get(data, "em_entity_assembly.details")
+
+    # Compose EM details from available fields
+    em_details_parts = []
+    if em_assembly_details:
+        em_details_parts.append(em_assembly_details)
+    if em_cryogen:
+        em_details_parts.append(f"Vitrified in {em_cryogen}")
+    em_details = "; ".join(em_details_parts) if em_details_parts else None
+
+    entry_pack = {
+        "rcsb_id": data.get("rcsb_id"),
+        "title": _safe_get(data, "struct.title"),
+        "initial_release_date": _safe_get(data, "rcsb_accession_info.initial_release_date"),
+        "exptl_method": _safe_get(data, "exptl.method"),
+        "resolution_combined": _safe_get(data, "rcsb_entry_info.resolution_combined"),
+        "crystal_grow": {
+            "pH": (
+                ph_struct if ph_struct is not None
+                else extract_ph_from_details(pdbx_details)
+            ),
+            "pH_structured": ph_struct,
+            "pH_from_details": extract_ph_from_details(pdbx_details),
+            "temp": xray_temp if xray_temp is not None else em_temp,
+            "pdbx_details": pdbx_details if pdbx_details is not None else em_details,
+        },
+        "refine": {
+            "ls_d_res_high": _safe_get(data, "refine.ls_d_res_high"),
+            "details": _safe_get(data, "refine.details"),
+        },
+    }
+    
+    # Find matching chain instance
+    polymer_entities = data.get("polymer_entities") or []
+    nonpolymer_entities = data.get("nonpolymer_entities") or []
+    
+    matches: List[Tuple[dict, dict]] = []
+    for ent in polymer_entities:
+        instances = ent.get("polymer_entity_instances") or []
+        for inst in instances:
+            ids = inst.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+            if ids.get("auth_asym_id") == auth_asym_id:
+                matches.append((ent, inst))
+    
+    if len(matches) == 0:
+        raise ValueError(
+            f"No polymer_entity_instance found with auth_asym_id='{auth_asym_id}' in entry {pdb_id}"
+        )
+    
+    if len(matches) > 1:
+        amb = []
+        for e, i in matches:
+            ids = i.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+            amb.append({
+                "entity_rcsb_id": e.get("rcsb_id"),
+                "instance_rcsb_id": i.get("rcsb_id"),
+                "asym_id": ids.get("asym_id"),
+                "auth_asym_id": ids.get("auth_asym_id"),
+            })
+        raise ValueError(
+            f"Ambiguous: {len(matches)} instances match auth_asym_id='{auth_asym_id}' in entry {pdb_id}. "
+            f"Candidates: {amb}"
+        )
+    
+    ent, inst = matches[0]
+    
+    # Build polymer entity pack
+    polymer_entity_pack = {
+        "rcsb_id": ent.get("rcsb_id"),
+        "entity_id": _safe_get(ent, "rcsb_polymer_entity_container_identifiers.entity_id"),
+        "sequence_length": _safe_get(ent, "entity_poly.rcsb_sample_sequence_length"),
+        "seq_can": _safe_get(ent, "entity_poly.pdbx_seq_one_letter_code_can"),
+        "reference_sequences": _safe_get(
+            ent,
+            "rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers",
+            default=[],
+        ),
+    }
+    
+    # Build polymer instance pack
+    ids = inst.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+    polymer_instance_pack = {
+        "rcsb_id": inst.get("rcsb_id"),
+        "asym_id": ids.get("asym_id"),
+        "auth_asym_id": ids.get("auth_asym_id"),
+        "binding_affinity": inst.get("rcsb_binding_affinity"),
+        "instance_annotations": inst.get("rcsb_polymer_entity_instance_annotation"),
+    }
+    
+    # Build nonpolymer entities list (ligands)
+    nonpolymer_list = []
+    for npe in nonpolymer_entities:
+        nonpolymer_list.append({
+            "rcsb_nonpolymer_entity_container_identifiers": npe.get(
+                "rcsb_nonpolymer_entity_container_identifiers"
+            ),
+            "nonpolymer_comp": npe.get("nonpolymer_comp"),
+        })
+    
+    return {
+        "entry": entry_pack,
+        "polymer_entity": polymer_entity_pack,
+        "polymer_entity_instance": polymer_instance_pack,
+        "nonpolymer_entities": nonpolymer_list,
+        "meta": {
+            "pdb_id": pdb_id,
+            "auth_asym_id": auth_asym_id,
+            "matched_instance_rcsb_id": inst.get("rcsb_id"),
+        },
+    }
+
+
+class ChainCache:
+    """In-memory cache for chain metadata with TTL and negative caching."""
+    
+    def __init__(self, ttl_hours: int = 24, negative_ttl_hours: int = 1):
+        self.cache: Dict[Tuple[str, str], Tuple[ChainMetadata, datetime]] = {}
+        self.negative_cache: Dict[Tuple[str, str], Tuple[str, datetime]] = {}  # Store error message + timestamp
+        self.ttl = timedelta(hours=ttl_hours)
+        self.negative_ttl = timedelta(hours=negative_ttl_hours)
+    
+    def get(self, pdb_id: str, auth_asym_id: str) -> Optional[ChainMetadata]:
+        """Get cached metadata if not expired."""
+        key = (pdb_id.lower(), auth_asym_id.upper())
+        if key in self.cache:
+            metadata, timestamp = self.cache[key]
+            if datetime.now() - timestamp < self.ttl:
+                logger.info(f"Cache hit for {pdb_id}:{auth_asym_id}")
+                return metadata
+            else:
+                # Expired, remove
+                del self.cache[key]
+                logger.info(f"Cache expired for {pdb_id}:{auth_asym_id}")
+        return None
+    
+    def get_negative(self, pdb_id: str, auth_asym_id: str) -> Optional[str]:
+        """Check if chain is in negative cache (known to not exist)."""
+        key = (pdb_id.lower(), auth_asym_id.upper())
+        if key in self.negative_cache:
+            error_msg, timestamp = self.negative_cache[key]
+            if datetime.now() - timestamp < self.negative_ttl:
+                logger.info(f"Negative cache hit for {pdb_id}:{auth_asym_id}")
+                return error_msg
+            else:
+                # Expired, remove
+                del self.negative_cache[key]
+                logger.info(f"Negative cache expired for {pdb_id}:{auth_asym_id}")
+        return None
+    
+    def set(self, pdb_id: str, auth_asym_id: str, metadata: ChainMetadata):
+        """Store metadata in cache."""
+        key = (pdb_id.lower(), auth_asym_id.upper())
+        self.cache[key] = (metadata, datetime.now())
+        # Remove from negative cache if it was there
+        self.negative_cache.pop(key, None)
+        logger.info(f"Cached metadata for {pdb_id}:{auth_asym_id}")
+    
+    def set_negative(self, pdb_id: str, auth_asym_id: str, error_msg: str):
+        """Store negative cache entry (chain not found)."""
+        key = (pdb_id.lower(), auth_asym_id.upper())
+        self.negative_cache[key] = (error_msg, datetime.now())
+        logger.info(f"Negative cached {pdb_id}:{auth_asym_id} - {error_msg}")
+    
+    def clear(self):
+        """Clear all cache."""
+        self.cache.clear()
+        self.negative_cache.clear()
+        logger.info("Cache cleared")
+
+
+# Global cache instance (24h positive cache, 1h negative cache)
+_chain_cache = ChainCache(ttl_hours=24, negative_ttl_hours=1)
+
+
+async def resolve_chain_async(pdb_id: str, auth_asym_id: str, use_cache: bool = True) -> ChainMetadata:
+    """
+    Async version of resolve_chain that works in FastAPI context.
+    
+    Args:
+        pdb_id: 4-character PDB ID (case-insensitive)
+        auth_asym_id: Chain identifier (case-insensitive)
+        use_cache: Whether to use cache (default True)
+    
+    Returns:
+        ChainMetadata object
+    
+    Raises:
+        HTTPException: 400 for invalid params, 404 if not found, 502 if upstream fails
+    """
+    # Validate inputs
+    if not pdb_id or len(pdb_id) != 4:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid PDB ID: '{pdb_id}'. Must be 4 characters."
+        )
+    
+    if not auth_asym_id:
+        raise HTTPException(
+            status_code=400,
+            detail="auth_asym_id is required"
+        )
+    
+    pdb_id = pdb_id.lower()
+    auth_asym_id = auth_asym_id.upper()
+    
+    # Check cache
+    if use_cache:
+        cached = _chain_cache.get(pdb_id, auth_asym_id)
+        if cached:
+            return cached
+
+    # Fetch from web
+    logger.info(f"Fetching chain metadata from web: {pdb_id}:{auth_asym_id}")
+    
+    try:
+        raw_data = await fetch_chain_record_async(pdb_id, auth_asym_id)
+    except ValueError as e:
+        # Chain not found or ambiguous - add to negative cache
+        error_msg = str(e)
+        logger.warning(f"Chain resolution failed for {pdb_id}:{auth_asym_id} - {error_msg}")
+        
+        # Cache 404 responses to prevent repeated upstream queries
+        if "No polymer_entity_instance found" in error_msg and use_cache:
+            _chain_cache.set_negative(pdb_id, auth_asym_id, error_msg)
+        
+        raise HTTPException(status_code=404, detail=error_msg)
+    except Exception as e:
+        # Upstream API failure
+        error_msg = f"Failed to fetch chain metadata from RCSB: {str(e)}"
+        logger.error(f"Upstream error for {pdb_id}:{auth_asym_id} - {error_msg}")
+        raise HTTPException(status_code=502, detail=error_msg)
+    
+    # Parse into our models
+    try:
+        entry_data = raw_data.get("entry", {})
+        crystal_grow_data = entry_data.get("crystal_grow", {})
+        
+        # Extract pH with fallback logic (prefer structured, then extracted from details)
+        pH_value = crystal_grow_data.get("pH")
+        if pH_value is None:
+            pH_value = crystal_grow_data.get("pH_from_details")
+        if pH_value is None:
+            pH_value = crystal_grow_data.get("pH_structured")
+        
+        crystal_grow = CrystalGrow(
+            pH=pH_value,
+            pH_structured=crystal_grow_data.get("pH_structured"),
+            pH_from_details=crystal_grow_data.get("pH_from_details"),
+            temp=crystal_grow_data.get("temp"),
+            pdbx_details=crystal_grow_data.get("pdbx_details")
+        )
+        
+        entry = EntryInfo(
+            rcsb_id=entry_data.get("rcsb_id"),
+            title=entry_data.get("title"),
+            initial_release_date=entry_data.get("initial_release_date"),
+            exptl_method=entry_data.get("exptl_method"),
+            resolution_combined=entry_data.get("resolution_combined"),
+            crystal_grow=crystal_grow
+        )
+        
+        polymer_entity_data = raw_data.get("polymer_entity", {})
+        polymer_entity = PolymerEntity(
+            rcsb_id=polymer_entity_data.get("rcsb_id"),
+            entity_id=polymer_entity_data.get("entity_id"),
+            sequence_length=polymer_entity_data.get("sequence_length"),
+            seq_can=polymer_entity_data.get("seq_can"),
+            reference_sequences=polymer_entity_data.get("reference_sequences")
+        )
+        
+        instance_data = raw_data.get("polymer_entity_instance", {})
+        polymer_instance = PolymerEntityInstance(
+            rcsb_id=instance_data.get("rcsb_id"),
+            asym_id=instance_data.get("asym_id"),
+            auth_asym_id=instance_data.get("auth_asym_id"),
+            binding_affinity=instance_data.get("binding_affinity")
+        )
+        
+        # Parse nonpolymer entities (ligands/binders) - ASYNC VERSION
+        nonpolymer_list = []
+        nonpolymer_entities_raw = raw_data.get("nonpolymer_entities", [])
+        for npe in nonpolymer_entities_raw:
+            identifiers = npe.get("rcsb_nonpolymer_entity_container_identifiers", {})
+            comp = npe.get("nonpolymer_comp", {})
+            chem_comp = comp.get("chem_comp", {})
+            descriptors = comp.get("rcsb_chem_comp_descriptor", {})
+            
+            nonpolymer_list.append(NonpolymerEntity(
+                rcsb_id=identifiers.get("rcsb_id"),
+                name=chem_comp.get("name"),
+                formula_weight=chem_comp.get("formula_weight"),
+                smiles=descriptors.get("SMILES"),
+                inchi=descriptors.get("InChI")
+            ))
+        
+        # Prefer TSV sequence over RCSB (faster, always available for dataset chains)
+        tsv_seq, tsv_len = tsv_loader.get_sequence(pdb_id, auth_asym_id)
+        if tsv_seq is not None:
+            polymer_entity = PolymerEntity(
+                rcsb_id=polymer_entity.rcsb_id,
+                entity_id=polymer_entity.entity_id,
+                sequence_length=tsv_len if tsv_len is not None else polymer_entity.sequence_length,
+                seq_can=tsv_seq,
+                reference_sequences=polymer_entity.reference_sequences,
+            )
+
+        metadata = ChainMetadata(
+            pdb_id=pdb_id,
+            chain_id=auth_asym_id,
+            entry=entry,
+            polymer_entity=polymer_entity,
+            polymer_entity_instance=polymer_instance,
+            nonpolymer_entities=nonpolymer_list if nonpolymer_list else None
+        )
+
+        # Cache it
+        if use_cache:
+            _chain_cache.set(pdb_id, auth_asym_id, metadata)
+
+        return metadata
+        
+    except Exception as e:
+        logger.error(f"Failed to parse chain metadata: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to parse chain metadata: {str(e)}"
+        )
+
+
+def resolve_chain(pdb_id: str, auth_asym_id: str, use_cache: bool = True) -> ChainMetadata:
+    """
+    Synchronous wrapper for resolve_chain_async - deprecated, use resolve_chain_async instead.
+    
+    Args:
+        pdb_id: 4-character PDB ID (case-insensitive)
+        auth_asym_id: Chain identifier (case-insensitive)
+        use_cache: Whether to use cache (default True)
+    
+    Returns:
+        ChainMetadata object
+    
+    Raises:
+        HTTPException: 400 for invalid params, 404 if not found, 502 if upstream fails
+    """
+    import asyncio
+    # Run the async version in a sync context
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+    
+    return loop.run_until_complete(resolve_chain_async(pdb_id, auth_asym_id, use_cache))
+
+
+def batch_resolve_chains(chains: list[Tuple[str, str]], use_cache: bool = True) -> Dict[str, ChainMetadata]:
+    """
+    Resolve multiple chains in batch (synchronous version - deprecated).
+    
+    Args:
+        chains: List of (pdb_id, auth_asym_id) tuples
+        use_cache: Whether to use cache
+    
+    Returns:
+        Dict mapping "pdb_id|auth_asym_id" to ChainMetadata (only successful resolutions)
+    """
+    results = {}
+    
+    for pdb_id, auth_asym_id in chains:
+        key = f"{pdb_id.lower()}|{auth_asym_id.upper()}"
+        try:
+            metadata = resolve_chain(pdb_id, auth_asym_id, use_cache=use_cache)
+            results[key] = metadata
+        except HTTPException as e:
+            logger.warning(f"Failed to resolve {key}: {e.detail}")
+            continue
+        except Exception as e:
+            logger.error(f"Unexpected error resolving {key}: {e}")
+            continue
+    
+    return results
+
+
+async def batch_resolve_chains_async(chains: list[Tuple[str, str]], use_cache: bool = True, max_concurrent: int = 10) -> Dict[str, ChainMetadata]:
+    """
+    Resolve multiple chains in batch with controlled concurrency.
+    
+    Args:
+        chains: List of (pdb_id, auth_asym_id) tuples
+        use_cache: Whether to use cache
+        max_concurrent: Maximum number of concurrent requests to RCSB (default 10)
+    
+    Returns:
+        Dict mapping "pdb_id|auth_asym_id" to ChainMetadata (only successful resolutions)
+    """
+    results = {}
+    semaphore = asyncio.Semaphore(max_concurrent)
+    
+    async def resolve_with_semaphore(pdb_id: str, auth_asym_id: str):
+        async with semaphore:
+            key = f"{pdb_id.lower()}|{auth_asym_id.upper()}"
+            try:
+                metadata = await resolve_chain_async(pdb_id, auth_asym_id, use_cache=use_cache)
+                return key, metadata
+            except HTTPException as e:
+                logger.warning(f"Failed to resolve {key}: {e.detail}")
+                return key, None
+            except Exception as e:
+                logger.error(f"Unexpected error resolving {key}: {e}")
+                return key, None
+    
+    # Execute all requests concurrently with semaphore limit
+    tasks = [resolve_with_semaphore(pdb_id, auth_asym_id) for pdb_id, auth_asym_id in chains]
+    results_list = await asyncio.gather(*tasks)
+    
+    # Filter out None results (failed resolutions)
+    results = {key: metadata for key, metadata in results_list if metadata is not None}
+    
+    return results
+
+
+def get_cache() -> ChainCache:
+    """Get the global cache instance (for testing/admin)."""
+    return _chain_cache

backend/app/protein/config.py

@@ -0,0 +1,94 @@
+"""Runtime configuration for the MuSProt application."""
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from huggingface_hub import hf_hub_download
+
+
+DEFAULT_VOLUME_DIR = Path("/data")
+LOCAL_DATA_DIR = Path(__file__).resolve().parents[2] / "data" / "data_protein"
+ASSETS_DIR = Path(__file__).resolve().parents[2] / "assets"
+
+
+def _existing_path(*candidates: Path) -> Path | None:
+    return next((path for path in candidates if path.exists()), None)
+
+
+@lru_cache(maxsize=1)
+def get_database_path() -> Path:
+    """Resolve MuSProt.db from an explicit path, mounted volume, local data, or Hub."""
+    explicit_path = os.getenv("MUSPROT_DB_PATH")
+    if explicit_path:
+        path = Path(explicit_path).expanduser().resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"MUSPROT_DB_PATH does not exist: {path}")
+        return path
+
+    local_path = _existing_path(
+        DEFAULT_VOLUME_DIR / "MuSProt.db",
+        LOCAL_DATA_DIR / "json" / "MuSProt.db",
+    )
+    if local_path:
+        return local_path.resolve()
+
+    repo_id = os.getenv("MUSPROT_DATASET_REPO")
+    if not repo_id:
+        raise FileNotFoundError(
+            "MuSProt.db was not found. Set MUSPROT_DB_PATH, mount it at "
+            "/data/MuSProt.db, or set MUSPROT_DATASET_REPO."
+        )
+
+    return Path(
+        hf_hub_download(
+            repo_id=repo_id,
+            repo_type="dataset",
+            filename=os.getenv("MUSPROT_DB_FILENAME", "MuSProt.db"),
+            revision=os.getenv("MUSPROT_DATASET_REVISION", "main"),
+            token=os.getenv("HF_TOKEN"),
+        )
+    )
+
+
+def get_summary_path() -> Path | None:
+    """Return an optional precomputed summary JSON path."""
+    explicit_path = os.getenv("MUSPROT_SUMMARY_PATH")
+    if explicit_path:
+        path = Path(explicit_path).expanduser().resolve()
+        return path if path.exists() else None
+
+    return _existing_path(
+        DEFAULT_VOLUME_DIR / "musprot_summary.json",
+        ASSETS_DIR / "musprot_summary.json",
+        LOCAL_DATA_DIR / "musprot_summary.json",
+    )
+
+
+def get_docs_path() -> Path | None:
+    """Return the dataset documentation path when available."""
+    explicit_path = os.getenv("MUSPROT_DOCS_PATH")
+    if explicit_path:
+        path = Path(explicit_path).expanduser().resolve()
+        return path if path.exists() else None
+
+    return _existing_path(
+        DEFAULT_VOLUME_DIR / "MuSProt_documentation.md",
+        ASSETS_DIR / "MuSProt_documentation.md",
+        LOCAL_DATA_DIR / "MuSProt_documentation.md",
+    )
+
+
+def get_plots_dir() -> Path | None:
+    """Return a directory containing only public MuSProt plot assets."""
+    explicit_path = os.getenv("MUSPROT_PLOTS_DIR")
+    if explicit_path:
+        path = Path(explicit_path).expanduser().resolve()
+        return path if path.is_dir() else None
+
+    return _existing_path(
+        DEFAULT_VOLUME_DIR / "plots",
+        ASSETS_DIR / "plots",
+        LOCAL_DATA_DIR / "plots",
+    )

backend/app/protein/data_loader.py

@@ -0,0 +1,324 @@
+"""
+SQLite-based data loader for protein structure data.
+Reads from MuSProt.db: edge table (pairwise comparisons from CSV)
+and node table (chain annotations from TSV).
+"""
+import json
+import pandas as pd
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+import logging
+
+from app.protein.config import get_database_path, get_summary_path
+from app.protein.database import connect_readonly
+
+logger = logging.getLogger(__name__)
+
+
+def _assign_cluster(tm: float) -> str:
+    if tm >= 0.99:
+        return "cluster_ultra_high"
+    if tm >= 0.95:
+        return "cluster_very_high"
+    if tm >= 0.90:
+        return "cluster_high"
+    if tm >= 0.80:
+        return "cluster_medium"
+    return "cluster_low"
+
+
+class DataManager:
+    """Manages SQL queries against MuSProt.db edge and node tables."""
+
+    def __init__(self, db_path: Optional[Path] = None, **_kwargs):
+        self.db_path = db_path or get_database_path()
+        self._loaded = False
+        self._total_records = 0
+        self._summary: Dict[str, Any] = {}
+
+    def load_data(self) -> None:
+        """Verify DB is accessible and load optional precomputed metadata."""
+        if self._loaded:
+            return
+        summary_path = get_summary_path()
+        if summary_path:
+            self._summary = json.loads(summary_path.read_text(encoding="utf-8"))
+            self._total_records = int(self._summary.get("total_records", 0))
+
+        conn = connect_readonly(self.db_path)
+        try:
+            cur = conn.cursor()
+            cur.execute("SELECT 1 FROM edge LIMIT 1")
+            if not self._total_records:
+                logger.warning(
+                    "No musprot_summary.json found; counting edge rows during startup. "
+                    "Publish the summary sidecar to avoid this scan."
+                )
+                cur.execute("SELECT COUNT(*) FROM edge")
+                self._total_records = cur.fetchone()[0]
+        finally:
+            conn.close()
+        self._loaded = True
+        logger.info(f"DataManager ready: {self._total_records:,} edge records in {self.db_path}")
+
+    def _connect(self):
+        if not self._loaded:
+            raise RuntimeError("Call load_data() first.")
+        return connect_readonly(self.db_path)
+
+    def get_all_chains(self) -> Set[str]:
+        """Return unique A-side chain identifiers as 'PDBID_ChainID' from node table."""
+        from app.protein import tsv_loader
+        index = tsv_loader._get_index()
+        return {f"{pdb.upper()}_{chain}" for pdb, chain in index.keys()}
+
+    def get_filters_data(self) -> Dict[str, Any]:
+        """Return aggregated ranges for filter UI."""
+        if self._summary:
+            return {
+                "tm_min": self._summary["tm_score_range"]["min"],
+                "tm_max": self._summary["tm_score_range"]["max"],
+                "rmsd_min": self._summary["rmsd_range"]["min"],
+                "rmsd_max": self._summary["rmsd_range"]["max"],
+                "length_min": self._summary["length_range"]["min"],
+                "length_max": self._summary["length_range"]["max"],
+                "total_records": self._total_records,
+            }
+
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT MIN(CAST(TM1 AS REAL)), MAX(CAST(TM1 AS REAL)),"
+                "       MIN(CAST(RMSD AS REAL)), MAX(CAST(RMSD AS REAL))"
+                " FROM edge"
+            )
+            tm_min, tm_max, rmsd_min, rmsd_max = cur.fetchone()
+        finally:
+            conn.close()
+
+        from app.protein import tsv_loader
+        lengths = []
+        for row in tsv_loader._get_index().values():
+            try:
+                lengths.append(int(row["sequence_length"]))
+            except (ValueError, TypeError):
+                pass
+
+        return {
+            "tm_min": tm_min or 0.0,
+            "tm_max": tm_max or 1.0,
+            "rmsd_min": rmsd_min or 0.0,
+            "rmsd_max": rmsd_max or 10.0,
+            "length_min": min(lengths) if lengths else 0,
+            "length_max": max(lengths) if lengths else 0,
+            "total_records": self._total_records,
+        }
+
+    def query_edge(
+        self,
+        pdb_id_a: Optional[str] = None,
+        auth_asym_id_a: Optional[str] = None,
+        chain_ids: Optional[List[str]] = None,
+        rmsd_min: Optional[float] = None,
+        rmsd_max: Optional[float] = None,
+        tm_min: Optional[float] = None,
+        tm_max: Optional[float] = None,
+        limit: int = 1000,
+    ) -> pd.DataFrame:
+        """Query edge table with filters. Returns DataFrame with cluster_id and lengths."""
+        where_clauses: List[str] = []
+        params: List[Any] = []
+
+        if pdb_id_a and auth_asym_id_a:
+            where_clauses.append("LOWER(pdb_id_A) = LOWER(?) AND LOWER(auth_asym_id_A) = LOWER(?)")
+            params.extend([pdb_id_a, auth_asym_id_a])
+        elif chain_ids:
+            sub: List[str] = []
+            for cid in chain_ids:
+                parts = cid.split("_", 1)
+                if len(parts) == 2:
+                    sub.append("(LOWER(pdb_id_A) = LOWER(?) AND LOWER(auth_asym_id_A) = LOWER(?))")
+                    params.extend(parts)
+            if sub:
+                where_clauses.append("(" + " OR ".join(sub) + ")")
+
+        if rmsd_min is not None:
+            where_clauses.append("CAST(RMSD AS REAL) >= ?")
+            params.append(rmsd_min)
+        if rmsd_max is not None:
+            where_clauses.append("CAST(RMSD AS REAL) <= ?")
+            params.append(rmsd_max)
+        if tm_min is not None:
+            where_clauses.append("CAST(TM1 AS REAL) >= ?")
+            params.append(tm_min)
+        if tm_max is not None:
+            where_clauses.append("CAST(TM1 AS REAL) <= ?")
+            params.append(tm_max)
+
+        where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
+        sql = f"""
+            SELECT e.pdb_id_A, e.auth_asym_id_A, e.pdb_id_B, e.auth_asym_id_B,
+                   CAST(e.TM1 AS REAL) AS TM1,
+                   CAST(e.RMSD AS REAL) AS RMSD,
+                   CAST(e.structure_sim AS REAL) AS structure_sim,
+                   e."delta_Rosetta", e."delta_FoldX", e."delta_EvoEF2",
+                   e."delta_RM", e."delta_RM+",
+                   e.state_id_B, e.state_fidelity, e.avg_sim, e.pair_fidelity
+            FROM edge e
+            {where_sql}
+            LIMIT ?
+        """
+        params.append(limit)
+
+        conn = self._connect()
+        try:
+            df = pd.read_sql_query(sql, conn, params=params)
+        finally:
+            conn.close()
+
+        # Rename columns with special characters so itertuples works cleanly
+        df = df.rename(columns={"delta_RM+": "delta_RM_plus"})
+
+        df["cluster_id"] = df["TM1"].apply(
+            lambda t: _assign_cluster(t) if pd.notna(t) else "cluster_low"
+        )
+
+        from app.protein import tsv_loader
+        df["length_a"] = [
+            tsv_loader.get_sequence(r.pdb_id_A, r.auth_asym_id_A)[1]
+            for r in df.itertuples(index=False)
+        ]
+        df["length_b"] = [
+            tsv_loader.get_sequence(r.pdb_id_B, r.auth_asym_id_B)[1]
+            for r in df.itertuples(index=False)
+        ]
+        node_rows = [
+            tsv_loader.get_node_row(r.pdb_id_B, r.auth_asym_id_B)
+            for r in df.itertuples(index=False)
+        ]
+        df["experimental_method"] = [row.get("experimental_method") if row else None for row in node_rows]
+        df["pH"] = [row.get("pH") if row else None for row in node_rows]
+        df["temp_K"] = [row.get("temp_K") if row else None for row in node_rows]
+
+        return df
+
+    def get_summary_stats(
+        self,
+        chain_ids: Optional[List[str]] = None,
+        rmsd_min: Optional[float] = None,
+        rmsd_max: Optional[float] = None,
+        tm_min: Optional[float] = None,
+        tm_max: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Compute aggregate statistics via SQL, with optional filters."""
+        if not any([chain_ids, rmsd_min, rmsd_max, tm_min, tm_max]) and self._summary:
+            return self._summary
+
+        where_clauses: List[str] = []
+        params: List[Any] = []
+
+        if chain_ids:
+            sub: List[str] = []
+            for cid in chain_ids:
+                parts = cid.split("_", 1)
+                if len(parts) == 2:
+                    sub.append("(LOWER(pdb_id_A) = LOWER(?) AND LOWER(auth_asym_id_A) = LOWER(?))")
+                    params.extend(parts)
+            if sub:
+                where_clauses.append("(" + " OR ".join(sub) + ")")
+
+        if rmsd_min is not None:
+            where_clauses.append("CAST(RMSD AS REAL) >= ?")
+            params.append(rmsd_min)
+        if rmsd_max is not None:
+            where_clauses.append("CAST(RMSD AS REAL) <= ?")
+            params.append(rmsd_max)
+        if tm_min is not None:
+            where_clauses.append("CAST(TM1 AS REAL) >= ?")
+            params.append(tm_min)
+        if tm_max is not None:
+            where_clauses.append("CAST(TM1 AS REAL) <= ?")
+            params.append(tm_max)
+
+        where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
+
+        conn = self._connect()
+        try:
+            cur = conn.cursor()
+            cur.execute(
+                f"SELECT COUNT(*), AVG(CAST(RMSD AS REAL)), AVG(CAST(TM1 AS REAL))"
+                f" FROM edge {where_sql}",
+                params,
+            )
+            total, avg_rmsd, avg_tm = cur.fetchone()
+
+            cur.execute(
+                f"SELECT COUNT(DISTINCT LOWER(pdb_id_A) || '_' || LOWER(auth_asym_id_A))"
+                f" FROM edge {where_sql}",
+                params,
+            )
+            unique_chains = cur.fetchone()[0]
+
+            def _dist(col, bins, labels):
+                cases = " ".join(
+                    f"WHEN CAST({col} AS REAL) >= {lo} AND CAST({col} AS REAL) < {hi} THEN '{lbl}'"
+                    for (lo, hi), lbl in zip(zip(bins, bins[1:]), labels)
+                )
+                sql = (
+                    f"SELECT CASE {cases} ELSE '{labels[-1]}' END AS bucket, COUNT(*)"
+                    f" FROM edge {where_sql} GROUP BY bucket"
+                )
+                cur.execute(sql, params)
+                return {r[0]: r[1] for r in cur.fetchall()}
+
+            rmsd_dist = _dist(
+                "RMSD",
+                [0, 0.5, 1.0, 1.5, 2.0, 5.0, 1e9],
+                ["0-0.5", "0.5-1.0", "1.0-1.5", "1.5-2.0", "2.0-5.0", ">5.0"],
+            )
+            tm_dist = _dist(
+                "TM1",
+                [0, 0.5, 0.7, 0.85, 0.95, 1.01],
+                ["0-0.5", "0.5-0.7", "0.7-0.85", "0.85-0.95", "0.95-1.0"],
+            )
+        finally:
+            conn.close()
+
+        from app.protein import tsv_loader
+        lengths = []
+        for row in tsv_loader._get_index().values():
+            try:
+                lengths.append(int(row["sequence_length"]))
+            except (ValueError, TypeError):
+                pass
+        avg_len = sum(lengths) / len(lengths) if lengths else 0.0
+        len_dist = {}
+        for length in lengths:
+            if length <= 100:
+                bucket = "0-100"
+            elif length <= 200:
+                bucket = "100-200"
+            elif length <= 300:
+                bucket = "200-300"
+            elif length <= 500:
+                bucket = "300-500"
+            elif length <= 1000:
+                bucket = "500-1000"
+            else:
+                bucket = ">1000"
+            len_dist[bucket] = len_dist.get(bucket, 0) + 1
+
+        return {
+            "total_records": total or 0,
+            "unique_chains": unique_chains or 0,
+            "avg_rmsd": avg_rmsd or 0.0,
+            "avg_tm_score": avg_tm or 0.0,
+            "avg_sequence_length": avg_len,
+            "rmsd_distribution": rmsd_dist,
+            "tm_score_distribution": tm_dist,
+            "length_distribution": len_dist,
+        }
+
+    def get_total(self) -> int:
+        return self._total_records

backend/app/protein/database.py

@@ -0,0 +1,13 @@
+"""Read-only SQLite connection helpers."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def connect_readonly(db_path: Path) -> sqlite3.Connection:
+    """Open an immutable, query-only SQLite connection."""
+    uri = f"file:{db_path.resolve()}?mode=ro&immutable=1"
+    connection = sqlite3.connect(uri, uri=True)
+    connection.execute("PRAGMA query_only = ON")
+    return connection

backend/app/protein/fetch_chain_info_from_pdb.py

@@ -0,0 +1,303 @@
+from typing import Any, Dict, Optional, List, Tuple
+import json
+from rcsbapi.data import DataQuery
+
+def build_query(pdb_id: str) -> DataQuery:
+    return DataQuery(
+        input_type="entry",
+        input_ids=[pdb_id],
+        return_data_list=[
+            # Entry basics
+            "rcsb_id",
+            "struct.title",
+            "exptl.method",
+            "rcsb_entry_info.resolution_combined",
+            "rcsb_accession_info.initial_release_date",
+
+            # Experimental info
+            "exptl.method",
+            "rcsb_entry_info.resolution_combined",
+            "exptl_crystal_grow.pH",
+            "exptl_crystal_grow.temp",
+            "exptl_crystal_grow.pdbx_details",
+            "refine.ls_d_res_high",
+            "refine.details",
+
+            # Polymer entities (sequence-level)
+            "polymer_entities.rcsb_id",
+            "polymer_entities.rcsb_polymer_entity_container_identifiers.entity_id",
+            "polymer_entities.entity_poly.rcsb_sample_sequence_length",
+            "polymer_entities.entity_poly.pdbx_seq_one_letter_code_can",
+            "polymer_entities.rcsb_polymer_entity_container_identifiers."
+            "reference_sequence_identifiers.database_name",
+            "polymer_entities.rcsb_polymer_entity_container_identifiers."
+            "reference_sequence_identifiers.database_accession",
+
+            # Polymer entity instances (chain-level)
+            "polymer_entities.polymer_entity_instances.rcsb_id",
+            "polymer_entities.polymer_entity_instances.rcsb_polymer_entity_instance_container_identifiers.asym_id",
+            "polymer_entities.polymer_entity_instances.rcsb_polymer_entity_instance_container_identifiers.auth_asym_id",
+            "rcsb_binding_affinity",
+
+            # Instance annotations (chain-level)
+            # "polymer_entities.polymer_entity_instances."
+            # "rcsb_polymer_entity_instance_annotation.annotation_id",
+            # "polymer_entities.polymer_entity_instances."
+            # "rcsb_polymer_entity_instance_annotation.description",
+            # "polymer_entities.polymer_entity_instances."
+            # "rcsb_polymer_entity_instance_annotation.source",
+
+            # Cryo-EM specific conditions (fallback for non-crystallography structures)
+            "em_vitrification.temp",
+            "em_vitrification.cryogen_name",
+            "em_entity_assembly.details",
+
+            # Nonpolymer (ligands)
+            "nonpolymer_entities.rcsb_nonpolymer_entity_container_identifiers.nonpolymer_comp_id",
+            "nonpolymer_entities.nonpolymer_comp.chem_comp.id",
+            "nonpolymer_entities.nonpolymer_comp.chem_comp.name",
+            "nonpolymer_entities.nonpolymer_comp.rcsb_chem_comp_descriptor.InChIKey",
+            "nonpolymer_entities.nonpolymer_comp.rcsb_chem_comp_descriptor.SMILES",
+        ],
+    )
+
+
+from typing import Any, Dict, Optional, List, Tuple
+
+from typing import Any, Dict, List, Union
+
+def _safe_get(
+    obj: Union[Dict[str, Any], List[Any]],
+    path: str,
+    default=None,
+    *,
+    take_first: bool = True,
+):
+    """
+    Safe getter for nested RCSB-style data.
+
+    Supports:
+      - dict
+      - list[dict]
+      - dict[list[dict]]
+
+    Rules:
+      - If encountering a list:
+          * take_first=True  -> use the first element
+          * take_first=False -> return the whole list
+    """
+    cur = obj
+    for p in path.split("."):
+        if cur is None:
+            return default
+
+        # Case 1: list encountered
+        if isinstance(cur, list):
+            if len(cur) == 0:
+                return default
+            if take_first:
+                cur = cur[0]
+            else:
+                return cur
+
+        # Case 2: dict expected
+        if not isinstance(cur, dict):
+            return default
+
+        if p not in cur:
+            return default
+
+        cur = cur[p]
+
+    return cur
+
+import re
+from typing import Optional, Union
+
+def extract_ph_from_details(details: Union[str, list, None]) -> Optional[float]:
+    """
+    Extract pH value from pdbx_details free text.
+    Supports patterns like:
+      - "pH 7.5"
+      - "PH=6.8"
+      - "ph: 8.0"
+      - "crystallized at pH/ph/PH xxx"
+
+    Returns:
+      float pH if found, else None
+    """
+    if details is None:
+        return None
+
+    # If list (RCSB sometimes returns list[dict or str]), flatten
+    if isinstance(details, list):
+        texts = []
+        for d in details:
+            if isinstance(d, dict):
+                texts.extend(str(v) for v in d.values())
+            else:
+                texts.append(str(d))
+        text = " ".join(texts)
+    else:
+        text = str(details)
+
+    # Normalize
+    text = text.replace(",", " ")
+
+    # Regex: pH / PH / ph followed by number
+    # Examples matched:
+    #   pH 7.0
+    #   PH=6.8
+    #   ph:8.5
+    pattern = re.compile(
+        r"\b(?:pH|PH|ph)\s*[:=]?\s*([0-9]+(?:\.[0-9]+)?)"
+    )
+
+    match = pattern.search(text)
+    if match:
+        try:
+            return float(match.group(1))
+        except ValueError:
+            return None
+
+    return None
+
+
+
+def fetch_chain_record(
+    pdb_id: str,
+    auth_asym_id: str,
+    query_builder=build_query,
+) -> Dict[str, Any]:
+    """
+    Fetch entry-level data and return ONLY the chain instance matching auth_asym_id,
+    plus its parent polymer_entity (sequence-level) and entry metadata.
+
+    Raises:
+      - ValueError if no chain or multiple chains match (ambiguous).
+    """
+    dq = query_builder(pdb_id)
+    data = dq.exec()["data"]["entries"][0]
+
+    if not data:
+        raise ValueError(f"No data returned for entry {pdb_id}")
+
+    # ---- entry-level pack
+    ph_struct = _safe_get(data, "exptl_crystal_grow.pH")
+    pdbx_details = _safe_get(data, "exptl_crystal_grow.pdbx_details")
+    xray_temp = _safe_get(data, "exptl_crystal_grow.temp")
+
+    # Cryo-EM fallbacks (used when crystal grow fields are absent)
+    em_temp = _safe_get(data, "em_vitrification.temp")
+    em_cryogen = _safe_get(data, "em_vitrification.cryogen_name")
+    em_assembly_details = _safe_get(data, "em_entity_assembly.details")
+
+    em_details_parts = []
+    if em_assembly_details:
+        em_details_parts.append(em_assembly_details)
+    if em_cryogen:
+        em_details_parts.append(f"Vitrified in {em_cryogen}")
+    em_details = "; ".join(em_details_parts) if em_details_parts else None
+
+    entry_pack = {
+        "rcsb_id": data.get("rcsb_id"),
+        "title": _safe_get(data, "struct.title"),
+        "initial_release_date": _safe_get(data, "rcsb_accession_info.initial_release_date"),
+        "exptl_method": _safe_get(data, "exptl.method"),
+        "resolution_combined": _safe_get(data, "rcsb_entry_info.resolution_combined"),
+        "crystal_grow": {
+            "pH": (
+                ph_struct if ph_struct is not None
+                else extract_ph_from_details(pdbx_details)
+            ),
+            "pH_structured": ph_struct,
+            "pH_from_details": extract_ph_from_details(pdbx_details),
+            "temp": xray_temp if xray_temp is not None else em_temp,
+            "pdbx_details": pdbx_details if pdbx_details is not None else em_details,
+        },
+        "refine": {
+            "ls_d_res_high": _safe_get(data, "refine.ls_d_res_high"),
+            "details": _safe_get(data, "refine.details"),
+        },
+    }
+
+    polymer_entities = data.get("polymer_entities") or []
+    nonpolymer_entities = data.get("nonpolymer_entities") or []
+
+    matches: List[Tuple[Dict[str, Any], Dict[str, Any]]] = []
+    for ent in polymer_entities:
+        instances = ent.get("polymer_entity_instances") or []
+        for inst in instances:
+            ids = inst.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+            if ids.get("auth_asym_id") == auth_asym_id:
+                matches.append((ent, inst))
+
+    if len(matches) == 0:
+        # Helpful debug info: list available auth_asym_id
+        available = []
+        for ent in polymer_entities:
+            instances = ent.get("polymer_entity_instances") or []
+            for inst in instances:
+                ids = inst.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+                if ids.get("auth_asym_id") is not None:
+                    available.append(ids.get("auth_asym_id"))
+        raise ValueError(
+            f"No chain instance matches auth_asym_id='{auth_asym_id}' in entry {pdb_id}. "
+            f"Available auth_asym_id: {sorted(set(available))}"
+        )
+
+    if len(matches) > 1:
+        amb = []
+        for e, i in matches:
+            ids = i.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+            amb.append({
+                "entity_rcsb_id": e.get("rcsb_id"),
+                "instance_rcsb_id": i.get("rcsb_id"),
+                "asym_id": ids.get("asym_id"),
+                "auth_asym_id": ids.get("auth_asym_id"),
+            })
+        raise ValueError(
+            f"Ambiguous: {len(matches)} instances match auth_asym_id='{auth_asym_id}' in entry {pdb_id}. "
+            f"Candidates: {amb}"
+        )
+
+    ent, inst = matches[0]
+
+    polymer_entity_pack = {
+        "rcsb_id": ent.get("rcsb_id"),
+        "entity_id": _safe_get(ent, "rcsb_polymer_entity_container_identifiers.entity_id"),
+        "sequence_length": _safe_get(ent, "entity_poly.rcsb_sample_sequence_length"),
+        "seq_can": _safe_get(ent, "entity_poly.pdbx_seq_one_letter_code_can"),
+        "reference_sequences": _safe_get(
+            ent,
+            "rcsb_polymer_entity_container_identifiers.reference_sequence_identifiers",
+            default=[],
+        ),
+    }
+
+    ids = inst.get("rcsb_polymer_entity_instance_container_identifiers") or {}
+    polymer_instance_pack = {
+        "rcsb_id": inst.get("rcsb_id"),
+        "asym_id": ids.get("asym_id"),
+        "auth_asym_id": ids.get("auth_asym_id"),
+        "binding_affinity": inst.get("rcsb_binding_affinity"),
+        "instance_annotations": inst.get("rcsb_polymer_entity_instance_annotation"),
+    }
+
+    return {
+        "entry": entry_pack,
+        "polymer_entity": polymer_entity_pack,
+        "polymer_entity_instance": polymer_instance_pack,
+        "nonpolymer_entities": nonpolymer_entities,
+        "meta": {
+            "pdb_id": pdb_id,
+            "auth_asym_id": auth_asym_id,
+            "matched_instance_rcsb_id": inst.get("rcsb_id"),
+        },
+    }
+
+
+if __name__=="__main__":
+    rec = fetch_chain_record("2D4F", "A")
+    with open("data.json", "w") as file:
+        json.dump(rec, file, indent=2)

backend/app/protein/models.py

@@ -0,0 +1,140 @@
+"""
+Data models for the protein visualization API.
+"""
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class CrystalGrow(BaseModel):
+    """Crystal growth conditions."""
+    pH: Optional[float] = None
+    pH_structured: Optional[float] = None
+    pH_from_details: Optional[float] = None
+    temp: Optional[float] = None
+    pdbx_details: Optional[str] = None
+
+
+class EntryInfo(BaseModel):
+    """Entry-level information."""
+    rcsb_id: Optional[str] = None
+    title: Optional[str] = None
+    initial_release_date: Optional[str] = None
+    exptl_method: Optional[str] = None
+    resolution_combined: Optional[List[float]] = None
+    crystal_grow: Optional[CrystalGrow] = None
+
+
+class PolymerEntity(BaseModel):
+    """Polymer entity (sequence-level) information."""
+    rcsb_id: Optional[str] = None
+    entity_id: Optional[str] = None
+    sequence_length: Optional[int] = None
+    seq_can: Optional[str] = None
+    reference_sequences: Optional[List[Dict[str, str]]] = None
+
+
+class PolymerEntityInstance(BaseModel):
+    """Polymer entity instance (chain-level) information."""
+    rcsb_id: Optional[str] = None
+    asym_id: Optional[str] = None
+    auth_asym_id: Optional[str] = None
+    binding_affinity: Optional[Any] = None
+
+
+class NonpolymerEntity(BaseModel):
+    """Nonpolymer entity (ligand/binder) information."""
+    rcsb_id: Optional[str] = None
+    name: Optional[str] = None
+    formula_weight: Optional[float] = None
+    smiles: Optional[str] = None
+    inchi: Optional[str] = None
+
+
+class ChainMetadata(BaseModel):
+    """Complete chain metadata from RCSB."""
+    pdb_id: str
+    chain_id: str
+    entry: EntryInfo
+    polymer_entity: Optional[PolymerEntity] = None
+    polymer_entity_instance: Optional[PolymerEntityInstance] = None
+    nonpolymer_entities: Optional[List[NonpolymerEntity]] = None
+    binding_status: Optional[str] = None
+    cath_id: Optional[str] = None
+    cath_superfamily: Optional[str] = None
+    state_id: Optional[str] = None
+
+
+class FilterParams(BaseModel):
+    """Request model for filtering protein data."""
+    chain_ids: Optional[List[str]] = Field(default=None, description="List of chain IDs to filter")
+    pdb_id: Optional[str] = Field(default=None, description="PDB ID for single chain search")
+    auth_asym_id: Optional[str] = Field(default=None, description="Chain ID for single chain search")
+    rmsd_min: Optional[float] = Field(default=None, ge=0, description="Minimum RMSD value")
+    rmsd_max: Optional[float] = Field(default=None, ge=0, description="Maximum RMSD value")
+    tm_score_min: Optional[float] = Field(default=None, ge=0, le=1, description="Minimum TM-score")
+    tm_score_max: Optional[float] = Field(default=None, ge=0, le=1, description="Maximum TM-score")
+    length_min: Optional[int] = Field(default=None, ge=0, description="Minimum sequence length")
+    length_max: Optional[int] = Field(default=None, ge=0, description="Maximum sequence length")
+    include_duplicates: Optional[bool] = Field(default=None, description="Include duplicate structures")
+    cluster_id: Optional[str] = Field(default=None, description="Structural similarity cluster ID")
+    limit: Optional[int] = Field(default=1000, ge=1, le=10000, description="Maximum results to return")
+
+
+class FilterOptions(BaseModel):
+    """Available filter options and ranges."""
+    chain_ids: List[str] = Field(description="Available chain IDs")
+    rmsd_range: Dict[str, float] = Field(description="Min and max RMSD values")
+    tm_score_range: Dict[str, float] = Field(description="Min and max TM-score values")
+    length_range: Dict[str, int] = Field(description="Min and max sequence lengths")
+    clusters: List[str] = Field(description="Available similarity clusters")
+    total_records: int = Field(description="Total number of records")
+
+
+class DataRecord(BaseModel):
+    """Single protein comparison record."""
+    pdb_id_a: str
+    auth_asym_id_a: str
+    pdb_id_b: str
+    auth_asym_id_b: str
+    tm_score: float
+    rmsd: float
+    structure_sim: Optional[float] = None
+    sequence_identity: Optional[float] = None
+    length_a: Optional[int] = None
+    length_b: Optional[int] = None
+    aligned_length: Optional[int] = None
+    status: Optional[str] = None
+    cluster_id: Optional[str] = None
+    exptl_method: Optional[str] = None
+    temp: Optional[float] = None
+    pH: Optional[float] = None
+    # Energy score deltas fetched directly from the edge table
+    delta_rosetta: Optional[float] = None
+    delta_foldx: Optional[float] = None
+    delta_evoef2: Optional[float] = None
+    delta_rm: Optional[float] = None
+    delta_rm_plus: Optional[float] = None
+    # Alternative state similarity fields from edge table
+    state_id_b: Optional[str] = None
+    state_fidelity: Optional[str] = None
+    avg_sim: Optional[str] = None
+    pair_fidelity: Optional[str] = None
+
+
+class DataResponse(BaseModel):
+    """Response model for filtered data."""
+    data: List[DataRecord]
+    total: int
+    filtered: int
+
+
+class SummaryStats(BaseModel):
+    """Aggregate statistics for the dataset."""
+    total_records: int
+    unique_chains: int
+    avg_rmsd: float
+    avg_tm_score: float
+    avg_sequence_length: float
+    rmsd_distribution: Dict[str, int]
+    tm_score_distribution: Dict[str, int]
+    length_distribution: Dict[str, int]

backend/app/protein/tsv_loader.py

@@ -0,0 +1,181 @@
+"""
+Node table lookup for chain annotations.
+
+Loads the node table from MuSProt.db once on first use and indexes rows
+by (pdb_id_lower, auth_asym_id_upper).  When multiple rows share the same
+key the first occurrence is kept.
+"""
+import ast
+import sqlite3
+import logging
+from typing import Dict, List, Optional, Tuple, Any
+
+from app.protein.config import get_database_path
+from app.protein.database import connect_readonly
+
+logger = logging.getLogger(__name__)
+
+_Row = Dict[str, str]
+
+# (pdb_id_lower, auth_asym_id_upper) -> relevant fields
+_index: Optional[Dict[Tuple[str, str], _Row]] = None
+
+
+def _load() -> Dict[Tuple[str, str], _Row]:
+    index: Dict[Tuple[str, str], _Row] = {}
+    db_path = get_database_path()
+    conn = connect_readonly(db_path)
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            'SELECT pdb_id, auth_asym_id, base_label, sequence, sequence_length,'
+            '       CATH_ID, cath_superfamily, Rosetta, FoldX, EvoEF2, RM, "RM+", ranked_functions,'
+            '       state_id, experimental_method, pH, temp_K'
+            ' FROM node'
+        )
+        for row in cur:
+            pdb_id = row["pdb_id"] or ""
+            auth_asym_id = row["auth_asym_id"] or ""
+            key = (pdb_id.lower(), auth_asym_id.upper())
+            if key not in index:
+                index[key] = {
+                    "base_label": row["base_label"] or "",
+                    "sequence": row["sequence"] or "",
+                    "sequence_length": row["sequence_length"] or "",
+                    "CATH_ID": row["CATH_ID"] or "",
+                    "cath_superfamily": row["cath_superfamily"] or "",
+                    "Rosetta": row["Rosetta"] or "",
+                    "FoldX": row["FoldX"] or "",
+                    "EvoEF2": row["EvoEF2"] or "",
+                    "RM": row["RM"] or "",
+                    "RM+": row["RM+"] or "",
+                    "ranked_functions": row["ranked_functions"] or "",
+                    "state_id": row["state_id"] or "",
+                    "experimental_method": row["experimental_method"] or "",
+                    "pH": row["pH"] or "",
+                    "temp_K": row["temp_K"] or "",
+                }
+    finally:
+        conn.close()
+
+    logger.info(f"Node index loaded: {len(index):,} entries from {db_path}")
+    return index
+
+
+def _get_index() -> Dict[Tuple[str, str], _Row]:
+    global _index
+    if _index is None:
+        _index = _load()
+    return _index
+
+
+def reset_index() -> None:
+    """Force reload of node index."""
+    global _index
+    _index = None
+
+
+def _parse_functions(raw: str) -> List[str]:
+    raw = raw.strip()
+    if not raw:
+        return []
+    try:
+        parsed = ast.literal_eval(raw)
+        if isinstance(parsed, list):
+            return [str(f).strip() for f in parsed if str(f).strip()]
+    except (ValueError, SyntaxError):
+        pass
+    return [f.strip() for f in raw.split(";") if f.strip()]
+
+
+def _parse_float(val: str) -> Optional[float]:
+    val = val.strip()
+    if not val:
+        return None
+    try:
+        return float(val)
+    except ValueError:
+        return None
+
+
+def get_energy_scores(pdb_id: str, auth_asym_id: str) -> Optional[Dict[str, Any]]:
+    """Return energy scores (Rosetta, FoldX, EvoEF2, RM, RM+) or None if not found."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return None
+    return {
+        "Rosetta": _parse_float(row.get("Rosetta", "")),
+        "FoldX": _parse_float(row.get("FoldX", "")),
+        "EvoEF2": _parse_float(row.get("EvoEF2", "")),
+        "RM": _parse_float(row.get("RM", "")),
+        "RM+": _parse_float(row.get("RM+", "")),
+    }
+
+
+def get_node_row(pdb_id: str, auth_asym_id: str) -> Optional[_Row]:
+    """Return the cached node row for a chain."""
+    return _get_index().get((pdb_id.lower(), auth_asym_id.upper()))
+
+
+def get_binding_status(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return binding status (base_label: apo/holo) or None if not found."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return None
+    return row.get("base_label") or None
+
+
+def get_cath_id(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return CATH_ID or 'uncategorized' if not found."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return "uncategorized"
+    val = row.get("CATH_ID", "").strip()
+    return val if val else "uncategorized"
+
+
+def get_cath_superfamily(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return CATH superfamily code (e.g. '3.40.190.10') or None if not found."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return None
+    val = row.get("cath_superfamily", "").strip()
+    return val if val else None
+
+
+def get_sequence(pdb_id: str, auth_asym_id: str) -> Tuple[Optional[str], Optional[int]]:
+    """Return (seq_can, sequence_length) from node table, or (None, None) if not found."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return None, None
+    seq = row["sequence"] or None
+    try:
+        length = int(row["sequence_length"]) if row["sequence_length"].strip() else None
+    except ValueError:
+        length = None
+    return seq, length
+
+
+def get_functions(pdb_id: str, auth_asym_id: str) -> Optional[List[str]]:
+    """Return ranked function list for a chain, or None if not in node table."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return None
+    return _parse_functions(row["ranked_functions"])
+
+
+def get_state_id(pdb_id: str, auth_asym_id: str) -> Optional[str]:
+    """Return state_id for a chain, or None if not found."""
+    key = (pdb_id.lower(), auth_asym_id.upper())
+    row = _get_index().get(key)
+    if row is None:
+        return None
+    val = row.get("state_id", "").strip()
+    return val if val else None

backend/assets/MuSProt_documentation.md

@@ -0,0 +1,138 @@
+# MuSProt Dataset Documentation
+
+**MuSProt** (Multistate Protein Database) is a large-scale structural database capturing conformational diversity across protein chains derived from the Protein Data Bank (PDB). It encodes pairwise structural relationships between chain instances sharing the same UniProt annotation, enabling systematic analysis of protein flexibility, binding effects, and functional variation.
+
+---
+
+## Download
+
+The full dataset is distributed as a single SQLite database file (`MuSProt.db`, ~6.3 GB). Download it from the dataset page using the **Download DB** button.
+
+For detailed protein structures and atom coordinates, users are expected to download [Protein Data Bank (PDB)](https://rcsb.org) and fetch from `mmCIF` or `.pdb` files based on the PDB entry and chain ID.
+
+---
+
+## Database Schema
+
+The database contains two tables: **`node`** and **`edge`**.
+
+---
+
+### Table: `node`
+
+Each row represents a single protein chain instance (one PDB entry + chain).
+
+| Column | Type | Description |
+|---|---|---|
+| `uniprot_id` | TEXT | UniProt accession number |
+| `pdb_id` | TEXT | 4-character PDB entry ID (lowercase) |
+| `auth_asym_id` | TEXT | Author chain identifier (e.g. `A`) |
+| `base_label` | TEXT | Canonical label combining UniProt ID and chain state |
+| `sequence` | TEXT | SEQRES amino acid sequence |
+| `sequence_length` | INT | Number of residues in the chain |
+| `original_metals` | TEXT | Metal ions present in the structure |
+| `original_ligands` | TEXT | Small-molecule ligands present in the structure |
+| `sequence_id` | TEXT | Internal sequence cluster identifier |
+| `CATH_ID` | TEXT | CATH domain assignment |
+| `cath_class` | TEXT | CATH class (e.g. `1` = Mainly Alpha) |
+| `cath_arch` | TEXT | CATH architecture |
+| `cath_topo` | TEXT | CATH topology |
+| `cath_homology` | TEXT | CATH homology superfamily |
+| `cath_superfamily` | TEXT | Full CATH superfamily code (e.g. `1.10.10.10`) |
+| `domain_length` | INT | Length of the matched CATH domain |
+| `Rosetta` | FLOAT | Rosetta total energy score |
+| `FoldX` | FLOAT | FoldX total energy score |
+| `EvoEF2` | FLOAT | EvoEF2 total energy score |
+| `RM` | FLOAT | RosettaMembrane energy score |
+| `RM+` | FLOAT | RosettaMembrane+ energy score |
+| `ranked_functions` | TEXT | JSON-encoded list of ranked GO/functional annotations |
+
+---
+
+### Table: `edge`
+
+Each row represents a pairwise structural comparison between two chain instances (A and B) that share the same UniProt identity.
+
+| Column | Type | Description |
+|---|---|---|
+| `pdb_id_A` | TEXT | PDB ID of chain A |
+| `auth_asym_id_A` | TEXT | Chain identifier of chain A |
+| `pdb_id_B` | TEXT | PDB ID of chain B |
+| `auth_asym_id_B` | TEXT | Chain identifier of chain B |
+| `TM1` | FLOAT | TM-score of the alignment (chain A as reference) |
+| `RMSD` | FLOAT | Root-mean-square deviation of Cα atoms (Å) |
+| `structure_sim` | FLOAT | Composite structural similarity score |
+| `delta_Rosetta` | FLOAT | Rosetta energy difference (B − A) |
+| `delta_FoldX` | FLOAT | FoldX energy difference (B − A) |
+| `delta_EvoEF2` | FLOAT | EvoEF2 energy difference (B − A) |
+| `delta_RM` | FLOAT | RosettaMembrane energy difference (B − A) |
+| `delta_RM+` | FLOAT | RosettaMembrane+ energy difference (B − A) |
+
+---
+
+## Usage Examples
+
+### Python (sqlite3)
+
+```python
+import sqlite3
+import pandas as pd
+
+conn = sqlite3.connect("MuSProt.db")
+
+# Load all chains for a UniProt entry
+df_nodes = pd.read_sql(
+    "SELECT * FROM node WHERE uniprot_id = 'P00533'",
+    conn
+)
+
+# Find all structural neighbours of a given chain
+df_edges = pd.read_sql(
+    "SELECT * FROM edge WHERE pdb_id_A = '1ivo' AND auth_asym_id_A = 'A'",
+    conn
+)
+
+conn.close()
+```
+
+### Filter by structural similarity
+
+```python
+# Retrieve pairs with high TM-score and low RMSD
+df = pd.read_sql("""
+    SELECT *
+    FROM edge
+    WHERE CAST(TM1 AS REAL) > 0.8
+      AND CAST(RMSD AS REAL) < 2.0
+    LIMIT 1000
+""", conn)
+```
+
+### Join nodes and edges
+
+```python
+# Get full info for both chains in each pair
+df = pd.read_sql("""
+    SELECT
+        e.pdb_id_A, e.auth_asym_id_A,
+        e.pdb_id_B, e.auth_asym_id_B,
+        e.TM1, e.RMSD,
+        nA.sequence_length AS len_A,
+        nB.sequence_length AS len_B,
+        nA.cath_superfamily
+    FROM edge e
+    JOIN node nA ON e.pdb_id_A = nA.pdb_id AND e.auth_asym_id_A = nA.auth_asym_id
+    JOIN node nB ON e.pdb_id_B = nB.pdb_id AND e.auth_asym_id_B = nB.auth_asym_id
+    WHERE nA.uniprot_id = 'P00533'
+    LIMIT 500
+""", conn)
+```
+
+---
+
+## Notes
+
+- All numeric fields (energies, TM-score, RMSD, lengths) are stored as `TEXT`; cast them with `CAST(col AS REAL)` or `CAST(col AS INTEGER)` as needed.
+- `ranked_functions` in the `node` table is a JSON string. Parse it with `json.loads()`.
+- The `edge` table is directional: (A→B) and (B→A) are separate rows and may differ slightly in TM-score.
+- Energy delta values represent B − A; a negative delta means chain B is lower energy than chain A.

backend/assets/musprot_summary.json

@@ -0,0 +1,42 @@
+{
+  "total_records": 27586348,
+  "unique_chains": 325320,
+  "avg_rmsd": 0.6675476253688963,
+  "avg_tm_score": 0.9602746188440746,
+  "avg_sequence_length": 235.7717984028132,
+  "rmsd_distribution": {
+    "0-0.5": 11970560,
+    "0.5-1.0": 10422936,
+    "1.0-1.5": 3551996,
+    "1.5-2.0": 905068,
+    "2.0-5.0": 730332,
+    ">5.0": 5456
+  },
+  "tm_score_distribution": {
+    "0-0.5": 144940,
+    "0.5-0.7": 319272,
+    "0.7-0.85": 917410,
+    "0.85-0.95": 4632994,
+    "0.95-1.0": 21571732
+  },
+  "length_distribution": {
+    "300-500": 57390,
+    "500-1000": 19801,
+    "100-200": 101177,
+    "0-100": 76718,
+    "200-300": 65315,
+    ">1000": 4921
+  },
+  "tm_score_range": {
+    "min": 0.0,
+    "max": 1.0
+  },
+  "rmsd_range": {
+    "min": 0.0,
+    "max": 9.83
+  },
+  "length_range": {
+    "min": 1,
+    "max": 4542
+  }
+}

backend/requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.109.0
+uvicorn[standard]==0.27.0
+pandas==2.2.0
+pydantic==2.5.3
+rcsb-api>=1.7.3
+huggingface_hub>=0.32.0

backend/scripts/generate_summary.py

@@ -0,0 +1,36 @@
+"""Generate the small summary sidecar used by the deployed MuSProt app."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from app.protein.data_loader import DataManager
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("database", type=Path)
+    parser.add_argument("-o", "--output", type=Path, default=Path("musprot_summary.json"))
+    args = parser.parse_args()
+
+    manager = DataManager(args.database)
+    manager.load_data()
+    summary = manager.get_summary_stats()
+    filters = manager.get_filters_data()
+    summary.update(
+        {
+            "tm_score_range": {"min": filters["tm_min"], "max": filters["tm_max"]},
+            "rmsd_range": {"min": filters["rmsd_min"], "max": filters["rmsd_max"]},
+            "length_range": {"min": filters["length_min"], "max": filters["length_max"]},
+        }
+    )
+    args.output.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+    print(f"Wrote {args.output}")
+
+
+if __name__ == "__main__":
+    main()

backend/space_app.py

@@ -0,0 +1,111 @@
+"""MuSProt-only FastAPI application for Hugging Face Docker Spaces."""
+from __future__ import annotations
+
+import logging
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, PlainTextResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from app.protein.api.routes.protein import router as protein_router
+from app.protein.api.routes.protein import set_data_manager
+from app.protein.config import get_database_path, get_docs_path, get_plots_dir
+from app.protein.data_loader import DataManager
+from app.protein import tsv_loader
+
+
+logging.basicConfig(
+    level=os.getenv("LOG_LEVEL", "INFO"),
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+BACKEND_DIR = Path(__file__).resolve().parent
+FRONTEND_DIR = Path(os.getenv("MUSPROT_FRONTEND_DIR", BACKEND_DIR / "frontend"))
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    """Initialize the shared read-only database manager."""
+    db_path = get_database_path()
+    logger.info("Using read-only MuSProt database: %s", db_path)
+    manager = DataManager(db_path)
+    manager.load_data()
+    set_data_manager(manager)
+
+    if os.getenv("MUSPROT_PRELOAD_NODE_INDEX", "1") == "1":
+        tsv_loader._get_index()
+
+    yield
+    set_data_manager(None)
+
+
+app = FastAPI(
+    title="MuSProt",
+    description="Multistate protein structure dataset explorer",
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+    openapi_url="/api/openapi.json",
+)
+app.include_router(protein_router, prefix="/api/protein", tags=["MuSProt"])
+
+
+@app.get("/health")
+async def health():
+    return {"status": "healthy", "database": str(get_database_path())}
+
+
+@app.get("/api/protein/docs", response_class=PlainTextResponse)
+async def protein_docs():
+    path = get_docs_path()
+    if not path:
+        raise HTTPException(status_code=404, detail="MuSProt documentation is not available")
+    return path.read_text(encoding="utf-8")
+
+
+@app.get("/api/protein/download/db")
+async def download_database():
+    repo_id = os.getenv("MUSPROT_DATASET_REPO")
+    if repo_id:
+        revision = os.getenv("MUSPROT_DATASET_REVISION", "main")
+        filename = os.getenv("MUSPROT_DB_FILENAME", "MuSProt.db")
+        return RedirectResponse(
+            f"https://huggingface.co/datasets/{repo_id}/resolve/{revision}/{filename}?download=true"
+        )
+
+    return FileResponse(
+        get_database_path(),
+        media_type="application/x-sqlite3",
+        filename="MuSProt.db",
+    )
+
+
+plots_dir = get_plots_dir()
+if plots_dir:
+    app.mount("/api/protein/plots", StaticFiles(directory=plots_dir), name="protein-plots")
+
+assets_dir = FRONTEND_DIR / "assets"
+if assets_dir.is_dir():
+    app.mount("/assets", StaticFiles(directory=assets_dir), name="frontend-assets")
+
+
+@app.get("/{path:path}", include_in_schema=False)
+async def frontend(path: str):
+    """Serve the React SPA and its pre-rendered routes."""
+    requested = FRONTEND_DIR / path
+    if path and requested.is_file():
+        return FileResponse(requested)
+
+    prerendered = requested / "index.html"
+    if path and prerendered.is_file():
+        return FileResponse(prerendered)
+
+    index = FRONTEND_DIR / "index.html"
+    if not index.is_file():
+        raise HTTPException(status_code=503, detail="Frontend build is not available")
+    return FileResponse(index)

frontend/.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+build
+coverage
+package-lock.json

frontend/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "es5",
+  "printWidth": 100
+}

frontend/eslint.config.js

@@ -0,0 +1,61 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+
+export default [
+  {
+    ignores: [
+      'build/**',
+      'node_modules/**',
+      'coverage/**',
+      'tests/**',
+      'src/components/benchmarks/**',
+      'src/components/datasets/materials/**',
+      'src/components/evaluation/**',
+      'src/components/home/**',
+      'src/components/ui/**',
+      'src/data/**',
+      'src/pages/benchmarks/**',
+    ],
+  },
+  js.configs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      'no-undef': 'off',
+    },
+  },
+];

frontend/index.html

@@ -0,0 +1,16 @@
+
+  <!DOCTYPE html>
+  <html lang="en">
+    <head>
+      <meta charset="UTF-8" />
+      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+      <title>MuSProt: Multistate Protein Structure Database</title>
+      <meta name="description" content="Explore multistate protein structures, pairwise comparisons, energy scores, and functional annotations." />
+    </head>
+
+    <body>
+      <div id="root"></div>
+      <script type="module" src="/src/main.tsx"></script>
+    </body>
+  </html>
+  

frontend/package.json

@@ -0,0 +1,42 @@
+{
+      "name": "musprot",
+      "version": "1.0.0",
+      "private": true,
+      "type": "module",
+      "license": "MIT",
+      "homepage": "https://huggingface.co/spaces/wenruifan/MuSProt",
+      "dependencies": {
+            "axios": "^1.13.4",
+            "lucide-react": "^0.487.0",
+            "react": "^18.3.1",
+            "react-dom": "^18.3.1",
+            "react-helmet-async": "^3.0.0",
+            "react-markdown": "^10.1.0",
+            "react-router-dom": "^7.13.0",
+            "remark-gfm": "^4.0.1"
+      },
+      "devDependencies": {
+            "@types/node": "^20.10.0",
+            "@types/react": "^19.2.9",
+            "@types/react-dom": "^19.2.3",
+            "@typescript-eslint/eslint-plugin": "^8.56.0",
+            "@typescript-eslint/parser": "^8.56.0",
+            "@vitejs/plugin-react-swc": "^3.10.2",
+            "eslint": "^9.39.2",
+            "eslint-plugin-react-hooks": "^7.0.1",
+            "eslint-plugin-react-refresh": "^0.5.0",
+            "globals": "^17.3.0",
+            "prettier": "^3.8.1",
+            "typescript": "^5.9.3",
+            "vite": "^6.4.3"
+      },
+      "scripts": {
+            "dev": "vite",
+            "build": "vite build && node scripts/prerender.mjs",
+            "lint": "eslint .",
+            "lint:fix": "eslint . --fix",
+            "format": "prettier --write .",
+            "format:check": "prettier --check .",
+            "typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
+      }
+}

frontend/public/robots.txt

@@ -0,0 +1,6 @@
+User-agent: *
+Allow: /
+
+Disallow: /api/
+
+Sitemap: https://wenruifan-musprot.hf.space/sitemap.xml

frontend/public/sitemap.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://wenruifan-musprot.hf.space/</loc>
+    <changefreq>monthly</changefreq>
+    <priority>1.0</priority>
+  </url>
+  <url>
+    <loc>https://wenruifan-musprot.hf.space/docs</loc>
+    <changefreq>monthly</changefreq>
+    <priority>0.8</priority>
+  </url>
+</urlset>

frontend/scripts/prerender.mjs

@@ -0,0 +1,42 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const BUILD_DIR = 'build';
+const BASE_URL = 'https://wenruifan-musprot.hf.space';
+const template = readFileSync(join(BUILD_DIR, 'index.html'), 'utf-8');
+
+const routes = [
+  {
+    path: '',
+    title: 'MuSProt: Multistate Protein Structure Database',
+    description:
+      'Explore multistate protein structures, pairwise comparisons, energy scores, and functional annotations.',
+  },
+  {
+    path: 'docs',
+    title: 'MuSProt Documentation',
+    description: 'MuSProt dataset format, SQLite schema, and usage examples.',
+  },
+];
+
+for (const route of routes) {
+  const canonical = `${BASE_URL}/${route.path}`;
+  const head = [
+    `<title>${route.title}</title>`,
+    `<meta name="description" content="${route.description}" />`,
+    `<link rel="canonical" href="${canonical}" />`,
+    `<meta property="og:title" content="${route.title}" />`,
+    `<meta property="og:description" content="${route.description}" />`,
+    `<meta property="og:url" content="${canonical}" />`,
+    `<meta property="og:site_name" content="MuSProt" />`,
+  ].join('\n    ');
+
+  const html = template
+    .replace(/<title>[^<]*<\/title>/, '')
+    .replace(/<meta\s+name="description"[^>]*\/?>/, '')
+    .replace('</head>', `    ${head}\n  </head>`);
+
+  const outputDir = route.path ? join(BUILD_DIR, route.path) : BUILD_DIR;
+  mkdirSync(outputDir, { recursive: true });
+  writeFileSync(join(outputDir, 'index.html'), html, 'utf-8');
+}

frontend/src/App.tsx

@@ -0,0 +1,23 @@
+import { Navigate, Route, Routes } from 'react-router-dom';
+import { Header } from './components/layout/Header';
+import { Footer } from './components/layout/Footer';
+import { ProteinDashboard } from './components/datasets/protein/ProteinDashboard';
+import { ProteinDocsPage } from './pages/datasets/ProteinDocsPage';
+
+export default function App() {
+  return (
+    <div className="min-h-screen bg-white">
+      <Header />
+      <main>
+        <Routes>
+          <Route path="/" element={<ProteinDashboard />} />
+          <Route path="/docs" element={<ProteinDocsPage />} />
+          <Route path="/datasets/musprot" element={<Navigate to="/" replace />} />
+          <Route path="/datasets/musprot/docs" element={<Navigate to="/docs" replace />} />
+          <Route path="*" element={<Navigate to="/" replace />} />
+        </Routes>
+      </main>
+      <Footer />
+    </div>
+  );
+}

frontend/src/api/protein.ts

@@ -0,0 +1,119 @@
+/**
+ * API client for protein visualization backend
+ * Connects to FastAPI backend (default: http://localhost:8000)
+ */
+import axios from 'axios';
+import type { FilterParams, FilterOptions, DataResponse, SummaryStats, ChainMetadata } from '../types/protein';
+
+// API base URL - uses Vite proxy in development
+const API_BASE_URL = import.meta.env.VITE_PROTEIN_API_BASE || '/api';
+
+const api = axios.create({
+  baseURL: API_BASE_URL,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+// Enhanced error handling with diagnostics
+api.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    const url = error.config?.url || 'unknown';
+    const method = error.config?.method?.toUpperCase() || 'REQUEST';
+    const status = error.response?.status || 'NO_RESPONSE';
+    const statusText = error.response?.statusText || 'Connection failed';
+    
+    // Try to get response body
+    let responseBody = '';
+    if (error.response?.data) {
+      if (typeof error.response.data === 'string') {
+        responseBody = error.response.data;
+      } else {
+        responseBody = JSON.stringify(error.response.data);
+      }
+    }
+    
+    const diagnosticMessage = `API Error: ${method} ${url} → ${status} ${statusText}${responseBody ? '\nResponse: ' + responseBody : ''}`;
+    console.error(diagnosticMessage);
+    
+    // Re-throw with enhanced message
+    error.message = diagnosticMessage;
+    return Promise.reject(error);
+  }
+);
+
+export const proteinApi = {
+  /**
+   * Get available filter options
+   */
+  async getFilters(): Promise<FilterOptions> {
+    const response = await api.get<FilterOptions>('/protein/filters');
+    return response.data;
+  },
+
+  /**
+   * Get filtered protein data
+   */
+  async getData(filters: FilterParams): Promise<DataResponse> {
+    const response = await api.post<DataResponse>('/protein/data', filters);
+    return response.data;
+  },
+
+  /**
+   * Get summary statistics
+   */
+  async getSummary(params?: Partial<FilterParams>): Promise<SummaryStats> {
+    const response = await api.get<SummaryStats>('/protein/summary', { params });
+    return response.data;
+  },
+
+  /**
+   * Resolve chain metadata from RCSB web API
+   * @param signal - AbortSignal for request cancellation
+   */
+  async resolveChain(
+    pdb_id: string, 
+    auth_asym_id: string, 
+    options?: { use_cache?: boolean; signal?: AbortSignal }
+  ): Promise<ChainMetadata> {
+    const { use_cache = true, signal } = options || {};
+    try {
+      const response = await api.get<ChainMetadata>('/protein/chain/resolve', {
+        params: { pdb_id, auth_asym_id, use_cache },
+        signal
+      });
+      return response.data;
+    } catch (error: any) {
+      // Normalize 404 errors
+      if (error.response?.status === 404) {
+        const notFoundError: any = new Error('Chain not found');
+        notFoundError.code = 'NOT_FOUND';
+        notFoundError.status = 404;
+        notFoundError.detail = error.response?.data?.detail || 'Chain not found in PDB';
+        throw notFoundError;
+      }
+      throw error;
+    }
+  },
+
+  /**
+   * Batch resolve multiple chains
+   */
+  async batchResolveChains(chains: Array<{ pdb_id: string; auth_asym_id: string }>, use_cache: boolean = true): Promise<Record<string, ChainMetadata>> {
+    const response = await api.post<Record<string, ChainMetadata>>('/protein/chain/batch-resolve', chains, {
+      params: { use_cache }
+    });
+    return response.data;
+  },
+
+  /**
+   * Get ranked functional annotations for a chain from local TSV
+   */
+  async getChainFunctions(pdb_id: string, auth_asym_id: string): Promise<string[]> {
+    const response = await api.get<{ functions: string[] }>('/protein/chain/functions', {
+      params: { pdb_id, auth_asym_id },
+    });
+    return response.data.functions;
+  },
+};

frontend/src/components/datasets/protein/BindersPanel.tsx

@@ -0,0 +1,108 @@
+/**
+ * Binders panel for a selected chain
+ * Displays nonpolymer entities (ligands/binders) with name and SMILES
+ */
+import React, { useState } from 'react';
+import { ChainMetadata } from '../../../types/protein';
+import { formatText, truncateText } from '../../../utils/format';
+
+interface BindersPanelProps {
+  metadata: ChainMetadata | null;
+  isLoading?: boolean;
+}
+
+const BindersPanel: React.FC<BindersPanelProps> = ({ metadata, isLoading }) => {
+  const [copiedIndex, setCopiedIndex] = useState<number | null>(null);
+
+  const binders = metadata?.nonpolymer_entities || [];
+
+  const handleCopySmiles = async (smiles: string | null | undefined, index: number) => {
+    if (!smiles) return;
+    
+    try {
+      await navigator.clipboard.writeText(smiles);
+      setCopiedIndex(index);
+      setTimeout(() => setCopiedIndex(null), 2000);
+    } catch (err) {
+      console.error('Failed to copy SMILES:', err);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <section className="space-y-4">
+        <h3 className="text-xl font-semibold text-slate-900">Binders</h3>
+        <div className="text-center py-10 text-slate-600">Loading binders...</div>
+      </section>
+    );
+  }
+
+  if (binders.length === 0) {
+    return (
+      <section className="space-y-4">
+        <h3 className="text-xl font-semibold text-slate-900">Binders</h3>
+        <div className="text-center py-10 text-slate-600">No binder annotations available</div>
+      </section>
+    );
+  }
+
+  return (
+    <section className="space-y-4">
+      {/* Title + Count Chip */}
+      <div className="flex items-start justify-between">
+        <h3 className="text-xl font-semibold text-slate-900">Binders</h3>
+        <span className="px-3 py-1.5 bg-amber-50 text-amber-700 text-xs font-medium rounded-full border border-amber-200">
+          {binders.length} {binders.length === 1 ? 'binder' : 'binders'}
+        </span>
+      </div>
+      
+      {/* Table */}
+      <div className="overflow-x-auto rounded-lg border border-slate-200">
+        <table className="w-full text-sm">
+          <thead className="bg-slate-50 border-b border-slate-200">
+            <tr>
+              <th className="px-4 py-3 text-left text-xs font-semibold text-slate-700 uppercase tracking-wider">Name</th>
+              <th className="px-4 py-3 text-left text-xs font-semibold text-slate-700 uppercase tracking-wider">SMILES</th>
+              <th className="px-4 py-3 text-center text-xs font-semibold text-slate-700 uppercase tracking-wider w-20">Copy</th>
+            </tr>
+          </thead>
+          <tbody>
+            {binders.map((binder, idx) => {
+              const name = formatText(binder.name);
+              const smiles = formatText(binder.smiles, '');
+              const truncatedSmiles = smiles ? truncateText(smiles, 50) : '—';
+              
+              return (
+                <tr key={idx} className="border-b border-slate-100 hover:bg-slate-50 transition-colors last:border-b-0">
+                  <td className="px-4 py-3 text-slate-900 font-medium">{name}</td>
+                  <td className="px-4 py-3 text-slate-900">
+                    {smiles ? (
+                      <code className="bg-slate-100 px-2 py-1 rounded font-mono text-xs inline-block max-w-md overflow-hidden text-ellipsis whitespace-nowrap border border-slate-200" title={smiles}>
+                        {truncatedSmiles}
+                      </code>
+                    ) : (
+                      <span className="text-slate-400">—</span>
+                    )}
+                  </td>
+                  <td className="px-4 py-3 text-center">
+                    {smiles && (
+                      <button
+                        className="inline-flex items-center justify-center w-8 h-8 border border-gray-300 text-slate-700 rounded-lg hover:bg-slate-50 hover:border-slate-400 transition-colors text-sm"
+                        onClick={() => handleCopySmiles(smiles, idx)}
+                        title="Copy SMILES"
+                      >
+                        {copiedIndex === idx ? '✓' : '📋'}
+                      </button>
+                    )}
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </section>
+  );
+};
+
+export default BindersPanel;

frontend/src/components/datasets/protein/ChainBasicInfoCards.tsx

@@ -0,0 +1,141 @@
+/**
+ * Basic information card for a selected chain
+ * Displays: PDB ID, Protein name, Chain ID, UniProt ID in a single well-designed card
+ */
+import { ChainMetadata } from '../../../types/protein';
+
+interface ChainBasicInfoCardsProps {
+  metadata: ChainMetadata | null;
+  isLoading?: boolean;
+}
+
+const ChainBasicInfoCards: React.FC<ChainBasicInfoCardsProps> = ({ metadata, isLoading }) => {
+  const getUniProtId = () => {
+    if (!metadata?.polymer_entity?.reference_sequences) return '—';
+    
+    const refSeqs = metadata.polymer_entity.reference_sequences;
+    const uniprotRefs = refSeqs.filter((ref: any) => ref.database_name === 'UniProt');
+    
+    if (uniprotRefs.length > 0) {
+      const first = uniprotRefs[0].database_accession;
+      if (uniprotRefs.length > 1) {
+        return (
+          <span title={uniprotRefs.map((r: any) => r.database_accession).join(', ')}>
+            {first} <span className="text-gray-500 text-xs">+{uniprotRefs.length - 1} more</span>
+          </span>
+        );
+      }
+      return first;
+    }
+    
+    // Fallback to first reference sequence
+    if (refSeqs.length > 0) {
+      return refSeqs[0].database_accession || '—';
+    }
+    
+    return '—';
+  };
+
+  if (isLoading) {
+    return (
+      <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm">
+        <div className="flex items-center gap-3">
+          <div className="w-8 h-8 border-4 border-slate-200 border-t-slate-900 rounded-full animate-spin"></div>
+          <span className="text-slate-600 text-sm">Loading chain metadata...</span>
+        </div>
+      </div>
+    );
+  }
+
+  const pdbId = metadata?.entry?.rcsb_id || metadata?.pdb_id;
+  const chainId = metadata?.chain_id || metadata?.polymer_entity_instance?.auth_asym_id;
+
+  return (
+    <div className="h-full w-full border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+      <div className="flex items-start justify-between mb-4">
+        <h3 className="text-xl font-semibold text-slate-900">Chain Metadata</h3>
+        <div className="flex flex-wrap gap-2">
+          <span className="px-3 py-1.5 bg-blue-50 text-blue-700 text-xs font-medium rounded-full border border-blue-200">
+            {pdbId || 'N/A'}
+          </span>
+          {chainId && (
+            <span className="px-3 py-1.5 bg-purple-50 text-purple-700 text-xs font-medium rounded-full border border-purple-200">
+              Chain {chainId}
+            </span>
+          )}
+        </div>
+      </div>
+
+      {/* Chips Row */}
+
+      {/* Compact three-column metadata flow */}
+      <div className="gap-4" style={{ columnCount: 3, columnGap: '1rem' }}>
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Protein Name</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono" title={metadata?.entry?.title || ''}>
+            {metadata?.entry?.title || '—'}
+          </div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">PDB ID</div>
+          <div className="text-sm font-semibold text-slate-900">
+            <a 
+              href={`https://www.rcsb.org/structure/${pdbId}`}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-blue-600 hover:text-blue-800 font-mono hover:underline inline-flex items-center gap-1 transition-colors"
+            >
+              {pdbId || '—'}
+              <span className="text-xs">↗</span>
+            </a>
+          </div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Chain ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{chainId || '—'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">UniProt ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{getUniProtId()}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Binding Status</div>
+          <div className="text-sm font-semibold text-slate-900 capitalize">{metadata?.binding_status || '—'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.cath_id || 'uncategorized'}</div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH Domain</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">
+            {metadata?.cath_superfamily ? (
+              <a
+                href={`https://www.cathdb.info/version/latest/superfamily/${metadata.cath_superfamily}`}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-blue-600 hover:text-blue-800 hover:underline inline-flex items-center gap-1 transition-colors"
+              >
+                {metadata.cath_superfamily}
+                <span className="text-xs">↗</span>
+              </a>
+            ) : '—'}
+          </div>
+        </div>
+
+        <div className="break-inside-avoid mb-3">
+          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">State ID</div>
+          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.state_id || '—'}</div>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default ChainBasicInfoCards;

frontend/src/components/datasets/protein/ChainSearchInput.tsx

@@ -0,0 +1,204 @@
+import React, { useState, useEffect, useRef } from 'react';
+import type { ChainMetadata } from '../../../types/protein';
+
+type SearchStatus = 'idle' | 'typing' | 'loading' | 'success' | 'not_found' | 'error';
+
+interface ChainSearchInputProps {
+  value: string;
+  onValueChange: (value: string) => void;
+  onChainSelect: (pdb_id: string, auth_asym_id: string) => void;
+  onMetadataLoaded: (metadata: ChainMetadata) => void;
+  onClear: () => void;
+  resolveChain: (pdb_id: string, auth_asym_id: string) => Promise<ChainMetadata>;
+  searchStatus: SearchStatus;
+  resolvedLabel?: string;
+  errorMessage?: string;
+  disabled?: boolean;
+}
+
+interface ParsedChain {
+  pdb_id: string;
+  auth_asym_id: string;
+  valid: boolean;
+  error?: string;
+}
+
+export const ChainSearchInput: React.FC<ChainSearchInputProps> = ({
+  value,
+  onValueChange,
+  onChainSelect,
+  onMetadataLoaded,
+  onClear,
+  resolveChain,
+  searchStatus,
+  resolvedLabel,
+  errorMessage,
+  disabled
+}) => {
+  const [parsed, setParsed] = useState<ParsedChain | null>(null);
+  const [debouncedValue, setDebouncedValue] = useState('');
+  const lastResolvedKey = useRef<string | null>(null);
+
+  // Debounce input (500ms)
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, 500);
+
+    return () => clearTimeout(timer);
+  }, [value]);
+
+  // Parse chain identifier
+  const parseChainId = (value: string): ParsedChain => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return { pdb_id: '', auth_asym_id: '', valid: false };
+    }
+
+    // Accept formats: "3vgm.A", "3VGM:A", "3VGM_A", "3vgm A"
+    const separatorRegex = /[.\s:_]+/;
+    const parts = trimmed.split(separatorRegex);
+
+    if (parts.length < 2) {
+      return {
+        pdb_id: '',
+        auth_asym_id: '',
+        valid: false,
+        error: 'Format: PDB_ID + Chain (e.g., "3vgm.A", "3VGM:A", "3VGM_A")'
+      };
+    }
+
+    const pdb_id = parts[0].trim();
+    const auth_asym_id = parts.slice(1).join('').trim(); // Handle multi-char chain IDs
+
+    // Validate PDB ID (4 characters)
+    if (pdb_id.length !== 4) {
+      return {
+        pdb_id,
+        auth_asym_id,
+        valid: false,
+        error: 'PDB ID must be exactly 4 characters'
+      };
+    }
+
+    // Validate chain ID (at least 1 character)
+    if (auth_asym_id.length === 0) {
+      return {
+        pdb_id,
+        auth_asym_id,
+        valid: false,
+        error: 'Chain ID is required (e.g., "A", "B", "AA")'
+      };
+    }
+
+    return {
+      pdb_id: pdb_id.toLowerCase(),
+      auth_asym_id: auth_asym_id.toUpperCase(),
+      valid: true
+    };
+  };
+
+  // Parse and validate when debounced value changes
+  useEffect(() => {
+    if (!debouncedValue) {
+      setParsed(null);
+      lastResolvedKey.current = null;
+      return;
+    }
+
+    const result = parseChainId(debouncedValue);
+    setParsed(result);
+
+    if (!result.valid) {
+      return;
+    }
+
+    // Create key for this chain
+    const currentKey = `${result.pdb_id}|${result.auth_asym_id}`;
+    
+    // Only resolve if key changed (prevent duplicate requests)
+    if (currentKey === lastResolvedKey.current) {
+      return;
+    }
+    
+    lastResolvedKey.current = currentKey;
+
+    // Valid - trigger resolution (parent manages loading/error state)
+    resolveChain(result.pdb_id, result.auth_asym_id)
+      .then(metadata => {
+        onChainSelect(result.pdb_id, result.auth_asym_id);
+        onMetadataLoaded(metadata);
+      })
+      .catch(() => {
+        // Parent handles error state
+      });
+  }, [debouncedValue, resolveChain, onChainSelect, onMetadataLoaded]);
+
+  const handleClear = () => {
+    setParsed(null);
+    setDebouncedValue('');
+    lastResolvedKey.current = null;
+    onClear();
+  };
+
+  const getBorderColor = () => {
+    if (searchStatus === 'loading') return 'border-blue-400';
+    if (searchStatus === 'error' || searchStatus === 'not_found' || (parsed && !parsed.valid)) return 'border-red-400';
+    if (searchStatus === 'success') return 'border-green-400';
+    return 'border-gray-300';
+  };
+
+  const showError = searchStatus === 'error' || searchStatus === 'not_found' || (parsed && !parsed.valid && value);
+  const displayError = errorMessage || parsed?.error || 'Invalid chain identifier';
+
+  return (
+    <div className="space-y-3">
+      <label className="block">
+        <span className="text-sm font-medium text-slate-900">Chain Identifier</span>
+        <span className="block text-xs text-slate-500 mt-1">
+          Format: PDB ID + Chain (e.g., 3vgm.A, 3VGM:A, 3VGM_A, 3vgm A)
+        </span>
+      </label>
+      
+      <div className={`relative flex items-center border-2 ${getBorderColor()} rounded-lg transition-all duration-200 focus-within:ring-2 focus-within:ring-slate-900 focus-within:ring-offset-2 bg-white`}>
+        <input
+          type="text"
+          className="flex-1 px-4 py-3 text-sm text-slate-900 bg-transparent rounded-lg outline-none placeholder:text-slate-400 disabled:bg-slate-50 disabled:cursor-not-allowed"
+          value={value}
+          onChange={(e) => onValueChange(e.target.value)}
+          placeholder="e.g., 3vgm.A"
+          disabled={disabled}
+        />
+        
+        {value && searchStatus !== 'loading' && (
+          <button
+            className="absolute right-3 w-7 h-7 flex items-center justify-center text-slate-400 hover:text-slate-600 hover:bg-slate-100 rounded-md transition-colors disabled:cursor-not-allowed"
+            onClick={handleClear}
+            disabled={disabled}
+            title="Clear"
+          >
+            ✕
+          </button>
+        )}
+
+        {searchStatus === 'loading' && (
+          <div className="absolute right-3 w-5 h-5 border-2 border-slate-200 border-t-slate-900 rounded-full animate-spin" title="Resolving chain..."></div>
+        )}
+      </div>
+
+      {searchStatus === 'success' && resolvedLabel && (
+        <div className="flex items-center gap-2 text-sm text-green-700 bg-green-50 px-3 py-2 rounded-lg border border-green-200">
+          <span className="text-base">✓</span>
+          <span className="font-medium">{resolvedLabel}</span>
+        </div>
+      )}
+
+      {showError && (
+        <div className="flex items-center gap-2 text-sm text-red-700 bg-red-50 px-3 py-2 rounded-lg border border-red-200">
+          <span className="text-base">✗</span>
+          <span>{displayError}</span>
+        </div>
+      )}
+    </div>
+  );
+};

frontend/src/components/datasets/protein/DataTable.css

@@ -0,0 +1,177 @@
+.data-table-container {
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.table-header {
+  padding: 15px 20px;
+  border-bottom: 2px solid #e0e0e0;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.table-header h3 {
+  margin: 0;
+}
+
+.table-stats {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  color: #666;
+  font-size: 0.9rem;
+}
+
+.separator {
+  color: #ccc;
+}
+
+.table-wrapper {
+  flex: 1;
+  overflow: auto;
+}
+
+.data-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+
+.data-table thead {
+  position: sticky;
+  top: 0;
+  background: #f5f5f5;
+  z-index: 10;
+}
+
+.data-table th {
+  padding: 12px 15px;
+  text-align: left;
+  font-weight: 600;
+  color: #555;
+  border-bottom: 2px solid #e0e0e0;
+  cursor: pointer;
+  user-select: none;
+  white-space: nowrap;
+}
+
+.data-table th:hover {
+  background: #e8e8e8;
+}
+
+.data-table td {
+  padding: 10px 15px;
+  border-bottom: 1px solid #f0f0f0;
+}
+
+.data-table tbody tr:hover {
+  background: #fafafa;
+}
+
+.chain-id {
+  font-weight: 600;
+  color: #2196f3;
+}
+
+.asym-id {
+  color: #666;
+  font-size: 0.85rem;
+}
+
+.numeric {
+  text-align: right;
+  font-family: 'Courier New', monospace;
+}
+
+.cluster {
+  font-size: 0.85rem;
+  color: #666;
+  text-transform: capitalize;
+}
+
+.pagination {
+  padding: 15px 20px;
+  border-top: 1px solid #e0e0e0;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 15px;
+}
+
+.pagination button {
+  padding: 8px 16px;
+  background: #2196f3;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 0.9rem;
+  transition: background 0.3s;
+}
+
+.pagination button:hover:not(:disabled) {
+  background: #1976d2;
+}
+
+.pagination button:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.page-info {
+  color: #666;
+  font-size: 0.9rem;
+}
+
+.table-loading,
+.table-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: #888;
+  font-size: 1.1rem;
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.table-empty {
+  color: #999;
+}
+
+.table-hint {
+  font-size: 0.8em;
+  font-weight: normal;
+  color: #888;
+}
+
+.placeholder {
+  color: #999;
+  font-style: italic;
+}
+
+.experimental-method {
+  max-width: 200px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.delta-cell {
+  font-family: 'Courier New', monospace;
+  text-align: right;
+}
+
+.delta-pos {
+  color: #d32f2f;
+}
+
+.delta-neg {
+  color: #2e7d32;
+}

frontend/src/components/datasets/protein/DataTable.tsx

@@ -0,0 +1,197 @@
+import React, { useState } from 'react';
+import type { DataRecord } from '../../../types/protein';
+import { formatTemperature, formatPH } from '../../../utils/format';
+import './DataTable.css';
+
+interface DataTableProps {
+  data: DataRecord[];
+  loading: boolean;
+  total: number;
+  filtered: number;
+}
+
+type SortField = keyof DataRecord;
+type SortDirection = 'asc' | 'desc';
+
+export const DataTable: React.FC<DataTableProps> = ({ data, loading, total, filtered }) => {
+  const [sortField, setSortField] = useState<SortField>('rmsd');
+  const [sortDirection, setSortDirection] = useState<SortDirection>('asc');
+  const [currentPage, setCurrentPage] = useState(1);
+  const itemsPerPage = 50;
+
+  if (loading) {
+    return <div className="table-loading">Loading data...</div>;
+  }
+
+  if (data.length === 0) {
+    return <div className="table-empty">No data to display. Adjust filters to see results.</div>;
+  }
+
+  // Sorting
+  const sortedData = [...data].sort((a, b) => {
+    const aValue = a[sortField];
+    const bValue = b[sortField];
+    
+    if (typeof aValue === 'number' && typeof bValue === 'number') {
+      return sortDirection === 'asc' ? aValue - bValue : bValue - aValue;
+    }
+    
+    if (typeof aValue === 'string' && typeof bValue === 'string') {
+      return sortDirection === 'asc' 
+        ? aValue.localeCompare(bValue)
+        : bValue.localeCompare(aValue);
+    }
+    
+    return 0;
+  });
+
+  // Pagination
+  const totalPages = Math.ceil(sortedData.length / itemsPerPage);
+  const startIndex = (currentPage - 1) * itemsPerPage;
+  const endIndex = startIndex + itemsPerPage;
+  const paginatedData = sortedData.slice(startIndex, endIndex);
+
+  const handleSort = (field: SortField) => {
+    if (sortField === field) {
+      setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc');
+    } else {
+      setSortField(field);
+      setSortDirection('asc');
+    }
+    setCurrentPage(1);
+  };
+
+  const getSortIcon = (field: SortField) => {
+    if (sortField !== field) return '↕';
+    return sortDirection === 'asc' ? '↑' : '↓';
+  };
+
+  return (
+    <div className="data-table-container">
+      <div className="table-header">
+        <h3 className="text-xl font-semibold text-slate-900">Alternative observations</h3>
+        <div className="table-stats">
+          <span>Showing {paginatedData.length} of {filtered.toLocaleString()} filtered</span>
+          <span className="separator">|</span>
+          <span>Total: {total.toLocaleString()}</span>
+        </div>
+      </div>
+
+      <div className="table-wrapper">
+        <table className="data-table">
+          <thead>
+            <tr>
+              <th onClick={() => handleSort('pdb_id_b')}>
+                PDB ID <span className="table-hint">(Matched)</span> {getSortIcon('pdb_id_b')}
+              </th>
+              <th onClick={() => handleSort('auth_asym_id_b')}>
+                Chain ID {getSortIcon('auth_asym_id_b')}
+              </th>
+              <th onClick={() => handleSort('tm_score')}>
+                TM-score {getSortIcon('tm_score')}
+              </th>
+              <th onClick={() => handleSort('rmsd')}>
+                RMSD (Å) {getSortIcon('rmsd')}
+              </th>
+              <th>
+                Experimental Method
+              </th>
+              <th>
+                Temp (K)
+              </th>
+              <th>
+                pH
+              </th>
+              <th onClick={() => handleSort('delta_rosetta')}>
+                ΔRosetta {getSortIcon('delta_rosetta')}
+              </th>
+              <th onClick={() => handleSort('delta_foldx')}>
+                ΔFoldX {getSortIcon('delta_foldx')}
+              </th>
+              <th onClick={() => handleSort('delta_evoef2')}>
+                ΔEvoEF2 {getSortIcon('delta_evoef2')}
+              </th>
+              <th onClick={() => handleSort('delta_rm')}>
+                ΔRM {getSortIcon('delta_rm')}
+              </th>
+              <th onClick={() => handleSort('delta_rm_plus')}>
+                ΔRM+ {getSortIcon('delta_rm_plus')}
+              </th>
+              <th onClick={() => handleSort('state_id_b')}>
+                State ID {getSortIcon('state_id_b')}
+              </th>
+              <th onClick={() => handleSort('state_fidelity')}>
+                State fidelity {getSortIcon('state_fidelity')}
+              </th>
+              <th onClick={() => handleSort('avg_sim')}>
+                State avg. similarity {getSortIcon('avg_sim')}
+              </th>
+              <th onClick={() => handleSort('pair_fidelity')}>
+                Observation fidelity {getSortIcon('pair_fidelity')}
+              </th>
+              <th onClick={() => handleSort('structure_sim')}>
+                Observation similarity {getSortIcon('structure_sim')}
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {paginatedData.map((record, index) => (
+              <tr key={`${record.pdb_id_a}-${record.auth_asym_id_a}-${record.pdb_id_b}-${record.auth_asym_id_b}-${index}`}>
+                <td>
+                  <span className="chain-id">{record.pdb_id_b.toUpperCase()}</span>
+                </td>
+                <td>
+                  <span className="asym-id">{record.auth_asym_id_b}</span>
+                </td>
+                <td className="numeric">{record.tm_score.toFixed(3)}</td>
+                <td className="numeric">{record.rmsd.toFixed(2)}</td>
+                <td className="experimental-method">
+                  {record.exptl_method || <span className="placeholder">—</span>}
+                </td>
+                <td className="numeric">
+                  {formatTemperature(record.temp)}
+                </td>
+                <td className="numeric">
+                  {formatPH(record.pH)}
+                </td>
+                {(['delta_rosetta', 'delta_foldx', 'delta_evoef2', 'delta_rm', 'delta_rm_plus'] as const).map(field => {
+                  const val = record[field];
+                  return (
+                    <td key={field} className={`numeric delta-cell${val == null ? '' : val > 0 ? ' delta-pos' : val < 0 ? ' delta-neg' : ''}`}>
+                      {val == null ? <span className="placeholder">—</span> : `${val > 0 ? '+' : ''}${val.toFixed(2)}`}
+                    </td>
+                  );
+                })}
+                <td className="font-mono">{record.state_id_b ?? <span className="placeholder">—</span>}</td>
+                <td>{record.state_fidelity ?? <span className="placeholder">—</span>}</td>
+                <td>{record.avg_sim ?? <span className="placeholder">—</span>}</td>
+                <td>{record.pair_fidelity ?? <span className="placeholder">—</span>}</td>
+                <td className="numeric">{record.structure_sim != null ? record.structure_sim.toFixed(3) : <span className="placeholder">—</span>}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {totalPages > 1 && (
+        <div className="pagination">
+          <button
+            onClick={() => setCurrentPage(Math.max(1, currentPage - 1))}
+            disabled={currentPage === 1}
+          >
+            Previous
+          </button>
+          <span className="page-info">
+            Page {currentPage} of {totalPages}
+          </span>
+          <button
+            onClick={() => setCurrentPage(Math.min(totalPages, currentPage + 1))}
+            disabled={currentPage === totalPages}
+          >
+            Next
+          </button>
+        </div>
+      )}
+    </div>
+  );
+};

frontend/src/components/datasets/protein/ErrorBoundary.css

@@ -0,0 +1,93 @@
+/* Error Boundary Fallback Styling */
+
+.error-boundary-fallback {
+  background: #fff;
+  border: 2px solid #fecaca;
+  border-radius: 12px;
+  padding: 32px;
+  text-align: center;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+}
+
+.error-boundary-icon {
+  font-size: 48px;
+  margin-bottom: 16px;
+}
+
+.error-boundary-fallback h3 {
+  margin: 0 0 8px 0;
+  font-size: 18px;
+  font-weight: 600;
+  color: #991b1b;
+}
+
+.error-boundary-fallback p {
+  margin: 0 0 24px 0;
+  font-size: 14px;
+  color: #6b7280;
+}
+
+.error-boundary-actions {
+  display: flex;
+  gap: 12px;
+  justify-content: center;
+  margin-bottom: 16px;
+}
+
+.error-boundary-btn {
+  padding: 10px 20px;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  border: none;
+}
+
+.error-boundary-btn.primary {
+  background: #667eea;
+  color: white;
+}
+
+.error-boundary-btn.primary:hover {
+  background: #5568d3;
+}
+
+.error-boundary-btn.secondary {
+  background: #e5e7eb;
+  color: #374151;
+}
+
+.error-boundary-btn.secondary:hover {
+  background: #d1d5db;
+}
+
+.error-boundary-details {
+  margin-top: 16px;
+  text-align: left;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  padding: 12px;
+}
+
+.error-boundary-details summary {
+  cursor: pointer;
+  font-weight: 600;
+  font-size: 13px;
+  color: #6b7280;
+  margin-bottom: 8px;
+}
+
+.error-boundary-stack {
+  margin: 8px 0 0 0;
+  padding: 12px;
+  background: #1f2937;
+  color: #f9fafb;
+  border-radius: 6px;
+  font-size: 12px;
+  font-family: 'Courier New', monospace;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+}

frontend/src/components/datasets/protein/ErrorBoundary.tsx

@@ -0,0 +1,105 @@
+/**
+ * Error Boundary component to catch React render errors
+ * Prevents a single component crash from taking down the entire app
+ */
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+import './ErrorBoundary.css';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+  componentName?: string;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+  errorInfo: ErrorInfo | null;
+}
+
+class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = {
+      hasError: false,
+      error: null,
+      errorInfo: null,
+    };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return {
+      hasError: true,
+      error,
+      errorInfo: null,
+    };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('ErrorBoundary caught an error:', error, errorInfo);
+    this.setState({
+      error,
+      errorInfo,
+    });
+  }
+
+  handleReset = () => {
+    this.setState({
+      hasError: false,
+      error: null,
+      errorInfo: null,
+    });
+  };
+
+  handleCopyError = () => {
+    const { error, errorInfo } = this.state;
+    const errorText = `Error: ${error?.toString()}\n\nStack: ${errorInfo?.componentStack}`;
+    navigator.clipboard.writeText(errorText).then(() => {
+      alert('Error details copied to clipboard');
+    });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      // Custom fallback if provided
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      // Default fallback UI
+      const componentName = this.props.componentName || 'this component';
+      const isDev = import.meta.env?.DEV || process.env.NODE_ENV === 'development';
+
+      return (
+        <div className="error-boundary-fallback">
+          <div className="error-boundary-icon">⚠️</div>
+          <h3>Unable to render {componentName}</h3>
+          <p>Something went wrong while displaying this section.</p>
+          <div className="error-boundary-actions">
+            <button onClick={this.handleReset} className="error-boundary-btn primary">
+              Try Again
+            </button>
+            {isDev && this.state.error && (
+              <button onClick={this.handleCopyError} className="error-boundary-btn secondary">
+                Copy Error Details
+              </button>
+            )}
+          </div>
+          {isDev && this.state.error && (
+            <details className="error-boundary-details">
+              <summary>Error Details (dev only)</summary>
+              <pre className="error-boundary-stack">
+                {this.state.error.toString()}
+                {this.state.errorInfo?.componentStack}
+              </pre>
+            </details>
+          )}
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+export default ErrorBoundary;

frontend/src/components/datasets/protein/ExperimentalConditionsPanel.tsx

@@ -0,0 +1,117 @@
+/**
+ * Experimental conditions panel for a selected chain
+ * Displays method, resolution, pH, temperature, details, and RCSB link
+ */
+import React, { useState } from 'react';
+import { ChainMetadata } from '../../../types/protein';
+import { formatText, formatPH, formatTemperature, truncateText } from '../../../utils/format';
+
+interface ExperimentalConditionsPanelProps {
+  metadata: ChainMetadata | null;
+  isLoading?: boolean;
+}
+
+const ExperimentalConditionsPanel: React.FC<ExperimentalConditionsPanelProps> = ({ metadata, isLoading }) => {
+  const [showFullDetails, setShowFullDetails] = useState(false);
+
+  if (isLoading) {
+    return (
+      <section className="space-y-4">
+        <h3 className="text-xl font-semibold text-slate-900">Experimental Conditions</h3>
+        <div className="text-center py-10 text-slate-600">Loading conditions...</div>
+      </section>
+    );
+  }
+
+  if (!metadata) {
+    return (
+      <section className="space-y-4">
+        <h3 className="text-xl font-semibold text-slate-900">Experimental Conditions</h3>
+        <div className="text-center py-10 text-slate-600">No experimental data available</div>
+      </section>
+    );
+  }
+
+  // Safe extraction with optional chaining and nullish coalescing
+  const pdbId = metadata.pdb_id || metadata.entry?.rcsb_id;
+  const website = pdbId ? `https://www.rcsb.org/structure/${String(pdbId).toUpperCase()}` : null;
+  const exptlMethod = metadata.entry?.exptl_method;
+  const pH = metadata.entry?.crystal_grow?.pH;
+  const temp = metadata.entry?.crystal_grow?.temp;
+  const details = metadata.entry?.crystal_grow?.pdbx_details;
+
+  // Safe formatting
+  const formattedMethod = formatText(exptlMethod);
+  const formattedPH = formatPH(pH);
+  const formattedTemp = formatTemperature(temp);
+  const formattedDetails = formatText(details, '');
+
+  const detailsPreview = formattedDetails ? truncateText(formattedDetails, 120) : '';
+  const hasLongDetails = formattedDetails && formattedDetails.length > 120;
+
+  return (
+    <section className="space-y-4">
+      {/* Title + Method Chip */}
+      <div className="flex items-start justify-between">
+        <h3 className="text-xl font-semibold text-slate-900">Experimental Conditions</h3>
+        {formattedMethod !== '—' && (
+          <span className="px-3 py-1.5 bg-green-50 text-green-700 text-xs font-medium rounded-full border border-green-200">
+            {formattedMethod}
+          </span>
+        )}
+      </div>
+      
+      {/* Definition List */}
+      <dl className="space-y-3 pt-2">
+        {website && (
+          <div className="flex justify-between items-center py-2 border-b border-slate-100">
+            <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Website</dt>
+            <dd>
+              <a href={website} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1 text-sm text-blue-600 hover:text-blue-800 font-medium hover:underline transition-colors">
+                RCSB PDB <span className="text-xs">↗</span>
+              </a>
+            </dd>
+          </div>
+        )}
+
+        <div className="flex justify-between items-center py-2 border-b border-slate-100">
+          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Method</dt>
+          <dd className="text-sm font-semibold text-slate-900">{formattedMethod}</dd>
+        </div>
+
+<div className="flex justify-between items-center py-2 border-b border-slate-100">
+          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">pH</dt>
+          <dd className="text-sm font-semibold text-slate-900">{formattedPH}</dd>
+        </div>
+
+        <div className="flex justify-between items-center py-2 border-b border-slate-100">
+          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Temperature</dt>
+          <dd className="text-sm font-semibold text-slate-900">{formattedTemp}</dd>
+        </div>
+
+        <div className="flex justify-between items-center py-2 border-b border-slate-100">
+          {formattedDetails && (
+            <div className="experimental-item experimental-details">
+          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Details</dt>
+          <dd className="text-sm font-semibold text-slate-900">
+                <div className="details-content">
+                  {showFullDetails ? formattedDetails : detailsPreview}
+                </div>
+                {hasLongDetails && (
+                  <button
+                    className="details-toggle"
+                    onClick={() => setShowFullDetails(!showFullDetails)}
+                  >
+                    {showFullDetails ? '▲ Show less' : '▼ Show more'}
+                  </button>
+                )}
+              </dd>
+            </div>
+          )}
+        </div>
+      </dl>
+    </section>
+  );
+};
+
+export default ExperimentalConditionsPanel;

frontend/src/components/datasets/protein/FilterPanel.tsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import type { FilterParams, FilterOptions, ChainMetadata } from '../../../types/protein';
+import { ChainSearchInput } from './ChainSearchInput';
+
+interface FilterPanelProps {
+  filterOptions: FilterOptions | null;
+  filters: FilterParams;
+  searchInputValue: string;
+  onSearchInputChange: (value: string) => void;
+  onSearchClear: () => void;
+  searchStatus: 'idle' | 'typing' | 'loading' | 'success' | 'not_found' | 'error';
+  searchError: string | null;
+  resolvedLabel?: string;
+  onFiltersChange: (filters: FilterParams) => void;
+  onChainMetadataLoaded: (metadata: ChainMetadata) => void;
+  resolveChain: (pdb_id: string, auth_asym_id: string) => Promise<ChainMetadata>;
+  loading: boolean;
+  showResetButton?: boolean;
+}
+
+export const FilterPanel: React.FC<FilterPanelProps> = ({
+  filterOptions,
+  searchInputValue,
+  onSearchInputChange,
+  onSearchClear,
+  searchStatus,
+  searchError,
+  resolvedLabel,
+  onFiltersChange,
+  onChainMetadataLoaded,
+  resolveChain,
+  loading,
+  showResetButton = false,
+}) => {
+  const handleChainSelect = (pdb_id: string, auth_asym_id: string) => {
+    onFiltersChange({ pdb_id, auth_asym_id });
+  };
+
+  if (!filterOptions) {
+    return (
+      <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm">
+        <div className="flex items-center justify-center min-h-[100px] text-slate-500">
+          Loading...
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex flex-col gap-4">
+        <ChainSearchInput
+          value={searchInputValue}
+          onValueChange={onSearchInputChange}
+          onChainSelect={handleChainSelect}
+          onMetadataLoaded={onChainMetadataLoaded}
+          onClear={onSearchClear}
+          resolveChain={resolveChain}
+          searchStatus={searchStatus}
+          resolvedLabel={resolvedLabel}
+          errorMessage={searchError || undefined}
+          disabled={loading}
+        />
+        {showResetButton && (
+          <button 
+            onClick={onSearchClear} 
+            className="inline-flex items-center justify-center px-5 py-2.5 border border-gray-300 text-slate-900 font-medium rounded-lg hover:bg-slate-50 transition-colors duration-200 text-sm"
+          >
+            Reset Search
+          </button>
+        )}
+      </div>
+    </div>
+  );
+};

frontend/src/components/datasets/protein/FunctionPanel.tsx

@@ -0,0 +1,67 @@
+import React, { useEffect, useState } from 'react';
+import { proteinApi } from '../../../api/protein';
+
+interface FunctionPanelProps {
+  pdbId: string;
+  chainId: string;
+}
+
+const FunctionPanel: React.FC<FunctionPanelProps> = ({ pdbId, chainId }) => {
+  const [functions, setFunctions] = useState<string[] | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [notFound, setNotFound] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setNotFound(false);
+    setFunctions(null);
+
+    proteinApi.getChainFunctions(pdbId, chainId)
+      .then(fns => { if (!cancelled) setFunctions(fns); })
+      .catch(() => { if (!cancelled) setNotFound(true); })
+      .finally(() => { if (!cancelled) setLoading(false); });
+
+    return () => { cancelled = true; };
+  }, [pdbId, chainId]);
+
+  return (
+    <div className="border border-gray-200 rounded-2xl bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+      {/* Header */}
+      <div className="flex items-center justify-between px-6 py-4 border-b border-gray-100">
+        <h3 className="text-xl font-semibold text-slate-900">Ranked Functions</h3>
+        {functions && (
+          <span className="text-sm text-slate-500">
+            {functions.length} annotation{functions.length !== 1 ? 's' : ''}
+          </span>
+        )}
+      </div>
+
+      {/* Scrollable body */}
+      <div className="px-6 py-4" style={{ overflowY: 'auto', overflowX: 'hidden', maxHeight: '14rem' }}>
+        {loading && (
+          <p className="text-sm text-slate-500 text-center py-4">Loading functions…</p>
+        )}
+
+        {!loading && (notFound || (functions && functions.length === 0)) && (
+          <p className="text-sm text-slate-500 text-center py-4">No functional annotation available</p>
+        )}
+
+        {!loading && functions && functions.length > 0 && (
+          <ol className="space-y-3">
+            {functions.map((fn, idx) => (
+              <li key={idx} className="flex gap-3 text-sm text-slate-700" style={{ minWidth: 0 }}>
+                <span className="shrink-0 mt-0.5 w-5 h-5 rounded-full bg-slate-100 text-slate-500 text-[10px] font-semibold flex items-center justify-center">
+                  {idx + 1}
+                </span>
+                <span style={{ flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>{fn}</span>
+              </li>
+            ))}
+          </ol>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default FunctionPanel;

frontend/src/components/datasets/protein/ProteinDashboard.tsx

@@ -0,0 +1,426 @@
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { Link } from 'react-router-dom';
+import { Home, Download, BookOpen } from 'lucide-react';
+import { FilterPanel } from './FilterPanel';
+import { StaticDistributionPlots } from './StaticDistributionPlots';
+import { DataTable } from './DataTable';
+import { StatsPanel } from './StatsPanel';
+import ChainBasicInfoCards from './ChainBasicInfoCards';
+import SequencePanel from './SequencePanel';
+import ExperimentalConditionsPanel from './ExperimentalConditionsPanel';
+import BindersPanel from './BindersPanel';
+import FunctionPanel from './FunctionPanel';
+import ErrorBoundary from './ErrorBoundary';
+import { proteinApi } from '../../../api/protein';
+import type { FilterParams, FilterOptions, DataResponse, SummaryStats, ChainMetadata } from '../../../types/protein';
+import { PageSEO } from '../../seo/PageSEO';
+import { MuSProtJsonLd } from '../../seo/MuSProtJsonLd';
+
+interface CacheEntry {
+  status: 'success' | 'not_found' | 'error';
+  timestamp: number;
+  message?: string;
+  metadata?: ChainMetadata;
+}
+
+const NEGATIVE_CACHE_TTL = 10 * 60 * 1000; // 10 minutes
+
+export function ProteinDashboard() {
+  // State management
+  const [filterOptions, setFilterOptions] = useState<FilterOptions | null>(null);
+  const [filters, setFilters] = useState<FilterParams>({});
+  const [dataResponse, setDataResponse] = useState<DataResponse | null>(null);
+  const [summaryStats, setSummaryStats] = useState<SummaryStats | null>(null);
+  
+  // Search input state (controlled)
+  const [searchInputValue, setSearchInputValue] = useState('');
+  const [searchStatus, setSearchStatus] = useState<'idle' | 'typing' | 'loading' | 'success' | 'not_found' | 'error'>('idle');
+  const [searchError, setSearchError] = useState<string | null>(null);
+  
+  // Chain metadata cache (client-side) — used for the searched chain's detail panels
+  const [chainMetadataCache, setChainMetadataCache] = useState<Record<string, ChainMetadata>>({});
+
+  // Request control refs
+  const negativeCache = useRef<Map<string, CacheEntry>>(new Map());
+  const inFlightResolve = useRef<{ key: string; controller: AbortController } | null>(null);
+  const lastAttemptedKey = useRef<string | null>(null);
+  
+  const [, setLoadingFilters] = useState(true);
+  const [loadingData, setLoadingData] = useState(false);
+  const [loadingStats, setLoadingStats] = useState(false);
+  
+  const [error, setError] = useState<string | null>(null);
+
+  // Load filter options on mount
+  useEffect(() => {
+    const loadFilters = async () => {
+      try {
+        setLoadingFilters(true);
+        const options = await proteinApi.getFilters();
+        setFilterOptions(options);
+      } catch (err) {
+        setError('Failed to load filter options. The MuSProt database may still be initializing.');
+        console.error('Error loading filters:', err);
+      } finally {
+        setLoadingFilters(false);
+      }
+    };
+
+    loadFilters();
+  }, []);
+
+  const fetchData = useCallback(async () => {
+    try {
+      setLoadingData(true);
+      setError(null);
+      const response = await proteinApi.getData(filters);
+      setDataResponse(response);
+    } catch (err) {
+      setError('Failed to fetch data. Please check your filters and try again.');
+      console.error('Error fetching data:', err);
+    } finally {
+      setLoadingData(false);
+    }
+  }, [filters]);
+
+  const fetchStats = useCallback(async () => {
+    try {
+      setLoadingStats(true);
+      const stats = await proteinApi.getSummary(filters);
+      setSummaryStats(stats);
+    } catch (err) {
+      console.error('Error fetching stats:', err);
+    } finally {
+      setLoadingStats(false);
+    }
+  }, [filters]);
+
+  // Debounced data fetching — skip fetchData when there's no active chain search
+  useEffect(() => {
+    const timeoutId = setTimeout(() => {
+      if (filters.pdb_id && filters.auth_asym_id) {
+        fetchData();
+      }
+      fetchStats();
+    }, 500);
+
+    return () => clearTimeout(timeoutId);
+  }, [fetchData, fetchStats, filters.pdb_id, filters.auth_asym_id]);
+
+  const handleFiltersChange = (newFilters: FilterParams) => {
+    setFilters(newFilters);
+  };
+
+  const handleSearchInputChange = useCallback((value: string) => {
+    setSearchInputValue(value);
+    if (value && searchStatus !== 'loading') {
+      setSearchStatus('typing');
+      // Clear last attempted key when user starts typing new value
+      lastAttemptedKey.current = null;
+    } else if (!value) {
+      setSearchStatus('idle');
+      setSearchError(null);
+    }
+  }, [searchStatus]);
+
+  const handleSearchClear = useCallback(() => {
+    setSearchInputValue('');
+    setSearchStatus('idle');
+    setSearchError(null);
+    setFilters({});
+    lastAttemptedKey.current = null;
+    // Abort any in-flight request
+    if (inFlightResolve.current) {
+      inFlightResolve.current.controller.abort();
+      inFlightResolve.current = null;
+    }
+  }, []);
+  
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      // Abort any in-flight requests
+      if (inFlightResolve.current) {
+        inFlightResolve.current.controller.abort();
+      }
+    };
+  }, []);
+
+  const handleChainMetadataLoaded = useCallback((metadata: ChainMetadata) => {
+    const key = `${metadata.pdb_id.toLowerCase()}|${metadata.chain_id.toUpperCase()}`;
+    setChainMetadataCache(prev => ({ ...prev, [key]: metadata }));
+    setSearchStatus('success');
+    setSearchError(null);
+    
+    negativeCache.current.set(key, {
+      status: 'success',
+      timestamp: Date.now(),
+      metadata
+    });
+  }, []);
+
+  const resolveChainWrapper = useCallback(async (pdb_id: string, auth_asym_id: string): Promise<ChainMetadata> => {
+    const key = `${pdb_id.toLowerCase()}|${auth_asym_id.toUpperCase()}`;
+    
+    // Check if same key as last attempt (prevent duplicate requests)
+    if (key === lastAttemptedKey.current && inFlightResolve.current?.key === key) {
+      throw new Error('Request already in flight');
+    }
+    
+    // Check positive cache first
+    if (chainMetadataCache[key]) {
+      setSearchStatus('success');
+      return chainMetadataCache[key];
+    }
+    
+    // Check negative cache
+    const cachedEntry = negativeCache.current.get(key);
+    if (cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      if (age < NEGATIVE_CACHE_TTL) {
+        if (cachedEntry.status === 'not_found') {
+          setSearchStatus('not_found');
+          setSearchError(cachedEntry.message || `No chain '${auth_asym_id}' found in PDB ${pdb_id.toUpperCase()}. Check the chain ID or entry.`);
+          const error: any = new Error('Chain not found');
+          error.code = 'NOT_FOUND';
+          throw error;
+        } else if (cachedEntry.status === 'error') {
+          setSearchStatus('error');
+          setSearchError(cachedEntry.message || 'Failed to resolve chain');
+          throw new Error(cachedEntry.message || 'Failed to resolve chain');
+        }
+      } else {
+        // TTL expired, remove from cache
+        negativeCache.current.delete(key);
+      }
+    }
+    
+    // Abort previous request if different key
+    if (inFlightResolve.current && inFlightResolve.current.key !== key) {
+      inFlightResolve.current.controller.abort();
+      inFlightResolve.current = null;
+    }
+    
+    // Start new request
+    lastAttemptedKey.current = key;
+    const controller = new AbortController();
+    inFlightResolve.current = { key, controller };
+    
+    setSearchStatus('loading');
+    setSearchError(null);
+    
+    try {
+      const metadata = await proteinApi.resolveChain(pdb_id, auth_asym_id, { signal: controller.signal });
+      
+      // Only update state if not aborted
+      if (inFlightResolve.current?.key === key) {
+        inFlightResolve.current = null;
+      }
+      
+      return metadata;
+    } catch (err: any) {
+      // Ignore aborted requests
+      if (err.name === 'AbortError' || err.name === 'CanceledError') {
+        return Promise.reject(err);
+      }
+      
+      // Clear in-flight if this was our request
+      if (inFlightResolve.current?.key === key) {
+        inFlightResolve.current = null;
+      }
+      
+      // Handle 404 not found
+      if (err.code === 'NOT_FOUND' || err.status === 404) {
+        const message = err.detail || `No chain '${auth_asym_id}' found in PDB ${pdb_id.toUpperCase()}. Check the chain ID or entry.`;
+        negativeCache.current.set(key, {
+          status: 'not_found',
+          timestamp: Date.now(),
+          message
+        });
+        setSearchStatus('not_found');
+        setSearchError(message);
+      } else {
+        // Other errors
+        const message = err.response?.data?.detail || err.message || 'Failed to resolve chain';
+        negativeCache.current.set(key, {
+          status: 'error',
+          timestamp: Date.now(),
+          message
+        });
+        setSearchStatus('error');
+        setSearchError(message);
+      }
+      
+      throw err;
+    }
+  }, [chainMetadataCache]);
+
+  // exptl_method, temp, pH are now included directly in each record from the DB
+  const enrichedData = useMemo(() => dataResponse?.data ?? [], [dataResponse?.data]);
+
+  // Determine if we have an active chain search
+  const hasActiveChainSearch = filters.pdb_id && filters.auth_asym_id;
+  const activeChainKey = hasActiveChainSearch 
+    ? `${filters.pdb_id!.toLowerCase()}|${filters.auth_asym_id!.toUpperCase()}`
+    : null;
+  const activeChainMetadata = activeChainKey ? chainMetadataCache[activeChainKey] : null;
+
+  // Generate resolved label for success message
+  const resolvedLabel = hasActiveChainSearch 
+    ? `Found ${filters.pdb_id!.toUpperCase()} Chain ${filters.auth_asym_id!.toUpperCase()}`
+    : undefined;
+
+  return (
+    <div className="protein-dashboard min-h-screen bg-white">
+      <PageSEO
+        title="MuSProt: Multistate Protein Structure Database"
+        description="Explore 355,731 protein chains from 121,584 PDB entries with pairwise structural comparisons, energy scoring, and CATH functional annotations. Download the full SQLite database."
+        path="/"
+      />
+      <MuSProtJsonLd />
+      {/* Breadcrumb */}
+      <section className="bg-slate-50 py-4 border-b border-gray-200">
+        <div className="max-w-7xl mx-auto px-6 flex items-center justify-between">
+          <nav className="flex items-center gap-2 text-sm">
+            <Link
+              to="/"
+              className="text-slate-600 hover:text-slate-900 transition-colors flex items-center gap-1"
+            >
+              <Home className="w-4 h-4" />
+              Home
+            </Link>
+            <span className="text-slate-900 font-medium">MuSProt: Multistate Protein Database</span>
+          </nav>
+          <div className="flex items-center gap-3">
+            <Link
+              to="/docs"
+              className="flex items-center gap-1.5 px-4 py-1.5 text-sm font-medium text-slate-700 border border-gray-200 rounded-lg hover:border-slate-900 hover:text-slate-900 transition-colors bg-white"
+            >
+              <BookOpen className="w-4 h-4" />
+              Docs
+            </Link>
+            <a
+              href="/api/protein/download/db"
+              download="MuSProt.db"
+              className="flex items-center gap-1.5 px-4 py-1.5 text-sm font-medium text-white bg-slate-900 rounded-lg hover:bg-slate-700 transition-colors"
+            >
+              <Download className="w-4 h-4" />
+              Download DB
+            </a>
+          </div>
+        </div>
+      </section>
+
+      {error && (
+        <div className="max-w-7xl mx-auto px-6 mt-4">
+          <div className="protein-error-banner">
+            <span>⚠️ {error}</span>
+            <button onClick={() => setError(null)}>×</button>
+          </div>
+        </div>
+      )}
+
+      <div className="max-w-7xl mx-auto px-6 py-6">
+        <main className="space-y-6">
+          {hasActiveChainSearch && activeChainMetadata ? (
+            <>
+              {/* First Row: Search + Chain Information (left-right 3:7 split) */}
+              <div className="grid gap-6 items-stretch" style={{ gridTemplateColumns: 'minmax(0, 3fr) minmax(0, 7fr)' }}>
+                <section className="min-w-0 h-full border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+                  <FilterPanel
+                    filterOptions={filterOptions}
+                    filters={filters}
+                    searchInputValue={searchInputValue}
+                    onSearchInputChange={handleSearchInputChange}
+                    onSearchClear={handleSearchClear}
+                    searchStatus={searchStatus}
+                    searchError={searchError}
+                    resolvedLabel={resolvedLabel}
+                    onFiltersChange={handleFiltersChange}
+                    onChainMetadataLoaded={handleChainMetadataLoaded}
+                    resolveChain={resolveChainWrapper}
+                    loading={loadingData}
+                    showResetButton={true}
+                  />
+                </section>
+
+                <section className="min-w-0 h-full flex">
+                  <ErrorBoundary componentName="Chain Information">
+                    <ChainBasicInfoCards metadata={activeChainMetadata} />
+                  </ErrorBoundary>
+                </section>
+              </div>
+
+              {/* Second Row: Sequence, Experimental Conditions, Binders (3 columns, equal height) */}
+              <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6">
+                <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+                  <ErrorBoundary componentName="Sequence Panel">
+                    <SequencePanel metadata={activeChainMetadata} />
+                  </ErrorBoundary>
+                </div>
+                <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+                  <ErrorBoundary componentName="Experimental Conditions">
+                    <ExperimentalConditionsPanel metadata={activeChainMetadata} />
+                  </ErrorBoundary>
+                </div>
+                {activeChainMetadata.nonpolymer_entities && activeChainMetadata.nonpolymer_entities.length > 0 && (
+                  <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+                    <ErrorBoundary componentName="Binders Panel">
+                      <BindersPanel metadata={activeChainMetadata} />
+                    </ErrorBoundary>
+                  </div>
+                )}
+              </div>
+
+              {/* Functions block — full width, between panels and Results */}
+              <ErrorBoundary componentName="Function Panel">
+                <FunctionPanel pdbId={filters.pdb_id!} chainId={filters.auth_asym_id!} />
+              </ErrorBoundary>
+            </>
+          ) : (
+            <>
+              {/* Search Panel Full Width */}
+              <section className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+                <FilterPanel
+                  filterOptions={filterOptions}
+                  filters={filters}
+                  searchInputValue={searchInputValue}
+                  onSearchInputChange={handleSearchInputChange}
+                  onSearchClear={handleSearchClear}
+                  searchStatus={searchStatus}
+                  searchError={searchError}
+                  resolvedLabel={resolvedLabel}
+                  onFiltersChange={handleFiltersChange}
+                  onChainMetadataLoaded={handleChainMetadataLoaded}
+                  resolveChain={resolveChainWrapper}
+                  loading={loadingData}
+                  showResetButton={false}
+                />
+              </section>
+
+              {/* Default Dataset Summary View */}
+              <section className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
+                <StatsPanel stats={summaryStats} loading={loadingStats} />
+              </section>
+
+              <section>
+                <StaticDistributionPlots />
+              </section>
+            </>
+          )}
+
+          {hasActiveChainSearch && (
+            <section className="protein-table-section">
+              <DataTable
+                data={enrichedData}
+                loading={loadingData}
+                total={dataResponse?.total || 0}
+                filtered={dataResponse?.filtered || 0}
+              />
+            </section>
+          )}
+        </main>
+      </div>
+    </div>
+  );
+}

frontend/src/components/datasets/protein/SequencePanel.tsx

@@ -0,0 +1,137 @@
+/**
+ * Sequence display panel for a selected chain
+ * Shows sequence length and sequence with copy/download features
+ */
+import React, { useState } from 'react';
+import { ChainMetadata } from '../../../types/protein';
+import { formatText, formatNumber } from '../../../utils/format';
+
+interface SequencePanelProps {
+  metadata: ChainMetadata | null;
+  isLoading?: boolean;
+}
+
+const SequencePanel: React.FC<SequencePanelProps> = ({ metadata, isLoading }) => {
+  const [copied, setCopied] = useState(false);
+  const [showAll, setShowAll] = useState(false);
+
+  const sequence = metadata?.polymer_entity?.seq_can;
+  const sequenceLength = metadata?.polymer_entity?.sequence_length;
+
+  // Format sequence with line breaks every 60 chars
+  const formatSequence = (seq: string): string[] => {
+    if (!seq) return [];
+    const lines = [];
+    for (let i = 0; i < seq.length; i += 60) {
+      lines.push(seq.substring(i, i + 60));
+    }
+    return lines;
+  };
+
+  const handleCopy = async () => {
+    if (sequence) {
+      try {
+        await navigator.clipboard.writeText(sequence);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+      } catch (err) {
+        console.error('Failed to copy:', err);
+      }
+    }
+  };
+
+  const handleDownload = () => {
+    if (!sequence || !metadata) return;
+
+    const pdbId = formatText(metadata.pdb_id || metadata.entry?.rcsb_id, 'unknown');
+    const chainId = formatText(metadata.chain_id || metadata.polymer_entity_instance?.auth_asym_id, 'X');
+    const title = formatText(metadata.entry?.title, 'Unknown protein');
+    
+    const fasta = `>${pdbId}:${chainId} ${title}\n${sequence}`;
+    const blob = new Blob([fasta], { type: 'text/plain' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `${pdbId}_${chainId}.fasta`;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  if (isLoading) {
+    return (
+      <section className="space-y-4">
+        <h3 className="text-xl font-semibold text-slate-900">Amino Acid Sequence</h3>
+        <div className="text-center py-10 text-slate-600">Loading sequence...</div>
+      </section>
+    );
+  }
+
+  if (!sequence) {
+    return (
+      <section className="space-y-4">
+        <h3 className="text-xl font-semibold text-slate-900">Amino Acid Sequence</h3>
+        <div className="text-center py-10 text-slate-600">No sequence data available</div>
+      </section>
+    );
+  }
+
+  const lines = formatSequence(sequence);
+  const displayLines = showAll ? lines : lines.slice(0, 10);
+  const hasMore = lines.length > 10;
+  const formattedLength = formatNumber(sequenceLength, { decimals: 0 });
+
+  return (
+    <section className="space-y-4">
+      {/* Header + Actions */}
+      <div className="flex justify-between items-start">
+        <div>
+          <h3 className="text-xl font-semibold text-slate-900 mb-1">Amino Acid Sequence</h3>
+          {formattedLength !== '—' && (
+            <div className="text-sm text-slate-600">
+              <span className="font-medium">{formattedLength}</span> residues
+            </div>
+          )}
+        </div>
+        <div className="flex gap-2">
+          <button
+            className="inline-flex items-center gap-1.5 px-3 py-1.5 border border-gray-300 text-slate-900 font-medium rounded-lg hover:bg-slate-50 transition-colors text-xs"
+            onClick={handleCopy}
+            title="Copy to clipboard"
+          >
+            {copied ? '✓' : '📋'}
+          </button>
+          <button
+            className="inline-flex items-center gap-1.5 px-3 py-1.5 bg-slate-900 text-white font-medium rounded-lg hover:bg-slate-800 transition-colors text-xs"
+            onClick={handleDownload}
+            title="Download FASTA"
+          >
+            ⬇ FASTA
+          </button>
+        </div>
+      </div>
+      
+      {/* Sequence Display */}
+      <div className="bg-slate-50 border border-slate-200 rounded-lg p-4 font-mono text-xs max-h-80 overflow-y-auto">
+        {displayLines.map((line, idx) => (
+          <div key={idx} className="flex mb-1 leading-relaxed">
+            <span className="text-gray-400 mr-4 min-w-[50px] text-right select-none">{idx * 60 + 1}</span>
+            <span className="text-gray-800 tracking-wide break-all">{line}</span>
+          </div>
+        ))}
+      </div>
+
+      {hasMore && (
+        <div className="text-center">
+          <button
+            className="inline-flex items-center gap-2 px-4 py-2 border border-gray-300 text-slate-900 font-medium rounded-lg hover:bg-slate-50 transition-colors text-sm"
+            onClick={() => setShowAll(!showAll)}
+          >
+            {showAll ? '▲ Show less' : `▼ Show all (${lines.length - 10} more lines)`}
+          </button>
+        </div>
+      )}
+    </section>
+  );
+};
+
+export default SequencePanel;

frontend/src/components/datasets/protein/StaticDistributionPlots.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+
+const IMG_BASE = '/api/protein/plots';
+const CACHE_BUST = '?v=20260527';
+
+const plots = [
+  { name: 'Structure Similarity', file: 'TM-RMSD.png' },
+  { name: 'TM-Align Distribution', file: 'TM-Dis.png' },
+  { name: 'RMSD Distribution', file: 'RMSD-Dis.png' },
+  { name: 'State Distribution', file: 'States-Dis.png' },
+  { name: 'Sequence Length Distribution', file: 'Seq-Len.png' },
+  { name: 'Function Rank Correlation vs. Structure Similarity', file: 'Func_rank.png' },
+];
+
+export const StaticDistributionPlots: React.FC = () => {
+  return (
+    <div style={{ columns: '400px', columnGap: '1.5rem' }}>
+      {plots.map(({ name, file }) => (
+        <div
+          key={file}
+          style={{ breakInside: 'avoid', marginBottom: '1.5rem' }}
+          className="border border-gray-200 rounded-2xl bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300 overflow-hidden"
+        >
+          <div className="px-4 pt-5 pb-2 text-xl font-semibold text-slate-900">{name}</div>
+          <div className="px-4 pb-4">
+            <img
+              src={`${IMG_BASE}/${file}${CACHE_BUST}`}
+              alt={name}
+              style={{ width: '100%', height: 'auto', display: 'block' }}
+            />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};

frontend/src/components/datasets/protein/StatsPanel.css

@@ -0,0 +1,52 @@
+.stats-panel {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 15px;
+  padding: 0;
+}
+
+.stat-card {
+  background: white;
+  padding: 20px;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  text-align: center;
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.stat-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+.stat-value {
+  font-size: 2rem;
+  font-weight: 700;
+  color: #2196f3;
+  margin-bottom: 5px;
+}
+
+.stat-label {
+  font-size: 0.9rem;
+  color: #666;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.stats-loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100px;
+  color: #888;
+  font-size: 1.1rem;
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+@media (max-width: 768px) {
+  .stats-panel {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}

frontend/src/components/datasets/protein/StatsPanel.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import type { SummaryStats } from '../../../types/protein';
+import './StatsPanel.css';
+
+interface StatsPanelProps {
+  stats: SummaryStats | null;
+  loading: boolean;
+}
+
+export const StatsPanel: React.FC<StatsPanelProps> = ({ stats, loading }) => {
+  if (loading || !stats) {
+    return null;
+  }
+
+  return (
+    <div className="stats-panel">
+      <div className="stat-card">
+        <div className="stat-value">{stats.total_records.toLocaleString()}</div>
+        <div className="stat-label">Total Records</div>
+      </div>
+      
+      <div className="stat-card">
+        <div className="stat-value">{stats.unique_chains.toLocaleString()}</div>
+        <div className="stat-label">Unique Chains</div>
+      </div>
+      
+      <div className="stat-card">
+        <div className="stat-value">{stats.avg_rmsd.toFixed(2)} Å</div>
+        <div className="stat-label">Avg RMSD</div>
+      </div>
+      
+      <div className="stat-card">
+        <div className="stat-value">{stats.avg_tm_score.toFixed(3)}</div>
+        <div className="stat-label">Avg TM-score</div>
+      </div>
+      
+      <div className="stat-card">
+        <div className="stat-value">{Math.round(stats.avg_sequence_length)}</div>
+        <div className="stat-label">Avg Length</div>
+      </div>
+    </div>
+  );
+};

frontend/src/components/layout/Footer.tsx

@@ -0,0 +1,25 @@
+import { Database } from 'lucide-react';
+
+export function Footer() {
+  return (
+    <footer className="bg-slate-900 text-white mt-12">
+      <div className="max-w-7xl mx-auto px-6 py-8 flex flex-col md:flex-row gap-4 items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Database className="w-5 h-5" />
+          <span className="font-semibold">MuSProt</span>
+        </div>
+        <p className="text-sm text-slate-400">
+          Multistate protein structures, pairwise comparisons, energy scores, and functional annotations.
+        </p>
+        <a
+          href="https://huggingface.co/spaces/wenruifan/MuSProt"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-sm text-slate-400 hover:text-white transition-colors"
+        >
+          Hosted on Hugging Face
+        </a>
+      </div>
+    </footer>
+  );
+}

frontend/src/components/layout/Header.tsx

@@ -0,0 +1,50 @@
+import { BookOpen, Database, Download } from 'lucide-react';
+import { Link, useLocation } from 'react-router-dom';
+
+export function Header() {
+  const location = useLocation();
+
+  return (
+    <header className="border-b border-gray-200 bg-white sticky top-0 z-50 shadow-sm">
+      <div className="max-w-7xl mx-auto px-6 py-4 flex items-center justify-between gap-6">
+        <Link to="/" className="flex items-center gap-3 hover:opacity-80 transition-opacity">
+          <div className="w-9 h-9 bg-slate-900 rounded-lg flex items-center justify-center">
+            <Database className="w-5 h-5 text-white" />
+          </div>
+          <div>
+            <div className="text-xl font-semibold text-slate-900">MuSProt</div>
+            <div className="text-xs text-slate-500">Multistate Protein Structure Database</div>
+          </div>
+        </Link>
+
+        <nav className="flex items-center gap-2">
+          <Link
+            to="/"
+            className={`flex items-center gap-1.5 px-3 py-2 text-sm rounded-lg transition-colors ${
+              location.pathname === '/' ? 'bg-slate-100 text-slate-900 font-semibold' : 'text-slate-600 hover:bg-slate-50'
+            }`}
+          >
+            <Database className="w-4 h-4" />
+            Explorer
+          </Link>
+          <Link
+            to="/docs"
+            className={`flex items-center gap-1.5 px-3 py-2 text-sm rounded-lg transition-colors ${
+              location.pathname === '/docs' ? 'bg-slate-100 text-slate-900 font-semibold' : 'text-slate-600 hover:bg-slate-50'
+            }`}
+          >
+            <BookOpen className="w-4 h-4" />
+            Docs
+          </Link>
+          <a
+            href="/api/protein/download/db"
+            className="flex items-center gap-1.5 px-4 py-2 text-sm font-medium text-white bg-slate-900 rounded-lg hover:bg-slate-700 transition-colors"
+          >
+            <Download className="w-4 h-4" />
+            Download DB
+          </a>
+        </nav>
+      </div>
+    </header>
+  );
+}