SDK Integration (Reference)

This page is a technical reference for the uyava SDK APIs and behavior.

If you are onboarding, start with Getting Started first, then use this page for exact API choices.

Startup and graph APIs

Initialize once:

Uyava.initialize();
// Optional: start every node as disposed and activate explicitly later.
Uyava.initialize(defaultLifecycleState: UyavaLifecycleState.disposed);

Graph snapshot and updates:

Uyava.replaceGraph(nodes: [...], edges: [...]);
Uyava.loadGraph(nodes: [...], edges: [...]);

Uyava.addNode(const UyavaNode(id: 'logic.auth', type: 'service'));
Uyava.addEdge(const UyavaEdge(id: 'ui->logic', from: 'ui', to: 'logic'));

Uyava.patchNode('logic.auth', {'label': 'Auth Service'});
Uyava.patchEdge('ui->logic', {'label': 'Auth request'});

Uyava.removeEdge('ui->logic');
Uyava.removeNode('logic.auth');

Reference rule: keep node/edge IDs stable and unique.

Runtime event APIs

Node and edge events:

Uyava.emitNodeEvent(
  nodeId: 'logic.auth',
  message: 'Sign in pressed',
  severity: UyavaSeverity.info,
  tags: ['auth'],
  sourceRef: Uyava.caller(),
);

Uyava.emitEdgeEvent(
  edge: 'ui.login->logic.auth',
  message: 'Auth request sent',
  severity: UyavaSeverity.warn,
  sourceRef: Uyava.caller(),
);

Lifecycle signals:

Uyava.updateNodeLifecycle(
  nodeId: 'logic.auth',
  state: UyavaLifecycleState.initialized,
);

Uyava.updateNodesListLifecycle(
  nodeIds: ['logic.auth', 'data.session'],
  state: UyavaLifecycleState.disposed,
);

Uyava.updateSubtreeLifecycle(
  rootNodeId: 'feature.checkout',
  state: UyavaLifecycleState.disposed,
  includeRoot: true,
);

Important:

  • message is required for emitNodeEvent and emitEdgeEvent.
  • sourceRef: Uyava.caller() enables Desktop IDE jump-to-code behavior.

Diagnostics APIs

Emit and clear diagnostics:

Uyava.postDiagnostic(
  code: 'auth.token_expired',
  level: UyavaDiagnosticLevel.warn,
  nodeId: 'logic.auth',
  context: {'tokenAgeMinutes': 87},
);

Uyava.clearDiagnostics();

Use diagnostics for integrity or domain issues that should be visible in the Diagnostics panel.

Console mirroring

Enable console mirror output when you want standard terminal logs in parallel with Uyava hosts:

Uyava.enableConsoleLogging(
  config: UyavaConsoleLoggerConfig(
    minLevel: UyavaSeverity.info,
    includeTypes: {'nodeEvent', 'edgeEvent'},
    excludeTypes: {'graphDiagnostics'},
  ),
);

Disable when no longer needed:

await Uyava.disableConsoleLogging();

Notes:

  • Console mirroring does not replace DevTools/Desktop visualization.
  • includeTypes and excludeTypes are useful for noisy sessions.
  • Keep it optional in production unless your support flow depends on it.

Transport APIs

Uyava emits through a transport hub:

  • default transport: VM Service (used by DevTools/Desktop)
  • optional: file logging transport
  • optional: custom transports (for internal pipelines)
final transport = MyWebSocketTransport(uri: Uri.parse('ws://...'));
Uyava.registerTransport(transport);
// Keep an existing channel instance instead of replacing it.
Uyava.registerTransport(
  MyWebSocketTransport(uri: Uri.parse('ws://backup-host')),
  replaceExisting: false,
);

// Remove by channel (enum), or use transport.channel.
Uyava.unregisterTransport(UyavaTransportChannel.webSocket);

File-logging runtime helpers:

final Stream<UyavaLogArchiveEvent>? archive = Uyava.archiveEvents;
final Stream<UyavaDiscardStats>? discardStats = Uyava.discardStatsStream;
final UyavaDiscardStats? lastDiscard = Uyava.latestDiscardStats;
final UyavaLogArchive? latestAny = await Uyava.latestArchiveSnapshot();
final UyavaLogArchive? latestRotatedOnly =
    await Uyava.latestArchiveSnapshot(includeExports: false);

Use archiveEvents to observe archive lifecycle updates:

  • rotation
  • export
  • clone
  • recovery (streaming journal recovery)
  • panicSeal

Use discard stats to monitor dropped events caused by filters/sampling/burst limits in real time.

Shutdown helper:

await Uyava.shutdownTransports();

For file transport usage and replay logs, see Recording and .uyava Logs.

Global error bootstrap (optional, file logging flows)

Use these APIs when you want panic-tail/error capture with a file transport:

final transport = await Uyava.enableFileLogging(
  config: UyavaFileLoggerConfig(directoryPath: '/tmp/uyava'),
);

final handle = UyavaBootstrap.installGlobalErrorHandlers(
  transport: transport,
  options: const UyavaGlobalErrorOptions(
    enableIsolateErrors: true,
    captureCurrentIsolateErrors: true,
  ),
);

await UyavaBootstrap.runZoned(
  () async {
    Uyava.initialize();
    runApp(const MyApp());
  },
  transport: transport,
);

final SendPort? isolatePort = UyavaBootstrap.isolateErrorPort;
UyavaBootstrap.ensurePresentErrorHook();
// Optional for spawned isolates:
// UyavaBootstrap.attachIsolateErrorListener(mySpawnedIsolate);

// Dispose when no longer needed:
handle.dispose();

Default UyavaGlobalErrorOptions values:

  • enableFlutterError: true
  • enablePlatformDispatcher: true
  • enableZonedErrors: true
  • delegateOriginalHandlers: true
  • propagateToZone: true
  • enableIsolateErrors: false
  • captureCurrentIsolateErrors: true
  • emitNonFatalDiagnostics: true
  • autoGuardZone: false
  • flushTimeout: Duration(milliseconds: 500)

Integrity rules and constraints

  • Node and edge IDs must be unique.
  • Colors must be #RRGGBB or #AARRGGBB.
  • Shapes must match ^[a-z0-9_-]+$.
  • Unknown/dangling references are surfaced as diagnostics.
  • Prefer structural stability (graph) + runtime variability (events, lifecycle, metrics, chains).
  • Avoid a synthetic single global root node for the entire graph; prefer meaningful top-level feature/domain roots.