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.
Related issues
Contributes to #243 (closed)
Related MRs
- !479 (closed) (implementation)
- !411 (merged) (proto sync decisions referenced in ADR)
Related snippets
- 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