Deployment Principles

ContextUnity is built on a service-oriented gRPC mesh. It runs symmetrically: as a locally-orchestrated developer sandbox or as a hardened bare-metal native systemd cluster.

1. Environments

Local Development

In local mode, the environment runs with minimal overhead and rapid reload capability.

• Orchestration: The ContextUnity CLI supervisor controls the processes locally. Running contextunity up launches the entire mesh (Router, Brain, Worker, View, Shield) in the foreground.
• Network: Services bind to their default gRPC ports on localhost (e.g. 50050 for Router, 50051 for Brain).
• Storage: Connects to local Redis and PostgreSQL instances.
• Security: Symmetrical security checks are active. API keys and secrets are loaded from the local .env file or environment variables, acting as lightweight fallbacks to the production credentials store. TLS is optionally disabled locally for debugging.

Production Deployment

Production environments focus on Zero-Trust isolation, bare-metal speed, and high availability.

• Orchestration: Ansible playbooks (infrastructure/ansible/) provision and configure native systemd services on physical or virtual Linux hosts.
• Network: Services communicate primarily over standard gRPC, bound to discrete ports.
• Storage: Connects to high-availability external managed databases (e.g., PostgreSQL clusters, Redis instances, and Temporal clusters).
• Security: Zero-Trust configuration. Services communicate over gRPC with mandatory TLS/mTLS. Redis payloads are encrypted. Plaintext secrets are strictly prohibited on disk; all secrets are provisioned via systemd-creds and decrypted directly into the service process’s memory space.

---

2. Horizontal Scaling

Every ContextUnity Python service (contextunity.router, contextunity.brain, contextunity.worker) is designed to be stateless.

Service Discovery & Load Balancing

1. Register: When a service replica (e.g., contextunity.brain) starts up, it registers its listening endpoint with Redis.
2. Heartbeat: Replicas maintain an active lease with Redis. If a service process crashes, its lease expires, and it is automatically removed from the active registry.
3. Resolve: contextunity.router monitors the Redis registry and dynamically adds discovered service instances to its gRPC client pool.
4. Execute: Client calls are load-balanced across the pool using round-robin routing or sharded keys.

This enables you to scale any service tier up or down (e.g., running multiple ContextWorker workers to process high-volume supplier feed updates) dynamically without any service disruption.

---

3. Configuration Management

ContextUnity isolates configurations from runtime state. Configuration models are typed and validated on startup using Pydantic schemas.

Precedence & Separation of Concerns

• YAML Config Files: Source of truth for all non-sensitive parameters. Deployed to the service working directory (/opt/contextunity/{service}/{service}.yml).
• Encrypted Secrets: Handled strictly via systemd credentials. Encrypted at rest, decrypted in memory.
• Minimal Environment: The .env file contains only runtime environment declarations like pathing or Python interpreter overrides.

Production Configuration Example

Non-secret parameters are read from the YAML configuration:

/opt/contextunity/brain/brain.yml

host: "192.168.77.123"
port: 50051
log_level: INFO
redis:
  url: "redis://192.168.77.121:6379/0"
tls_enabled: true
tls_ca_cert: "/opt/contextunity/brain/certs/ca.crt"

The systemd service unit loads the minimal .env file for runtime context:

/opt/contextunity/brain/.env

PYTHONPATH=/opt/contextunity/core/src:/opt/contextunity/brain/src
PYTHONUNBUFFERED=1

All credentials (such as the database URL containing the connection password and Redis keys) are provisioned securely via systemd-creds and never appear on disk or in the env file in plaintext.