UI Components

UI Components

Back to Home

The ByteBiota web interface is built using a modular UI system integrated into the distributed server. This page documents the UI components, their structure, and how they work together.

Overview {#overview}

The UI system is located in src/bytebiota/ui/ and provides:
- Icon Generation: Procedural SVG icon generation for organisms
- Static Assets: CSS, JavaScript, and image files
- HTML Templates: Jinja2 templates for server-side rendering
- Web Interface: Integrated into the distributed server

Directory Structure {#directory-structure}

src/bytebiota/ui/
├── __init__.py              # UI module exports
├── icon_generator.py        # Procedural icon generation
├── static/                  # Frontend assets
│   ├── css/                # Stylesheets
│   │   ├── main.css        # Main application styles
│   │   ├── components.css  # Component-specific styles
│   │   ├── charts.css      # Chart styling
│   │   ├── analytics.css   # Analytics page styles
│   │   ├── distributed.css # Distributed view styles
│   │   └── memory-map.css  # Memory map visualization
│   ├── js/                 # JavaScript modules
│   │   ├── main.js         # Main application logic
│   │   ├── charts.js       # Chart utilities
│   │   ├── analytics.js    # Analytics functionality
│   │   ├── distributed.js  # Distributed system UI
│   │   └── memory-map.js   # Memory map interactions
│   ├── icons/              # Generated organism icons
│   │   └── *.svg          # SVG icon files
│   └── images/             # Static images
│       └── logo.svg        # Application logo
└── templates/              # HTML templates
    ├── base.html           # Base template
    ├── index.html          # Dashboard
    ├── monitoring.html     # Monitoring page
    ├── distributed.html    # Distributed system view
    ├── analytics.html      # Analytics dashboard
    ├── taxonomy.html       # Species taxonomy browser
    ├── organism.html       # Individual organism details
    ├── memory-map.html     # Memory map visualization
    ├── wiki.html           # Wiki page template
    └── monitoring_dashboard.html # Legacy monitoring

Icon Generation System {#icon-generation}

The ByteBiota Icon System (DLIS) generates procedural SVG icons for organisms based on their taxonomic classification and behavioral traits.

IconSpec Class {#icon-spec}

The IconSpec dataclass defines the parameters for icon generation:

@dataclass
class IconSpec:
    kingdom: str           # Taxonomic kingdom
    phylum: str            # Taxonomic phylum  
    class_name: str        # Taxonomic class
    order: str             # Taxonomic order
    family: str            # Taxonomic family
    genus: str             # Taxonomic genus
    species: str           # Taxonomic species
    traits: Dict[str, bool] # Behavioral traits
    genome_hash: str       # Genome identifier
    genome_size: int       # Genome size
    valid_opcodes: int     # Valid opcode count
    invalid_opcodes: int   # Invalid opcode count
    dominant_family: str   # Dominant opcode family

Visual Mapping {#visual-mapping}

Icons are generated using deterministic visual mappings:

  • Kingdom → Shape: Each kingdom maps to a specific geometric shape
  • Phylum → Pattern: Each phylum adds visual patterns (checker, fractal lines, etc.)
  • Class → Color: Each class uses specific color palettes
  • Order → Symmetry: Radial or bilateral symmetry patterns
  • Family → Outline: Different outline styles (solid, dashed, gradient glow)
  • Genus → Motif: Internal decorative elements
  • Traits → Overlays: Additional visual elements for behavioral traits

Usage {#icon-usage}

from bytebiota.ui import ByteBiotaIconGenerator, generate_organism_icon

# Create generator
generator = ByteBiotaIconGenerator()

# Generate from classification data
icon_path = generate_organism_icon(classification_data)

# Or create custom spec
spec = IconSpec(kingdom="Digitalis Animata", ...)
icon_path = generator.generate_icon(spec)

Static Assets {#static-assets}

CSS Architecture {#css-architecture}

The CSS is organized into modular files:

  • main.css: Core application styles, variables, and layout
  • components.css: Reusable component styles
  • charts.css: Chart.js styling and customizations
  • analytics.css: Analytics-specific layouts and components
  • distributed.css: Distributed system monitoring styles
  • memory-map.css: Memory visualization styling

JavaScript Modules {#javascript-modules}

JavaScript functionality is split into focused modules:

  • main.js: Core application logic, navigation, and utilities
  • charts.js: Chart creation and data visualization
  • analytics.js: Analytics calculations and forecasting
  • distributed.js: Real-time distributed system monitoring
  • memory-map.js: Interactive memory map visualization

HTML Templates {#html-templates}

Templates use Jinja2 for server-side rendering with the following structure:

Base Template {#base-template}

base.html provides the common layout:
- HTML5 document structure
- CSS and JavaScript includes
- Navigation header
- Content blocks for page-specific content
- Footer and metadata

Page Templates {#page-templates}

Each page template extends base.html and defines:
- Page-specific content blocks
- Additional CSS/JavaScript includes
- Page-specific data and context

Template Context {#template-context}

Templates receive context data from the server:
- Simulation status and metrics
- Organism and species data
- User preferences and settings
- Navigation state

Server Integration {#server-integration}

The UI is integrated into the distributed server (src/bytebiota/server/server.py):

Static File Serving {#static-serving}

# Mount static files
static_path = Path(self.config.static_dir)  # src/bytebiota/ui/static
if static_path.exists():
    self.app.mount("/static", StaticFiles(directory=static_path), name="static")

Template Rendering {#template-rendering}

# Setup templates
template_path = Path(self.config.template_dir)  # src/bytebiota/ui/templates
if template_path.exists():
    templates = Jinja2Templates(directory=template_path)

Icon Generation API {#icon-api}

The server provides dynamic icon generation:

@app.get("/api/organism/{organism_id}/icon")
async def get_organism_icon(organism_id: int):
    # Generate icon using organism classification data
    icon_path = self.icon_generator.generate_icon_for_classification(organism_data)
    return {"icon_path": f"/static/icons/{icon_filename}"}

Configuration {#configuration}

UI paths are configured in src/bytebiota/server/config.py:

@dataclass
class ServerConfig:
    # Web UI settings
    enable_web_ui: bool = True
    static_dir: str = "src/bytebiota/ui/static"
    template_dir: str = "src/bytebiota/ui/templates"

Development {#development}

Adding New Pages {#adding-pages}

  1. Create HTML template in src/bytebiota/ui/templates/
  2. Add route in src/bytebiota/server/server.py
  3. Add navigation link in base.html
  4. Create page-specific CSS/JS if needed

Adding New Components {#adding-components}

  1. Add component styles to appropriate CSS file
  2. Add component JavaScript to appropriate JS file
  3. Document component usage and API

Icon Customization {#icon-customization}

  1. Modify visual mapping tables in icon_generator.py
  2. Add new shape/pattern drawing methods
  3. Update trait overlay definitions
  4. Test with various classification combinations

Performance {#performance}

Optimization Strategies {#optimization}

  • Icon Caching: Generated icons are cached by filename
  • Static Asset Caching: Browser caching for CSS/JS files
  • Template Caching: Jinja2 template compilation caching
  • Lazy Loading: JavaScript modules loaded on demand

Monitoring {#monitoring}

  • Icon generation performance metrics
  • Static file serving statistics
  • Template rendering times
  • Client-side performance tracking

Browser Support {#browser-support}

  • Chrome 90+: Full support
  • Firefox 88+: Full support
  • Safari 14+: Full support
  • Edge 90+: Full support
  • Mobile browsers: Responsive design support

Phylogenetic Tree Component {#phylogenetic-tree}

The phylogenetic tree is an interactive D3.js-based visualization component that displays the evolutionary relationships between digital organisms in a hierarchical tree structure.

Component Overview {#tree-overview}

The phylogenetic tree component provides:
- Interactive Tree Visualization: D3.js-powered tree with zoom, pan, and collapsible nodes
- Organism Aggregation: Multiple organisms of the same species are grouped and displayed with red circular count badges (white text on red background for high visibility)
- Full Taxonomy Hierarchy: Complete 8-level taxonomy (Kingdom → Phylum → Class → Order → Family → Genus → Species)
- Multiple Layout Types: Vertical, horizontal, and radial tree layouts
- Export Capabilities: PNG, SVG, and JSON export options
- Tooltips: Detailed information on hover including population counts and aggregated statistics

D3.js Layout Types {#tree-layouts}

The component supports three different layout algorithms:

Vertical Tree (Default)
  • Layout: Top-down hierarchical tree
  • Use Case: Traditional phylogenetic tree view
  • Implementation: d3.tree() with vertical orientation
Horizontal Tree
  • Layout: Left-to-right hierarchical tree
  • Use Case: Wide displays or when horizontal space is preferred
  • Implementation: d3.tree() with swapped x/y coordinates
Radial Tree
  • Layout: Circular tree with root at center
  • Use Case: Compact visualization or aesthetic preference
  • Implementation: d3.tree() with polar coordinate transformation

Interaction Patterns {#tree-interactions}

Node Interactions
  • Click to Expand/Collapse: Click nodes with children to toggle visibility
  • Hover Tooltips: Mouse over nodes to see detailed information
  • Visual Feedback: Node colors change based on state (expanded/collapsed/leaf)
  • Count Badge Hover: Population count badges scale up and darken on hover for better visibility
Zoom & Pan
  • Mouse Wheel: Zoom in/out (0.5x to 3x scale)
  • Click and Drag: Pan around the tree
  • Zoom Controls: Dedicated buttons for zoom in, zoom out, and reset
  • Constrained Zoom: Prevents over-zooming beyond useful limits
View Controls
  • Layout Toggle: Switch between vertical, horizontal, and radial layouts
  • Export Menu: Access PNG, SVG, and JSON export options
  • Responsive Design: Adapts to container size changes

Data Structure Requirements {#tree-data-structure}

The component expects hierarchical data in this format:

{
  "tree": {
    "name": "Digital Life Ecosystem",
    "population": 1000,
    "count": 1000,
    "children": [
      {
        "name": "Digitalis Plantae",
        "kingdom": "Digitalis Plantae",
        "population": 350,
        "count": 350,
        "avg_fitness": 0.75,
        "avg_energy": 85.3,
        "organism_ids": [1, 2, 3, ...],
        "children": [
          {
            "name": "Polymorphid",
            "phylum": "Polymorphid",
            "population": 200,
            "count": 200,
            "children": [...]
          }
        ]
      }
    ]
  }
}
Required Fields
  • name: Display name for the node
  • population: Total population count (for aggregation)
  • count: Number of organisms at this level
Optional Fields
  • avg_fitness: Average fitness across organisms
  • avg_energy: Average energy across organisms
  • organism_ids: Array of organism IDs for drill-down
  • kingdom, phylum, class, order, family, genus, species: Taxonomy information

API Endpoint Reference {#tree-api}

GET /api/analytics/phylogenetic-tree

Returns hierarchical phylogenetic tree data with organism aggregation.

Parameters:
- time_range (string): Time range for data, default "7d"

Response:

{
  "tree": {
    "name": "Digital Life Ecosystem",
    "population": 1000,
    "count": 1000,
    "children": [...]
  },
  "nodes": ["kingdom1", "kingdom2", ...],
  "edges": []
}

Features:
- Full 8-level taxonomy hierarchy
- Organism aggregation by species
- Aggregated statistics (fitness, energy)
- Organism ID tracking for drill-down

Export Capabilities {#tree-export}

The component supports three export formats:

PNG Export
  • Format: Raster image (PNG)
  • Use Case: Presentations, documents, reports
  • Implementation: SVG to Canvas conversion
  • Filename: phylogenetic-tree-YYYY-MM-DD.png
SVG Export
  • Format: Vector image (SVG)
  • Use Case: Scalable graphics, further editing
  • Implementation: Direct SVG serialization
  • Filename: phylogenetic-tree-YYYY-MM-DD.svg
JSON Export
  • Format: Structured data (JSON)
  • Use Case: Data analysis, backup, integration
  • Implementation: API data fetch and download
  • Filename: phylogenetic-tree-data-YYYY-MM-DD.json

Browser Compatibility {#tree-compatibility}

D3.js Requirements
  • D3.js v7: Required for tree functionality
  • SVG Support: Modern browsers with SVG support
  • ES6 Features: Arrow functions, template literals, destructuring
Fallback Strategy
  • D3.js Detection: Checks for window.d3 availability
  • Simple Tree Fallback: HTML-based tree when D3.js unavailable
  • Graceful Degradation: Shows warning message and simplified view
Supported Browsers
  • Chrome 90+: Full D3.js support
  • Firefox 88+: Full D3.js support
  • Safari 14+: Full D3.js support
  • Edge 90+: Full D3.js support
  • Mobile: Touch gesture support for zoom/pan

Performance Considerations {#tree-performance}

Optimization Strategies
  • Collapsible Nodes: Start with root collapsed for large trees
  • Smooth Transitions: 300ms animated transitions for layout changes
  • RequestAnimationFrame: Smooth zoom/pan operations
  • Debounced Resize: 300ms debounce for window resize events
  • SVG Caching: Reuse SVG elements where possible
Large Dataset Handling
  • Node Limit: Recommended max 100 nodes for optimal performance
  • Aggregation: Multiple organisms grouped by species
  • Lazy Loading: Children loaded on demand
  • Memory Management: Cleanup of unused SVG elements

Implementation Details {#tree-implementation}

File Locations
  • JavaScript: src/bytebiota/ui/static/js/analytics.js
  • CSS: src/bytebiota/ui/static/css/analytics.css
  • API: src/bytebiota/server/analytics_service.py
Key Functions
  • renderPhylogeneticTree(data): Main rendering function
  • toggleTreeView(): Layout switching
  • exportTree(): Export functionality
  • renderSimpleTree(data, container): Fallback renderer
Dependencies
  • D3.js v7: Tree layout and visualization
  • CSS Variables: Theme integration
  • Modern JavaScript: ES6+ features

Security {#security}

  • XSS Prevention: Jinja2 auto-escaping enabled
  • CSRF Protection: Token-based form protection
  • Content Security Policy: Restricted resource loading
  • Static File Security: No executable content in static files