cloudlysis/docs/architecture/transport.md

Transport Contracts

Context

• Tenant: HTTP x-tenant-id; NATS tenant-id
• Correlation: HTTP x-correlation-id; NATS x-correlation-id + correlation-id
• Trace: HTTP traceparent; NATS traceparent + trace-id

Internal RPC (gRPC)

• Aggregate: CommandService (submit commands)
• Projection: QueryService (execute queries)
• Runner: RunnerAdmin (drain, status, reload)
• All calls set deadlines and propagate context metadata

NATS JetStream

• Streams:
  • AGGREGATE_EVENTS: tenant..aggregate..*
  • WORKFLOW_COMMANDS, WORKFLOW_EVENTS
• Producers set headers: tenant-id, Nats-Msg-Id, correlation, traceparent/trace-id
• Consumers use AckPolicy::Explicit, bounded ack_wait, max_deliver, max_ack_pending

Routing

• Gateway routes per-tenant to shards for Aggregate/Projection/Runner
• Routing tables hot-reload atomically