A Terminal User Interface (TUI) for browsing, visualizing, and analyzing bacteriophage genetic data. Features color-coded DNA/amino acid sequences, rotating 3D ASCII phage models, and instant navigation between genomes—no browser, no cloud, just a fast local binary.

One-liner install:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/phage_explorer/main/install.sh?$(date +%s)" | bash

Main dashboard — Phage selector with 24 genomes, Lambda phage illustration, color-coded sequence grid, 3D protein structure viewer, and Analysis Tools panel

Sequence + Structure view — Color-coded amino acid grid with gene map, alongside WebGL 3D protein structure (8ZVI, 28,618 atoms) fetched from RCSB PDB

Virtual Gel Electrophoresis [Alt+G] — Simulate restriction enzyme digestion with EcoRI, HindIII, BamHI and more; compare predicted band patterns against experimental gels

Simulation Hub [Shift+S] — Interactive phage biology simulations: Lysogeny Decision Circuit, Plaque Growth Automata, Ribosome Traffic, Burst Kinetics, and more

What phages are (in engineering terms): self-assembling nanosyringes that package code (DNA/RNA) in a protein shell, land on bacteria, and inject that code to hijack the host. They’re the most abundant biological “edge devices” on Earth (≈10³¹ particles), continuously stress‑testing bacterial firmware.

• Medicine: design phage cocktails to beat antibiotic‑resistant infections.
• Biotech: workhorse enzymes (T7 RNA polymerase, Phi29 DNA pol) are phage gifts used in PCR, in‑vitro transcription, and genome amplification.
• Evolution & ecology: phages rewrite bacterial genomes, drive the ocean carbon cycle, and shape your gut microbiome.
• Engineering playground: modular genomes swap parts (tail fibers, lysis cassettes) like microservice plugins.

• Hershey–Chase blender experiment (1952) used phage T2 to prove DNA is the hereditary material.
• Crick–Brenner frameshift experiment (1961) in phage T4 rII genes showed the code is read in triplets—delete/insert three bases and the protein still works.
• Early codon assignments relied on phage RNA/DNA templates (e.g., poly‑U/UGG) to map base triplets to amino acids, paving the way for the 64‑codon table we use today.

• What they are: Bacteriophages (“phages”) are bacteria‑infecting viruses. They self‑assemble into nanomachines with a head (capsid) that stores DNA/RNA and a tail that injects it like a syringe.
• Why they matter today
  • Medicine: design phage cocktails to beat antibiotic‑resistant infections.
  • Biotech: workhorse enzymes (T7 RNA polymerase, Phi29 DNA pol) are phage gifts used in PCR, in‑vitro transcription, and genome amplification.
  • Evolution & ecology: phages are the most abundant biological entities on Earth. They rewrite bacterial genomes, drive the ocean carbon cycle, and shape your gut microbiome.
• Modular by design: Phage genomes behave like Lego kits—swapping tail fibers, lysis cassettes, and regulatory modules across lineages. That modularity is exactly what Phage Explorer visualizes.
• Historical impact: Foundational experiments (Hershey–Chase blender test for DNA as genetic material; Luria–Delbrück fluctuation test revealing random mutation) used phages. They were also the playground for cracking the genetic code.

• Genome = source code (A/C/G/T chars) with strongly typed 3-char opcodes (codons).
• Promoter/RBS = function entry points that recruit ribosomes (the runtime) to start decoding.
• Reading frame = instruction pointer alignment; shift by one base and every downstream opcode changes.
• Stop codons = return; terminate translation and hand control back to the host.
• Phage lifecycle = deployment strategy: lytic = rm -rf host; lysogenic = git clone into host genome and wait.

• DNA alphabet: A, C, G, T (RNA swaps T→U). Proteins are chains of 20 amino acids.
• Translation reads DNA in codons—non‑overlapping triplets of bases (64 possible combos). Every three letters → one amino acid or a stop signal.
• The mapping is fixed and mostly redundant (“degenerate”): several codons can encode the same amino acid. Three codons encode stop, and ATG usually marks start.
• Reading frames matter: shift by one base and every downstream codon changes. Phage Explorer lets you flip frames live to see amino acid strings reflow.
• Triplets are proven by phage genetics: three-base indels restore the reading frame; doublet/singlet changes scramble everything.
• Quick lookup:

