Hashi - ChimeraX Web Integration

Overview

Hashi is a web application that integrates with UCSF ChimeraX to provide molecular visualization and analysis capabilities through a browser interface. The name "Hashi" (橋) means "bridge" in Japanese, representing the connection between ChimeraX's powerful molecular visualization capabilities and the web.

The project follows a three-tier architecture:

React Frontend - User interface with WebGL visualization and fallback mechanisms
Node.js Backend - API endpoints and ChimeraX process management
ChimeraX Engine - Headless processes for molecular operations

Hashi enables users to:

Visualize molecular structures from various file formats (PDB, SDF, MOL, CIF, XYZ) with robust fallback mechanisms
Run ChimeraX commands via a web interface
Manage user sessions with up to 10 concurrent ChimeraX instances
Generate high-quality snapshots and movies for visualization
Configure camera, lighting, and style settings for molecular rendering
Interact with molecular structures remotely
Save and manage molecular structures, sessions, and projects in a database
Organize structures with tags and metadata
Track version history of molecular structures and sessions

Quick Start with Docker

The fastest way to get Hashi running is with Docker:

# Clone the repository
git clone https://github.com/gomesgroup/hashi.git
cd hashi

# Configure environment (minimum required)
cp .env.example .env
# Edit .env to set CHIMERAX_PATH to your ChimeraX installation

# Start containers
docker-compose up -d

# Access the application
open http://localhost:3000

Project Structure

/hashi
  /src
    /client            # React frontend 
      /components      # Reusable UI components
        /MolecularViewer.tsx    # Three.js based 3D renderer
        /StructureRenderer.tsx  # Multi-mode renderer with fallbacks
        /StructurePlaceholder.tsx # Placeholder component
        /EnhancedViewerControls.tsx # Controls with fallback support
      /contexts        # React contexts for state management
      /hooks           # Custom React hooks
        /useChimeraX.ts         # ChimeraX interaction hook
        /useStructure.ts        # Structure data handling
      /pages           # Top-level page components
        /StructureViewer.tsx    # Structure viewing page with fallbacks
      /services        # API client services
        /chimeraxService.ts     # ChimeraX API client
        /structureService.ts    # Structure data service
      /styles          # Global styles
      /types           # TypeScript type definitions
      /utils           # Utility functions
      /App.tsx         # Main application component
      /index.html      # HTML entry point
      /main.tsx        # Application entry point
    /server            # Node.js backend
      /controllers     # Route controllers
      /middlewares     # Express middlewares
      /services        # Business logic
      /utils           # Utility functions
      /models          # Data models
      /routes          # API route definitions
      /config          # Configuration
      /types           # TypeScript types
      /validation      # Input validation schemas
    /fileHandling      # File handling system
    /shared            # Shared code between client and server
  /tests               # Test files
  /docs                # Documentation
  /.github             # GitHub workflows
  /monitoring          # Monitoring configuration (Prometheus, Grafana, ELK)
  /scripts             # Deployment and utility scripts

Installation

Docker Deployment (Recommended)

Clone the repository

git clone https://github.com/gomesgroup/hashi.git
cd hashi

Configure environment

cp .env.example .env
# Edit .env with your configuration

Validate configuration

npm install
node scripts/validate-env.js

Start containers
```
docker-compose up -d
```
Access Hashi at http://localhost:3000

Manual Installation

Clone the repository

git clone https://github.com/gomesgroup/hashi.git
cd hashi

Install dependencies
```
npm install
```

Configure environment

cp .env.example .env
# Edit .env with your configuration

Build the application
```
npm run build
```
Start the server
```
npm start
```

Development Setup

Clone the repository

git clone https://github.com/gomesgroup/hashi.git
cd hashi

Install dependencies
```
npm install
```

Configure environment

cp .env.example .env
# Edit .env with your configuration
# Make sure to set CHIMERAX_PATH to your ChimeraX installation

Start development servers
```
npm run dev
```

Test ChimeraX connectivity

# Run the simplified development server for testing ChimeraX integration
node dev-server.js

# In another terminal, test the ChimeraX connection
curl http://localhost:4000/api/chimerax/status

# Start ChimeraX process
curl -X POST http://localhost:4000/api/chimerax/start

# Send a command to ChimeraX
curl -X POST -H "Content-Type: application/json" \
  -d '{"command": "open 1abc"}' \
  http://localhost:4000/api/chimerax/command

Production Deployment

For production deployment, we recommend using Docker with appropriate security configurations:

Use a reverse proxy (Nginx/Apache) with SSL termination
Configure environment variables for production:
- Set NODE_ENV=production
- Use a PostgreSQL database
- Configure a strong JWT secret
- Set up appropriate rate limits

