Skip to content

docs: Add comprehensive TUI module documentation#83

Merged
inureyes merged 2 commits intomainfrom
docs/issue-81-tui-documentation
Dec 15, 2025
Merged

docs: Add comprehensive TUI module documentation#83
inureyes merged 2 commits intomainfrom
docs/issue-81-tui-documentation

Conversation

@inureyes
Copy link
Member

Summary

This PR adds comprehensive documentation for the Terminal User Interface (TUI) module that was implemented in issue #68. The documentation covers both the technical architecture (for developers) and user-facing features (for end users).

Documentation Updates

ARCHITECTURE.md

Added extensive TUI architecture section (~500 lines) covering:

  • Module structure: Complete file hierarchy and component descriptions
  • ViewMode state machine: Summary, Detail, Split, and Diff view modes
  • Event handling: Keyboard input processing with mode-specific handlers
  • RollingBuffer design: Memory protection mechanism (10MB per node)
  • Event loop architecture: Non-blocking polling and lazy rendering
  • State management: Change detection, scroll positions, follow mode
  • Performance characteristics: Target metrics and optimization strategies
  • Terminal safety: RAII guards for panic-safe cleanup
  • Output mode auto-detection: TUI activation conditions
  • Testing strategy: Unit test coverage and integration testing approach
  • Known limitations: Documented TODOs and future enhancements

README.md

Enhanced TUI documentation with user-friendly reference:

  • View modes table: Description and access keys for all 4 views
  • Comprehensive keyboard shortcuts table: Organized by context (Global, Summary, Detail, Split, Diff)
  • TUI activation conditions: When TUI is automatically enabled/disabled
  • Feature highlights: Progress detection, memory limits, real-time updates
  • Minimum requirements: Terminal size requirements (40x10)

src/ui/tui/app.rs

Fixed missing keyboard shortcut in help overlay:

  • Added "1-9: Jump to node N" in detail view help text
  • Ensures help overlay matches actual available shortcuts

Related Issues

Test Plan

  • Documentation formatting verified (markdown tables, code blocks)
  • Keyboard shortcuts table matches implementation in event.rs
  • Help overlay includes all available shortcuts
  • ARCHITECTURE.md structure follows existing patterns
  • No code changes beyond help text addition
  • Pre-commit hooks passed (cargo fmt, clippy)

Checklist

  • Documentation follows existing style and conventions
  • All keyboard shortcuts documented and verified
  • Help overlay updated with complete shortcuts
  • ARCHITECTURE.md section added after Interactive Mode
  • README.md TUI section enhanced with tables
  • Commit message follows conventional commits format
  • Issue Add TUI module documentation to ARCHITECTURE.md and README #81 resolved in commit message

Add detailed architecture documentation and user-facing guides for the
Terminal User Interface (TUI) module implemented in issue #68.

Changes:
- ARCHITECTURE.md: Add extensive TUI architecture section covering:
  - Module structure and component descriptions
  - ViewMode state machine and event handling
  - RollingBuffer design for memory protection
  - Event loop architecture and state management
  - Performance characteristics and optimization strategies
  - Error handling and terminal safety with RAII guards
- README.md: Enhance TUI documentation with:
  - Comprehensive keyboard shortcuts reference table
  - View modes description table
  - TUI activation conditions and requirements
  - Feature highlights (progress detection, memory limits)
- src/ui/tui/app.rs: Add missing keyboard shortcut to help overlay
  - Add "1-9: Jump to node N" in detail view help text

Resolves #81
Related to #68
@inureyes inureyes added type:docs Improvements or additions to documentation status:review Under review priority:medium Medium priority issue labels Dec 15, 2025
@inureyes inureyes self-assigned this Dec 15, 2025
- Remove line counts from ARCHITECTURE.md to prevent documentation drift
- Add footnote for unimplemented diff view scroll feature in README.md
@inureyes inureyes merged commit 726393a into main Dec 15, 2025
2 checks passed
@inureyes inureyes deleted the docs/issue-81-tui-documentation branch December 15, 2025 14:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority:medium Medium priority issue status:review Under review type:docs Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add TUI module documentation to ARCHITECTURE.md and README

1 participant