Skip to content
Wovyr

C4 Model – Level 1: System Context

Document ID: ARCH-002 Version: 1.0.1 Status: Draft — Day-1 target-state context diagram, unrevised since project inception. Corrected 2026-07-07: the “Databases”/“Messaging Systems” lists below are illustrative categories of external system this architecture could integrate with, not a description of what’s wired today. The shipping single-node binary (wovyr-server, ADR-0010 Path A) uses file-based storage by default; PostgreSQL/Redis/Qdrant are real but optional, feature-gated backends; there is no messaging system of any kind (NATS/Kafka/RabbitMQ) — see prd.md §25 for where the NATS gap is now tracked. Owner: Architecture Team Last Updated: 2026-07-07

1. Purpose

Section titled “1. Purpose”

This document describes the highest level of the Wovyr AI Platform architecture using the C4 Model.

The System Context view answers the following questions:

  • What is the Wovyr AI Platform?
  • Who uses it?
  • Which external systems interact with it?
  • What are the platform boundaries?
  • What responsibilities belong inside and outside the platform?

This document provides a common understanding for business stakeholders, architects, developers, operations teams, and security teams.

2. Scope

Section titled “2. Scope”

This document covers:

  • Platform boundary
  • Primary users
  • External systems
  • High-level integrations
  • Trust boundaries
  • Primary data flows
  • Architectural assumptions

It intentionally omits internal implementation details, which are covered in the Container and Component architecture documents.

3. System Context

Section titled “3. System Context”

The Wovyr AI Platform is an enterprise-grade platform for building, deploying, orchestrating, and operating intelligent AI systems.

It provides reusable infrastructure for:

  • AI agent execution
  • Workflow orchestration
  • Memory management
  • Tool execution
  • Plugin management
  • Multi-provider LLM integration
  • Operational monitoring
  • API access
  • Enterprise governance

The platform exposes these capabilities through APIs, SDKs, a web dashboard, and a CLI.

4. System Boundary

Section titled “4. System Boundary”

The following capabilities are considered part of the Wovyr AI Platform:

  • API Gateway
  • Agent Runtime
  • Workflow Engine
  • Memory Engine
  • Tool Runtime
  • LLM Gateway
  • Plugin Framework
  • Dashboard Backend
  • CLI Backend
  • Authentication
  • Authorization
  • Scheduler
  • Event Bus
  • Configuration
  • Observability
  • Audit Services

The following capabilities are external to the platform:

  • Foundation model providers
  • External databases
  • Identity providers
  • Source control systems
  • Cloud infrastructure
  • Enterprise messaging systems
  • Third-party APIs

5. Primary Actors

Section titled “5. Primary Actors”

Developer

Section titled “Developer”

Responsibilities:

  • Create AI applications
  • Build workflows
  • Develop plugins
  • Configure deployments
  • Debug executions

Primary Interfaces:

  • CLI
  • Dashboard
  • REST API
  • SDK

Platform Administrator

Section titled “Platform Administrator”

Responsibilities:

  • Manage users
  • Configure providers
  • Manage deployments
  • Monitor runtime health
  • Configure policies

Enterprise User

Section titled “Enterprise User”

Responsibilities:

  • Execute approved workflows
  • Review results
  • Manage projects
  • Collaborate with teams

Plugin Developer

Section titled “Plugin Developer”

Responsibilities:

  • Build reusable extensions
  • Publish plugins
  • Maintain compatibility
  • Test integrations

DevOps Engineer

Section titled “DevOps Engineer”

Responsibilities:

  • Deploy infrastructure
  • Configure Kubernetes
  • Scale workloads
  • Monitor services
  • Manage upgrades

6. External Systems

Section titled “6. External Systems”

Identity Provider

Section titled “Identity Provider”

Examples:

  • Microsoft Entra ID
  • Keycloak
  • Okta
  • Auth0

Responsibilities:

  • Authentication
  • Single Sign-On (SSO)
  • Identity federation

LLM Providers

Section titled “LLM Providers”

Examples:

  • OpenAI
  • Anthropic
  • Google Gemini
  • Ollama
  • Azure OpenAI
  • Local inference servers

Responsibilities:

  • Model inference
  • Embeddings
  • Streaming responses

Databases

Section titled “Databases”

Examples:

  • PostgreSQL
  • Redis
  • Qdrant
  • S3-compatible object storage

Responsibilities:

  • Persistence
  • Caching
  • Vector search
  • Artifact storage

Messaging Systems

Section titled “Messaging Systems”

Examples:

  • NATS
  • Apache Kafka
  • RabbitMQ

