Skip to content
Wovyr

Deployment Architecture

Document ID: ARCH-008 Version: 1.0.1 Status: Draft — Day-1 target-state deployment vision, unrevised since project inception; superseded for GA by ADR-0010 (Path A, 2026-07-06): GA ships as a single-node appliance, not the multi-service HA topology described below. Corrected 2026-07-07: what’s real is deployment/docker-compose.yml (one wovyr binary + optional Postgres + Qdrant) and deployment/helm/wovyr/ (the same single-binary topology, replicas: 1 by product decision, offline-validated only, never applied to a live cluster). NATS JetStream and S3-compatible/MinIO object storage are not built at all (see ADR-0005’s current-status note and prd.md §25 for where the object-storage gap is now tracked — GA-002). mTLS between services is moot since there’s only one process; the real security floor is wovyr-server’s own auth/TLS layer (RM-GA-P1). The multi-replica/HA remainder of this document is the acknowledged, still-open gap tracked in GA-002 and Track B of phase3-scale-distribution-tickets.md (the v1.1 “Scale-Out” milestone). Owner: Architecture Team Last Updated: 2026-07-07

1. Purpose

Section titled “1. Purpose”

This document defines the deployment architecture of the Wovyr AI Platform.

It describes supported deployment models, infrastructure topology, networking, service discovery, scaling, high availability, disaster recovery, secrets management, and operational considerations.

2. Objectives

Section titled “2. Objectives”

The deployment architecture is designed to provide:

  • Cloud portability
  • High availability
  • Horizontal scalability
  • Secure operations
  • Operational simplicity
  • Infrastructure automation
  • Zero-downtime deployments

3. Deployment Philosophy

Section titled “3. Deployment Philosophy”

The platform follows a Deploy Anywhere model.

Supported environments:

  • Local development
  • CI/CD ephemeral environments
  • Team shared environments
  • Production Kubernetes clusters
  • Multi-region enterprise deployments

Infrastructure choices must not require changes to business logic.

4. Deployment Topologies

Section titled “4. Deployment Topologies”

Local Development

Section titled “Local Development”

Purpose:

  • Individual developer workstations

Components:

  • Single Rust executable
  • Angular development server
  • PostgreSQL
  • Redis
  • Qdrant
  • NATS JetStream
  • Local object storage (MinIO)

Characteristics:

  • Fast startup
  • Minimal operational overhead
  • Hot reload for UI and APIs

Team Environment

Section titled “Team Environment”

Purpose:

  • Shared integration and QA

Components:

  • Modular monolith
  • Managed PostgreSQL
  • Managed Redis
  • Shared Qdrant
  • Shared object storage

Characteristics:

  • Stable integration testing
  • Shared configuration
  • Centralized monitoring

Production

Section titled “Production”

Purpose:

  • Customer-facing workloads

Components:

  • API Gateway
  • Agent Runtime
  • Workflow Engine
  • Memory Engine
  • LLM Gateway
  • Dashboard Backend
  • Scheduler
  • Plugin Engine

Characteristics:

  • Independent scaling
  • Rolling updates
  • Health monitoring
  • Auto-recovery

Enterprise

Section titled “Enterprise”

Purpose:

  • Mission-critical deployments

Capabilities:

  • Multi-region clusters
  • Active-active or active-passive topology
  • Disaster recovery
  • Regional failover
  • Dedicated observability stack

5. Reference Deployment

Section titled “5. Reference Deployment”
                   Internet
                       │
               External Load Balancer
                       │
                 Kubernetes Ingress
                       │
                  API Gateway Service
                       │
      ┌───────────────┼────────────────┐
      ▼               ▼                ▼
 Agent Runtime   Workflow Engine   Platform Services
      │               │                │
      ├───────────────┼────────────────┤
      ▼               ▼                ▼
 Memory Engine   LLM Gateway     Tool Runtime
      │               │                │
      └───────────────┼────────────────┘
                      ▼
                 NATS JetStream
                      │
      ┌───────────────┼────────────────┐
      ▼               ▼                ▼
 PostgreSQL       Redis            Qdrant
                      │
                      ▼
              S3-Compatible Storage

6. Containerization

Section titled “6. Containerization”

Every deployable service is packaged as a minimal OCI-compatible container image.

Guidelines:

  • Multi-stage builds
  • Non-root user
  • Read-only root filesystem where possible
  • Health endpoints exposed
  • Immutable images

7. Kubernetes Architecture

Section titled “7. Kubernetes Architecture”

Recommended resources:

  • Deployments
  • StatefulSets (where required)
  • Services
  • Ingress
  • ConfigMaps
  • Secrets
  • PersistentVolumeClaims
  • HorizontalPodAutoscalers
  • NetworkPolicies

