Upload files to "docs"

docs/architecture.md

@@ -0,0 +1,161 @@
+# 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