Skip to content

ADR-008: Enhanced Console User Interface (TUI)

Status: Accepted

Date: November 2025

Deciders: Chippr Robotics LLC Engineering Team

Context

Fukuii Ethereum Client operators and developers need real-time visibility into node status for monitoring, debugging, and operational awareness. Previously, the only way to monitor a running node was through:

  1. Log file inspection: Requires tailing logs and parsing text output
  2. RPC queries: Requires separate tools and scripting
  3. External monitoring: Grafana dashboards and metrics exporters
  4. Health endpoints: Limited to HTTP checks without rich status information

While these methods work for production deployments and automated monitoring, they lack immediate visual feedback for: - Initial node startup and sync progress - Direct operator interaction and debugging - Development and testing workflows - Quick health checks without additional tools

User Stories

Node Operator: "I want to see at a glance if my node is syncing, how many peers are connected, and when sync will complete, without setting up external monitoring."

Developer: "During development and testing, I want immediate visual feedback on node state without parsing logs or writing scripts."

System Administrator: "I need a quick way to check node health during SSH sessions without installing additional monitoring tools."

Technical Landscape

Terminal UI Libraries: - JLine 3: Mature Java library for terminal control and line editing - Lanterna: Pure Java TUI framework (heavier dependency) - Scala Native TUI: Limited ecosystem, not suitable for JVM projects - ANSI Escape Codes: Manual control (complex, error-prone)

Design Patterns: - Dashboard/monitoring TUIs common in infrastructure tools (htop, k9s, lazydocker) - Non-scrolling, grid-based layouts for status monitoring - Keyboard-driven interaction for control - Graceful degradation when terminal features unavailable

Requirements

From Issue #300: 1. Enabled by default when using fukuii-launcher Update: Disabled by default per maintainer decision 2. Can be enabled/disabled with a flag on launch 3. Screen should not scroll (fixed layout) 4. Grid layout for organized information display 5. Display: peer connections, network, block height, sync progress 6. Basic keyboard commands (quit, toggle features) 7. Green color scheme matching Ethereum Classic branding 8. Proper terminal cleanup on exit

Status Update (November 2025): The console UI is currently disabled by default while under further development. Users can enable it explicitly with the --tui flag.

Decision

We decided to implement an Enhanced Console User Interface (TUI) using JLine 3 with the following design:

Architecture

Component Structure: - ConsoleUI: Core rendering and terminal management - ConsoleUIUpdater: Background status polling and updates - Integration points: Fukuii.scala (initialization), StdNode.scala (lifecycle)

Key Design Choices:

  1. JLine 3 as Terminal Library
  2. Already a project dependency (used for CLI commands)
  3. Cross-platform (Linux, macOS, Windows)
  4. Robust terminal capability detection

  5. No additional dependencies required

  6. Grid-Based Fixed Layout

  7. Non-scrolling display with sections
  8. Automatic terminal size adaptation
  9. Organized sections: Network, Blockchain, Runtime

  10. Visual separators between sections

  11. Default Disabled with Opt-In

  12. --tui flag to enable for interactive monitoring
  13. Standard logging by default for headless/background mode
  14. Automatic fallback on initialization failure

  15. No impact on existing deployments using systemd/docker

  16. Singleton Pattern

  17. Single ConsoleUI instance per process
  18. Thread-safe state management with @volatile variables

  19. Proper cleanup on shutdown

  20. Non-Blocking Updates

  21. Background thread for periodic updates (1 second interval)
  22. Non-blocking keyboard input checking

  23. Doesn't interfere with actor system or node operations

  24. Visual Design

  25. Ethereum Classic logo (ASCII art from community)
  26. Green/cyan color scheme (ETC branding)
  27. Progress bars for sync status
  28. Color-coded indicators (green=healthy, yellow=warning, red=error)
  29. Visual peer count indicators

Implementation Details

Keyboard Commands: - Q: Quit application - R: Refresh/redraw display - D: Disable UI (switch to standard logging)

Display Sections: 1. Header with branding 2. Ethereum Classic ASCII logo (when space permits) 3. Network & Connection (network name, status, peer count) 4. Blockchain (current block, best block, sync progress) 5. Runtime (uptime) 6. Footer with keyboard commands

Graceful Degradation: - Initialization failure → automatic fallback to standard logging - Unsupported terminal → logs warning and continues - Small terminal → adapts layout (hides logo if needed) - Standard logging by default → skips initialization unless --tui flag provided

Consequences

Positive

  1. Improved User Experience
  2. Immediate visual feedback on node status
  3. No external tools required for basic monitoring
  4. Intuitive, self-documenting interface

  5. Reduces time to understand node state

  6. Better Development Workflow

  7. Real-time feedback during development
  8. Quick health checks without log parsing
  9. Visual confirmation of changes

  10. Easier debugging of sync issues

  11. Minimal System Impact

  12. Updates every 1 second (low overhead)
  13. No additional dependencies
  14. Graceful fallback maintains compatibility

  15. Clean separation from core node logic

  16. Operational Flexibility

  17. Standard logging by default for automation and scripting
  18. Optional --tui flag for interactive monitoring
  19. Works in SSH sessions when enabled
  20. Compatible with screen/tmux

  21. Doesn't interfere with log aggregation

  22. Community Alignment

  23. Uses community-contributed ASCII art
  24. Matches Ethereum Classic branding
  25. Follows TUI best practices from ecosystem
  26. Enables better documentation and support