Namespaces should separate environments (e.g., dev, staging, prod).

8. Networking

Section titled “8. Networking”

Traffic Flow:

  1. Client → Ingress
  2. Ingress → API Gateway
  3. API Gateway → Internal services
  4. Internal services → Data stores / Event Bus

All service-to-service communication should use authenticated and encrypted channels (mTLS where supported).

9. Service Discovery

Section titled “9. Service Discovery”

Service discovery options:

  • Kubernetes DNS
  • Consul (optional)
  • Service mesh integration (optional)

Internal services communicate using stable service names rather than IP addresses.

10. Configuration Management

Section titled “10. Configuration Management”

Configuration sources:

  • Environment variables
  • ConfigMaps
  • Secrets
  • Runtime configuration service (future)

Configuration must be externalized and version-controlled where appropriate.

11. Secrets Management

Section titled “11. Secrets Management”

Secrets include:

  • API keys
  • Database credentials
  • LLM provider tokens
  • TLS certificates

Recommended options:

  • Kubernetes Secrets
  • HashiCorp Vault
  • Cloud-native secret managers

Secrets must never be embedded in container images or source code.

12. Data Persistence

Section titled “12. Data Persistence”
ComponentStorage
Relational DataPostgreSQL
CacheRedis
Vector IndexQdrant
Object StorageS3-compatible
Event StreamsNATS JetStream

Persistent volumes should be provisioned according to workload requirements.

13. High Availability

Section titled “13. High Availability”

Key strategies:

  • Multiple replicas for stateless services
  • Database replication
  • Redundant message brokers
  • Health probes
  • Automatic restart policies

Critical services should tolerate node failures without service interruption.

14. Scaling Strategy

Section titled “14. Scaling Strategy”
ComponentScaling Approach
API GatewayHorizontal
Agent RuntimeHorizontal
Workflow EngineHorizontal
Memory EngineRead-heavy horizontal scaling
LLM GatewayHorizontal
Dashboard BackendHorizontal
PostgreSQLPrimary/Replica
RedisCluster
QdrantDistributed
NATSClustered

Autoscaling should be based on CPU, memory, queue depth, and request latency.

15. Deployment Strategy

Section titled “15. Deployment Strategy”

Supported deployment methods:

  • Rolling updates
  • Blue/Green deployments
  • Canary releases

Rollback procedures must be automated and tested.

16. Disaster Recovery

Section titled “16. Disaster Recovery”

Objectives:

  • Backup relational data
  • Snapshot vector indexes
  • Replicate object storage
  • Preserve event streams where required

Define:

  • Recovery Point Objective (RPO)
  • Recovery Time Objective (RTO)

Regular disaster recovery drills should be part of operations.

17. Observability

Section titled “17. Observability”

Every deployment includes:

  • Prometheus metrics
  • OpenTelemetry traces
  • Structured logs
  • Grafana dashboards
  • Alerting

Health endpoints:

  • /health
  • /ready
  • /live

18. Security

Section titled “18. Security”

Deployment security includes:

  • TLS termination
  • Mutual TLS for internal traffic
  • Network policies
  • Role-Based Access Control (RBAC)
  • Image signing
  • Vulnerability scanning
  • Runtime security monitoring

19. CI/CD Integration

Section titled “19. CI/CD Integration”

Deployment pipeline stages:

  1. Build
  2. Unit Tests
  3. Static Analysis
  4. Security Scans
  5. Container Build
  6. Integration Tests
  7. Publish Images
  8. Deploy
  9. Smoke Tests
  10. Promote

20. Environment Matrix

Section titled “20. Environment Matrix”
EnvironmentPurposeScale
LocalDevelopmentSingle process
CIAutomated validationEphemeral
DevTeam integrationSmall
StagingPre-productionProduction-like
ProductionCustomer workloadsScalable
EnterpriseMulti-regionHighly available

21. Operational Guidelines

Section titled “21. Operational Guidelines”
  • Prefer immutable infrastructure.
  • Automate provisioning using Infrastructure as Code.
  • Monitor service-level objectives (SLOs).
  • Document runbooks for common operational tasks.
  • Test backup and restore procedures regularly.
Section titled “22. Related Documents”
  • System Overview
  • C4 Context
  • C4 Container
  • C4 Component
  • Clean Architecture
  • Event-Driven Architecture
  • DevOps Architecture
  • Disaster Recovery Plan
  • ADRs

23. Revision History

Section titled “23. Revision History”
VersionDateDescription
1.0.12026-07-07Added a header note: this doc’s multi-service HA/multi-region topology is superseded for GA by ADR-0010’s Path A decision; NATS and object storage were never built. Found during a project-wide doc review; no content changed
1.0.02026-06-26Initial Deployment Architecture document