# carloshpds/my-worktime architecture

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

- Interactive diagram: https://gitdiagram.com/carloshpds/my-worktime
- Repository: https://github.com/carloshpds/my-worktime

## Overview

##### Project type and purpose
- This is a monorepo containing two main deliverables:
a. A CLI tool (“my-worktime”) built with oclif to record, query, and calculate work-time punches.
b. A browser extension (Chrome/Firefox) that integrates with in-browser systems (e.g., Ahgora) to display or inject work-time data into web pages.

##### Top-level structure
- bin/            → wrappers for invoking the CLI
- src/cli/        → the oclif-based CLI code (commands, logic, providers, tools, storage)
- src/cli_legacy/ → previous version of the CLI (can be shown as deprecated/archived)
- src/extension/  → the browser-extension code (background scripts, content scripts, popup UI, shared modules)
- root configs   → linting, formatting, workspace, TS and Jest configs

A. CLI Application
1. oclif Core
2. Command Layer (check, hit, hit:calc, hit:clear, etc.)
3. Business Logic
- check executor & displayer
- hit operations (calc, clear, delete, reset)
4. Providers
- Ahgora Provider (real API adapter)
- Faker Provider (mock adapter)
- LocalFileSystem Provider (persistent JSON store)
5. Tools & Utilities
- ClockHelper, i18n, LocalSettingsManager, UI formatters
6. Storage
- local JSON files via the LocalFileSystem provider
7. CLI User (terminal)
- Input: commands & CLI flags
- Output: console logs, tables, formatted resumes

B. Browser Extension
1. Manifest & Build
- manifest.json
- babel & webpack/Vue build pipeline
2. Background Scripts
- Browser-specific entrypoints (chromium, firefox)
- Communicate with content scripts & popup via message passing
- Extras: Ahgora API integration module
3. Content Scripts
- Injected into target pages to scrape or augment work-time data
4. Popup UI (Vue.js)
- Displays settings, summary of punches, etc.
5. Shared Core Modules
- Settings manager (main.setup, window.setup, observer extensions)
- Storage abstraction (chrome.storage)
- Internationalization (compiled messages, custom formatters)
- Styles & Components
6. User (browser)
- Interacts with the popup UI
- Navigates to target pages for content scripts

C. External Dependencies
- Ahgora’s REST API (for real-time point punches)
- NPM Registry (for CLI distribution)
- Chrome/Firefox extension stores

##### Relationships and data flows
- CLI flow:
Terminal → oclif CLI → Command Handler → Business Logic → Provider → External System (Ahgora) or Local FS → Logic → Displayer → Terminal
- Extension flow:
Popup UI ←→ Background Script ←→ Content Script → Web Page ↔ Ahgora Web Endpoints
Background uses Shared Storage & Settings, runs health checks, analytics
- Shared code (in extension): Settings & storage abstractions used by both background and content contexts