• Chemistry buckets: Amino acids group into hydrophobic, polar, acidic, basic, and “special” (glycine, proline, cysteine, histidine). Themes color by these groups so chemical patterns pop while you scroll.

• Full-Screen HUD Interface — Navigate between phages instantly with arrow keys
• Color-Coded Sequences — DNA (ACTG) and amino acid views with distinct, beautiful colors
• 5 Color Themes — Classic, Ocean, Matrix, Sunset, Forest (cycle with T)
• 3D Structure Viewer — Real PDB structures from RCSB with cartoon/ball-and-stick/surface modes (web), ASCII wireframe (TUI)
• Gene Map Navigation — Visual gene bar with position tracking and snap-to-gene
• Layer-1 Quick Overlays — G GC skew, X complexity, B bendability, P promoter/RBS motifs, R repeats/palindromes
• Diff Mode — Compare sequences between phages visually
• Search — Fuzzy search by name, host, family, or accession
• 24 Real Phages — Lambda, T4, T7, PhiX174, MS2, M13, P22, Phi29, Mu, Phi6, SPbeta, T5, P1, P2, N4, Felix O1, D29, L5, PhiC31, PhiKZ, PRD1, PM2, Qβ, T1
• WASM-Accelerated — Rust-compiled spatial algorithms for instant analysis of large structures
• Zero Dependencies at Runtime — Single binary, no Bun/Node required

# Install latest release (includes database)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/phage_explorer/main/install.sh?$(date +%s)" | bash -s -- --with-database

# Run
phage-explorer

# Clone and install
git clone https://github.com/Dicklesworthstone/phage_explorer.git
cd phage_explorer
bun install

# Build the phage database (fetches from NCBI, ~1 minute)
bun run build:db

# Run the TUI
bun run dev

The full web experience is live at https://phage-explorer.org. It includes:

• 3D Structure Viewer — Real PDB structures from RCSB with cartoon, ball-and-stick, and surface rendering modes
• Interactive Sequence Grid — Color-coded DNA/amino acid display with smooth scrolling
• 30+ Analysis Overlays — GC skew, dot plots, Hilbert curves, HGT detection, synteny, and more
• WASM-Accelerated — Rust-compiled spatial algorithms for instant loading of large structures (50K+ atoms)
• Mobile-Friendly — Touch gestures, bottom sheets, haptic feedback

Deployment details:

• Hosting: Vercel (prod alias: phage-explorer.org)
• Build command: bun run build:web
• Output: packages/web/dist
• SQLite database bundled as static asset, queried via sql.js in-browser
• Zero telemetry, works offline after initial load

The TUI remains available for terminal enthusiasts:

• Local SQLite DB with instant queries
• ASCII 3D wireframe models
• Real-time keyboard controls, diff mode, command palette
• Build locally: bun install && bun run build:db && bun run dev (or use the prebuilt binary)

Cycle through themes with T:

• Classic — Traditional bioinformatics colors (green A, blue C, amber G, red T)
• Ocean — Cool blue/teal palette
• Matrix — Green terminal aesthetic
• Sunset — Warm orange/coral tones
• Forest — Natural earth greens and browns

Each theme provides distinct colors for:

• 4 nucleotides (A, C, G, T) + N
• 20 amino acids grouped by property (hydrophobic, polar, acidic, basic, special) + stop codon

