UXDL Docs
AI

Delivery Standards

Mandatory PR checklist, observability, and span naming.

Mandatory checklist for every AI feature at UXDL. No feature is complete without these steps.

Decision tree

  1. Multi-step, tools, or shared across apps? Extend the hosted graph (new route or input branch) and add webhook plus persist logic. See Integration flow.
  2. Single service, bounded graph? Add src/agents/<name>/ plus service and routes. See Folder layout & setup.
  3. One LLM call, structured output? Service function plus prompt module; cache result on the document.

Hosted graph checklist

  • Graph change deployed to LangGraph Platform (Alpha → Beta → Prod)
  • runs.create input and config documented
  • Webhook handler extracts the correct values field
  • Product DB schema and indexes
  • Reconciliation path if webhook can be missed
  • Usage limits if user-facing
  • Env vars in .env.example and UXDL env doc

In-process agent checklist

Mandatory for every AI feature PR:

  1. Tests: bun test src/tests; mock OpenAI, LangGraph, MongoDB, fetch
  2. Docs: docs/<feature>.md plus link from docs/index.md
  3. JSDoc: every exported symbol
  4. Tracing: withSpan and structured logger in services
  5. Changelog: CHANGELOG.md entry
  6. Bruno: bruno/<Feature>/ sequential .bru files

Observability (AI-specific)

Use the same stack as other UXDL backends. See Observability Overview.

LayerToolAI-specific usage
LogsPino → AxiomInclude thread_id, run_id, job ID on every log line
TracesOpenTelemetry withSpanSpan names: feature.service.operationName
Graph tracesLangSmith / LangfuseCorrelate webhook trace_id with graph host project
UsageApp-level rate limitingCap agent conversations and expensive generation per user

Span naming: feature.service.operationName (e.g. chat.service.stream, job.service.reconcile).

See also

Official documentation