Skip to content

ADR-0004: Plugin Architecture

Status: Superseded

Date: 2026-07-23

Related Documents:

  • ARCHITECTURE.md
  • ROADMAP.md

Supersedes: None

Superseded by: ADR-0008: Community Provider Plugin Boundary

Context

The AI ecosystem evolves rapidly.

New providers, authentication methods, routing strategies, protocols, observability integrations, and deployment environments continue to emerge.

Embedding these integrations directly into the runtime would tightly couple Trussium to specific implementations, making the project increasingly difficult to maintain and extend.

An extensibility model is therefore required.

Decision

Trussium adopts a plugin-based architecture for extensible components.

The runtime provides stable extension points through well-defined interfaces.

Plugins implement those interfaces and register themselves with the runtime during initialization.

The runtime discovers and orchestrates plugins without depending on their internal implementations.

Plugin Types

The following components are designed to support plugins.

AI Providers

Examples:

  • OpenAI
  • Anthropic
  • Google Gemini
  • Ollama
  • Azure OpenAI
  • Amazon Bedrock
  • vLLM

Capabilities

Examples:

  • Chat
  • Embeddings
  • Image Generation
  • Audio
  • Reranking
  • Video
  • Tool Execution
  • Agent Execution

Protocols

Examples:

  • REST
  • gRPC
  • Model Context Protocol (MCP)

Future protocols may be introduced without modifying the runtime.

Authentication

Examples:

  • API Keys
  • OAuth2
  • JWT
  • mTLS

Authorization

Examples:

  • RBAC
  • ABAC
  • Custom Policy Engines

Routing

Examples:

  • Round Robin
  • Provider Priority
  • Cost Optimized
  • Latency Optimized
  • Geographic Routing

Observability

Examples:

  • OpenTelemetry
  • Prometheus
  • Custom Metrics Exporters
  • Distributed Tracing

Middleware

Examples:

  • Request Logging
  • Rate Limiting
  • Request Validation
  • Auditing
  • Request Transformation

Registration

Plugins register themselves with the runtime through dedicated registries.

Conceptually:

Plugin

↓

Registry

↓

Runtime Discovery

↓

Execution

The runtime interacts with plugin interfaces rather than concrete implementations.

Discovery

The runtime is responsible for discovering registered plugins during initialization.

Discovery mechanisms may evolve over time.

Examples include:

  • Static registration
  • Package entry points
  • Configuration-driven loading
  • Dynamic plugin discovery

The discovery mechanism is intentionally separated from plugin implementations.

Design Principles

Plugins should:

  • Be independently testable.
  • Have clearly defined interfaces.
  • Avoid dependencies on other plugins.
  • Be replaceable without modifying the runtime.
  • Minimize assumptions about deployment environments.

The runtime should remain unaware of plugin implementation details.

Benefits

The plugin architecture provides:

  • Extensibility
  • Loose coupling
  • Independent evolution
  • Easier testing
  • Community contributions
  • Vendor neutrality

The architecture allows Trussium to evolve alongside the AI ecosystem without requiring fundamental runtime redesign.

Consequences

Positive

  • New functionality can be added without modifying core runtime components.
  • Provider integrations remain isolated.
  • Plugins can evolve independently.
  • Third-party extensions become possible.
  • Cleaner architectural boundaries.

Negative

  • Additional abstraction.
  • More interface definitions.
  • Plugin lifecycle management increases complexity.
  • Compatibility between runtime and plugins must be maintained.

These trade-offs are considered acceptable for a long-lived extensible platform.

Alternatives Considered

Option 1 — Built-in Integrations

All providers and runtime components are implemented directly within the runtime.

Advantages

  • Simpler implementation.
  • Fewer abstractions.
  • Easier debugging.

Rejected because:

  • Tight coupling.
  • Reduced extensibility.
  • Larger runtime.
  • Difficult community contribution model.

Option 2 — Plugin-Based Architecture

Core runtime remains small.

Integrations are implemented as plugins.

Advantages

  • Extensible.
  • Modular.
  • Easier maintenance.
  • Supports third-party integrations.
  • Long-term scalability.

Accepted.

Compliance

Any component expected to support multiple implementations should expose a stable plugin interface.

Plugins should interact with the runtime exclusively through documented extension points.

Changes that affect plugin contracts require a new Architecture Decision Record.