ArchitectureAdrADR-0012: Hybrid Data Architecture (Native + MCP)

ADR-0012: Hybrid Data Architecture (Native + MCP)

ADR-0012: Hybrid Data Architecture (Native + MCP)

Status: Accepted Date: 2026-01-08 Deciders: Architect, Gatekeeper Context: Phase J/K implementation decisions

Context

Jorvis started as a PostgreSQL-only Text-to-SQL system. As the platform scaled, we faced a decision:

  1. Build native adapters for every database (MySQL, MSSQL, Snowflake, BigQuery, etc.)
  2. Use MCP (Model Context Protocol) as a universal connector
  3. Hybrid: Combine both approaches

Considerations

ApproachProsCons
Native OnlyMaximum performance, deep integrationHigh maintenance, slow expansion
MCP OnlyUniversal access, rapid expansionLimited optimization, dependency on external servers
HybridBest of both worldsComplexity in routing

Decision

We adopt a Hybrid Data Architecture with two tiers:

Tier 1: Native Adapters (High Performance)

For databases where we need maximum performance, GraphRAG integration, and deep query optimization:

  • PostgreSQL (primary, includes pgvector)
  • MySQL (backtick quoting, information_schema)
  • SQL Server (sys.* catalog, T-SQL support)

These adapters live in src/data/dialects/ and share a common SqlDialectAdapter interface.

Tier 2: MCP Client (Universal Access)

For extending reach without building custom adapters:

  • Any MCP-compatible server
  • Snowflake, BigQuery (via MCP bridges)
  • SaaS APIs (via MCP tools)
  • Local files (via filesystem MCP)

The MCP client lives in src/mcp/ and uses McpClientService with stdio/SSE transports.

Consequences

Positive

  • Performance where it matters: Native adapters for core databases
  • Extensibility: MCP covers long-tail use cases
  • Reduced maintenance: Don't build adapters for rarely-used sources

Negative

  • Routing complexity: Must decide which path each query takes
  • Feature parity: MCP sources may lack advanced features (GraphRAG, caching)

Neutral

  • Testing burden: Both tiers need independent test coverage

Implementation

  • Phase J: Implemented native MySQL and SQL Server adapters
  • Phase K: Implemented universal MCP client (Task-067b)
  • Routing: DataSourceRouter selects adapter based on connection config

References

  • MySQL Adapter (analytics-platform/src/data/dialects/mysql/)
  • SQL Server Adapter (analytics-platform/src/data/dialects/mssql/)
  • MCP Client Service (analytics-platform/src/mcp/mcp-client.service.ts)