phage-explorer/
├── packages/
│   ├── core/           # Domain logic: codons, theming, grid virtualization
│   ├── db-schema/      # Drizzle ORM schema (phages, sequences, genes, etc.)
│   ├── db-runtime/     # Repository implementations over SQLite
│   ├── state/          # Zustand store for UI state management
│   ├── renderer-3d/    # ASCII 3D rendering engine with Z-buffering
│   ├── wasm-compute/   # Rust/WASM for performance-critical algorithms
│   ├── data-pipeline/  # NCBI fetcher and database builder
│   ├── web/            # React web app with WebGL 3D viewer
│   └── tui/            # Ink/React TUI components
├── phage.db            # SQLite database (generated)
└── install.sh          # One-liner installer script

To keep 31+ planned features coherent, Phage Explorer follows a lightweight design system tailored for text UIs:

• Color semantics

  • Green #22c55e: good / conserved / similar
  • Yellow #eab308: caution / neutral
  • Red #ef4444: warning / divergent
  • Blue #3b82f6: informational metrics
  • Purple #a855f7: notable / special
  • Gray #6b7280: background / reference / inactive

• Graph & sparkline standards

  • Height: 3–5 text rows; Width: terminal width where possible
  • Auto-normalize values; show min/max in labels
  • Prefer Braille dots for dense sparklines; fall back to ASCII if needed

• Panels, modals, overlays

  • Single-line box borders, 1-char padding
  • Headers bold, centered, include close hint (e.g., “Esc to close”)
  • Max width 80 chars or (terminal width - 4), whichever is smaller

• Interaction “depth layers” (progressive disclosure)

  • Layer 0: Core always-on controls (navigation, view toggles, help, search)
  • Layer 1: Quick overlays (single-key toggles; limit 3 active)
  • Layer 2: Analysis menu (A) with numbered shortcuts + fuzzy search
  • Layer 3: Simulation hub (Shift+S) for interactive models
  • Layer 4: Command palette (: or Ctrl+P) that fuzzy-searches all actions

Use these conventions for any new component: pick colors from the palette above, respect padding/borders, and place advanced features in deeper layers so newcomers see a stable core UI.

Phage Explorer serves both newcomers and power users by stacking features in “depth layers”:

• Layer 0 – Sacred Surface (always available, never changed)
  Navigation: ↑ ↓ ← → PgUp PgDn Home End
  View: N/C/Space (DNA/AA), F (frame), T (theme), D (diff), M (3D model)
  Meta: ? (help), S or / (search), Q (quit)
  These keys are stable forever; everything else builds on top.

• Layer 1 – Quick Overlays (single-key toggles; max 3 active)
  Reserved keys: G (GC skew), X (complexity), B (bendability), P (promoter/RBS), R (repeats).
  Data is precomputed on phage selection so toggles feel instant. (Feature hooks coming next.)

• Layer 2 – Analysis Menu (A)
  Categorized, numbered actions (e.g., GC skew analysis, dot plots, codon dashboards). Supports fuzzy search.

• Layer 3 – Simulation Hub (Shift+S)
  Full-screen interactive simulations (lysogeny circuits, ribosome traffic, plaque automata, etc.).

• Layer 4 – Command Palette (: or Ctrl+P)
  Fuzzy-search every action; shows the shortcut path (e.g., “GC skew [G] Overlay” or “Dot plot [A→4] Analysis”).

Keystroke budget rule: Layer 0 keys are immutable; new features must live in higher layers. This keeps discoverability for beginners and speed for experts.

# Install to custom directory
curl -fsSL .../install.sh | bash -s -- --dest ~/bin

# Install system-wide
curl -fsSL .../install.sh | bash -s -- --system

# Install specific version
curl -fsSL .../install.sh | bash -s -- --version v1.0.0

# Build from source instead of downloading binary
curl -fsSL .../install.sh | bash -s -- --from-source

# Include phage database
curl -fsSL .../install.sh | bash -s -- --with-database

# Auto-add to PATH
curl -fsSL .../install.sh | bash -s -- --easy-mode

