#ADR 0002 — Collector, SDK Language, Producer-of-Record, and Durability Strategy

#Context

CX Orbit needs a durable, auditable path for Simiaroom to prove business outcomes (booking, payment, session, churn) without coupling primary workflows to analytics availability. The ingestion contract in SDK-AND-DATA-INGESTION.md already defines collector-centric boundaries, at-least-once delivery, and quarantine semantics. T0.6 locks implementation choices so Wave B can ship the collector (T2.2), backend SDK (T2.2a), and first P0 instrumentation (T2.2b).

Constraints:

• Collector is the sole event write ingress — Simiaroom SDKs and integrations never connect to PostgreSQL, ClickHouse, or Orbit raw storage.
• Backend proves outcomes — browser events describe behavior and intent only.
• Three-person team — prefer one primary backend SDK language and a layered durability model operable without Kafka/self-managed streaming for MVP.
• Simiaroom stack is not yet inventoried in-repo (T0.5) — language choice documents an explicit assumption pending confirmation.

#Decision

#1. Collector placement and boundary

Deploy cx-orbit-collector as a dedicated CX Orbit service (HTTP ingestion API + internal ingest workers). It is the only entry point for externally produced events.

The collector subsystem owns: authentication, rate limits, schema/privacy validation, batch responses, durable accept buffer, quarantine for invalid payloads, and routing to immutable raw storage. Downstream canonical mapping, identity, and operational stores are Orbit-internal only.

flowchart LR
  subgraph simiaroom [Simiaroom — never writes Orbit storage]
    BE[Backend services]
    Outbox[(Transactional outbox)]
    ProdDB[(Product DB)]
    BE --> Outbox
    Outbox --> NodeSDK["@cx-orbit/node"]
  end

  subgraph orbit [CX Orbit — sole write ingress]
    Collector[Collector API]
    Worker[CDC / import ingest worker]
    Validate[Auth + schema + privacy]
    Buffer[(Durable accept buffer)]
    Quarantine[(Quarantine)]
    Raw[(Immutable raw events)]
    NodeSDK --> Collector
    Worker --> Validate
    Collector --> Validate
    Validate -->|valid| Buffer --> Raw
    Validate -->|invalid| Quarantine
    ProdDB -.->|read-only CDC| Worker
  end

Hosting: co-locate collector with CX Orbit on the platform chosen in ADR 0001 (T0.2). Expose staging and production collector endpoints with separate credentials per environment.

#2. Primary backend SDK language (MVP)

Primary language: Node.js / TypeScript — package @cx-orbit/node.

MVP scope: ship one first-class backend SDK (@cx-orbit/node). Services in other languages call the versioned collector HTTP API directly with the same envelope and idempotency keys; no second SDK until a confirmed integration requires it (per ingestion doc §15 Stage 4).

Validation required: T0.5 source inventory must confirm or correct this assumption. If Simiaroom's authoritative backend is PHP/Laravel or Python instead, keep @cx-orbit/node for Orbit-side tooling but prioritize HTTP contract + instrumentation guide for the confirmed primary stack; defer a native SDK to a follow-on task.

Alternatives considered

#3. Producer-of-record

Every authoritative P0 outcome has exactly one producer of record. Duplicate observations from other sources are diagnostic only and must not create duplicate business facts.

Full matrix: SOURCE-OWNERSHIP.md (booking, payment, session, churn/retention, and initial 8–12 event slice).

Rules preserved:

• Browser / GA → behavior and intent only.
• Booking, payment, session, refund outcomes → Simiaroom backend or CDC-reconciled source table.
• Internal case/action outcomes → CX Orbit operational store emits after committed state change.

#4. Durability strategy — layered outbox + sync HTTP + CDC reconciliation

Use all three patterns in layers, not as mutually exclusive choices:

MVP sequencing (matches TECHNICAL-TASKS.md Wave B):

1. Stage 1: L2 sync HTTP + collector durable buffer (T2.2, T2.2a, T2.2b).
2. Stage 2: L3 CDC reconciliation for sessions, bookings, payments (T2.2c).
3. Stage 1–2 overlap: L1 transactional outbox in Simiaroom when instrumenting each P0 write path (T2.14 — implement where business DB supports same-transaction insert).

Do not introduce self-managed Kafka or a separate message broker for MVP. Collector accept buffer + PostgreSQL (T2.1) is sufficient until T0.7/T3.12 measured volume proves otherwise.

Alternatives considered

#5. Failure modes and ownership

#5.1 Simiaroom-side (producer + SDK + outbox)

#5.2 CX Orbit collector and ingest

#5.3 Reconciliation and quarantine (cross-boundary)

#5.4 Non-blocking guarantee

Analytics failures never fail booking, payment, or session workflows. Business commit completes first; event emission is post-commit (outbox or async SDK call).

#6. Delivery semantics summary

Aligned with the locked envelope contract (SDK-AND-DATA-INGESTION.md §7.4 / §8.2; T0.4):

• At-least-once end-to-end; dedup at collector/canonical layer.
• Transport dedup key: project_id + event_id — SDK/outbox retries preserve the same event_id through backoff.
• Canonical idempotency key: project_id + source + source_event_id — one canonical business fact per source outcome; this is the DoD key source + source_event_id scoped by project_id.
• Cross-path rule: CDC, import, webhook, and SDK copies of the same source fact must share source + source_event_id (each path may generate a new transport event_id).
• No exactly-once promise.
• Ordering: not guaranteed globally; use occurred_at, sent_at, received_at for late-event handling.

#Consequences

#Positive

• Clear separation: Simiaroom owns business truth and outbox durability; Orbit owns validation, storage, quarantine, and reconciliation.
• Single backend SDK reduces Wave B scope and CI/fixture cost.
• Layered L1/L2/L3 meets completeness targets without Kafka.
• Collector API remains stable if storage moves from PostgreSQL to ClickHouse (T3.12).

#Negative / tradeoffs

• Simiaroom must implement outbox table + relay (T2.14) for highest-reliability P0 paths.
• CDC adds read access to product DB (dependency for T0.5).
• Node/TypeScript assumption may require revision after T0.5 — HTTP contract limits rework cost.

#Follow-on tasks unblocked

#Open items (not blockers for T0.6 test)

1. Confirm Simiaroom primary backend language with eng (T0.5).
2. Exact outbox table schema and relay: packages/outbox/sql/cx_outbox_events.postgres.sql + ops/OUTBOX-RELAY.md (T2.14). Simiaroom product-repo same-TX wiring remains a follow-on.
3. CDC technology choice (logical replication vs polling) after DB access inventory (T0.5).
4. Collector hosting details pending ADR 0001 (T0.2).