##### Architectural patterns & design principles
- Separation of concerns
- CLI: commands vs logic vs providers vs tools vs storage
- Extension: UI vs background vs content vs shared core
- Adapter pattern for providers (Ahgora, Faker, LocalFS)
- Message-passing event bus in extension (Chrome runtime messaging)
- Plugin-based CLI via oclif
- Modular shared code in extension (core, extras, tools)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Application Layer
    subgraph "CLI Application" 
        direction TB
        OclifCore["oclif Core"]:::cli
        subgraph "Command Layer" 
            direction TB
            CheckCmd["check.ts"]:::cli
            HitCmd["hit/"]:::cli
        end
        subgraph "Business Logic" 
            direction TB
            LogicCheck["logic/check"]:::cli
            LogicSetup["logic/setup"]:::cli
        end
        subgraph "Providers (Adapters)" 
            direction TB
            AhgoraProvider["Ahgora"]:::cli
            FakerProvider["Faker"]:::cli
            FSProvider["LocalFileSystem"]:::cli
            WorktimeProvider["WorktimeProvider"]:::cli
        end
        subgraph "Tools & Utilities" 
            direction TB
            ClockHelper["ClockHelper"]:::cli
            SettingsMgr["LocalSettingsManager"]:::cli
            I18nTool["i18n"]:::cli
            StorageTool["tools/storage"]:::cli
            UILogger["ui/logAppName"]:::cli
        end
        StorageFS["Local JSON Storage"]:::cli
        CLIUser["CLI User (Terminal)"]:::external
    end

    %% Legacy CLI
    subgraph "Legacy CLI (Deprecated)" 
        direction TB
        LegacyCLI["src/cli_legacy"]:::legacy
    end

    %% Browser Extension Layer
    subgraph "Browser Extension" 
        direction TB
        subgraph "Manifest & Build" 
            direction TB
            Manifest["manifest.json"]:::ext
            BabelConfig["babel.config.js"]:::ext
            VueConfig["vue.config.js"]:::ext
        end
        subgraph "Background Scripts" 
            direction TB
            BGChromium["chromium/background.js"]:::ext
            BGFirefox["firefox/background.js"]:::ext
            BGEntry["background.js"]:::ext
        end
        subgraph "Content Scripts" 
            direction TB
            ContentScript["index.js"]:::ext
        end
        subgraph "Popup UI (Vue.js)" 
            direction TB
            PopupVue["PopupApp.vue"]:::ext
            PopupTS["index.ts"]:::ext
            PopupHTML["popup.html"]:::ext
        end
        subgraph "Shared Core Modules" 
            direction TB
            CoreBrowser["core/browser"]:::ext
            CoreSettings["main.setup.ts"]:::ext
            CoreStyles["styles"]:::ext
        end
        subgraph "Extension Storage" 
            direction TB
            ExtStorage["tools/storage"]:::ext
        end
        subgraph "Internationalization" 
            direction TB
            ExtI18n["languages"]:::ext
        end
        subgraph "Extras & Analytics" 
            direction TB
            AhgoraAPI["ahgora/api"]:::ext
            Analytics["tools/analytics"]:::ext
            HealthCheck["health/checkGCSelectors.js"]:::ext
        end
        BrowserUser["Browser User"]:::external
    end

    %% External Systems
    subgraph "External Dependencies" 
        direction TB
        AhgoraAPIExt["Ahgora REST API"]:::external
        NPMReg["NPM Registry"]:::external
        Store["Chrome/Firefox Store"]:::external
    end

    %% Connections CLI
    CLIUser -->|"commands & flags"| OclifCore
    OclifCore -->|loads| CheckCmd
    OclifCore -->|loads| HitCmd
    CheckCmd -->|invokes| LogicCheck
    HitCmd -->|invokes| LogicSetup
    LogicCheck -->|uses| AhgoraProvider
    LogicCheck -->|uses| FakerProvider
    LogicCheck -->|uses| FSProvider
    LogicSetup -->|uses| WorktimeProvider
    LogicCheck -->|calls| ClockHelper
    LogicCheck -->|calls| SettingsMgr
    LogicSetup -->|calls| I18nTool
    LogicSetup -->|calls| UILogger
    FSProvider -->|reads/writes| StorageFS
    StorageFS -->|persists| CLIUser
    LogicCheck -->|outputs| CLIUser

    %% Connections Extension
    BrowserUser -->|opens| PopupVue
    PopupVue -->|sends message| BGEntry
    BGEntry -->|message| BGChromium
    BGEntry -->|message| BGFirefox
    BGEntry -->|communicates| ContentScript
    ContentScript -->|injects/scrape| BrowserUser
    BGEntry -->|uses| CoreBrowser
    BGEntry -->|uses| CoreSettings
    ContentScript -->|uses| CoreBrowser
    CoreBrowser -->|stores| ExtStorage
    CoreSettings -->|i18n| ExtI18n
    BGEntry -->|calls| AhgoraAPI
    AhgoraAPI -->|HTTP request| AhgoraAPIExt
    Analytics -->|collects| BGEntry
    HealthCheck -->|runs| BGEntry

    %% External relationships
    OclifCore -->|publish| NPMReg
    BrowserUser -->|downloads| Store

    %% Legacy
    LegacyCLI -.->|deprecated| OclifCore

    %% Click events - CLI
    click OclifCore "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/index.ts"
    click CheckCmd "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/commands/check.ts"
    click HitCmd "https://github.com/carloshpds/my-worktime/tree/master/src/cli/src/commands/hit"
    click LogicCheck "https://github.com/carloshpds/my-worktime/tree/master/src/cli/src/logic/check"
    click LogicSetup "https://github.com/carloshpds/my-worktime/tree/master/src/cli/src/logic/setup"
    click AhgoraProvider "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/providers/Ahgora/index.ts"
    click FakerProvider "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/providers/Faker/index.ts"
    click FSProvider "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/providers/LocalFileSystem/index.ts"
    click WorktimeProvider "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/providers/WorktimeProvider.ts"
    click ClockHelper "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/tools/ClockHelper/index.ts"
    click SettingsMgr "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/tools/LocalSettingsManager/index.ts"
    click I18nTool "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/tools/i18n/index.ts"
    click StorageTool "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/tools/storage/index.ts"
    click UILogger "https://github.com/carloshpds/my-worktime/blob/master/src/cli/src/tools/ui/logAppName.ts"
    click LegacyCLI "https://github.com/carloshpds/my-worktime/tree/master/src/cli_legacy"

    %% Click events - Extension
    click Manifest "https://github.com/carloshpds/my-worktime/blob/master/src/extension/manifest.json"
    click BabelConfig "https://github.com/carloshpds/my-worktime/blob/master/src/extension/babel.config.js"
    click VueConfig "https://github.com/carloshpds/my-worktime/blob/master/src/extension/vue.config.js"
    click BGChromium "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/apps/backgroundScripts/browser/chromium/background.js"
    click BGFirefox "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/apps/backgroundScripts/browser/firefox/background.js"
    click BGEntry "https://github.com/carloshpds/my-worktime/blob/master/src/extension/background.js"
    click ContentScript "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/apps/contentScripts/index.js"
    click PopupVue "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/apps/popup/PopupApp.vue"
    click PopupTS "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/apps/popup/index.ts"
    click PopupHTML "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/apps/popup/popup.html"
    click CoreBrowser "https://github.com/carloshpds/my-worktime/tree/master/src/extension/src/shared/core/browser"
    click CoreSettings "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/shared/core/settings/main.setup.ts"
    click CoreStyles "https://github.com/carloshpds/my-worktime/tree/master/src/extension/src/shared/core/styles"
    click ExtStorage "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/shared/tools/storage/index.ts"
    click ExtI18n "https://github.com/carloshpds/my-worktime/tree/master/src/extension/src/shared/core/browser/languages"
    click AhgoraAPI "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/shared/extras/ahgora/api/index.ts"
    click Analytics "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/shared/tools/analytics/index.ts"
    click HealthCheck "https://github.com/carloshpds/my-worktime/blob/master/src/extension/src/shared/tools/health/checkGCSelectors.js"

    %% Styles
    classDef cli fill:#e0ffe0,stroke:#008000,color:#000
    classDef ext fill:#e0f0ff,stroke:#0066cc,color:#000
    classDef external fill:#ffe0b2,stroke:#e65100,color:#000
    classDef legacy fill:#f0f0f0,stroke:#999999,color:#666
    classDef externalIcon fill:#fff,stroke:#000,color:#000
    classDef cli,ext,external,legacy external-icon
```
