StructBind — Offline-First Protein Structure, Binding-Pocket & Molecular Docking Workbench

An offline-first computational biology and bioinformatics desktop web application for macromolecular structure visualization, geometric binding pocket detection, ligand preparation, receptor parameterization, AutoDock Vina docking, and standalone scientific report generation.

---

🌟 Offline-First Architecture

StructBind is designed to operate 100% locally on your computer without requiring an active internet connection for core scientific workflows:

1. Local Loopback Security (127.0.0.1): The FastAPI server strictly binds to loopback interface by default to prevent unauthorized external network access.
2. Local SQLite Database: Structures, ligands, binding pockets, docking jobs, and scientific reports are stored in local SQLite (data/app.db).
3. Offline Scientific Engines:
   • Gemmi (v0.7.5): High-performance local macromolecular parser for PDB and mmCIF coordinate files, atom/residue extraction, and chain analysis.
   • RDKit (v2026.03.6): Offline cheminformatics for parsing SMILES, SDF, MOL, computing physicochemical descriptors, and ETKDGv3 3D conformer embedding.
   • Meeko (v0.8.0): Local preparation of small molecules into PDBQT format with Gasteiger partial charges.
   • Alpha-Sphere Geometric Cavity Detector: Mathematical binding pocket identification running entirely in local memory.
   • AutoDock Vina (Optional): Built-in environment auditor that automatically detects vina executable or Python bindings; never fabricates fake scores if unavailable.
4. Progressive Web App (PWA) Shell:
   • Custom Service Worker (sw.js) precaches the application shell and static bundles.
   • Web App Manifest (manifest.webmanifest) with standalone display mode and dedicated branding icons.
   • Offline fallback page (offline.html) when network connectivity is disrupted.
   • In-app telemetry indicator displaying real-time database, engine, and network status.
5. Standalone Report Generator: Compiles self-contained reports in HTML (with @media print 1-click Save-as-PDF styling), Markdown, and JSON.

---

🚀 Desktop Quick Start

1. One-Click Windows Launcher (Recommended)

Double-click start_structbind.bat in the project root:

start_structbind.bat

This automatically detects Python, validates the environment, boots the local FastAPI server, mounts the pre-compiled frontend, and opens http://127.0.0.1:8000 in your default browser.

2. Python Desktop Launcher

# Launch server and automatically open browser
python run_offline.py

# Or specify custom port without opening browser
python run_offline.py --port 8000 --no-browser

3. Compiling Standalone Windows Executable (StructBind.exe)

You can compile StructBind into a single, standalone Windows .exe that bundles the Python runtime, FastAPI backend, scientific libraries, and pre-built React frontend:

1. Double-click build_exe.bat (or run pyinstaller --clean structbind.spec).
2. The standalone binary will be created at dist\StructBind.exe.
3. Running StructBind.exe boots the local offline server, mounts the frontend, persists local databases to data/app.db, and opens the user's browser.

4. Installing as a Desktop App (PWA)

1. Open http://127.0.0.1:8000 in Google Chrome or Microsoft Edge.
2. Click the "Install StructBind App" button in the top navigation status bar, or click the browser install icon in the URL bar.
3. StructBind will install as a standalone desktop window on your taskbar/desktop with its own window frame and icon.

---

📊 Offline vs. Online Capability Matrix

Feature	Offline Mode (Local Only)	Online Mode (Internet Active)
Protein Structure Viewing (Mol 3D)*	✅ Full (Local PDB/mmCIF files & cached structures)	✅ Full (RCSB PDB live download & caching)
Local Structure Library	✅ 100% Offline (SQLite + Gemmi parsing)	✅ Full
Binding Pocket Detection	✅ Full (Built-in Alpha-Sphere geometric cavity engine)	✅ Full
Ligand Management	✅ 100% Offline (SMILES parsing, SDF/MOL import)	✅ Full + PubChem live search
Ligand 3D Conformer Generation	✅ Full (RDKit ETKDGv3 & MMFF94 force field)	✅ Full
Receptor & Ligand PDBQT Prep	✅ Full (Gemmi + Meeko + Gasteiger charges)	✅ Full
Molecular Docking	✅ Real calculation if AutoDock Vina installed locally	✅ Real calculation if AutoDock Vina installed locally
Scientific Report Generation	✅ Full (HTML printable to PDF, Markdown, JSON)	✅ Full
UniProt & PubMed Search	⚠️ Cached entries only	✅ Live remote search

