GemReader/docs/architecture.md

Project Architecture

This document describes the architecture and structure of the GemReader application.

Overview

GemReader is a terminal-based markdown viewer built with Go using the Bubble Tea framework for the terminal user interface. The application reads markdown files, renders them for terminal display, and provides navigation capabilities.

Architecture Pattern

The application follows a modular architecture with clear separation of concerns:

• Presentation Layer: Bubble Tea-based TUI in the tui package
• Business Logic: Navigation and content handling in the tui package
• Configuration: Viper-based configuration loading in the config package
• Entry Point: Command-line interface in the main package

Package Structure

cmd/gemreader/main.go

The main entry point of the application that:

• Defines the command-line interface using Cobra
• Handles command-line argument validation
• Reads the markdown file specified by the user
• Loads application configuration
• Initializes and runs the TUI

internal/config/config.go

Configuration management that:

• Defines the application configuration structure
• Loads configuration from config.toml using Viper
• Provides configuration data to other parts of the application
• Handles configuration loading errors gracefully

internal/tui/tui.go

Terminal user interface implementation that:

• Implements the Bubble Tea model for TUI functionality
• Handles all user interactions and navigation
• Manages dual-pane interface (TOC and content)
• Renders content for terminal display using viewports
• Generates and manages table of contents from markdown headers
• Provides pane switching functionality

Design Patterns

Model-View-Update (MVU) Pattern

The TUI uses the Bubble Tea framework which implements the MVU pattern:

• Model: The state of the application (model struct)
• Update: Functions that modify the state based on messages (keyboard input, etc.)
• View: Function that renders the current state to the terminal

Viewport Pattern

The TUI uses dual viewports for the split-screen interface:

• TOC Viewport: Dedicated scrolling region for table of contents
• Content Viewport: Dedicated scrolling region for markdown content
• Both viewports are managed by the Bubble Tea framework

Dependency Management

The application uses Go modules for dependency management with the following key dependencies:

• github.com/charmbracelet/bubbletea: TUI framework
• github.com/charmbracelet/lipgloss: Styling library for terminal interfaces
• github.com/charmbracelet/bubbles/viewport: Viewport component for scrolling
• github.com/spf13/cobra: Command-line interface framework
• github.com/spf13/viper: Configuration management
• github.com/MichaelMure/go-term-markdown: Markdown rendering for terminals

Data Flow

1. Initialization: main.go parses command-line arguments and loads configuration
2. Content Loading: Markdown file is read and rendered for terminal display
3. Model Creation: TUI model is created with content and configuration
4. Event Loop: Bubble Tea enters event loop handling user input
5. State Updates: User actions update the model state via the Update method
6. Rendering: Changes to model trigger View method to refresh display

File Organization

gemreader/
├── cmd/
│   └── gemreader/
│       └── main.go                 # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go              # Configuration loading
│   └── tui/
│       └── tui.go                 # Terminal user interface
├── docs/                          # Documentation files
│   ├── configuration.md
│   ├── navigation.md
│   ├── api.md
│   └── architecture.md
├── config.toml                    # Default configuration
├── sample.md                      # Sample markdown file
├── go.mod                         # Go module file
├── go.sum                         # Go module checksums
├── README.md                      # Main documentation file
└── CONTRIBUTING.md                # Contribution guide

Component Responsibilities

Main Component

• Command-line argument parsing and validation
• File loading and error handling
• Configuration loading
• TUI initialization and execution

Config Component

• Loading configuration from TOML file
• Providing configuration to other components
• Handling configuration errors gracefully

TUI Component

• Managing application state
• Handling user input and navigation
• Rendering the dual-pane interface
• Managing pane switching between TOC and content
• Content display and positioning using viewports
• Generating and displaying table of contents

Security Considerations

• The application only reads files specified by the user
• No network connections are made during normal operation
• Configuration loading is restricted to local files
• Input validation is handled by the underlying libraries

Performance Characteristics

• Content is loaded entirely into memory at startup
• Navigation operations are performed in memory without file access
• Markdown rendering happens once at startup
• TOC generation happens once at startup
• Dual viewport system provides efficient scrolling in both panes

Extensibility Points

The architecture supports extension through:

• Configuration options (new fields in Config struct)
• Enhanced dual-pane functionality
• Additional keyboard controls (in Update method)
• New content processing features (in TUI package)
• Enhanced viewport behaviors and styling
• Additional TOC features and navigation options