Architecture
Contributors: start with the repo-root
(package map, where to change code, how tests and CI are wired). This page is the short product view; event JSON and HTTP routes stay in
High level
┌─────────────────────────────────────────────────────────┐
│ Browser + @idebug/react │
│ fetch/XHR → client span + inject W3C traceparent │
│ (default: same-origin only) │
└───────────────────────────┬─────────────────────────────┘
│ traceparent: 00-traceId-spanId-01
▼
┌─────────────────────────────────────────────────────────┐
│ Express / Nest + @idebug/node|nest │
│ inherit traceId / parentSpanId · mint local spanId │
│ server span events → @idebug/core store │
│ │ │
│ ├── createIdebugHandler → /__idebug SPA+API │
│ ├── @idebug/db adapters → dbQuery on call tree│
│ └── list by session (span) or traceId │
└─────────────────────────────────────────────────────────┘Trace–Span model: each process only emits spans for its own boundary work
(inbound request, outbound call). Shared traceId + parentSpanId stitch the
tree across FE and BE. Internal function/middleware work stays as events under
the active span — not nested spans.
Contract source of truth
Detailed frozen contracts live in the monorepo:
the documentation site
Includes event schemas, HTTP routes, package dependency rules, samples contract, and no-stubs policy.
Design history (short)
- Agent 0 — SPEC +
@idebug/core - Agents 1–3 — node/nest, ui, react (worktrees)
- Agent 4 — samples
- Agent 5 — review + live UI checks
- Follow-ups — enter/exit paths, app-only filter, AlignUI + Baselayer theme, this docs site,
@idebug/db+sample-db-api
Out of scope
- Multi-tenant self-hosted control plane
- AI diagnosis
- Production multi-region telemetry
IDebug stays an in-process, opt-in developer tool.