Responsibilities:

  • Event distribution
  • Asynchronous communication

Monitoring Systems

Section titled “Monitoring Systems”

Examples:

  • Prometheus
  • Grafana
  • Jaeger
  • OpenTelemetry collectors

Responsibilities:

  • Metrics
  • Dashboards
  • Tracing
  • Alerting

Source Control

Section titled “Source Control”

Examples:

  • GitHub
  • GitLab
  • Azure DevOps

Responsibilities:

  • Repository management
  • CI/CD integration
  • Workflow storage

7. System Context Diagram

Section titled “7. System Context Diagram”
                        +------------------------------+
                        |         Developers           |
                        +--------------+---------------+
                                       |
                                       |
                     CLI / SDK / Dashboard / REST API
                                       |
                                       v
+--------------------------------------------------------------------------+
|                         Wovyr AI Platform                                 |
|--------------------------------------------------------------------------|
| API Gateway                                                              |
| Agent Runtime                                                            |
| Workflow Engine                                                          |
| Memory Engine                                                            |
| LLM Gateway                                                              |
| Tool Runtime                                                             |
| Plugin Framework                                                         |
| Dashboard Backend                                                        |
| Scheduler                                                                |
| Event Bus                                                                |
| Identity & Access                                                        |
| Observability                                                            |
+--------------------------------------------------------------------------+
     |            |             |            |            |             |
     |            |             |            |            |             |
     v            v             v            v            v             v
 Identity     LLM Providers  Databases   Messaging   Monitoring   Source Control
 Provider                    Storage      Systems      Systems        Systems

8. Trust Boundaries

Section titled “8. Trust Boundaries”

The architecture defines the following trust zones:

External Zone

Section titled “External Zone”

Untrusted clients and internet-facing systems.

Examples:

  • Browsers
  • CLI users
  • SDK clients

Platform Zone

Section titled “Platform Zone”

Trusted application services.

Examples:

  • Runtime
  • Workflow
  • Memory
  • Scheduler
  • APIs

Infrastructure Zone

Section titled “Infrastructure Zone”

Managed infrastructure.

Examples:

  • Databases
  • Object storage
  • Message brokers

Third-Party Zone

Section titled “Third-Party Zone”

External services outside platform control.

Examples:

  • LLM providers
  • Identity providers
  • External APIs

Communication across trust boundaries should use authenticated and encrypted channels.

9. High-Level Interaction Flow

Section titled “9. High-Level Interaction Flow”
  1. A developer or application submits a request.
  2. The API Gateway authenticates and authorizes the request.
  3. The Agent Runtime receives the task.
  4. The Workflow Engine creates or resumes execution.
  5. The Memory Engine retrieves contextual information.
  6. The LLM Gateway invokes one or more model providers.
  7. The Tool Runtime executes permitted tools when required.
  8. Workflow state is persisted.
  9. Observability services record metrics, logs, and traces.
  10. The response is returned to the caller.

10. External Interfaces

Section titled “10. External Interfaces”

The platform provides the following public interfaces:

  • REST API
  • gRPC API
  • WebSocket API
  • Command Line Interface
  • Software Development Kits
  • Dashboard UI

Future interfaces may include GraphQL and Model Context Protocol (MCP) adapters.

11. Security Considerations

Section titled “11. Security Considerations”

All external requests should pass through:

  • Authentication
  • Authorization
  • Rate limiting
  • Audit logging
  • Input validation
  • TLS encryption

Plugins and tool execution should operate within defined permission boundaries.

12. Assumptions

Section titled “12. Assumptions”

This architecture assumes:

  • Multi-cloud deployment support
  • Provider-neutral integrations
  • Stateless service design where appropriate
  • Durable workflow execution
  • Horizontal scalability
  • Extensible plugin ecosystem

13. Constraints

Section titled “13. Constraints”

The platform must:

  • Remain cloud-agnostic
  • Avoid mandatory vendor lock-in
  • Support modular deployment
  • Maintain stable public APIs
  • Preserve backward compatibility for supported releases
Section titled “14. Related Documents”
  • System Overview
  • C4 Container Diagram
  • C4 Component Diagram
  • Domain-Driven Design
  • Clean Architecture
  • Deployment Architecture
  • Security Architecture
  • Architecture Decision Records (ADRs)

15. Revision History

Section titled “15. Revision History”
VersionDateDescription
1.0.12026-07-07Added a header note clarifying the “Databases”/“Messaging Systems” lists are illustrative categories, not current integrations; ADR-0010’s Path A reality has no messaging system at all. Found during a project-wide doc review; no content changed
1.0.02026-06-26Initial C4 Level 1 – System Context document