GenoBank.io

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the GenoBank.io frontend repository - a Jekyll-based static website that serves as the main interface for GenoBank’s genomic data platform. It integrates with multiple GenoBank microservices via Web3 authentication and provides user dashboards, laboratory interfaces, and biosample management.

Essential Commands

Local Development

# Install Jekyll dependencies
bundle install

# Run Jekyll development server
bundle exec jekyll serve

# For live development with hot reload (requires VS Code Live Server extension)
# Visit http://127.0.0.1:5500/

Test/Staging Environment

# Access test environment locally
# http://127.0.0.1:5500/test/

# Test activation flow with sample data
# http://127.0.0.1:5500/activate/?biosampleId=60&laboratoryId=2&secret=67d6516e1229eee318e5032776377b639f1c2ee2fe93531164bf5706d56fdcf1#1940837240937409237

Building User Dashboard (test/user)

cd test/user
npm install
npm start          # Runs gulp watch with BrowserSync
gulp build         # Build CSS/JS

High-Level Architecture

Environment Configuration

The site uses a dynamic environment configuration system (js/env.js):

• Automatically detects test vs production based on URL path
• Test environment: URLs starting with /test/
• API endpoints switch between staging and production automatically

Key environment variables:

window.API_BASE = test ? 'https://staging.genobank.app' : 'https://genobank.app'
window.MESSAGE_TO_SIGN = "I want to proceed"
window.MAGIC_API_KEY = "pk_live_5F9630468805C3A0"  // Google OAuth

Authentication Architecture

The site supports three authentication methods, all converging to Web3 signatures:

1. MetaMask: Traditional Web3 wallet
2. BioWallet: GenoBank’s custom wallet (feature branch)
   • Detected via window.ethereum.isBioWallet === true
   • Auto-signs “I want to proceed” message
   • Extension ID: eohejafelpaeejocncecjofhjmgflahn
3. Magic (Google OAuth): For non-crypto users

Authentication flow:

1. User signs message with chosen method
2. Signature and wallet address stored in localStorage
3. All API calls include user_signature parameter
4. Backend validates signature to authenticate requests

API Integration Pattern

All GenoBank microservices use consistent Web3 authentication:

// Standard API call pattern
fetch(`${window.NEW_API_BASE}/endpoint?user_signature=${localStorage.getItem('user_sign')}`)

// Common endpoints
/recover                 // Get wallet from signature
/get_owner_details      // User profile
/get_user_files         // User's biofiles
/validate_permittee     // Check permissions

Key User Interfaces

1. Dashboard (/consent/biofile/)
   • File management and sharing
   • BioNFT™ viewing
   • Lab connections
2. Lab Dashboard (/consent/lab_biofile/)
   • Laboratory-specific interface
   • Biosample management
   • Certificate generation
3. Activation Flow (/activate/)
   • DNA kit activation
   • Multi-step wizard
   • Partner-specific flows (e.g., /activate-somos/)
4. Certificate System (/certificates/)
   • Blockchain-verified certificates
   • QR code generation
   • Multi-language support

File Structure Conventions

genobank.io/
├── _layouts/              # Jekyll layouts (base.html, default.html)
├── _includes/             # Reusable components
├── js/                    # Shared JavaScript
│   ├── env.js            # Environment configuration
│   └── web3-functions.js # Web3 utilities
├── css/                   # Global styles
└── [feature]/            # Feature-specific directories
    ├── index.html        # Main page
    └── [feature].js      # Feature-specific JS

CDN and Security Requirements

All external resources must include integrity hashes:

<script src="https://cdn.jsdelivr.net/..." 
        integrity="sha384-..." 
        crossorigin="anonymous"></script>

Calculate integrity hash:

wget http://domain.com/resource.js
cat resource.js | openssl dgst -sha256 -binary | openssl base64 -A

Critical Development Rules

1. Always Create Backups

Before modifying any file, especially in login functionality:

cp file.js file.js.bkp.$(date +"%m%d%Y")

2. BioWallet Integration Requirements

• Must set window.ethereum.isBioWallet = true
• Must set window.ethereum.isMetaMask = false
• Support only Story Protocol and Avalanche networks
• No hardcoded wallet addresses

3. Web3 Authentication

• All API calls must include user_signature
• Use checksummed addresses (EIP-55)
• Store credentials in localStorage, not sessionStorage

4. Testing Checklist

• Test with MetaMask, BioWallet, and Google OAuth
• Verify signature validation
• Check error handling and user feedback
• Test in both production and test environments

Deployment

The site is deployed via GitHub Pages with GitHub Actions:

• Production (master): https://genobank.io/
• Staging (dev): https://genobank.io/dev/

Changes pushed to master or dev branches automatically deploy via the GitHub Actions workflow defined in CONTRIBUTING.md.

Working with Test Environment

The test environment (/test/ path) provides:

• Connection to staging API
• Test blockchain network (Avalanche Testnet)
• Red banner indicating test mode
• Separate localStorage namespace

To develop features:

1. Work in /test/ directory first
2. Test thoroughly with staging API
3. Move to production path when ready
4. Ensure environment detection works correctly

Common API Response Patterns

GenoBank APIs typically return:

{
  "success": true/false,
  "data": {...},
  "message": "Human readable message"
}

Always check success field before processing data.

Browser Support

Target modern browsers with ES6+ support:

• Chrome/Edge 80+
• Firefox 75+
• Safari 13+

Use CDN polyfills for older browser support when necessary.