CXOS — Low-Level Design (LLD)

📚 Purpose & Scope

The BRD answers why CXOS exists and what it must guarantee; the six module pages answer what each stage does conceptually; the BRD's Microservices catalog answers which service owns what. This document answers how a single request or event actually moves through the system, byte for byte — the sequence of calls, the shape of the data at each hop, the exact schema each store persists, and the topology it all runs on. It's scoped to the platform's Core Domain path (ingestion through activation, the flow used as the running example throughout) rather than re-deriving low-level detail for all 92 detail pages — each of those already documents its own Technical Overview, artifact payload, and Services Consumed.

🛠 Component Design — Cxos.Ingestion.Api Internal Layering

One representative service, worked through down to class responsibilities, so the pattern is clear enough to replicate for any other Cxos.*.Api. Every service in the BRD's DDD catalog follows the same four-layer shape (Domain has no dependencies on anything; Infrastructure implements the interfaces Domain declares — classic dependency inversion, not a Domain that reaches out to Azure SDKs directly).

services.AddScoped<IEventValidator, SchemaRegistryValidator>();
services.AddScoped<IConsentPolicy, ConsentEnforcementPolicy>();
services.AddScoped<IEventPublisher, EventHubsPublisher>();
services.AddScoped<IngestionService>();

// IngestionService constructor depends only on the interfaces above —
// it has no idea Event Hubs or Redis exist.
public IngestionService(IEventValidator validator, IConsentPolicy consent, IEventPublisher publisher) { ... }

🗃️ Database Schema Detail

One concrete schema artifact per store in the polyglot persistence design — matches the database assignments already shown on the homepage's Full Application Service Map.

CREATE TABLE event_schema (
  event_type       text NOT NULL,
  version          int  NOT NULL,
  owner_team       text NOT NULL,
  compatibility    text NOT NULL CHECK (compatibility IN ('backward','forward','full')),
  pii_fields       text[] DEFAULT '{}',
  registered_at    timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (event_type, version)
);
CREATE INDEX idx_event_schema_owner ON event_schema (owner_team);

{
  "id": "cust_004821",
  "partitionKey": "tenant_northwind",
  "tenant_id": "tenant_northwind",
  "lifecycle_stage": "active",
  "ltv_band": "gold",
  "consent_basis": { "marketing": true, "analytics": true },
  "churn_risk": 0.12,
  "conversion_propensity": 0.34,
  "model_version": "churn_risk_v4",
  "updated_at": "2026-08-02T06:00:00Z",
  "_etag": "\"a1b2c3d4\""
}
// Partitioned by tenant_id — keeps every tenant's profiles co-located
// and enforces the isolation boundary Cxos.Tenancy.Api defines.

// Add a resolved edge
g.V().has('customer', 'customer_key', 'cust_004821').as('c')
  .addE('resolves_to').to(
    g.addV('identifier').property('value', 'dev_88f2').property('type', 'device_id')
  ).from('c')

// Resolve any known identifier back to its canonical customer
g.V().has('identifier', 'value', 'dev_88f2').out('resolves_to').values('customer_key')

enrich:geo:{ip_hash}              TTL 24h    -- geo/device enrichment lookup cache
idem:event:{event_id}             TTL 15m    -- idempotency/dedup key at ingestion
profile:hot:{customer_key}        TTL 5m     -- hot-key read-through cache in front of Cosmos DB
query:{metric_hash}:{dim_hash}    TTL varies -- semantic-layer query-result cache, invalidated on dbt run

CREATE TABLE curated.identity_stitched_events (
  event_id         string,
  customer_key     string,
  event_type       string,
  event_version    int,
  event_timestamp  timestamp,
  properties       map<string, string>
)
USING iceberg
PARTITIONED BY (days(event_timestamp))
TBLPROPERTIES ('write.format.default'='parquet');

🔗 API Contracts

Request/response shape for the three calls in the sequence diagram above. Every response follows the same error envelope on failure.

POST https://ingest.cxos.io/v1/events
Authorization: Bearer <client-token>
Content-Type: application/json
Idempotency-Key: c2a9f1e0-8b3d-4e7a-9c1f-2d6a8e0b4c73

{
  "event": "product_viewed",
  "user_id": "cust_004821",
  "context": { "channel": "web" },
  "properties": { "sku": "sku-1029", "price": 2499 }
}

202 Accepted
{ "event_id": "c2a9f1e0-8b3d-4e7a-9c1f-2d6a8e0b4c73", "accepted_at": "2026-08-02T06:00:00Z" }

GET https://api.cxos.io/v1/profile/cust_004821
Authorization: Bearer <service-token>

200 OK
{
  "customer_key": "cust_004821",
  "lifecycle_stage": "active",
  "ltv_band": "gold",
  "churn_risk": 0.12
  // fields the caller isn't entitled to are omitted, not nulled
}

404 Not Found
{ "error": { "code": "PROFILE_NOT_FOUND", "message": "No profile for customer_key", "trace_id": "..." } }

POST https://api.cxos.io/v1/activate
Authorization: Bearer <service-token>

{
  "customer_key": "cust_004821",
  "trigger": "cart_abandonment",
  "channel": "email",
  "template_id": "cart_recovery_v3"
}

202 Accepted
{ "dispatch_id": "disp_9931", "routed_to": "Cxos.Connectors.SendGrid" }

409 Conflict
{ "error": { "code": "CONSENT_DENIED", "message": "Customer has not consented to marketing", "trace_id": "..." } }

⚠️ Error Handling & Resiliency

🔐 Security Design Detail

Token issuance and validation for a service-to-service call — the same flow every Cxos.*.Api enforces via shared middleware, per Cxos.Security.Api in the Full Application Service Map.

• 1. Caller authenticates against Azure AD (Entra ID) — internal/employee callers federate through ADFS from on-prem AD; customer-facing callers use Azure AD B2C, kept entirely separate
• 2. Azure AD issues a short-lived JWT access token scoped to the caller's role/app registration
• 3. Azure API Management validates the token signature and expiry at the edge before a request ever reaches a service
• 4. The receiving Cxos.*.Api's shared authentication middleware re-validates the token and resolves roles/attributes for RBAC/ABAC checks (Cxos.Foundation.Api's Access Control policies)
• 5. Service-to-service calls inside the cluster use managed identities, not shared secrets — no long-lived credential to leak
• 6. Every access decision (allow/deny, masked fields) is logged to the write-once Audit Logs store, per Governance & Security

📈 Observability Design

One correlation ID is generated at the edge (Azure API Management) and propagated via the X-Correlation-Id header through every hop in the sequence diagram above, so a single request can be traced end to end in Application Insights regardless of how many services it touched.