Architecture — bRRAIn Docs

An overview of bRRAIn's eight-zone architecture and how each zone contributes to the platform.

Architecture

bRRAIn is built on an eight-zone architecture designed for security, scalability, and separation of concerns. Each zone operates independently with well-defined interfaces, allowing teams to scale, upgrade, or replace individual components without affecting the rest of the system.

The Eight Zones

The following diagram illustrates how data flows through the bRRAIn platform:

Client Request
    |
    v
[1. Integration Zone] --> [2. Ingestion Zone] --> [3. Processing Zone]
                                                         |
                                                         v
[8. Observability Zone]  <--  [4. Storage Zone]  <--  [Enrichment]
         |                          |
         v                          v
[7. Orchestration Zone]      [5. Retrieval Zone]
                                    |
                                    v
                            [6. Security Zone]

Zone 1: Integration

The Integration Zone is the external boundary of the platform. It manages all inbound and outbound connections including REST APIs, webhooks, SDK clients, and third-party integrations. This zone handles request routing, protocol translation, and API versioning.

Key capabilities:

  • API Gateway with rate limiting, request validation, and response caching
  • Webhook delivery with retry logic and dead-letter queues
  • SDK endpoints optimized for the Go, Python, and JavaScript client libraries
  • OAuth 2.0 and SAML integration for enterprise single sign-on

The Integration Zone enforces API contracts and ensures backward compatibility across versions. All requests are authenticated and authorized before passing to downstream zones.

Zone 2: Ingestion

The Ingestion Zone receives raw content and normalizes it into a standard internal format. Whether data arrives as plain text, structured JSON, PDF documents, or Slack messages, the Ingestion Zone converts it into a canonical Memory Object representation.

Key capabilities:

  • Format detection and automatic content extraction
  • Chunking of large documents into semantically meaningful segments
  • Deduplication checks against existing memory objects using content hashing
  • Schema validation ensuring all required metadata fields are present

The zone uses a queue-based architecture to handle burst traffic. Incoming objects are enqueued and processed asynchronously, with acknowledgment sent to the client immediately upon receipt.

Zone 3: Processing

The Processing Zone enriches memory objects with semantic understanding. This is where bRRAIn's AI capabilities transform raw content into knowledge.

Key capabilities:

  • Embedding generation using transformer models for semantic search
  • Entity extraction identifying people, organizations, dates, and concepts
  • Relationship mapping connecting new memory objects to existing knowledge
  • Summarization creating concise representations of longer content
  • Classification applying taxonomy labels based on content analysis

Processing is the most compute-intensive zone and scales horizontally with GPU-backed worker nodes. Each enrichment step is idempotent, allowing safe retries on failure.

Zone 4: Storage

The Storage Zone manages the persistent storage of memory objects and their associated metadata, embeddings, and relationships. It provides the underlying data layer that other zones query.

Key capabilities:

  • Encrypted object storage with per-vault encryption keys
  • Vector database for embedding-based similarity search
  • Graph storage for relationship traversal queries
  • Metadata index for structured filtering and faceted search
  • Versioned snapshots enabling point-in-time recovery

The Storage Zone uses PostgreSQL for metadata, a dedicated vector store for embeddings, and encrypted blob storage for raw content. All writes are transactional with write-ahead logging.

Zone 5: Retrieval

The Retrieval Zone handles all read operations, from simple key-based lookups to complex semantic queries. It orchestrates across multiple storage backends to assemble comprehensive results.

Key capabilities:

  • Semantic search using vector similarity with configurable distance metrics
  • Hybrid search combining keyword and semantic matching for optimal recall
  • Contextual ranking adjusting relevance based on the requester's workspace and history
  • Aggregation pipelines for analytics and reporting queries
  • Streaming responses for large result sets

Retrieval requests pass through a query planner that determines the optimal execution strategy based on the query type, expected result size, and available indexes.

Zone 6: Security

The Security Zone enforces authentication, authorization, and encryption across all other zones. It operates as a cross-cutting concern rather than a sequential step in the data pipeline.

Key capabilities:

  • Zero-trust authentication verifying identity on every request
  • Role-based access control (RBAC) with workspace-scoped permissions
  • Encryption key management with support for customer-managed keys (BYOK)
  • Audit logging recording every access and modification event
  • Data loss prevention (DLP) scanning content for sensitive information

The Security Zone maintains its own isolated key store and never exposes encryption keys to other zones. All inter-zone communication is mutually authenticated using short-lived certificates.

Zone 7: Orchestration

The Orchestration Zone coordinates complex workflows that span multiple zones. It manages agent scheduling, background jobs, and multi-step pipelines.

Key capabilities:

  • Agent lifecycle management starting, monitoring, and stopping autonomous agents
  • Workflow engine for multi-step ingestion and processing pipelines
  • Job scheduling with cron-based and event-driven triggers
  • Circuit breaking and backpressure to prevent cascade failures

The Orchestration Zone uses a durable task queue that guarantees at-least-once execution. Failed tasks are retried with exponential backoff and eventually routed to a dead-letter queue for manual review.

Zone 8: Observability

The Observability Zone provides visibility into the health, performance, and behavior of the entire platform. It collects metrics, logs, and traces from all other zones.

Key capabilities:

  • Distributed tracing with OpenTelemetry-compatible span collection
  • Metrics aggregation for latency, throughput, error rates, and resource utilization
  • Structured logging with correlation IDs linking related events across zones
  • Alerting with configurable thresholds and notification channels
  • Dashboards pre-built for common operational views

All telemetry data is stored in a time-series database with configurable retention periods. The Observability Zone itself is designed to degrade gracefully under load so that monitoring failures never impact production traffic.

Design Principles

The eight-zone architecture follows these guiding principles:

  1. Defense in depth: Security is not a single layer but a property enforced at every zone boundary
  2. Independent scalability: Each zone scales based on its own resource profile without over-provisioning others
  3. Graceful degradation: If one zone becomes unhealthy, the system continues to serve requests at reduced capacity
  4. Observability by default: Every zone emits structured telemetry without requiring additional instrumentation
  5. Immutable data: Memory objects are append-only, providing a complete audit trail and enabling point-in-time queries

Next Steps