ADR-038: Spatial Intelligence Architecture Patterns

Date: September 30, 2025 (Updated: October 1, 2025) Status: Accepted Context: CORE-GREAT-2C Verification Work (GitHub Issue #194), CORE-GREAT-2D Discovery (GitHub Issue #195) Supersedes: None Superseded by: None

Decision

Piper Morgan will support three distinct spatial intelligence patterns optimized for different integration domains:

  1. Granular Adapter Pattern for complex coordination scenarios
  2. Embedded Intelligence Pattern for streamlined knowledge management
  3. Delegated MCP Pattern for Model Context Protocol integrations (NEW - Oct 1, 2025)

All patterns are considered first-class architectural approaches, and new integrations should choose the pattern most appropriate for their domain.

Context

During CORE-GREAT-2C verification work (Phases 1-2, September 30, 2025), we discovered that Slack and Notion integrations implement fundamentally different but equally valid spatial architecture approaches.

During CORE-GREAT-2D investigation (Phase 0, October 1, 2025), we discovered Calendar implements a third distinct pattern using Model Context Protocol (MCP) delegation.

Slack Implementation (Granular Adapter Pattern)

Notion Implementation (Embedded Intelligence Pattern)

Calendar Implementation (Delegated MCP Pattern) - NEW

Verification Results

Options Considered

Option 1: Standardize on Single Pattern (REJECTED)

Force all integrations to use the same architectural approach.

Advantages:

Disadvantages:

Option 2: Support Multiple Patterns (CHOSEN)

Allow domain-optimized architectures based on integration characteristics.

Advantages:

Disadvantages:

Decision: CHOSEN - Benefits outweigh costs. October 2025 update: Calendar’s Delegated MCP Pattern confirms this approach scales well for protocol-based integrations.

Option 3: Hybrid Approach (REJECTED)

Combine both patterns in single implementation (e.g., granular components with embedded access).

Advantages:

Disadvantages:

Decision Rationale

Core Principle: Domain-Optimized Architecture

Key Insight: Domain-specific optimization outweighs standardization for standardization’s sake.

Different integration domains have fundamentally different spatial requirements:

Reactive Coordination (Slack):

Analytical Intelligence (Notion):

Evidence-Based Decision

Production Validation:

Architectural Quality:

Developer Experience:

Implementation

Pattern Selection Criteria

New spatial integrations must choose pattern based on:

  1. Domain Complexity:

    • Many distinct capabilities (>5) → Granular
    • Few focused capabilities (≤5) → Embedded
    • MCP Protocol required → Delegated MCP (Oct 2025)

  2. Requirement Stability:

    • Evolving requirements → Granular (easier to extend)
    • Stable requirements → Embedded (lower overhead)
    • Protocol-driven → Delegated MCP

  3. Performance Criticality:

    • Performance critical → Embedded (minimal overhead)
    • Performance adequate → Either pattern
    • External service → Delegated MCP (protocol overhead acceptable)

  4. Testing Requirements:

    • Component-level isolation needed → Granular
    • Integration-level testing sufficient → Embedded
    • Protocol compliance testing → Delegated MCP

  5. Team Structure:

    • Multiple developers on feature → Granular (parallel work)
    • Single developer or small team → Embedded (simpler)
    • MCP team + integration team → Delegated MCP (separation of concerns)

  6. Domain Nature:

    • Reactive coordination → Granular
    • Analytical intelligence → Embedded
    • Temporal/contextual awareness via protocol → Delegated MCP

  7. Integration Architecture (NEW - Oct 2025):

    • Model Context Protocol (MCP) required → Delegated MCP
    • Separate consumer layer exists → Delegated MCP
    • Protocol-specific spatial logic → Delegated MCP
    • All other cases → Granular or Embedded

Pattern Descriptions

Granular Adapter Pattern

When to Use:

Structure:

services/integrations/{integration}/
  spatial_types.py          # Domain types and primitives
  spatial_adapter.py        # Main adapter (inherits BaseSpatialAdapter)
  spatial_agent.py          # Navigation and awareness
  spatial_intent_classifier.py  # Intent classification
  spatial_mapper.py         # Domain-specific mapping
  spatial_memory.py         # Memory storage/retrieval
  tests/
    test_spatial_*.py       # Component-level tests

Access Pattern:

router = IntegrationRouter()
adapter = router.get_spatial_adapter()
result = await adapter.map_to_position(context)

Embedded Intelligence Pattern

When to Use:

Structure:

services/intelligence/spatial/{integration}_spatial.py
  # Single comprehensive class
  # 8-dimensional analysis methods
  # Built-in analytics tracking
  # Internal router usage

Access Pattern:

spatial = IntegrationSpatialIntelligence()
await spatial.connect()
analysis = await spatial.get_comprehensive_spatial_analysis(item_id)

Delegated MCP Pattern (NEW - Oct 2025)

When to Use:

Structure:

services/integrations/{integration}/
  {integration}_integration_router.py  # Minimal router (delegation only)

services/mcp/consumer/
  {integration}_adapter.py             # MCP adapter (inherits BaseSpatialAdapter)
    # Spatial intelligence implementation
    # MCP protocol compliance
    # Custom spatial context extraction

Access Pattern:

router = IntegrationRouter()
# Router methods delegate to MCP adapter
events = await router.get_todays_events()
# Spatial methods also available
context = router.get_context(external_id)

Key Characteristics:

Example: Calendar integration

Common Requirements

All spatial patterns must:

  1. Router Integration:

    • Use IntegrationRouter (directly or indirectly)
    • Support feature flag control (USESPATIAL*)
    • Provide health check capabilities
    • Update Oct 2025: Delegated MCP Pattern delegates through router to MCP adapter

  2. 8-Dimensional Spatial Metaphor:

    • Implement relevant dimensions for domain
    • Use consistent naming (HIERARCHY, TEMPORAL, PRIORITY, COLLABORATIVE, FLOW, QUANTITATIVE, CAUSAL, CONTEXTUAL)
    • Document which dimensions supported
    • Update Oct 2025: Calendar implements TEMPORAL dimension via temporal_summary

  3. Backward Compatibility:

    • Graceful degradation when spatial disabled
    • Don’t break existing functionality
    • Support legacy mode via feature flags
    • Update Oct 2025: All 3 patterns support feature flag control

  4. Async Patterns:

    • Use async/await for I/O operations
    • Support concurrent operations where appropriate
    • Handle cleanup properly

  5. Observability:

    • Log spatial operations appropriately
    • Track analytics/metrics
    • Support debugging and troubleshooting
    • Update Oct 2025: Delegated MCP Pattern includes circuit breaker pattern for resilience

Consequences

Positive Consequences

  1. Optimal Performance: Each integration uses pattern suited to its needs
  2. Appropriate Complexity: No over-engineering or under-engineering
  3. Production-Proven: Both patterns validated and operational
  4. Clear Guidance: Selection criteria documented
  5. Flexibility: Future integrations can choose appropriate pattern
  6. No Breaking Changes: Both existing patterns continue working

Negative Consequences

  1. Multiple Patterns: Two patterns to maintain instead of one
  2. Documentation Overhead: Must document both patterns
  3. Training: Developers need to understand pattern selection
  4. Consistency Risk: Must ensure both patterns follow core requirements

Mitigation Strategies

For Multiple Patterns:

For Documentation Overhead:

For Training:

For Consistency:

Compliance Requirements

For Existing Implementations

Slack (Granular Adapter Pattern):

Notion (Embedded Intelligence Pattern):

For New Implementations

New spatial integrations must:

  1. Choose Pattern: Use decision framework to select appropriate pattern
  2. Document Choice: Create brief rationale document explaining pattern choice
  3. Follow Requirements: Implement all common requirements
  4. Feature Flags: Support USESPATIAL{INTEGRATION}=true/false
  5. Router Integration: Integrate with IntegrationRouter infrastructure
  6. Dimensions: Implement relevant 8-dimensional analysis
  7. Testing: Provide appropriate test coverage (component or integration)
  8. Documentation: Update spatial pattern guide with integration

Review Process

Pattern selection should be reviewed during:

References

Documentation

Source Code

Verification

Version History

Date Version Author Changes
2025-09-30 1.0 Claude Code Initial ADR creation based on GREAT-2C verification

Approval

Approved by: CORE-GREAT-2C Verification Work (Phases 1-4) Implementation Status: Complete and Operational Production Status: Both patterns deployed and validated

Next Review: After next spatial integration implementation Related ADRs: None (first spatial architecture ADR) Supersedes: None Superseded by: None (active)

Update October 2025

See ADR-034: Plugin Architecture Implementation for the plugin system that now manages all spatial intelligence integrations. The three spatial patterns documented in this ADR are now implemented as plugins following the Wrapper/Adapter pattern, providing:

All spatial intelligence patterns remain valid architectural choices, now enhanced with plugin capabilities.

This ADR documents the discovery and validation of two production spatial patterns during GREAT-2C verification work (September 30, 2025).