• Sequence Storage: Chunked in 10kb segments for efficient virtualized rendering
• Virtualized Rendering: Only visible sequence portion rendered, smooth 60fps scrolling
• 3D Engine: Custom ASCII renderer (TUI) and WebGL/Three.js viewer (web) with real PDB structures
• WASM Acceleration: Rust-compiled WebAssembly for compute-intensive operations (spatial-hash bond detection, dot plots, k-mer analysis) with automatic JS fallback
• 3D Structure Loading: Fetches PDB/mmCIF from RCSB, parses in Web Worker, O(N) spatial-hash bond detection for structures with 50,000+ atoms
• State Management: Zustand for reactive UI updates
• Database: SQLite with Drizzle ORM, ~6MB for 24 phages with PDB structure references

• Network calls: Only to NCBI during database build
• No telemetry: Zero analytics or tracking
• Local data: All data stored in local SQLite database
• Open source: Full source code available for audit

• Single-binary distribution, no runtime dependencies
• SQLite database for instant local queries
• Virtualized sequence rendering for genomes up to 500kb+
• Chunked fetching avoids loading entire genomes into memory
• 3D model rendering at ~20fps with minimal CPU usage
• WASM spatial-hash: O(N) bond detection vs O(N²) naive—1000x faster for large structures (50K atoms: <1s vs 60s+)
• Web Worker isolation keeps UI responsive during heavy computation
• Automatic fallback to pure JS when WASM unavailable

• Lint + Typecheck: Every push and PR
• Cross-platform builds: macOS (arm64, x64), Linux (x64, arm64), Windows (x64)
• Automated releases: Tagged versions trigger binary builds and GitHub release
• Database artifacts: Pre-built phage.db included in releases

1. bun install to set up dependencies
2. bun run build:db to create the database
3. bun run dev to run the TUI
4. Run bun run check before committing changes

Phage Explorer implements a comprehensive suite of genomic analysis algorithms, from classic bioinformatics to cutting-edge machine learning approaches.

The Simulation Hub (Shift+S) provides interactive models of phage biology with adjustable parameters and real-time visualization.

Model: ODE system of Lambda lysis-lysogeny bistable switch State variables: CI and Cro repressor concentrations Parameters:

• Hill cooperativity (n=1-4) — controls switch steepness
• MOI (multiplicity of infection) — tips balance toward lysogeny
• UV damage — triggers lytic induction

Output: Phase classification (lysogenic/lytic/undecided) with time-series history

Model: Particle-based translation with stochastic elongation Mechanics:

• 9-codon ribosome footprint
• Elongation rates derived from phage codon usage bias
• Rare codons create traffic jams → bottlenecks

Output: Protein production rate, stall events, density heatmap

Model: Cellular automaton with reaction-diffusion dynamics Cell states: Empty → Bacteria → Infected → Lysed → Phage → Lysogen Parameters: Burst size, latent period, diffusion probability, adsorption rate, lysogeny probability Grid: Toroidal wrap-around, ~100 steps/frame

Model: SIR-like ODE system (dB/dt, dI/dt, dP/dt) Features:

• Adsorption kinetics: k [mL/(phage·min)]
• Exponential latent period decay
• Logistic bacterial growth with carrying capacity

Model: Gillespie stochastic simulation with tau-leaping States: Sensitive → Partially resistant (per phage) → Fully resistant Key insight: Mono-phage resistance emerges faster than cocktail resistance (synergy effect) Tracks: Sensitive/resistant populations, emergence time, individual phage counts

Model: Physics-informed DNA packaging Factors:

• Intrinsic pressure from DNA bending: L/(R²) energy model
• Ionic strength effects (Debye screening ~0.304/√I nm)
• Morphology-specific baselines (headful/cos/phi29)

Output: Fill fraction, internal pressure (atm), motor force (pN)

Model: Molecular clock with mutations and genetic drift Mechanics:

• Poisson-distributed mutations per generation
• Selection coefficients from normal distribution
• Fitness clamped 0.6-1.5, effective population (Ne) tracks drift

Performance-critical algorithms are implemented in Rust and compiled to WebAssembly for near-native speed in the browser.

Traditional bond detection is O(N²)—checking every atom pair. For a 50,000-atom structure, that's 2.5 billion comparisons.

