# wakatime/wakatime-cli architecture

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

- Interactive diagram: https://gitdiagram.com/wakatime/wakatime-cli
- Repository: https://github.com/wakatime/wakatime-cli

## Overview

##### Project Type and Purpose
- This is a **Go command‐line interface (CLI)**.
- Its sole purpose is to collect “heartbeats” (editor usage data) via subcommands, process or store them offline, then send them to the WakaTime API server.  It also reads/writes a common INI config file and provides utility commands (e.g. `offline`, `today`, `version`, etc.) for plugin authors.

##### File Structure
- **Top‐Level Entry**: `main.go` + `cmd/` subdirectories.  The CLI framework (Cobra) is set up in `cmd/root.go`, with individual subcommands in `cmd/<name>/`.
- **Domain Libraries**: `pkg/` contains all core logic, organized by concern:
- `pkg/api` – HTTP transport, authentication, request/response definitions
- `pkg/heartbeat` – heartbeat creation, sanitization, formatting
- `pkg/project` – project detection (Git, Hg, SVN, TFVC)
- `pkg/language` + `pkg/lexer` – language identification, syntax lexers
- `pkg/offline` + `cmd/offline*` – offline storage and replay
- `pkg/fileexperts`, `pkg/filter`, `pkg/summary`, `pkg/log`, `pkg/metrics` – auxiliary processing
- `pkg/file`, `pkg/ini`, `pkg/version`, etc. – configuration & I/O
- **Build & CI**: `Makefile`, GitHub Actions workflows, tests under `*_test.go` in each package.

##### README for Insights
- Confirms it is the **shared CLI** for editor plugins, driven by an INI config (`~/.wakatime.cfg`).
- Points to usage, troubleshooting, plugin author docs.

##### Components and Their Interactions

A. CLI Layer
- **Entrypoint** (`main.go`)
- **Command Dispatcher** (`cmd/root.go` + subcommands in `cmd/*`)
– Each subcommand invokes one or more domain services (e.g. `heartbeat`, `offlinecount`, `today`).

B. Configuration Manager
- Reads/Writes **INI config** (`pkg/ini`)
- Supplies API keys, base URL, offline settings to other modules

C. Domain Services
1. **Heartbeat Service** (`pkg/heartbeat`)
– Collects file metadata, language, project info
– Sanitizes and formats heartbeats
2. **Project Detector** (`pkg/project`)
– Inspects VCS dirs (Git, Hg, SVN, TFVC) to determine project name
3. **Language & Lexer** (`pkg/language`, `pkg/lexer`)
– Determines file’s programming language and other attributes
4. **FileExperts** (`pkg/fileexperts`)
– Calls external service to augment file metadata
5. **Offline Store** (`pkg/offline`)
– Saves heartbeats locally when API unreachable
– Replays them in batch later

D. Infrastructure
- **HTTP Client** (`pkg/api/transport*`) – makes REST calls to WakaTime API
- **Logging & Metrics** (`pkg/log`, `pkg/metrics`) – writes logs, collects internal metrics
- **Error Handling** (`pkg/wakaerror`, `pkg/exitcode`) – consistent error messages and exit codes

E. External Service
- **WakaTime API Server** – receives heartbeats, returns responses

##### Architectural Patterns and Principles
- **Layered Architecture**: Separation between CLI layer, domain services, infrastructure (HTTP, logging), and external API.
- **Modular Packaging**: Each `pkg/*` is an independent Go package with its own tests.
- **Single‐Responsibility**: Commands do not perform business logic—they delegate to `pkg/` services.
- **Resilience**: Offline queuing and retry/backoff (`pkg/backoff`) ensure reliability.

