Skip to content
Wovyr

C4 Model – Level 3: Component Diagram

Document ID: ARCH-004 Version: 1.0.1 Status: Draft — Day-1 target-state component diagram, unrevised since project inception. Corrected 2026-07-07: the components below are real (as in-process Rust modules within one wovyr-server binary — see the README’s architecture section and each crate’s own doc comments for the kept-current, per-crate description), but the “Cross-container” communication row using gRPC does not exist (no gRPC anywhere in the codebase) and “Event notification” is not NATS JetStream (no message broker exists — wovyr-events is a custom in-process system; see ADR-0005’s current-status note). This is consistent with ADR-0010’s Path A single-node decision. Owner: Architecture Team Last Updated: 2026-07-07

1. Purpose

Section titled “1. Purpose”

This document describes the internal component architecture of the Wovyr AI Platform.

Where the Container Diagram defines deployable applications, this document defines the major software components inside those containers.

These components map directly to Rust workspace crates and domain boundaries.

2. Scope

Section titled “2. Scope”

This document defines:

  • Internal components
  • Component responsibilities
  • Dependency rules
  • Communication patterns
  • Public interfaces
  • Crate mappings
  • Extension points

Implementation details are intentionally deferred to crate-specific documentation.

3. Component Philosophy

Section titled “3. Component Philosophy”

Components should satisfy the following principles:

  • Single Responsibility
  • High Cohesion
  • Low Coupling
  • Interface Segregation
  • Dependency Inversion
  • Replaceable Implementations
  • Testability
  • Stable Public Contracts

4. Component Hierarchy

Section titled “4. Component Hierarchy”
                           Wovyr AI Platform
                                   │
        ┌──────────────────────────┼──────────────────────────┐
        │                          │                          │
     Platform                 Runtime                    Infrastructure
        │                          │                          │
        ├──────────────┬───────────┴──────────────┬───────────┤
        ▼              ▼                          ▼
 Identity        Workflow Engine          Agent Runtime
 Projects         Scheduler               Planner
 Users            State Machine           Executor
 Config           DAG Engine              Reflection
 Audit            Retry Engine            Context Manager
                  Checkpoint              Goal Manager
        │
        ├─────────────────────────────────────────────────────┐
        ▼                                                     ▼
 Memory Engine                                       LLM Gateway
 Vector Search                                       Provider Registry
 Episodic Memory                                     Router
 Knowledge Graph                                     Streaming
 Embeddings                                          Token Manager
        │                                                     │
        └──────────────────────────┬──────────────────────────┘
                                   ▼
                            Tool Runtime
                          Plugin Framework
                          Event Bus

5. Platform Components

Section titled “5. Platform Components”

Identity Component

Section titled “Identity Component”

Responsibilities:

  • Authentication
  • Authorization
  • Token validation
  • Session management
  • RBAC

Public Interfaces:

  • Auth Service
  • User Context
  • Permission Resolver

Organization Component

Section titled “Organization Component”

Responsibilities:

  • Organizations
  • Teams
  • Membership
  • Tenant isolation

Project Component

Section titled “Project Component”

Responsibilities:

  • Project lifecycle
  • Environment configuration
  • Secrets references
  • Project metadata

Configuration Component

Section titled “Configuration Component”

Responsibilities:

  • Global settings
  • Environment settings
  • Feature flags
  • Runtime configuration

Audit Component

Section titled “Audit Component”

Responsibilities:

  • Audit events
  • Compliance records
  • Security logs

6. Workflow Components

Section titled “6. Workflow Components”

Workflow Definition

Section titled “Workflow Definition”

Responsibilities:

  • Parse workflow DSL
  • Validate definitions
  • Version workflows
  • Compile execution plans

Scheduler

Section titled “Scheduler”

Responsibilities:

  • Timers
  • Delayed execution
  • Cron schedules
  • Queue management

Execution Engine

Section titled “Execution Engine”

Responsibilities:

  • Execute workflow graph
  • Parallel branches
  • Conditional execution
  • Synchronization

State Machine

Section titled “State Machine”

Responsibilities:

  • Lifecycle transitions
  • Durable state
  • Recovery
  • Replay

Checkpoint Manager

Section titled “Checkpoint Manager”

Responsibilities:

  • Save progress
  • Restore execution
  • Snapshot generation

Retry Manager

Section titled “Retry Manager”

Responsibilities:

  • Retry policies
  • Backoff strategies
  • Failure handling

Compensation Engine

Section titled “Compensation Engine”

Responsibilities:

  • Rollback execution
  • Saga orchestration
  • Recovery actions

7. Agent Runtime Components

Section titled “7. Agent Runtime Components”

Planner

Section titled “Planner”

Creates execution plans from user goals.

Reasoner

Section titled “Reasoner”

Coordinates interaction with LLM providers and applies reasoning strategies.

Executor

Section titled “Executor”

Executes workflow steps and tool calls.

Reflection Engine

Section titled “Reflection Engine”