The WASM spatial hash:

1. Divides 3D space into grid cells (cell size = max bond length)
2. Each atom only checks neighbors in adjacent cells
3. Reduces to O(N) on average

Result: 50K atoms in <1s vs 60s+ naive. This enables real-time structure exploration.

When WASM isn't available (older browsers, restricted environments), Phage Explorer gracefully falls back to pure JavaScript implementations. Users get the same features, just slower on large datasets.

The SQLite database includes extensive precomputed annotations, enabling instant analysis with zero latency.

Annotations are precomputed via GitHub Actions:

1. NCBI fetch → Raw sequences and gene annotations
2. Pfam/InterPro scan → Protein domain identification
3. KEGG mapping → Metabolic pathway linkage
4. ESM2 inference → Protein fold embeddings
5. SQLite build → Indexed, compressed database (~6MB)

Users get instant results because all heavy computation happens at build time.

Traditional sequence comparison requires alignment (BLAST, etc.), which is slow and fails for distant homologs. Phage Explorer includes alignment-free methods that work on raw k-mer statistics.

Maps a genome to a 2D fractal image:

• Start at center (0.5, 0.5)
• For each nucleotide, move halfway toward its corner
• Plot the point

Result: A unique "fingerprint" where similar genomes produce similar fractals. Visually identifies sequence biases, repeat structures, and phylogenetic relationships without alignment.

1. Compute tetranucleotide (4-mer) frequency vectors (256 dimensions)
2. Run PCA to reduce to 2-3D
3. Cluster phages by genomic signature

Why it works: Oligonucleotide frequencies are remarkably stable within a genome but differ between species. This captures "genomic dialect" independent of gene order or alignment.

Detects horizontal gene transfer and mosaic genomes:

1. Slide a window across the query genome
2. Compute k-mer Jaccard similarity to each reference
3. Plot "donor" assignment along the genome

Output: Identifies breakpoints where the genome switches from one "parent" to another—direct evidence of recombination events.

Most phage genomics tools are either:

• Too specialized — Built for one analysis type, require pipeline assembly
• Too heavyweight — Need cloud infrastructure, accounts, or complex installation
• Too dated — Command-line tools from the 2000s with no visualization

Phage Explorer combines:

• Breadth — 25+ analyses in one interface
• Speed — Precomputed annotations + WASM = instant results
• Accessibility — Single binary or web app, zero configuration
• Education — Interactive simulations teach the biology, not just display data

It's designed for the researcher who wants to explore a phage genome, not run a production pipeline.

Phage Explorer handles genomes up to 500kb+ without loading the entire sequence into memory.

How it works:

1. Sequences stored in 10kb chunks in SQLite
2. Virtual window tracks visible region + 500bp overscan buffer
3. Only visible chunks loaded and rendered
4. Row tiles cached with content hashing—scroll reuses existing tiles
5. Incremental blitting renders only newly visible rows

GlyphAtlas optimization:

• Pre-renders all nucleotides and amino acids to a texture atlas
• 10x faster than calling fillText() per character
• O(1) array-based glyph lookup (not Map.get())
• Automatic device pixel ratio scaling (1x to 3x)

Zoom levels:

ASCII Renderer (TUI):

• 70-character gradient for smooth shading: .'-",:;Il!i><~+_-?][}{1)(|\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$
• Float32 Z-buffer for proper occlusion
• Cohen-Sutherland line clipping with z-interpolation
• Front-to-back edge sorting for optimal depth writes
• Brightness mapping: depth → 0.2-1.0 intensity range

WebGL Renderer (Web):

• Real PDB structures fetched from RCSB
• Three render modes: cartoon ribbons, ball-and-stick, surface mesh
• CRT post-processing: chromatic aberration, scanlines, bloom, vignette, film grain
• O(N) spatial-hash bond detection for 50K+ atom structures

8 scientifically-grounded themes, each with 40+ color tokens.

Colors map to biochemical properties so structural patterns are visible while scrolling:

