ADR-034: Plugin Architecture Implementation

Status

Implementation Status: Complete (October 2-4, 2025) Original Decision: Accepted (June 3, 2025)

Context

The June 3, 2025 architectural decision established plugin architecture from day one, but it was only partially implemented. Currently, GitHub integration is hardcoded rather than pluggable. With spatial intelligence patterns already in our MCP integrations and the need for Notion, Slack, and future PM tool integrations, implementing the plugin architecture is critical for extensibility.

Implementation Context (October 2025)

During GREAT-3A/3B/3C/3D work (October 2-4, 2025), we chose a Wrapper/Adapter Pattern to implement plugins without requiring major refactoring:

This pragmatic approach allowed us to:

  1. Add plugin capabilities to 4 existing integrations (GitHub, Slack, Notion, Calendar)
  2. Maintain backward compatibility (zero breaking changes)
  3. Complete implementation in 3 days instead of estimated 4 weeks
  4. Achieve exceptional performance (0.041μs overhead)

Decision

We will implement a plugin architecture where all external integrations (GitHub, Notion, Slack, Calendar, etc.) are pluggable components implementing a common interface. The architecture will be domain-driven, with PM concepts defining the interface rather than tool-specific features.

Implementation Choice: Wrapper/Adapter Pattern

Decision (October 2025): Use thin plugin wrappers that delegate to existing integration routers.

Rationale:

Plugin Architecture Principles

  1. Domain-first: PM concepts (WorkItem, TeamMember) drive the interface
  2. Tool-agnostic: No tool-specific logic in core
  3. Event-driven: Every plugin interaction emits learnable events
  4. Capability-based: Plugins declare their capabilities
  5. Spatial-aware: Leverage MCP spatial intelligence patterns (see ADR-038)

Core Components

Core System (web/app.py)
    ↓
Plugin Registry (services/plugins/plugin_registry.py)
    ↓
Plugin Interface (services/plugins/plugin_interface.py - PiperPlugin)
    ↓
Individual Plugins (services/integrations/*/‹name›_plugin.py)
    ↓ (delegates to)
Integration Routers (services/integrations/*/‹name›_integration_router.py)
    ↓ (uses)
Config Services (services/integrations/*/config_service.py)

Implementation Timeline

GREAT-3A: Foundation (October 2, 2025)

Duration: 1 day GitHub Issue: Part of plugin architecture epic

Achievements:

GREAT-3B: Dynamic Loading (October 3, 2025)

Duration: 1 day GitHub Issue: Part of plugin architecture epic

Achievements:

GREAT-3C: Documentation & Enhancement (October 4, 2025)

Duration: 0.5 day GitHub Issue: Part of plugin architecture epic

Achievements:

GREAT-3D: Validation (October 4, 2025)

Duration: 0.5 day GitHub Issue: Part of plugin architecture epic

Achievements:

Total Implementation: 3 days (October 2-4, 2025) vs estimated 4 weeks

Architecture Details

Two-File Pattern

Each integration consists of:

  1. Plugin File (services/integrations/<name>/<name>_plugin.py, ~111 lines)
    • Implements PiperPlugin interface
    • Delegates to integration router
    • Provides metadata, lifecycle hooks
    • Auto-registers via module import
  2. Router File (services/integrations/<name>/<name>_integration_router.py)
    • Contains business logic
    • Manages integration-specific operations
    • Provides FastAPI routes
    • May include spatial intelligence

Auto-Registration

Plugins auto-register when their module is imported:

# In plugin file
from services.plugins import get_plugin_registry

registry = get_plugin_registry()
registry.register_plugin("github", GitHubPlugin())

No manual registration needed - just import the plugin module.

Configuration in PIPER.user.md

Plugins are enabled/disabled via YAML blocks:

```plugins
enabled:
  - github
  - slack
  - notion
  - calendar
disabled:
  - demo


Config-driven loading allows:
- Runtime plugin control without code changes
- Graceful degradation for unconfigured integrations
- Easy testing with different plugin combinations

### Lifecycle Management

Plugins support async initialization and shutdown:

```python
# Startup
await registry.initialize_all()

# Shutdown
await registry.shutdown_all()

All lifecycle methods are idempotent (can be called multiple times safely).

Performance Characteristics

Performance validation (October 4, 2025) via benchmark suite:

Metric Target Actual Result Margin
Plugin Overhead < 0.05 ms 0.000041 ms ✅ PASS 120× better
Startup Time < 2000 ms 295.23 ms ✅ PASS 6.8× faster
Memory/Plugin < 50 MB 9.08 MB ✅ PASS 5.5× better
Concurrency < 100 ms 0.11 ms ✅ PASS 909× faster

Key Insights:

Benchmark Suite: scripts/benchmarks/ for regression detection

Consequences

Positive (Realized)

Negative (Mitigated)

Trade-offs

Migration Path

If we need to move to “pure plugins” (all logic in plugin, no routers):

  1. Incremental migration: Move one integration at a time
  2. Interface compatibility: PiperPlugin interface stays the same
  3. Router becomes internal: Router logic moves into plugin implementation
  4. No user impact: Plugin consumer code unchanged
  5. Spatial preserved: Spatial adapters move with plugin logic

Current Assessment: Migration not needed. Wrapper pattern performs exceptionally well.

References

Documentation

Implementation

Testing

Original Vision

Success Metrics

Target Metrics (from original decision)

Achieved Metrics (October 2025)

Verification (October 13, 2025)

Documentation Metrics Verification

Serena MCP Symbolic Analysis confirmed all core claims with corrections to documentation sizes:

Document Original Claim Verified Actual Status Notes
ADR-034 size 281 lines 280 lines ⚠️ CORRECTED Off by 1 line
API Reference 685 lines 902 lines ⚠️ CORRECTED +32% larger than claimed
Developer Guide 800+ lines 523 lines ⚠️ CORRECTED Actually smaller than claimed
Contract tests 92 tests 92 tests ✅ ACCURATE 23 methods × 4 plugins
Plugin wrappers 4 wrappers 4 wrappers ✅ ACCURATE GitHub, Slack, Notion, Calendar

Verification Method: Direct file measurement via Serena MCP + bash wc -l + pytest test collection

Implementation Status

Evidence

Verification Notes

Documentation size discrepancies were found and corrected in the GREAT-3 completion report. The plugin architecture implementation itself is sound and all functional claims are accurate. Documentation counts were updated to reflect actual measured file sizes as of October 13, 2025.

Evidence package: dev/2025/10/13/proof-3-great-3-evidence.md