DeepPhe Visualizer v2

A modern React application for medical data visualization and analysis, built with Material-UI and CRACO. DeepPhe Visualizer v2 is the next-generation visualization tool for cancer phenotype extraction and analysis.

Prerequisites

• Node.js 18.x or higher
• npm 8.x or higher

Installation

# Clone the repository
git clone https://github.com/DeepPhe/DeepPhe-Visualizer-v2.git
cd DeepPhe-Visualizer-v2

# Install dependencies
npm install --legacy-peer-deps

# Start development server
npm start

The application will open at http://localhost:3000

Available Scripts

Development

npm start                # Start development server on port 3000
npm run dev              # Alias for npm start

Testing

npm test                 # Run tests in watch mode
npm test -- --coverage   # Run tests with coverage report
npm run lint             # Run ESLint on source files
npm run lint:a11y        # Run accessibility-focused ESLint checks

Production

npm run build            # Create production build
npm run eject            # Eject from react-scripts (one-way operation)

User documentation

The task-oriented user guide is built with Docusaurus in an isolated docs-site/ package. Node.js 20 or later is required for documentation builds.

npm run docs:install     # Install the isolated documentation dependencies
npm run docs:start       # Preview the guide locally
npm run docs:build       # Generate the static guide in site/
npm run docs:pdf         # Export the printable guide PDF
npm run docs:generate    # Generate the feature guide: capture screenshots, build the site, export the PDF

Docker Deployment

# Build and run with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

# Stop the stack
docker compose down

Manual Docker commands:

# Build image
docker build -t deepphe-visualizer-v2 .

# Run container
docker run -d -p 3000:3000 --name deepphe-visualizer-v2 deepphe-visualizer-v2

# View logs
docker logs -f deepphe-visualizer-v2

# Stop and remove
docker stop deepphe-visualizer-v2 && docker rm deepphe-visualizer-v2

Standalone Executable

The app can be packaged into a single self-contained executable (no Node.js required on the target machine) with @yao-pkg/pkg. The binary serves the built SPA, mounts the read-only piper-files API, and reverse-proxies the DeepPhe data API to a runtime-configurable upstream.

# Build the web bundle (same-origin API base) and package all targets
npm run package

Output binaries are written to dist/ (one per platform): deepphe-visualizer-v2-macos-arm64, -macos-x64, -linux-x64, -win-x64.exe.

Build host requirements

• Node.js 20+ (required by the pkg toolchain).
• A target is built natively or cross-built per platform. macOS arm64 can only be built on an Apple Silicon host; macOS x64, Linux x64, and Windows x64 build on any x64 host. The packaging script skips (with a note) any target the current host can't fabricate.

Running a binary

# Piper files are read from ./data/piperfiles next to the executable
mkdir -p data/piperfiles   # then drop your .piper files in (or set PIPER_FILES_DIR)

PORT=3000 DEEPPHE_API_LOCATION=http://your-deepphe-host:3333 \
  ./deepphe-visualizer-v2-macos-x64

Then open http://localhost:3000. The DeepPhe backend is resolved at runtime, so the same binary works against any backend with no CORS configuration. See the runtime variables in Environment Variables.

Maintenance

npm run install:clean    # Clean install (removes node_modules and package-lock.json)

API Configuration

The application connects to a DeepPhe Data API backend. Configure the API location in src/config.js:

export const DEEPPHE_API_LOCATION = process.env.REACT_APP_DEEPPHE_API_LOCATION || "http://localhost:3333";

Or set the environment variable:

REACT_APP_DEEPPHE_API_LOCATION=http://localhost:3333 npm start

Accessibility

This project is committed to WCAG 2.1 Level AA compliance. Key features:

• Runtime accessibility auditing with axe-core (development mode)
• ESLint rules for accessibility best practices
• Keyboard navigation support
• Screen reader compatibility
• Proper ARIA attributes and semantic HTML

See ACCESSIBILITY.md for detailed guidelines and testing procedures.

Code Quality

ESLint Rules

The project enforces strict accessibility and code quality rules:

• All interactive elements must be keyboard accessible
• Images require alt text
• Form inputs must have labels
• Valid ARIA attributes
• Proper semantic HTML

Testing

Unit tests use Jest and React Testing Library. Test files are co-located with source files:

Run tests with coverage:

npm test -- --coverage --watchAll=false

Run all tests once (non-watch):

npm test -- --watchAll=false --runInBand

Browser Support

Production

Environment Variables

Build / development

Variable	Description	Default
REACT_APP_DEEPPHE_API_LOCATION	DeepPhe Data API base URL baked into the build	http://localhost:3333
NODE_ENV	Environment mode	development
PORT	Development server port	3000

npm run package:web builds with REACT_APP_DEEPPHE_API_LOCATION=/ so the packaged binary issues same-origin requests that flow through its reverse proxy.

Standalone binary (runtime)

Variable	Description	Default
PORT	Port the unified server listens on	3000
DEEPPHE_API_LOCATION	Upstream DeepPhe data API origin the binary proxies to	http://localhost:3333
PIPER_FILES_DIR	Directory of .piper files	data/piperfiles next to binary
PIPER_ACTIVE_FILE	Active piper filename within PIPER_FILES_DIR (optional)	unset

Troubleshooting

Port 3000 is already in use

# Find the process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or start on a different port
PORT=3001 npm start

ESLint errors about react-app config

# Reinstall dependencies
npm install --legacy-peer-deps

Build fails with peer dependency errors

# Clean install
npm run install:clean