1. Holographic (default) — Glassmorphic cyan/magenta, electric accents
2. Cyberpunk — Neon grid aesthetic (cyan/magenta/yellow)
3. Classic — Traditional bioinformatics (green A, blue C, amber G, red T)
4. Ocean — Cool water-inspired blues and teals
5. Matrix — Green monochrome terminal aesthetic
6. Sunset — Warm orange/red/gold gradient
7. Forest — Natural greens and earth tones
8. Monochrome — Accessibility-focused grayscale

Phage Explorer is fully touch-optimized with gesture navigation and haptic feedback.

9 distinct vibration patterns for tactile feedback:

Haptics respect prefers-reduced-motion and gracefully degrade on unsupported devices.

Mobile overlays use iOS-style bottom sheets:

• Snap points: 25%, 50%, 90% of screen height
• Drag handle with visual feedback
• Swipe-to-dismiss with velocity detection
• Safe area insets for notched devices

30+ analysis overlays, architected for performance and maintainability.

Eager-loaded (instant): Search, Help, Settings, Command Palette Lazy-loaded (on-demand): All analysis overlays via React Suspense

This keeps initial bundle small (~200KB) while supporting 30+ feature-rich overlays.

Overlays share 12+ reusable components:

• OverlaySection / OverlaySectionHeader — Consistent section styling
• OverlayGrid / OverlayRow — Responsive layouts
• OverlayStatCard / OverlayStatGrid — Metric displays
• OverlayKeyValue / OverlayBadge — Data presentation
• OverlayLegend — Color key explanations

Zustand powers all UI state, shared between TUI and web platforms.

The PhageExplorerStore manages ~170 state properties:

Overlay stack limit:

overlays: [...filtered, newOverlay].slice(-3) // Max 3 active

View mode scroll preservation:

• DNA→AA: scrollPosition / 3 (codons are 3bp)
• AA→DNA: scrollPosition * 3

LocalStorage persistence: Beginner mode, tour completion, theme preference

The data pipeline fetches sequences from NCBI's Entrez API:

1. ESearch — Query nucleotide database with filters
2. ESummary — Batch metadata retrieval (50 items/request)
3. EFetch — Full GenBank records with gene annotations

Filters applied:

• viruses[filter] OR phage[Title]
• Sequence length constraints
• Collection date for temporal analysis

For temporal analysis, the pipeline:

• Parses collection dates (ISO, "May-2020", "2020", etc.)
• Bins sequences by month/year
• Extracts geographic metadata
• Computes temporal coverage histograms

Comparative genomics:

1. Load two phages (e.g., Lambda and P22)
2. Toggle Diff mode (D) to highlight sequence differences
3. Use Dot Plot overlay to visualize synteny
4. Identify conserved vs. variable regions

Gene function prediction:

1. Navigate to gene of interest with [/]
2. Open Protein Domains overlay
3. Check fold embedding neighbors for structural homologs
4. Cross-reference with AMG Pathway overlay

Phage therapy candidate screening:

1. Use Host Tropism overlay to verify target range
2. Check Defense Arms Race for anti-CRISPR genes
3. Run Cocktail Compatibility for multi-phage therapy
4. Simulate Resistance Evolution to predict durability

Teaching the genetic code:

• Toggle reading frames (F) to show frameshift effects
• Compare DNA vs. amino acid views (N/C)
• Run Ribosome Traffic simulation to visualize translation

Demonstrating phage biology:

• Lysogeny Decision Circuit shows Lambda switch mechanics
• Plaque Growth Automata visualizes infection spread
• Packaging Motor demonstrates DNA condensation physics

Best for: Rapid exploration, education, phage therapy research Not ideal for: High-throughput pipelines (use command-line tools), primer design (use SnapGene)

MIT License (with OpenAI/Anthropic Rider) — see LICENSE for details.

• Sequence data from NCBI GenBank/RefSeq
• TUI framework: Ink (React for CLIs)
• Database: Drizzle ORM + SQLite
• Runtime: Bun