# gtlsgamr/tt architecture

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

- Interactive diagram: https://gitdiagram.com/gtlsgamr/tt
- Repository: https://github.com/gtlsgamr/tt

## Overview

##### Project type and purpose
- This is a CLI time-tracking tool written as a shell script (“tt”).
- Purpose: let users start/stop tasks, record durations, display reports, and export raw data for piping.

##### File structure
- Top-level:
- LICENSE
- README.md
- tt  (the executable shell script)
- No separate “src” or “lib” folders – all logic lives in the single `tt` file.
- Configuration resides externally in `~/.config/tt/` (or as specified by `$TITTY_CONFIG_DIR`).

##### Key insights from README
- Commands: start, status, stop/raw, display, delete, help.
- Data persistence: writes to a “masterlist” (presumably a flat file) under the config directory.
- Integration point: raw output is piped to other tools.

##### Main components and interactions
A. User & Shell Environment
- User invokes `tt` via a shell.
- Environment variables (e.g. `$TITTY_CONFIG_DIR`) flow in.
B. tt CLI Script
1. Command Parser
– Parses subcommands, arguments, optional time offsets.
2. Timer Engine
– Calculates start/stop times, accumulates durations.
3. Configuration Manager
– Reads/writes config from `~/.config/tt/`.
4. Data Storage Interface
– Reads/writes the “masterlist” log file.
5. Output Formatter
– Generates human-readable status/display or raw lines.
C. File System
- Persistent storage of config files and logs.
D. External Tools
- Downstream pipelines consuming “tt raw” output.
- Standard POSIX utilities (date, awk, etc.) invoked by the script.

Relationships and Data Flow:
– User → Shell → tt CLI
– CLI → Command Parser → appropriate subcomponent (Timer, Config, Storage)
– Storage ↔ File System (config + log)
– Output Formatter → STDOUT → User display or pipe to external tools

##### Architectural patterns and principles
- Single-entry script with modular internal functions.
- Separation of concerns:
- Parsing vs. timing logic vs. persistence vs. formatting.
- Extensibility point: raw output for integration with other reporting tools.

##### Putting it all together
1. User & Shell
3. File System (config + logs)
4. External Tools
– Ensure labels include file paths, env variables, and command names.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User & Shell"
        User["User"]:::external
        Shell["Shell"]:::external
    end
    User --> Shell
    Shell --> tt["tt CLI Script"]:::scriptInternals

    subgraph "tt CLI"
        Parser["Command Parser"]:::scriptInternals
        Engine["Timer Engine"]:::scriptInternals
        ConfigMgr["Configuration Manager"]:::scriptInternals
        StorageIF["Data Storage Interface"]:::scriptInternals
        Formatter["Output Formatter"]:::scriptInternals
    end
    tt --> Parser
    tt --> Engine
    tt --> ConfigMgr
    tt --> StorageIF
    tt --> Formatter

    Env["$TITTY_CONFIG_DIR"]:::external
    Env --> ConfigMgr

    subgraph "File System"
        ConfigDir["~/.config/tt/"]:::external
        Masterlist["masterlist Data File"]:::external
    end
    ConfigMgr --> ConfigDir
    StorageIF --> ConfigDir
    StorageIF --> Masterlist
    ConfigDir --> Masterlist

    Formatter -->|"STDOUT"| User
    Formatter -->|"STDOUT"| Tools

    Tools["External Tools"]:::external
    tt -->|"Invokes POSIX utils"| POSIX["POSIX Utilities (date, awk, etc.)"]:::external
    POSIX --> Formatter

    click tt "https://github.com/gtlsgamr/tt/tree/main/tt"
    click Parser "https://github.com/gtlsgamr/tt/tree/main/tt"
    click Engine "https://github.com/gtlsgamr/tt/tree/main/tt"
    click ConfigMgr "https://github.com/gtlsgamr/tt/tree/main/tt"
    click StorageIF "https://github.com/gtlsgamr/tt/tree/main/tt"
    click Formatter "https://github.com/gtlsgamr/tt/tree/main/tt"
    click README.md "https://github.com/gtlsgamr/tt/blob/main/README.md"
    click LICENSE "https://github.com/gtlsgamr/tt/tree/main/LICENSE"
    click ConfigDir "https://github.com/gtlsgamr/tt/tree/main/~/.config/tt/"
    click Masterlist "https://github.com/gtlsgamr/tt/tree/main/~/.config/tt/masterlist"

    classDef scriptInternals fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
```
