# alexmelanfromringo/rust-md-reader-tui architecture

> Architecture diagram of the GitHub repository alexmelanfromringo/rust-md-reader-tui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexmelanfromringo/rust-md-reader-tui
- Repository: https://github.com/alexmelanfromringo/rust-md-reader-tui

## Overview

##### Project Type and Purpose
- This is a console-based Markdown reader (MD Reader) written in Rust.
- It provides a TUI (text-based user interface) to list and view `.md` files with syntax formatting.
- No client-server or network-based components—everything runs as a single binary interacting with the file system and terminal.

##### File Structure
- Top-level files:
- Cargo.toml / Cargo.lock: Rust project definition + dependencies
- build.sh: build script targeting Windows and Linux
- src/main.rs: entire application logic in one executable
- README.md, LICENSE
- No separate “backend” vs “frontend” folders: this is a monolithic CLI app.
- Dependencies (in Cargo.toml): `ratatui`, `crossterm`, `pulldown-cmark`, `anyhow`.

##### Extract Key Architecture Insights from README
- Core modules implied:
- File Scanner: discover `.md` files in a directory
- File List UI: render list of filenames and capture navigation keystrokes
- Markdown Parser: convert raw Markdown to an AST or formatted spans (`pulldown-cmark`)
- Input Handler: read keystrokes and dispatch commands (`crossterm`)
- Error Handling: layered error management (`anyhow`)
- Workflow:
1. Launch app with folder path →
2. Scan directory → produce file list →
3. Render list view → await input →
4. On “Enter”, read chosen file → parse → render document view →
5. Handle scroll/navigation → back to list on `q`.

##### Main Components
- File System Interface
- Application Core
- FileScanner Module
- UiManager Module
- Parser Module
- Renderer Module
- InputController Module
- ErrorManager Module
- External Crates / Libraries
- `crossterm` (terminal I/O)
- `ratatui` (TUI rendering)
- `pulldown-cmark` (Markdown parsing)
- `anyhow` (error handling)
- OS Terminal

##### Relationships and Data Flows
- FileScanner ↔ OS File System: directory read, file read
- InputController → UiManager: keystroke events
- UiManager → Renderer: layout & drawing calls
- Parser → Renderer: formatted tokens → stylized output
- Renderer → Terminal (via crossterm)
- ErrorManager catches errors from FileScanner, Parser, Renderer, InputController

##### Architectural Patterns & Principles
- Modular separation by responsibility (Single Responsibility Principle)
- Event-driven loop (input → update state → render)
- Synchronous, single-threaded execution
- Minimal dependencies and clear layering (core logic vs external crates)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External crates
    subgraph "External Crates"
        Cros["crossterm"]:::external
        Ratu["ratatui"]:::external
        PDM["pulldown-cmark"]:::external
        Anyw["anyhow"]:::external
    end

    %% Application core
    subgraph "MD Reader Application"
        FS["FileScanner Module"]:::internal
        IC["InputController Module"]:::internal
        UI["UiManager Module"]:::internal
        PR["Parser Module"]:::internal
        RE["Renderer Module"]:::internal
        ER["ErrorManager Module"]:::internal
    end

    %% OS and scripts/docs
    FileSys[(File System)]:::resource
    Term[(Terminal)]:::resource
    BS["Build Script"]:::script
    PD["Project Definition"]:::script
    Doc["README.md"]:::doc
    Lic["LICENSE"]:::doc

    %% Build and project
    BS --> PD
    Doc --> PD
    Lic --> PD

    %% Crates to modules
    Cros --> IC
    Ratu --> UI
    Ratu --> RE
    PDM --> PR
    Anyw --> ER

    %% Core flows
    FS -->|reads| FileSys
    IC -->|keystrokes| Term
    IC -->|events| UI
    UI -->|layout| RE
    PR -->|tokens| RE
    RE -->|draws| Term

    %% Error handling
    FS --> ER
    IC --> ER
    UI --> ER
    PR --> ER
    RE --> ER

    %% Module ordering
    class FS,IC,UI,PR,RE,ER internal

    %% Click events
    click FS "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/src/main.rs"
    click IC "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/src/main.rs"
    click UI "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/src/main.rs"
    click PR "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/src/main.rs"
    click RE "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/src/main.rs"
    click ER "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/src/main.rs"
    click Cros "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/Cargo.toml"
    click Ratu "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/Cargo.toml"
    click PDM "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/Cargo.toml"
    click Anyw "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/Cargo.toml"
    click BS "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/build.sh"
    click PD "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/Cargo.toml"
    click Doc "https://github.com/alexmelanfromringo/rust-md-reader-tui/blob/main/README.md"
    click Lic "https://github.com/alexmelanfromringo/rust-md-reader-tui/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#3399ff;
    classDef external fill:#ffe0b3,stroke:#ff9900;
    classDef resource fill:#d5f5e3,stroke:#27ae60;
    classDef script fill:#ebedef,stroke:#7f8c8d;
    classDef doc fill:#f9e79f,stroke:#f1c40f;
```
