# krbreyn/gemcat architecture

> Architecture diagram of the GitHub repository krbreyn/gemcat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krbreyn/gemcat
- Repository: https://github.com/krbreyn/gemcat

## Overview

##### Project Type & Purpose
- Gemcat is a terminal-based, CLI-focused browser for the Gemini protocol (with Gopher support and planned RSS/TUI features). Its purpose is to let users fetch and read Gemini content using command-based interactions in a terminal.
- The README clearly explains that users can run a simple command to fetch content or launch an interactive (shell-/TUI-based) mode for navigation, making it a command-line browser utility.

##### Analyzing the File Structure
- Top-Level Files:
– README.md: Explains usage and features.
– gemcat.go: Likely contains core initialization or shared logic.
– go.mod and go.sum: Dependency management, confirming that this is a Go application.
- Key Directories:
- browser: Contains the core Gemini protocol implementation including:
– browser.go and fetch.go: Likely manage core protocol transmissions, fetching remote data.
– cmd.go and various cmd_*.go files (cmd_bookmark.go, cmd_history.go, etc.): Implement various commands for handling bookmarks, history, navigation, link handling, and stack management. They form the basis of the interactive command execution.
– shell.go: Likely manages the interactive shell loop.
- cmd: Contains the project’s entry point (main.go) which ties everything together.
- data: Contains data-related functionality (data.go) plus a dedicated gemtext module (in gemtext/gemtext.go) to parse/render Gemini content.
- interactive: Includes both CLI (cli.go) and prospective TUI components (tui.go) to support interactive user interface options.
- tofu: Provides additional features (tofu.go) that might complement the Gemini functionalities or provide utility functions.

- Observations:
– There is a separation between protocol handling (in the browser package), user interaction (in interactive), and data parsing (in data/gemtext).
– The file tree suggests modular design: each major aspect of the application is split into its own package or module.

##### Key Components to be Illustrated
a. User Interaction Layer:
- Command-Line Interface: Represented by the “cmd” (main.go) that starts the application and the “interactive” package (cli.go and tui.go) that handles interactive command input and (in the future) graphical interactions.
b. Core Gemini Browser Engine:
- Browser Module: Highlight the “browser” directory that implements the core functionality including fetching content (fetch.go), executing commands (various cmd_*.go files), and running the shell (shell.go).
c. Data Parsing & Content Rendering:
- Data Module: Capture the “data” directory’s role in managing data processing.
- Gemtext Module: Within data/gemtext, show that it handles parsing/rendering Gemini text.
d. Additional Utilities/Features:
- Tofu Module: Indicate the “tofu” directory as an auxiliary component, possibly providing extra functionality or processing tools.

##### Depicting Relationships & Interactions
- How the interactive CLI or TUI (interactive package) forwards commands to the browser module.
- Demonstrate that the browser engine coordinates tasks such as fetching data (through fetch.go), executing commands (via cmd_*.go), and maintaining session state (possibly in shell.go).
- That once data is fetched, it gets handed over to the data/gemtext module for parsing/rendering.
- That any additional utilities (like what may be in tofu/tofu.go) integrate with the core workflow.

##### Architectural Patterns & Design Principles
- Modular Design: Clearly separate concerns by grouping interaction logic, core browser functionality, and data parsing into different packages.
- Command-Driven Architecture: Emphasize that the application processes discrete commands (see multiple cmd_*.go files) following a command pattern.
- Layered Approach: Start with the UI layer (CLI/TUI), proceed to a command dispatch or shell layer, then to the content fetching and data processing layers.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "User Interaction Layer"
    UI1["CLI Interface"]:::ui
    UI2["TUI Interface (Planned)"]:::ui
  end

  MP["Main Process (cmd/main.go)"]:::entry

  UI1 --> MP
  UI2 --> MP

  BE["Browser Engine"]:::browser
  MP --> BE

  subgraph "Data Parsing & Content Rendering"
    DM["Data Module"]:::data
    GP["Gemtext Parser"]:::data
  end

  BE --> DM
  BE --> GP

  TU["Tofu Module"]:::utility
  BE --> TU

  click UI1 "https://github.com/krbreyn/gemcat/blob/master/interactive/cli.go"
  click UI2 "https://github.com/krbreyn/gemcat/blob/master/interactive/tui.go"
  click MP "https://github.com/krbreyn/gemcat/blob/master/cmd/main.go"
  click BE "https://github.com/krbreyn/gemcat/tree/master/browser"
  click DM "https://github.com/krbreyn/gemcat/blob/master/data/data.go"
  click GP "https://github.com/krbreyn/gemcat/blob/master/gemtext/gemtext.go"
  click TU "https://github.com/krbreyn/gemcat/blob/master/tofu/tofu.go"

  classDef ui fill:#F9E79F,stroke:#000,stroke-width:2px;
  classDef entry fill:#AED6F1,stroke:#000,stroke-width:2px;
  classDef browser fill:#A9DFBF,stroke:#000,stroke-width:2px;
  classDef data fill:#F5B7B1,stroke:#000,stroke-width:2px;
  classDef utility fill:#D2B4DE,stroke:#000,stroke-width:2px;
```
