Developer guide

Use this section to understand how MolSysViewer is built. You also use it as the source of truth for contributor workflows and docs style.

Getting started

• Getting started
• Developer setup
  • Requirements
  • Recommended Node installation (NVM)
  • Python environment
  • TypeScript environment
  • Typical dev loop
  • Tests
  • Using Codex or other AI tools (optional)
  • Documentation workflow
  • Troubleshooting
• Repository structure
  • Top-level layout
  • Python package (molsysviewer/)
  • TypeScript runtime (molsysviewer/js/)
  • Generated artifacts
  • Legacy path mapping
• Configuration (Python)
  • What belongs here
  • Cross-links
• Demo systems
  • Where they live
  • Why this matters
  • Recommended usage
• Contributing
  • Basic workflow
  • What to include in a PR
  • What to avoid
  • Issues
• CI and automation
  • CI entry points
  • What you run locally
  • Placeholder

Architecture

• MolSysViewer Concepts (Python ↔ AnyWidget ↔ Mol* ↔ WebGL)
  • Layers and roles
  • Message flow (Python → JS → Mol* → WebGL)
  • Why MolSysViewer (vs. raw Mol*)
  • Shape philosophy (API → Mol* → WebGL)
  • Key components
• Public API and stability
  • Public Python API
  • Internal Python APIs
  • Python ↔ TypeScript contracts
  • Exports (HTML lite)
• Protocol and payloads (Python ↔ TypeScript)
  • ViewerMessage protocol
  • MolSys payload schema (Python → JS)
  • JS → Python events
  • Tags and registries
• Architecture
• Architecture (full)
  • Layers and responsibilities
  • Core data model
  • Data flow
  • Visibility model
  • Regions, layers, and whole
  • Shapes pipeline
  • Popup (popout) architecture
  • Trajectory controls
  • Implementation notes (detailed)
• Regions and layers
  • Naming and concepts
  • Python API (sketch)
  • JS responsibilities
  • Visibility (global vs regions vs viewer)
  • Global presets and tags: collision risk
  • Ideas
• Debugging
  • Python-side checks
  • Frontend logs
  • Message-level debugging
  • Popup / popout sync
  • Placeholder

Workflow

• JS/TS workflow
  • Source of truth
  • Install and build
  • Test
  • Debug
• Testing & QA
• Warnings (planned)
  • Goals
  • Proposed structure
  • Candidate categories
  • What should warn (examples)
  • Testing (planned)
• Releasing and publishing
  • Versioning
  • JS runtime (npm)
  • Python packages (pip/conda)
  • Pre-releases

Documentation

• Documentation
• Docs workflow (local build and RTD parity)
  • Before you build
  • Build locally
  • Review locally
  • Notebook outputs
  • RTD parity checklist
• Documentation for the web
  • Web documentation editorial guidelines
  • Web docs build & layout
  • MyST in MolSysViewer documentation
  • References and Cross-links in Documentation
• API documentation guidelines
  • Docstrings
  • Doctests

Style

• Coding style & conventions
• Type annotations (Python ≥3.10)
• String and quotation style
  • Policy
  • Why this is safe

Planning and history

• Roadmap
• MolSysViewer — ROADMAP (Unified and Definitive)
• Phase 0 — Architecture Reset (Completed)
  • Achievements
• Phase 1 — Core Features (Active)
  • 1. Molecule Input
  • 2. Shape System (v1)
  • 3. Scene Management (v1)
• Phase 1.5 — Immediate Next Steps
  • Shape Grouping
  • New Shape Primitives
  • Camera Utilities
  • Rendering Engine Enhancements
• Phase 2 — Integration with the uibcdf Ecosystem
  • TopoMT Integration
  • PharmacophoreMT Integration
  • MolSysMT Integration
• Phase 3 — UX / UI Enhancements
• Phase 4 — Structure Module
  • Numerical Functions (get_*)
  • Visual Functions (show_*)
• Phase 5 — Hbonds & Topology Module
  • Hydrogen Bonds
  • Topology
• Phase 6 — Advanced Shape Primitives
• Phase 7 — Engines & Performance
  • Multi-Engine Support
  • Benchmarking Suite
• Phase 8 — Documentation, Tests & Demos
• Long-Term Vision
• Legacy Notes
• Current Status (Summary)
• Changes notes
• Future (index)
  • CI roadmap (future)
  • Performance notes (future)
  • Security (future)
• Appendix
  • Historical documents