Evaluates previous outputs and determines whether additional reasoning or correction is required.

Goal Manager

Section titled “Goal Manager”

Tracks objectives, progress, priorities, and completion status.

Context Manager

Section titled “Context Manager”

Aggregates runtime state, workflow context, memory retrievals, and tool outputs.

8. Memory Components

Section titled “8. Memory Components”

Short-Term Memory

Section titled “Short-Term Memory”

Maintains execution-specific context.

Long-Term Memory

Section titled “Long-Term Memory”

Stores persistent knowledge and historical interactions.

Semantic Memory

Section titled “Semantic Memory”

Indexes and retrieves embeddings.

Knowledge Graph

Section titled “Knowledge Graph”

Maintains structured relationships between entities.

Embedding Manager

Section titled “Embedding Manager”

Generates, stores, and updates embeddings.

Retrieval Pipeline

Section titled “Retrieval Pipeline”

Ranks, filters, and returns relevant context.

9. LLM Gateway Components

Section titled “9. LLM Gateway Components”

Provider Registry

Section titled “Provider Registry”

Maintains available model providers and capabilities.

Router

Section titled “Router”

Selects the appropriate provider based on policy.

Streaming Engine

Section titled “Streaming Engine”

Supports incremental response delivery.

Token Manager

Section titled “Token Manager”

Tracks token usage, quotas, and estimated cost.

Failover Manager

Section titled “Failover Manager”

Redirects requests when providers are unavailable or exceed policy thresholds.

10. Tool Runtime Components

Section titled “10. Tool Runtime Components”

Tool Registry

Section titled “Tool Registry”

Registers available tools and their metadata.

Permission Manager

Section titled “Permission Manager”

Evaluates tool execution permissions.

Sandbox Manager

Section titled “Sandbox Manager”

Executes tools within isolated environments.

Invocation Engine

Section titled “Invocation Engine”

Coordinates tool execution, validation, and result handling.

11. Plugin Framework Components

Section titled “11. Plugin Framework Components”

Plugin Registry

Section titled “Plugin Registry”

Discovers and indexes installed plugins.

Lifecycle Manager

Section titled “Lifecycle Manager”

Handles installation, activation, upgrade, and removal.

Compatibility Manager

Section titled “Compatibility Manager”

Validates version compatibility and dependency constraints.

Capability Registry

Section titled “Capability Registry”

Publishes plugin-provided services to the platform.

12. Shared Components

Section titled “12. Shared Components”

These cross-cutting components are available across the platform:

  • Event Bus
  • Metrics
  • Logging
  • Distributed Tracing
  • Configuration
  • Secrets
  • Cache
  • Serialization
  • Error Handling
  • Health Monitoring

13. Dependency Rules

Section titled “13. Dependency Rules”

The following dependency rules are mandatory:

  1. Components depend only on published interfaces.
  2. Domain components do not access infrastructure directly.
  3. Infrastructure implementations are replaceable.
  4. Components communicate through explicit contracts.
  5. Circular dependencies are prohibited.

14. Component Communication

Section titled “14. Component Communication”

Preferred communication mechanisms:

InteractionPattern
Same processRust trait interfaces
Cross-containergRPC
Event notificationNATS JetStream
Client accessREST / WebSocket
Long-running workAsynchronous messaging

15. Rust Workspace Mapping

Section titled “15. Rust Workspace Mapping”

Each major component corresponds to one or more Rust crates.

Illustrative mapping:

ComponentWorkspace Crate
Workflow Engineengine-workflow
Agent Runtimeengine-runtime
Memory Engineengine-memory
LLM Gatewayengine-llm
Tool Runtimeengine-tools
Plugin Frameworkengine-plugin
Identityplatform-identity
Projectsplatform-projects
Configurationplatform-config
Auditplatform-audit
Common abstractionsengine-core

Additional crate organization is defined in the Rust workspace architecture.

16. Extension Points

Section titled “16. Extension Points”

Supported extension mechanisms include:

  • Custom LLM providers
  • Workflow activities
  • Memory providers
  • Storage backends
  • Authentication providers
  • Scheduling strategies
  • Plugins
  • Dashboard modules

Extension points must be documented with stable public interfaces.

17. Design Constraints

Section titled “17. Design Constraints”

Components should:

  • Remain independently testable.
  • Avoid implementation leakage.
  • Expose minimal public APIs.
  • Maintain backward compatibility.
  • Minimize compile-time dependencies.
Section titled “18. Related Documents”
  • System Overview
  • C4 Context
  • C4 Container
  • Domain-Driven Design
  • Clean Architecture
  • Rust Workspace Design
  • Architecture Decision Records (ADRs)

19. Revision History

Section titled “19. Revision History”
VersionDateDescription
1.0.12026-07-07Added a header note: no gRPC or NATS exist anywhere in the codebase, contradicting the communication-pattern table. Found during a project-wide doc review; no content changed
1.0.02026-06-26Initial C4 Level 3 – Component Diagram