UI/UX Overview

UI/UX Overview

Back to Home

As ByteBiota grows a front-end, we document interface goals, navigation flows, and accessibility considerations here. Use this page to align design changes with stakeholder needs.

Interface Principles {#interface-principles}

The ByteBiota web application provides a comprehensive interface for monitoring and analyzing digital evolution simulations. The application consists of multiple interconnected pages that allow users to observe real-time simulation data, explore organism taxonomy, and analyze evolutionary patterns.

Technology Stack {#technology-stack}

  • Backend: FastAPI (Python)
  • Frontend: Jinja2 templates with vanilla JavaScript
  • Styling: Custom CSS with CSS custom properties for theming
  • Charts: Chart.js for data visualization
  • Data: Real-time JSON endpoints for simulation data

Design Principles {#design-principles}

  • Responsive Design: Mobile-first approach with tablet and desktop enhancements
  • Accessibility: Full keyboard navigation, screen reader support, high contrast mode
  • Performance: Lazy loading, progressive enhancement, aggressive caching
  • User Experience: Intuitive navigation, real-time updates, clear error handling

Icon System {#icon-system}

The ByteBiota Icon System (DLIS) provides procedural, deterministic visual representations for every classified organism. Icons are generated based on taxonomic classification and behavioral traits, creating a visual language that reflects the organism's genetic and behavioral characteristics.

Icon Specification {#icon-specification}

Each icon is defined by an IconSpec containing:
- Taxonomic classification (kingdom, phylum, class, order, family, genus, species)
- Behavioral traits (replication, memory allocation, environment interaction, task solving, energy harvesting)
- Genome metadata (hash, size, opcode counts, dominant family)

Visual Mapping {#visual-mapping}

The system maps taxonomic levels to visual elements:
- Kingdom → Base shape (circle, triangle, hexagon, pentagon, octagon, etc.)
- Phylum → Pattern overlay (checker, fractal lines, spiked radial, etc.)
- Class → Color palette (green/cyan, blue/teal, amber/orange, etc.)
- Order → Symmetry mode (radial, bilateral)
- Family → Outline style (solid, dashed, dual-layer, gradient glow)
- Genus → Internal motif (nested squares, gear circle, network nodes, etc.)
- Species → Deterministic variation via genome hash
- Traits → Overlay elements (double ring, square grid, radiating lines, etc.)

Icon Generator {#icon-generator}

The ByteBiotaIconGenerator class creates SVG icons (256×256) with the following features:
- Deterministic generation using genome hash as seed
- Hierarchical consistency where related species share visual themes
- Trait encoding with visual overlays for behavioral characteristics
- Scalable output in SVG format for crisp display at any size

Generation Process {#icon-generation}

  1. Seed Creation: Genome hash converted to integer for deterministic randomization
  2. Base Shape: Kingdom determines primary geometric form
  3. Pattern Overlay: Phylum adds texture and visual complexity
  4. Color Application: Class determines hue and gradient direction
  5. Motif Addition: Genus adds internal symbolic elements
  6. Trait Overlays: Behavioral traits add visual indicators
  7. Outline Application: Family determines border style
  8. SVG Output: Final icon saved as scalable vector graphic

API Integration {#icon-api}

The web application provides icon generation through:
- DataManager.generate_organism_icon() - Generate icon for specific organism
- DataManager.get_icon_path() - Get icon file path, generating if needed
- /api/organism/{id}/icon - REST endpoint for icon generation

Template Integration {#icon-templates}

Templates use get_organism_icon_url() helper function to display generated icons with fallback to emoji icons if generation fails. Icons are automatically pre-generated when taxonomy pages load to ensure smooth user experience.

Icon Alignment {#icon-alignment}

Kingdom distribution cards use specific CSS rules to ensure generated icons are perfectly centered within their containers. The .kingdom-icon .kingdom-icon-generated class overrides general margin rules and uses flexbox centering for optimal visual alignment.

Kingdom Representative Icons {#kingdom-representative-icons}

The get_kingdom_representative_icon_url() function finds the first organism of a given kingdom and returns its generated icon URL. This is used for kingdom distribution cards where a representative icon is needed for the entire kingdom rather than a specific organism.

Convenience Functions {#icon-convenience}

The generate_organism_icon() function provides a simple interface for generating icons from classification data, used by both the web application and external tools.

Page Specifications {#page-specifications}

Dashboard (Home Page) {#dashboard}

Route: /
Purpose: Overview of simulation status and quick access to key features

Layout
  • Header: Navigation bar with logo and main menu
  • Hero Section: Current simulation status with key metrics
  • Quick Stats Grid: 4-column grid showing:
  • Population count
  • Memory usage
  • Current step
  • Diversity ratio
  • Recent Activity: Timeline of recent events
  • Quick Actions: Buttons to start/stop simulation, view monitoring, browse taxonomy
Components
  • Status Card: Large card showing simulation state (Running/Stopped/Paused)
  • Metric Cards: Small cards with trend indicators
  • Activity Feed: Scrollable list of recent simulation events
  • Action Buttons: Primary actions for simulation control

Monitoring Dashboard {#monitoring}

Route: /monitoring
Purpose: Real-time visualization of simulation metrics and trends

Layout
  • Header: Page title with time range selector
  • KPI Row: Key performance indicators in horizontal layout
  • Chart Grid: 2x3 grid of interactive charts
  • Analysis Panel: Evolution analysis and recommendations
Charts
  1. Population Chart: Line chart showing population over time
  2. Memory Usage: Line chart showing memory occupancy percentage
  3. Average Size: Line chart showing organism size trends
  4. Energy Levels: Line chart showing average energy
  5. Diversity Index: Line chart showing genome diversity
  6. Seed Bank Size: Line chart showing seed bank growth
Interactive Features
  • Time Range Selector: Dropdown for different time windows
  • Chart Zoom: Click and drag to zoom into specific time periods
  • Hover Details: Tooltips showing exact values
  • Auto-refresh: Configurable refresh interval (2-10 seconds)

Taxonomy Browser {#taxonomy}

Route: /taxonomy
Purpose: Explore and analyze organism species and their characteristics

Layout
  • Header: Page title with search and filter controls
  • Kingdom Overview: Visual representation of kingdom distribution
  • Species List: Sortable, filterable table of all species
  • Detail Panel: Expandable details for selected species
Kingdom Overview
  • Pie Chart: Distribution of organisms across kingdoms
  • Kingdom Cards: Clickable cards showing:
  • Kingdom name
  • Organism count
  • Representative color
  • Brief description
Species List
  • Table Columns:
  • Species name
  • Kingdom/Phylum/Class
  • Population count
  • Average size
  • Dominant traits
  • Actions (View Details)
  • Sorting: By any column
  • Filtering: By kingdom, phylum, class, traits
  • Search: Text search across species names and traits

Organism Detail Page {#organism-detail}

Route: /organism/<organism_id>
Purpose: Detailed view of individual organism characteristics

Layout
  • Header: Organism ID and basic info
  • Genome Visualization: Visual representation of genome
  • Execution Profile: Opcode usage and execution patterns
  • Memory Layout: Memory address and size information
  • Performance Metrics: Age, energy, error statistics
Genome Visualization
  • Hex Dump: Formatted hexadecimal representation
  • Opcode Map: Color-coded opcode visualization
  • Family Distribution: Pie chart of opcode families
  • Mutation History: Track of mutations over time
  • Home: Dashboard overview
  • Monitoring: Real-time simulation data
  • Taxonomy: Species browser
  • Analytics: Advanced analysis tools
  • Distributed: Distributed simulation management
  • Memory Map: Real-time memory visualization
  • Wiki: Documentation browser

Secondary Navigation

  • Breadcrumbs: Show current page hierarchy
  • Quick Links: Context-sensitive shortcuts
  • User Actions: Profile, preferences, logout

Data Flow {#data-flow}

Real-time Updates

  1. WebSocket Connection: For live simulation data
  2. WebSocket-Only: Real-time bidirectional communication
  3. Data Caching: Client-side caching for performance
  4. Update Batching: Group updates to reduce server load

API Endpoints

  • GET /api/simulation/status - Current simulation state
  • GET /api/simulation/metrics - Real-time metrics
  • GET /api/simulation/history - Historical data
  • GET /api/taxonomy/species - Species list
  • GET /api/taxonomy/species/{id} - Species details
  • GET /api/organism/{id} - Organism details
  • GET /api/organism/{id}/icon - Organism icon
  • POST /api/simulation/control - Start/stop simulation

User Experience Features {#ux-features}

Responsive Design

  • Mobile-first: Optimized for mobile devices
  • Tablet Support: Adapted layouts for tablet screens
  • Desktop Enhancement: Full feature set on desktop

Accessibility

  • Keyboard Navigation: Full keyboard support
  • Screen Reader: ARIA labels and semantic HTML
  • High Contrast: Support for high contrast mode
  • Font Scaling: Respects user font size preferences

Performance

  • Lazy Loading: Load content as needed
  • Progressive Enhancement: Core functionality without JavaScript
  • Caching Strategy: Aggressive caching for static content
  • Compression: Gzip compression for all responses

Error Handling {#error-handling}

User-facing Errors

  • Connection Lost: Graceful handling of network issues
  • Data Unavailable: Clear messaging when data is missing
  • Simulation Errors: User-friendly error descriptions
  • 404 Pages: Custom error pages with helpful navigation

Developer Tools

  • Debug Mode: Detailed error information in development
  • Logging: Comprehensive server-side logging
  • Monitoring: Application performance monitoring
  • Health Checks: Endpoint for system health verification

Security Considerations {#security}

Data Protection

  • Input Validation: Sanitize all user inputs
  • CSRF Protection: Cross-site request forgery prevention
  • Rate Limiting: Prevent abuse of API endpoints
  • Secure Headers: Security headers for all responses

Access Control

  • Authentication: Optional user authentication
  • Authorization: Role-based access control
  • Session Management: Secure session handling
  • API Keys: Optional API key authentication

Wiki Interface {#wiki-interface}

The ByteBiota web application includes a comprehensive wiki interface that renders markdown documentation as HTML with full navigation support.

Wiki Manager {#wiki-manager}

The WikiManager class (implemented in src/bytebiota/server/wiki_service.py) handles:
- Markdown rendering using the markdown library with extensions for tables, code highlighting, and table of contents
- Link processing to convert relative wiki links to proper web routes
- Navigation parsing from the home.md structure to build sidebar navigation
- Caching for improved performance on repeated page loads

Wiki Features {#wiki-features}

  • Live markdown conversion - All markdown files in /wiki are automatically rendered as HTML
  • Cross-page navigation - Links between wiki pages work seamlessly
  • Directory support - Automatic handling of directory-based pages with README.md or auto-generated indexes
  • Sub-page navigation - Support for pages within directories (e.g., /wiki/species-profiles/computus)
  • Table of contents - Automatically generated from markdown headers
  • Anchor link support - {#anchor-name} syntax is converted to proper HTML anchors with hover-to-reveal links
  • Responsive design - Works on desktop and mobile devices
  • Search-friendly - All content is properly structured for search engines

Wiki Routes {#wiki-routes}

  • /wiki - Wiki home page (renders home.md)
  • /wiki/{page_name} - Individual wiki pages
  • /wiki/{directory} - Directory index pages (renders README.md or auto-generated index)
  • /wiki/{directory}/{sub_page} - Sub-pages within directories
  • /api/wiki/pages - API endpoint listing all available pages
  • /api/wiki/{page_name} - API endpoint for specific page content
  • /api/wiki/{directory}/{sub_page} - API endpoint for sub-page content

Wiki Navigation {#wiki-navigation}

The wiki sidebar automatically parses the home.md file to build a hierarchical navigation structure, organizing pages by sections as defined in the wiki index. Each page includes:
- Section headers parsed from ## Section Name in home.md
- Page links parsed from - \page.md` — description` format
- Active page highlighting based on current route
- Descriptive text for each page from the home.md index

Directory Support {#directory-support}

The wiki system supports directory-based organization:
- Directory pages: /wiki/species-profiles renders the directory's README.md or auto-generates an index
- Sub-pages: /wiki/species-profiles/computus renders individual files within directories
- Link processing: Relative links within directories are automatically converted to proper paths
- Auto-generated indexes: If no README.md exists, the system generates a page listing all markdown files in the directory

The wiki system automatically processes markdown anchor syntax:
- Input: ## Heading Text {#anchor-name}
- Output: <h2 id="heading-text">Heading Text <a id="anchor-name" class="anchor-link"></a></h2>
- Features:
- Hover-to-reveal anchor links (🔗 symbol appears on hover)
- Click to copy direct link to section
- Smooth scrolling to anchors
- Automatic anchor generation for headings without explicit anchors