docs: add unified query response schema ADR

What does this MR do and why?

Adds ADR 004 and updates the querying design docs to document the unified response schema -- a { query_type, nodes, edges } JSON payload that replaces flat tabular rows for all five query types.

New file:

  • docs/design-documents/decisions/004_unified_response_schema.md

Updated files:

  • docs/design-documents/querying/README.md -- added unified response section, fixed outdated response format description
  • docs/design-documents/querying/graph_engine.md -- added unified response format subsection under Request Flow

The ADR covers the design evolution (graph sidecar -> tabular rows with descriptors -> nodes+edges), research into 8 graph databases, the two-layer architecture (cached ontology + per-request response), and response examples for all 5 query types.

Aggregation computed values are inlined directly on nodes. The frontend uses query_type to pick table vs graph display. Pagination is deferred to a separate ADR (#248).

Docs-only. No code changes.

Contributes to #243 (closed)

  • 5965027 -- initial response format spike (Michael U.)
  • 5965036 -- industry research (Angelo)
  • 5965394 -- combined research document

Testing

Docs-only.

Performance analysis

  • This merge request does not introduce any performance regression.
Edited by Michael Angelo Rivera

Merge request reports

Loading