#XTND macOS Client Architecture & Specification

#1. Executive Summary

The XTND macOS Client (xtnd-macos-client) is an ultra-thin microkernel host designed to run on macOS as a background service or menu-bar assistant. By design, the host client in itself contains zero domain logic—it only handles plugin registration, topological dependency lifecycle management, service resolution, and asynchronous event dispatching.

Domain responsibilities are strictly encapsulated in three decoupled plugins:

1. XAuthPlugin (xauth): Identity gateway & desktop SSO facilitator (auth.xgi.io / api.auth.xgi.io), token storage, short-lived EdDSA tokens, and token auto-rotation.
2. VantageConnectionPlugin (connection): Authenticated transport layer for api.vantage.xgi.io and api.chronos.vantage.xgi.io. Handles automatic Bearer token injection, unauthenticated request queuing, 401 retry interception, and auth event coordination. Depends on xauth.
3. ChronosPlugin (chronos): Human activity tracking, active macOS window/app sampling, retrospective attribution, and telemetry sync via @xtnd-dynamics/xtnd-chronos-sdk. 100% auth-agnostic—has zero knowledge of tokens or sign-in pages, and depends strictly on connection.

#2. Component Decoupling & Dependency Graph

flowchart TD
    subgraph Microkernel ["XTND Client Microkernel (XtndClientHost)"]
        EventBus["Asynchronous EventBus"]
        ServiceRegistry["Service Registry (DI)"]
        ConfigManager["Config Manager"]
    end

    subgraph Plugins
        XAuth["XAuthPlugin ('xauth')\n- Identity & SSO Loopback\n- Token Storage & EdDSA Refresh"]
        Connection["VantageConnectionPlugin ('connection')\n- IVantageConnection Transport\n- Bearer Injection\n- Request Queueing Buffer\n- 401 Interceptor"]
        Chronos["ChronosPlugin ('chronos')\n- macOS Activity Sampler\n- Attribution & Timesheet Generation\n- Auth-Agnostic Telemetry"]
    end

    XAuth -->|Registers Service| ServiceRegistry
    Connection -->|Resolves 'xauth'| ServiceRegistry
    Connection -->|Registers 'connection'| ServiceRegistry
    Chronos -->|Resolves 'connection'| ServiceRegistry

    Connection -.->|Listens & Emits| EventBus
    XAuth -.->|Listens & Emits| EventBus
    Chronos -.->|Listens & Emits| EventBus

#Dependency Topological Ordering

Level 0: xauth       (Dependencies: [])
Level 1: connection  (Dependencies: ['xauth'])
Level 2: chronos     (Dependencies: ['connection'])

Shutdown operates in exact reverse topological order (chronos -> connection -> xauth).

#3. Asynchronous Auth & Transport Event Loop

When Chronos or any other plugin triggers an API request when the user is not authenticated, the transport handles it gracefully without breaking or requiring domain plugins to manage authentication:

sequenceDiagram
    autonumber
    participant Chronos as ChronosPlugin
    participant Connection as VantageConnection
    participant EventBus as EventBus
    participant XAuth as XAuthPlugin / SSO
    participant Backend as api.chronos.vantage.xgi.io

    Chronos->>Connection: post('/v1/timesheets/entries', entries)
    Note over Connection: Checks if token is available
    alt No Token or Token Expired
        Connection->>Connection: Enqueue request in memory buffer
        Connection->>EventBus: emit('auth:login_requested', { service: 'vantage', reason: '...' })
        EventBus->>XAuth: on('auth:login_requested')
        XAuth->>XAuth: Start SSO Loopback Server (http://localhost:58492/callback)
        Note over XAuth: User logs in at auth.xgi.io
        XAuth->>EventBus: emit('auth:authenticated', { tokens })
        EventBus->>Connection: on('auth:authenticated')
        Connection->>Connection: Flush buffered requests with Bearer token
        Connection->>Backend: POST /v1/timesheets/entries (Authorization: Bearer ...)
        Backend-->>Connection: 200 OK
        Connection-->>Chronos: Resolve promise with 200 OK
    else Token Active
        Connection->>Backend: POST /v1/timesheets/entries (Authorization: Bearer ...)
        Backend-->>Connection: 200 OK
        Connection-->>Chronos: 200 OK
    end

#4. Package Structure

xtnd-macos-client/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts                      # Top-level exports and createXtndClient factory
│   ├── cli.ts                        # Executable CLI host
│   ├── kernel/
│   │   ├── types.ts                  # Microkernel & plugin lifecycle definitions
│   │   ├── event-bus.ts              # Typed asynchronous event bus
│   │   ├── service-registry.ts       # Dependency injection container
│   │   ├── config.ts                 # Local configuration store
│   │   └── host.ts                   # Microkernel host with topological sort & lifecycle
│   └── plugins/
│       ├── xauth/
│       │   ├── types.ts              # IXAuthService, AuthTokens, XAuthConfig
│       │   ├── xauth-service.ts      # SSO loopback listener & auto-refresh
│       │   └── index.ts              # XAuthPlugin
│       ├── connection/
│       │   ├── types.ts              # IVantageConnection, RequestOptions, ApiResponse
│       │   ├── vantage-connection.ts # Queuing transport, Bearer injector, 401 retry
│       │   └── index.ts              # VantageConnectionPlugin
│       └── chronos/
│           ├── types.ts              # ChronosPluginConfig, IChronosService
│           ├── chronos-runner.ts     # macOS window/app activity sampler & sync
│           └── index.ts              # ChronosPlugin (depends on ['connection'])
└── tests/
    ├── microkernel.test.mjs          # Host lifecycle, topological sorting, circular checks
    ├── connection-plugin.test.mjs    # Request queueing, Bearer injection, 401 retry
    └── chronos-plugin.test.mjs       # Auth-agnostic telemetry & sync verification

#5. Verification & Tests

• 14/14 automated tests passing:
  • tests/microkernel.test.mjs: Validates host lifecycle, dependency ordering, cycle detection, and missing dependency rejection.
  • tests/connection-plugin.test.mjs: Validates request queuing until auth, automatic token injection, and 401 retry.
  • tests/chronos-plugin.test.mjs: Validates Chronos auth-agnostic telemetry submission through connection transport and host startup order.