# hzhang08/gocat architecture

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

- Interactive diagram: https://gitdiagram.com/hzhang08/gocat
- Repository: https://github.com/hzhang08/gocat

## Overview

##### Project type and purpose
- From the README and file tree, **gocat** is a **stand-alone, terminal‐based SGF viewer & editor** for Go game records, written in Rust.
- It is not a client–server or web app, but a single binary that runs interactively in your terminal, parsing SGF files, maintaining game state, rendering boards, and responding to keystrokes.

##### File structure
- Top-level Cargo.toml & src/ directory indicate a Rust project.
- src/main.rs: application entry point and orchestrator
- src/sgf_parser.rs: SGF file parsing and serialization
- src/game.rs: in-memory game state, move tree, annotations
- src/ui.rs: terminal rendering (drawing board, menus, dialogs)
- src/ui_mode_actions.rs: mapping user input (hotkeys) into game/UI operations

##### Key insights from the README
- Interactive, keyboard-driven interface
- Core workflows: open SGF → parse → initialize game state → render initial position → enter event loop (handle keys) → possibly mutate state → redraw → save back to SGF
- No external server or database—only filesystem I/O and terminal APIs

- CLI Entrypoint (main.rs)
- SGF Parser Module (sgf_parser.rs)
- Game State Manager (game.rs)
- UI Layer (ui.rs)
- Input/Mode Actions (ui_mode_actions.rs)
- Terminal I/O (external crate, e.g., termion/crossterm)
- File System (local storage)
b. Relationships and data flow
1) User invokes `gocat <file>.sgf` → CLI Entrypoint
2) Entrypoint calls Parser → reads SGF from File System → outputs GameRecord
3) Game State Manager loads GameRecord → exposes model API
4) UI Layer renders initial board using Game State → sends escape sequences to Terminal I/O
5) Terminal I/O captures keystrokes → forwards events to Input Handler (inside UI Layer)
6) Input Handler calls Mode Actions → Mode Actions mutate Game State or update annotations via Game State API
7) After each action, UI Layer queries Game State → produces new view → writes to Terminal I/O
8) On save/quit, Parser serializes Game State back to SGF → writes to File System
c. Architectural patterns & principles
- **Modular separation**: parser, model, UI, and input handling in distinct modules
- **MVC-like structure**:
- Model = Game State Manager
- View = UI Layer + Terminal I/O
- Controller = UI Mode Actions/Input Handler
- **Single event loop**: central loop in main.rs delegating to parser, UI, and action modules
- **Dependency flow**: main → parser, game, ui → ui_mode_actions; no circular dependencies
d. Key technologies & libraries
- Rust (Cargo, ownership model)
- SGF format (text-based game record)
- Terminal I/O crate (e.g., termion or crossterm for raw mode, input events, ANSI rendering)

## Diagram (Mermaid)

```mermaid
graph TB
    User["User"]:::external
    CLI["CLI Entrypoint"]:::app
    Parser["SGF Parser"]:::app
    Game["Game State Manager"]:::app
    subgraph "UI & Input"
        UI["UI Layer"]:::app
        Input["Input/Mode Actions"]:::app
    end
    TerminalIO["Terminal I/O (termion/crossterm)"]:::external
    FileSystem["File System"]:::external

    User -->|"runs gocat"| CLI
    CLI -->|"calls Parser"| Parser
    Parser -->|"reads SGF"| FileSystem
    Parser -->|"GameRecord"| Game
    CLI -->|"starts loop"| UI
    Game -->|"state data"| UI
    UI -->|"ANSI frames"| TerminalIO
    TerminalIO -->|"keystrokes"| Input
    Input -->|"mode actions"| Game
    Game -->|"on save"| Parser
    Parser -->|"writes SGF"| FileSystem

    click CLI "https://github.com/hzhang08/gocat/blob/master/src/main.rs"
    click Parser "https://github.com/hzhang08/gocat/blob/master/src/sgf_parser.rs"
    click Game "https://github.com/hzhang08/gocat/blob/master/src/game.rs"
    click UI "https://github.com/hzhang08/gocat/blob/master/src/ui.rs"
    click Input "https://github.com/hzhang08/gocat/blob/master/src/ui_mode_actions.rs"

    classDef app fill:#f9f,stroke:#333,stroke-width:2px;
    classDef external fill:#bbf,stroke:#333,stroke-width:2px;
```
