Overview and Architecture

Mr. Tick was designed with a decentralized, decoupled, provider-agnostic architecture.

The main application (Core Desktop) contains no business rules tied to specific tools such as Jira, Redmine, YouTrack, Discord, Google, or Microsoft. Extensibility, task synchronization, activity monitoring, and visual themes are exposed through standardized extensions using @mr-tick/sdk.

🏛️ Layered Architecture

The Mr. Tick ecosystem separates layers with clearly defined responsibilities:

┌────────────────────────────────────────────────────────┐
│                   Mr-tick Core Desktop                  │
│  (Windows, Native Timers , Keytar Vault, AddonLoader)  │
└──────────────────────────┬─────────────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────┐
│                 Application & Domain Engine            │
│    (@mr-tick/domain  &  @mr-tick/application)    │
│  (Workspaces, TimeEntries, Tasks, HTTP Sync Engine)    │
└──────────────────────────┬─────────────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────┐
│                   Official Mr-tick SDK                   │
│                  (@mr-tick/sdk)                     │
│    (IAddon, AddonContext, IAddonOAuthAPI, Vault, Events)  │
└──────────────────────────┬─────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
 ┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐
 │ DataSources │    │  Watchers   │    │  Calendars  │ ...
 └─────────────┘    └─────────────┘    └─────────────┘

1. Core Desktop (Electron / Node.js)

Manages application lifecycle, windows, global shortcuts, encrypted persistence in the native operating system keychain (Windows Credential Manager / macOS Keychain through Keytar), and isolated addon initialization through AddonLoader.

2. Domain & Application Layer (@mr-tick/domain / @mr-tick/application)

Contains pure business rules:

• Rich Entities: Workspace, Task, and TimeEntry ensure data integrity with Zod and functional error handling (Either / Result).
• Use Cases: Workspace creation, DataSource connection and disconnection, and the HTTP Synchronization Engine (Pull & Push of deltas).

3. Mr. Tick SDK (@mr-tick/sdk)

The entry point for developers. It provides strict TypeScript types, cryptographic utilities (PKCE RFC 7636 and State generation), and safe abstractions for storage, real-time events, timers, and notifications.

4. Deep Link Bridge (mr-tick-app://)

A universal bridge for web flows such as OAuth 2.0. The intermediate landing page receives external-provider callbacks and securely returns their parameters to the desktop application through mr-tick-app://oauth/callback.

🛡️ Fundamental Security Principles

1. Zero Secrets: Addons run as public clients on the desktop. No secret key (CLIENT_SECRET) is embedded or required in addon code. Authentication uses OAuth 2.0 with PKCE.
2. Workspace Isolation (Multi-Tenant): Credentials, access tokens, and settings persisted through context.host.vault are isolated by addon and the explicit scope passed to each call, independently of the active workspace.
3. Immutability and Conflict Prevention: The synchronization engine uses Optimistic Concurrency Control with assumedMasterState to detect concurrent changes without silently overwriting data.
4. Safe Event Communication: Addons react asynchronously to operating system and timer events (onTimerStart, onTimerStop, onIdleDetected) without blocking.