# blachniet/tgl architecture

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

- Interactive diagram: https://gitdiagram.com/blachniet/tgl
- Repository: https://github.com/blachniet/tgl

## Overview

##### Project type and purpose
- This is a Rust-based command-line application (“tgl-cli”) that interfaces with the Toggl time-tracking API.
- Its primary function is to let end users execute Toggl operations (e.g., start/stop timers, list projects) directly from the terminal.

##### File structure
- Top level:
- Cargo.toml, Cargo.lock, src/, examples/
- .github/workflows/ci.yml for CI on GitHub Actions
- src/:
- main.rs → CLI entry point, reads config (API token), invokes library APIs
- lib.rs → crate root, re-exports modules
- api.rs → defines HTTP client logic for interacting with Toggl REST API
- svc.rs → high-level service layer that coordinates use cases (e.g., start/stop) by calling api.rs and handling business logic
- examples/:
- api.rs and svc.rs showing how to use the library in other Rust code

##### README for additional insights
- Dependencies: uses the system keyring for token storage or environment variable TOGGL_API_TOKEN
- Usage flow described: first-run token prompt → store in keyring → subsequent runs skip prompt
- Irreversible actions: token persistence in OS keyring

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (main.rs)"]:::internal
    end

    %% Library Layer
    subgraph "Library Layer"
        LIB["Library Root (lib.rs)"]:::internal
        SVC["Service Layer (svc.rs)"]:::internal
        API["API Client (api.rs)"]:::internal
    end

    %% Examples
    subgraph "Examples"
        EX_API["API Client Usage (examples/api.rs)"]:::internal
        EX_SVC["Service Layer Usage (examples/svc.rs)"]:::internal
    end

    %% External Components
    subgraph "External Services"
        CRED["Credentials Store (Keyring/ENV)"]:::storage
        TOGGL["Toggl HTTP API"]:::cloud
    end

    %% CI/CD & Docs
    subgraph "Project Artifacts"
        CI["GitHub Actions CI (ci.yml)"]:::external
        MANIFEST["Manifest & Dependencies (Cargo.toml)"]:::external
        README["Documentation (README.md)"]:::external
    end

    %% Data Flows
    User(["User"]):::external -->|"invoke CLI"| CLI
    CLI -->|"calls Service Layer"| SVC
    SVC -->|"fetch token"| CRED
    SVC -->|"invoke API client"| API
    API -->|"HTTP JSON request"| TOGGL
    TOGGL -->|"JSON response"| API
    API -->|"response data"| SVC
    SVC -->|"formatted output"| CLI

    %% Examples usage
    EX_API -->|"uses API client"| API
    EX_SVC -->|"uses Service Layer"| SVC

    %% Project artifacts relations
    CLI --- MANIFEST
    SVC --- MANIFEST
    API --- MANIFEST
    LIB --- MANIFEST
    CI ---|"tests build"| MANIFEST
    README --- MANIFEST

    %% Click Events
    click CLI "https://github.com/blachniet/tgl/blob/master/src/main.rs"
    click SVC "https://github.com/blachniet/tgl/blob/master/src/svc.rs"
    click API "https://github.com/blachniet/tgl/blob/master/src/api.rs"
    click LIB "https://github.com/blachniet/tgl/blob/master/src/lib.rs"
    click EX_API "https://github.com/blachniet/tgl/blob/master/examples/api.rs"
    click EX_SVC "https://github.com/blachniet/tgl/blob/master/examples/svc.rs"
    click CI "https://github.com/blachniet/tgl/blob/master/.github/workflows/ci.yml"
    click MANIFEST "https://github.com/blachniet/tgl/blob/master/Cargo.toml"
    click README "https://github.com/blachniet/tgl/blob/master/README.md"

    %% Styles
    classDef internal fill:#d9edf7,stroke:#31708f,color:#31708f
    classDef external fill:#dff0d8,stroke:#3c763d,color:#3c763d
    classDef storage fill:#fcf8e3,stroke:#8a6d3b,color:#8a6d3b
    classDef cloud fill:#f5f5f5,stroke:#bbbbbb,color:#555555
```
