# ypatel2022/ttt architecture

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

- Interactive diagram: https://gitdiagram.com/ypatel2022/ttt
- Repository: https://github.com/ypatel2022/ttt

## Overview

##### Project Type and Purpose
- CLI/TUI application written in Go
- Provides typing tests in 200+ natural and programming languages
- Uses Bubble Tea for UI, Lipgloss for styling, Viper for config

##### File Structure
- ttt/
– main.go: application entrypoint
– app.go, model.go, ui.go: Bubble Tea model-view components
– config_picker.go, settings.go: settings menu and config management
– calculations.go: WPM & accuracy logic
– test.go: test orchestration
- config.yaml: persistent settings store
- languages/*.json: static word-list data sets
- assets/: images for README demos
- go.mod/go.sum: dependencies including Bubble Tea, Lipgloss, Viper

##### README Insights
- Describes three logical segments: configuration, UI, test logic
- Highlights use of external libs (Bubble Tea, Lipgloss, Viper)
- Language files sourced externally but used locally

##### Main Components and Their Relationships
a. User Interface Layer
– Bubble Tea framework (third-party)
– ui.go: defines View functions, keybindings, menu screens
– Lipgloss styling library
b. Application Core
– Model (model.go): holds current state (menu selection, test state)
– Controller logic (app.go): orchestrates transitions & commands
– Calculations (calculations.go): computes WPM/accuracy
– Test orchestration (test.go): picks words, tracks progress
c. Configuration
– settings.go & config_picker.go: read/write config.yaml via Viper
– config.yaml: YAML file persisted on disk
d. Data Store
– languages/*.json: JSON files loaded at runtime for word sets
– file-I/O module (part of core)
e. Entry Point
– main.go: initializes Viper, loads config, boots Bubble Tea program

##### Interactions and Data Flows
- On startup:
→ main.go loads config.yaml (Viper)
→ loads language JSON into memory
→ initializes Bubble Tea Program with model, view, update
- User navigates menus:
→ ui.go dispatches keystrokes → update() in model → view() renders UI
- Starting a test:
→ test.go selects words, updates model
→ calculations.go tracks keystrokes → computes metrics
→ UI layer displays live WPM/accuracy
- Settings change:
→ config_picker.go writes back to config.yaml (Viper)

##### Architectural Patterns and Principles
- MVC-style layering:
– Model: model.go
– View/Controller: ui.go & app.go
- Single-process, event-driven architecture provided by Bubble Tea
- Separation of concerns: UI, config, data, business logic separated into packages/files
- Static resources (languages) decoupled from code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    Entry["Entry Point\n(main.go)"]:::external
    Terminal["Terminal\n(STDIN/STDOUT)"]:::external

    %% Data Sources Layer
    subgraph "Data Sources" 
        direction TB
        ConfigStore["Config File\n(config.yaml)"]:::data
        LanguageStore["Language Files\n(languages/*.json)"]:::data
        Assets["Static Assets\n(assets/)"]:::data
    end

    %% Third-Party Libraries Layer
    subgraph "Third-Party Libraries"
        direction TB
        BubbleTea["Bubble Tea"]:::thirdParty
        Lipgloss["Lipgloss"]:::thirdParty
        Viper["Viper"]:::thirdParty
    end

    %% Configuration Manager Layer
    subgraph "Configuration Manager"
        direction TB
        SettingsMgr["Settings Manager\n(settings.go)"]:::core
        ConfigPicker["Config Picker UI\n(config_picker.go)"]:::ui
    end

    %% Application Core Layer
    subgraph "Application Core"
        direction TB
        Controller["Controller Logic\n(app.go)"]:::core
        Model["Model State\n(model.go)"]:::core
        TestOrch["Test Orchestration\n(test.go)"]:::core
        Calculations["Calculations\n(calculations.go)"]:::core
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        UIModule["UI Module\n(ui.go)"]:::ui
    end

    %% Legend
    subgraph "Legend"
        direction LR
        UIClass["UI Layer"]:::ui
        CoreClass["Core Logic"]:::core
        DataClass["Data Store"]:::data
        ThirdClass["Third-Party"]:::thirdParty
        ExternalClass["External"]:::external
    end

    %% Connections
    Entry -->|"loads config"| ConfigStore
    Entry -->|"loads languages"| LanguageStore
    Entry -->|"starts program"| BubbleTea
    Entry -->|"initializes Viper"| Viper

    BubbleTea -->|"renders"| Terminal
    Terminal -->|"user input"| BubbleTea

    BubbleTea -->|"UI loop"| UIModule
    UIModule -->|"dispatch keystrokes"| Controller
    UIModule -->|"uses styling"| Lipgloss

    Controller -->|"updates state"| Model
    Controller -->|"starts test"| TestOrch
    TestOrch -->|"selects words"| LanguageStore
    TestOrch -->|"updates state"| Model

    Controller -->|"invoke calculations"| Calculations
    Calculations -->|"compute WPM/Accuracy"| Model

    Model -->|"state changes"| UIModule

    UIModule -->|"open config picker"| ConfigPicker
    ConfigPicker -->|"write settings"| ConfigStore
    ConfigPicker -->|"uses Viper"| Viper

    %% Click Events
    click Entry "https://github.com/ypatel2022/ttt/blob/main/ttt/main.go"
    click UIModule "https://github.com/ypatel2022/ttt/blob/main/ttt/ui.go"
    click Controller "https://github.com/ypatel2022/ttt/blob/main/ttt/app.go"
    click Model "https://github.com/ypatel2022/ttt/blob/main/ttt/model.go"
    click Calculations "https://github.com/ypatel2022/ttt/blob/main/ttt/calculations.go"
    click TestOrch "https://github.com/ypatel2022/ttt/blob/main/ttt/test.go"
    click SettingsMgr "https://github.com/ypatel2022/ttt/blob/main/ttt/settings.go"
    click ConfigPicker "https://github.com/ypatel2022/ttt/blob/main/ttt/config_picker.go"
    click ConfigStore "https://github.com/ypatel2022/ttt/blob/main/config.yaml"
    click LanguageStore "https://github.com/ypatel2022/ttt/tree/main/languages/"
    click Assets "https://github.com/ypatel2022/ttt/tree/main/assets/"
    click BubbleTea "https://github.com/ypatel2022/ttt/blob/main/go.mod"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef data fill:#FFFFE0,stroke:#000
    classDef thirdParty fill:#FFA500,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
    class UIClass,Controller,Model,TestOrch,Calculations,SettingsMgr,ConfigPicker,Entry,Tail,LanguageStore,Assets,ConfigStore external
    class UIClass ui
    class CoreClass core
    class DataClass data
    class ThirdClass thirdParty
    class ExternalClass external
```