Available Scripts

npm run dev - Start both backend and frontend development servers with hot reloading
npm run dev:server - Start only the backend development server
npm run dev:client - Start only the frontend development server
npm run build - Build both backend and frontend for production
npm run build:server - Build only the backend for production
npm run build:client - Build only the frontend for production
npm start - Run the production build
npm test - Run tests
npm run lint - Run linting
npm run format - Format code using Prettier

Monitoring & Observability

Hashi comes with a complete monitoring stack:

Start monitoring services:

docker-compose --profile monitoring up -d

Access monitoring dashboards:
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3002 (default: admin/admin)
- Kibana: http://localhost:5601

Documentation

User Documentation

Getting Started
Structure Visualization
Rendering Fallback Mechanisms
File Management

Administrator Documentation

Installation Guide
Configuration Options
Security Hardening
Backup & Recovery

API Documentation

API Overview
Authentication
Sessions API
Structures API
Error Handling System
Authentication API
Structure Modification API
Structure Retrieval API
Security Implementation

Development Documentation

Architecture Overview
Contributing Guidelines
Testing Guide
ChimeraX Integration

Rendering Fallback Mechanisms

Hashi implements a robust three-tiered fallback mechanism for molecular visualization:

ChimeraX Server Rendering (Primary): Uses ChimeraX's powerful rendering capabilities with OSMesa for offscreen rendering
Three.js WebGL Rendering (First Fallback): Provides client-side 3D visualization using Three.js when ChimeraX rendering is unavailable
Static Image Fallback (Second Fallback): Sources pre-rendered images from RCSB PDB and other molecular databases when neither interactive option is available

This approach ensures users have access to molecular visualizations regardless of server configuration or client device capabilities. The system automatically detects the best available rendering method and transitions seamlessly between them.

Testing

The project has a comprehensive testing suite including unit tests, integration tests, end-to-end tests, performance tests, and security tests. All tests are fully integrated with CI/CD.

Test Commands

# Run all tests with Jest
npm test

# Run specific test types
npm run test:backend     # Run backend unit and integration tests
npm run test:client      # Run React component tests
npm run test:security    # Run security-focused tests
npm run test:e2e         # Run Playwright end-to-end tests
npm run test:perf        # Run K6 performance tests

# Run all test types in sequence
npm run test:all

# Generate test coverage report
npm run test:coverage

# Run OSMesa-specific tests
npm test -- -t "OSMesa"

Testing OSMesa and ChimeraX

The project includes specialized tests for ChimeraX integration and OSMesa rendering:

Dependency Verification: Run ./scripts/verify-dependencies.sh to check if ChimeraX and OSMesa are properly installed and configured.

Mock Environment Testing: Use the ChimeraXMockUtil to simulate different environments:

import ChimeraXMockUtil, { ChimeraXEnvironment } from './tests/mocks/chimeraxMock';

// Test with OSMesa available
ChimeraXMockUtil.setEnvironment(ChimeraXEnvironment.FULL_RENDERING);

// Test without OSMesa
ChimeraXMockUtil.setEnvironment(ChimeraXEnvironment.NO_OSMESA);

// Test without ChimeraX
ChimeraXMockUtil.setEnvironment(ChimeraXEnvironment.NO_CHIMERAX);

Fallback Testing: Test visualization fallback mechanisms for scenarios where OSMesa rendering is unavailable.

For detailed information on testing OSMesa integration, see:

OSMesa Testing Strategy
Debugging OSMesa

Contributing

Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

UCSF ChimeraX team for their powerful molecular visualization software
Gomes Group for the project vision and support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Hashi - ChimeraX Web Integration

Overview

Quick Start with Docker

Project Structure

Installation

Docker Deployment (Recommended)

Manual Installation

Development Setup

Production Deployment

Available Scripts

Monitoring & Observability

Documentation

User Documentation

Administrator Documentation

API Documentation

Development Documentation

Rendering Fallback Mechanisms

Testing

Test Commands

Testing OSMesa and ChimeraX

Contributing

License

Acknowledgments

Files

README.md

Latest commit

History

README.md

File metadata and controls

Hashi - ChimeraX Web Integration

Overview

Quick Start with Docker

Project Structure

Installation

Docker Deployment (Recommended)

Manual Installation

Development Setup

Production Deployment

Available Scripts

Monitoring & Observability

Documentation

User Documentation

Administrator Documentation

API Documentation

Development Documentation

Rendering Fallback Mechanisms

Testing

Test Commands

Testing OSMesa and ChimeraX

Contributing

License

Acknowledgments