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