Negative

  1. Terminal Compatibility
  2. May not work on all terminal emulators
  3. Windows requires proper terminal (Windows Terminal, ConEmu)
  4. Legacy terminals may have limited color support

  5. Mitigated by: automatic fallback, documentation

  6. Accessibility

  7. Screen readers may not work well with TUI
  8. Colorblind users may have difficulty with color indicators

  9. Mitigated by: TUI disabled by default, text-based status in addition to colors

  10. Maintenance Overhead

  11. Additional code to maintain and test
  12. Cross-platform terminal behavior differences

  13. Mitigated by: isolated component, comprehensive error handling

  14. Limited Interaction

  15. Currently read-only monitoring (no configuration changes)
  16. Cannot show detailed logs or full peer list
  17. Future enhancement: multiple views/tabs

Trade-offs

Chosen: Fixed grid layout with 1-second updates Alternative: Scrolling log view with embedded status Rationale: Non-scrolling layout provides stable, easy-to-read dashboard. Standard logs available by default (without --tui).

Chosen: JLine 3 library Alternative: Lanterna framework, raw ANSI codes Rationale: JLine 3 already in dependencies, lighter than Lanterna, more robust than raw ANSI.

Chosen: Background polling for status Alternative: Actor messages for real-time push updates Rationale: Simpler implementation, isolated from actor system, easier to maintain. 1-second updates sufficient for monitoring.

Chosen: Singleton pattern Alternative: Actor-based UI component Rationale: Terminal is inherently a singleton resource, simpler lifecycle management.

Implementation Notes

Code Organization

src/main/scala/com/chipprbots/ethereum/console/
├── ConsoleUI.scala          # Main UI rendering and terminal management
└── ConsoleUIUpdater.scala   # Background status polling

Integration Points

  1. Fukuii.scala: Command-line parsing, initialization
  2. StdNode.scala: Lifecycle integration, updater startup
  3. App.scala: Help text with --tui documentation

Testing Strategy

  • Manual testing on multiple platforms (Linux, macOS, Windows)
  • Terminal emulator compatibility testing
  • Error handling verification (terminal failures)
  • Performance impact measurement (CPU, memory)
  • Integration testing with node startup/shutdown

Documentation

  • docs/architecture/console-ui.md: Comprehensive user guide
  • docs/adr/008-console-ui.md: This ADR
  • Updated README.md with console UI information
  • Help text with --tui flag

Alternatives Considered

1. Web-Based Dashboard

Approach: Built-in HTTP server with JavaScript frontend

Pros: - Rich interaction possibilities - Better accessibility - Cross-platform consistency - Can be accessed remotely

Cons: - Significant additional complexity - Browser dependency - Security concerns (authentication, CORS) - Overhead of web server and assets - Not suitable for quick local monitoring

Decision: Rejected - Too complex for basic monitoring needs. Web dashboards better suited as separate projects.

2. External Monitoring Only

Approach: Rely on metrics exporters, Grafana, and health endpoints

Pros: - No additional code in node - Production-grade monitoring tools - Centralized monitoring for multiple nodes

Cons: - Requires setup and infrastructure - Not suitable for development/testing - Overhead for single-node operators - No immediate feedback during startup

Decision: Rejected - External monitoring still valuable, but doesn't replace need for immediate local visibility.

3. Enhanced Logging Only

Approach: Structured logging with better formatting

Pros: - Minimal complexity - Works everywhere - Easy to parse programmatically

Cons: - Scrolling output difficult to read - No real-time status dashboard - Harder to get quick overview - Still requires log parsing

Decision: Rejected - Logging is complementary but doesn't provide dashboard-style monitoring.

4. Curses/ncurses Binding

Approach: Use native terminal libraries via JNI

Pros: - Full terminal control - Rich TUI possibilities - High performance

Cons: - Platform-specific binaries - Complex build process - JNI overhead and complexity - Harder to maintain

Decision: Rejected - JLine 3 provides sufficient functionality without JNI complexity.

Future Enhancements

Potential improvements for future releases:

  1. Multiple Views/Tabs
  2. Toggle between dashboard, logs, peers, transactions

  3. Keyboard shortcuts for view switching

  4. Detailed Peer Information

  5. List of connected peers
  6. Per-peer statistics

  7. Peer discovery status

  8. Transaction Pool View

  9. Pending transaction count
  10. Transaction details

  11. Gas price statistics

  12. Interactive Configuration

  13. Runtime configuration changes
  14. Feature toggles

  15. Log level adjustment

  16. Historical Charts

  17. Block import rate over time
  18. Peer count trends

  19. Sync progress visualization

  20. Mouse Support

  21. Click to navigate
  22. Scroll through lists

  23. Select and copy text

  24. Customization

  25. User-configurable layout
  26. Theme selection
  27. Metric preferences

References

  • Issue #300: Improved c-ux
  • PR #301: Implementation
  • JLine 3 Documentation: https://github.com/jline/jline3
  • Terminal UI Best Practices: https://clig.dev/
  • Ethereum Classic Branding: Community-contributed ASCII art

Changelog

  • November 2025: Initial implementation with basic monitoring features
  • November 2025: Changed to disabled by default (opt-in with --tui flag) per maintainer decision