Handbook - Architecture

Read Flow

Public telemetry reads use GraphQL through the TypeScript BFF. Storage-read owns the telemetry query semantics.

On this page
On this page

Public telemetry reads use GraphQL through the TypeScript BFF. Storage-read owns the telemetry query semantics.

Sequence

diagram
GraphQL traces/logs/metrics/facets/detail Validate input and auth/session context NATS request/reply with AuthContext Validate request and authorization context Parameterized project-scoped query Bounded rows, counts, facets, or series Typed response or BridgeError GraphQL data or problem details Frontend TypeScript BFF storage-read SurrealDB
Mermaid diagram rendered with beautiful-mermaid.

BFF Responsibilities

  • Validate public GraphQL input.
  • Normalize auth context and selected project.
  • Send request/reply messages through the bridge adapter.
  • Validate decoded bridge responses.
  • Map canonical bridge errors to public GraphQL problem details.

The BFF does not filter, aggregate, correlate, rank, or enrich telemetry records.

storage-read Responsibilities

  • Push supported filters, sorting, cursor predicates, grouping, counts, and bounded facets into the database adapter.
  • Derive GraphQL-ready trace, log, metric, and facet view models.
  • Enforce read authorization context.
  • Return typed success or BridgeError.

Common Read Subjects

GraphQL surfacePrivate subject
Query.tracestelemetry.traces.search
Query.tracetelemetry.traces.get
Query.logstelemetry.logs.search
Query.metricNamestelemetry.metrics.names
Query.metricSeriestelemetry.metrics.query
facetstelemetry.facets

Next Step

Use Trace investigation, Logs, or Metrics for user workflows.

Last updated .