#Chronos Gateway API (xtnd-chronos-api)

Repository: XTND-DYNAMICS/xtnd-chronos-api
Production Route: https://api.chronos.vantage.xgi.io
Runtime: Cloudflare Worker (nodejs_compat)

#1. Overview

xtnd-chronos-api is the dedicated Cloudflare Edge Gateway Worker responsible for ingesting human activity telemetry, running edge session reconstructions, and forwarding batched activity data to the Central Vantage Ingestion Worker (api.vantage.xgi.io).

#2. API Endpoints

#2.1 GET /v1/health

Health check and service runtime descriptor.

Response:

{
  "service": "XTND Vantage Chronos Human Activity & Time Tracking Gateway",
  "domain": "api.chronos.vantage.xgi.io",
  "status": "OPERATIONAL",
  "environment": "production",
  "timestamp": "2026-09-06T00:15:00.000Z"
}

#2.2 POST /v1/events/evidence

Ingests individual or batched activity evidence records from client SDKs or background capture daemons.

Payload:

{
  "events": [
    {
      "source": "whatsapp_call",
      "timestamp": 1700000000000,
      "durationMs": 1320000,
      "actor": "user",
      "participants": ["Jørgen"],
      "identifiers": ["ORD-9821"]
    }
  ]
}

#2.3 POST /v1/sessions/reconstruct

Runs retrospective work-session clustering and attribution across a set of raw events.

Payload:

{
  "events": [ ... ],
  "catalog": [ ... ],
  "options": {
    "maxGapMinutes": 20,
    "roundUnitMinutes": 15
  }
}

#2.4 POST /v1/reconcile/notion

Reconciles work sessions against existing Notion entries, preventing double-billing.

#3. Data Flow Architecture

sequenceDiagram
    autonumber
    actor Client as Desktop Daemon / SDK
    participant ChronosAPI as xtnd-chronos-api (api.chronos.vantage.xgi.io)
    participant CentralAPI as xtnd-vantage-api (api.vantage.xgi.io)

    Client->>ChronosAPI: POST /v1/events/evidence (Activity Traces)
    ChronosAPI-->>Client: 200 OK (Acknowledged)
    
    rect rgb(20, 30, 45)
        Note over ChronosAPI,CentralAPI: Non-blocking Edge Forwarding (ctx.waitUntil)
        ChronosAPI->>CentralAPI: POST /v1/events/batch (X-Module-Source: chronos)
    end