##### Detailed Component Breakdown (suggest grouping rather than exhaustive listing)
- `pkg/backoff` attached to the HTTP Client, indicating retry logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External INI config
    INI["INI Config File"]:::external

    %% Main system
    subgraph "WakaTime CLI"
        subgraph "Control Layer"
            Entrypoint["Entrypoint\nmain.go"]:::cli
            Root["Command Dispatcher\ncmd/root.go"]:::cli
            Subcmds["CLI Subcommands\ncmd/<subcommand>/"]:::cli
            VersionCmd["Version Command\ncmd/version.go"]:::cli
        end

        subgraph "Domain & Infrastructure"
            subgraph "Configuration Manager"
                INIpkg["INI Config I/O\npkg/ini/ini.go"]:::domain
                APIKey["API Key Loader\npkg/apikey/apikey.go"]:::domain
            end

            subgraph "Domain Services"
                HB["Heartbeat Service\npkg/heartbeat/heartbeat.go"]:::domain
                PD["Project Detector\npkg/project/project.go"]:::domain
                LI["Language & Lexer\npkg/language/language.go"]:::domain
                FX["FileExperts Service\npkg/fileexperts/fileexperts.go"]:::domain
                OS["Offline Store & Replay\npkg/offline/offline.go"]:::domain
            end

            subgraph "Infrastructure"
                HTTP["HTTP Client & API Transport\npkg/api/transport.go"]:::infra
                LOG["Logging\npkg/log/log.go"]:::infra
                MET["Metrics\npkg/metrics/metrics.go"]:::infra
                ERR["Error Handling\npkg/wakaerror/wakaerror.go"]:::infra
                BACK["Retry/Backoff Logic\npkg/backoff/backoff.go"]:::infra
            end
        end
    end

    %% External API
    APIServer("WakaTime API Server"):::external

    %% Connections
    INI -->|reads/writes| INIpkg
    Entrypoint -->|initializes| Root
    Root -->|dispatches| Subcmds
    Root -->|handles| VersionCmd

    Subcmds -->|invoke| HB
    Subcmds -->|invoke| OS
    Subcmds -->|invoke| FX
    Subcmds -->|invoke| PD
    Subcmds -->|invoke| LI

    INIpkg -->|provides config| HB
    INIpkg -->|provides config| OS
    INIpkg -->|provides config| HTTP

    APIKey -->|provides API key| HTTP

    HB -->|collects data| PD
    HB -->|collects data| LI
    HB -->|augments| FX

    HB -->|requests| HTTP
    OS -->|flush/replay| HTTP

    HTTP -->|sends heartbeats| APIServer
    BACK -->|retry logic| HTTP

    HB -->|logs/metrics| LOG
    OS -->|logs/metrics| LOG
    HTTP -->|logs| LOG
    HB -->|metrics| MET
    HTTP -->|metrics| MET
    Subcmds -->|error handling| ERR
    HTTP -->|error handling| ERR

    %% Click Events
    click Entrypoint "https://github.com/wakatime/wakatime-cli/blob/develop/main.go"
    click Root "https://github.com/wakatime/wakatime-cli/blob/develop/cmd/root.go"
    click Subcmds "https://github.com/wakatime/wakatime-cli/tree/develop/cmd/<subcommand>/"
    click VersionCmd "https://github.com/wakatime/wakatime-cli/blob/develop/cmd/version.go"
    click INIpkg "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/ini/ini.go"
    click APIKey "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/apikey/apikey.go"
    click HTTP "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/api/transport.go"
    click HB "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/heartbeat/heartbeat.go"
    click PD "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/project/project.go"
    click LI "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/language/language.go"
    click FX "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/fileexperts/fileexperts.go"
    click OS "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/offline/offline.go"
    click LOG "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/log/log.go"
    click MET "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/metrics/metrics.go"
    click ERR "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/wakaerror/wakaerror.go"
    click BACK "https://github.com/wakatime/wakatime-cli/blob/develop/pkg/backoff/backoff.go"

    %% Styles
    classDef cli fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef domain fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef infra fill:#e0e0e0,stroke:#424242,color:#424242
    classDef external fill:#ffe082,stroke:#ff6f00,color:#ff6f00
```