---

🔬 Scientific Workflows

1. Local Protein Structure Library (HomePage & ProteinAnalysisPage)

• Import experimental structure files (.pdb, .cif, .mmcif, .ent) up to 15 MB.
• Inspect total atoms, residues, resolution, chains, and experimental methods offline.
• 1-click launch into the interactive Mol* 3D viewer or Binding Pocket detector.

2. Binding Pocket Detection (BindingPocketPage)

• Detects candidate binding cavities and drugability scores.
• Renders 3D cavity points and bounding boxes in Mol*.
• Displays participating amino acid residues with chain identifiers and sequence positions.
• Results are automatically archived in SQLite PocketRecord for offline docking grid calculation.

3. Ligand Preparation (LigandPage)

• Local Library: Browse and manage stored small molecules.
• SMILES & SDF Import: Validates chemical structures, detects heavy atoms, rotatable bonds, LogP, and H-bond donors/acceptors.
• 3D Conformer Embedding: Generates 3D coordinates via RDKit ETKDGv3 and performs MMFF94 energy minimization.
• PDBQT Generation: Adds polar hydrogens, assigns Gasteiger partial charges, and outputs Meeko PDBQT files ready for docking.

4. Molecular Docking Workbench (DockingPage)

• Environment Audit: Honest inspection of AutoDock Vina availability (checks PATH and Python module).
• Search Grid Configuration: Interactive center coordinates [X, Y, Z], box dimensions [Size X, Size Y, Size Z] in Angstroms, exhaustiveness, num modes, and energy range.
• Job Management: Launch local docking calculations, review binding affinity scores (kcal/mol), and download pose files (.pdbqt).

5. Molecular Dynamics Simulation (MDSimulationPage)

• OpenMM & GROMACS Integration: Dynamic force field preparation (AMBER14, CHARMM36, GAFF2) with explicit TIP3P solvent box and physiological ion neutralization.
• Minimization & Equilibration: Multi-stage NVT/NPT thermodynamic equilibration with temperature, pressure, and energy logging.
• Trajectory Analysis: RMSD, RMSF, Radius of Gyration (Rg), hydrogen bond kinetics, and Mol* trajectory playback.
• Educational Interpretation Panel: Interactive parameter guides, physics timelines, and structural stability summaries.

6. Scientific Report Generator (ReportPage)

• Select sections to include: Protein Metadata, Pocket Geometry, Receptor Preparation, Ligand Preparation, Docking Affinities, MD Trajectories, and Software Versions.
• Standalone HTML export: Includes embedded responsive CSS and @media print rules for clean, 1-click Save as PDF via browser print (Ctrl+P).
• Markdown and JSON exports for computational reproducibility.

---

⚙️ Development & Testing

Run Backend Tests (Pytest)

# Run complete test suite (74 tests)
py -3 -m pytest tests/ backend/tests/ -v

Compile Frontend Production Bundle

cd frontend
npm run build

---

🔒 Security Architecture

• Loopback Enforcement: Local backend binds to 127.0.0.1 to prevent remote execution on local networks.
• Path Traversal Defense: All file paths are strictly validated through validate_safe_path() against canonical application data directories (ALLOWED_BASE_DIRS). Relative path traversal sequences (../, ..\) are rejected with HTTP 400.
• Filename Sanitization: Uploaded filenames are sanitized through sanitize_filename() to remove dangerous characters and path separators.
• Upload Size Limits: Enforced 15 MB cap on macromolecular structure uploads.

---

📄 License & Attribution

StructBind is built with React, TypeScript, Vite, Tailwind CSS, FastAPI, SQLite, Gemmi, RDKit, Meeko, and Mol* Viewer.