How carloshpds/my-worktime works
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)