Framework Architecture

Understand the technical architecture and design principles behind AI Builder

AI Builder is built on a modern, event-driven architecture that enables scalable, flexible, and maintainable AI applications. This page explains the core architectural principles and components that power the platform.

Three-Tier Architecture

AI Builder follows a classic three-tier architecture pattern, modernized for cloud-native, event-driven applications:

Presentation Tier

The UI layer that users interact with, built using:

• Next.js: For server-side rendering and optimal performance
• React: For component-based UI development
• BlockProtocol.org Components: For standardized UI building blocks
• Tailwind CSS: For styling and responsive design

This tier consists of Pages and Blocks in the AI Builder interface.

Application Tier

The business logic layer that processes data and orchestrates workflows:

• Event Processing Engine: For handling asynchronous operations
• API Gateway: For external system integration
• Runtime: For automation runtime

This tier is represented by Automations in the AI Builder interface.

Data Tier

The storage layer that maintains state and persists information:

• Memory Stores: For session, user, and global variables
• Event Log: For activity tracking and debugging
• Vector Databases: For AI knowledge storage (with AI Knowledge)
• Relational Databases: For structured data (with AI Collection)

This tier is accessed through variables and specialized apps.

Event-Driven Architecture (EDA)

AI Builder’s core interaction model is built around events, enabling loose coupling and asynchronous communication between components:

Key Components of the EDA

Event Types

System Events

Description: Platform-generated events for key operations
Examples: page load, block mount, automation start/end, error occurrence

Custom Events

Description: User-defined events for application-specific logic
Examples: form submission, data request, process completion

UI Events

Description: User interaction events from blocks and pages
Examples: button click, selection change, data input

External Events

Description: Webhooks and API calls from outside systems
Examples: third-party notifications, scheduled triggers, external system callbacks

Event Communication Channels

WebSocket

Description: Real-time communication between frontend and backend
Used for: UI updates, event streaming, long-running processes

HTTP

Description: Request-response communication for APIs
Used for: External system integration, data fetching, authentication

Event Broker

Description: Internal communication between automations
Default implementation: Redis Streams for reliable, ordered event delivery

Event Processing

Synchronous Processing

Description: Immediate handling with response
Used for: Direct API calls, user-facing operations requiring immediate feedback

Asynchronous Processing

Description: Queued handling without waiting
Used for: Background tasks, long-running operations, scheduled processes

Event Correlation

Description: Tracking related events across the system
Implementation: Correlation IDs to trace event chains through the system

Event Flow in AI Builder

1. Event Emission

   Events can originate from multiple sources:

   • UI components (blocks) emitting user interaction events
   • Pages emitting lifecycle and navigation events
   • Automations emitting custom process events
   • External systems emitting webhook events
2. Event Routing

   The event router determines where events should be delivered:

   • UI events are routed to relevant automations
   • Automation events may be routed to other automations
   • System events are routed to appropriate handlers
   • Events can be filtered and transformed during routing
3. Event Handling

   Recipients process events according to their type:

   • Blocks may update their display based on received events
   • Pages may navigate or modify their structure
   • Automations execute logic sequences in response to events
   • System components update state or perform operations
4. Event Logging

   All events are recorded in the Activity log:

   • Event metadata (timestamp, source, type)
   • Event payload (data content)
   • Correlation information (related events)
   • Processing results and any errors

Microservices Architecture

AI Builder is built on a microservices foundation, providing scalability and resilience:

Service Isolation

Description: Each functional area operates as an independent service

• UI rendering service
• Automation execution service
• Event processing service
• Storage and persistence services
• Integration services

API-First Design

Description: All services communicate through well-defined APIs

• RESTful HTTP interfaces
• Event-based messaging
• Versioned API contracts
• Standardized error handling

Containerization

Description: Services are packaged as containers for consistent deployment

• Docker containers for all services
• Kubernetes orchestration
• Horizontal scaling capabilities
• Resource isolation
• Deployment consistency

Service Discovery

Description: Dynamic service location and communication

• Automatic service registration
• Load balancing between instances
• Health monitoring
• Circuit breaking for fault tolerance
• Failover mechanisms

Cloud-Native Architecture

AI Builder is designed as a cloud-native application with key characteristics:

Infrastructure as Code

All infrastructure components are defined as code:

• Terraform: For provisioning cloud resources
• Helm Charts: For Kubernetes deployments
• GitOps: For configuration management
• Declarative Specifications: For resource definitions

This enables consistent deployments across environments and clouds.

Multi-Cloud Support

AI Builder can run on multiple cloud providers:

• AWS: Amazon Web Services
• Azure: Microsoft Azure
• GCP: Google Cloud Platform
• OpenShift: For hybrid cloud environments

The platform is designed to leverage cloud-native services while maintaining portability.

Scalability

The architecture supports both vertical and horizontal scaling:

• Auto-scaling: Based on load and resource utilization
• Stateless Design: For easy replication
• Caching: For performance optimization
• Distributed Processing: For workload distribution

This ensures the platform can handle varying loads efficiently.

Security Architecture

Security is built into every layer of the AI Builder framework:

Authentication & Authorization

SSO Integration

Description:

Enterprise single sign-on support Supports:

SAML-v2 & OpenID Connect

RBAC

Description:

Role-based access control Features:

Granular permission model, custom role definitions, inheritance

API Security

Description: Secure API communication Implementation: API keys, JWT tokens, scoped permissions

Workspace Isolation

Description: Secure separation between workspaces Approach: Logical and physical isolation of resources and data

Data Protection

Encryption

Description: Data protection at rest and in transit Methods: TLS 1.3, AES-256, envelope encryption for secrets

Secrets Management

Description:

Secure storage of sensitive information Implementation:

Vault integration, key rotation, least privilege access

Data Residency

Description: Control over data location Features: Region selection, data sovereignty compliance

Privacy by Design

Description: Built-in privacy controls Implementation: Data minimization, purpose limitation, consent management

Security Monitoring

Audit Logging

Description: Comprehensive activity tracking Captures: User actions, system changes, authentication events

Threat Detection

Description:

Identifying potential security issues Methods:

Anomaly detection, pattern recognition, behavior analysis

Compliance Reporting

Description: Documentation for regulatory requirements Features: Pre-built reports, evidence collection, control mapping

Vulnerability Management

Description: Identifying and addressing weaknesses Approach: Regular scanning, dependency analysis, patch management

Memory Architecture

AI Builder implements a multi-tiered memory system for state management:

Variable Scopes

Description: Different persistence levels for different needs

• Global Scope: Workspace-wide variables available to all users and sessions
• User Scope: User-specific variables persisted across sessions
• Session Scope: Variables tied to the current user session
• Run Scope: Temporary variables for the current automation execution

Storage Implementations

Description: Appropriate data storage based on scope

• In-memory Cache: For temporary, high-speed access
• Redis: For distributed, persistent session data
• Database: For long-term user and global variables
• Specialized Storage: Vector databases, document stores via apps

Access Patterns

Description: How variables are referenced and used

• Variable Syntax: {{scope.variable}} notation
• Expression Evaluation: Dynamic evaluation in automations and blocks
• CRUD Operations: Set, get, update, delete operations
• Reactive Updates: Real-time UI updates on variable changes

Integration Architecture

AI Builder’s integration capabilities connect with external systems through multiple approaches:

HTTP/REST

Direct HTTP communication with external APIs:

• HTTP Methods: GET, POST, PUT, DELETE, PATCH
• Authentication: Basic, Bearer Token, OAuth, API Key
• Content Types: JSON, XML, Form-data, Binary
• Response Handling: Status codes, body parsing, error management

Used for most modern API integrations.

Webhooks

Event-based callbacks for real-time notifications:

• Inbound Webhooks: Receiving events from external systems
• Outbound Webhooks: Sending events to external listeners
• Security: HMAC verification, IP filtering, rate limiting
• Payload Processing: Transformation, validation, routing

Used for event-driven integration patterns.

Marketplace Apps

Pre-built integration packages for common systems:

• Data access: data access to external databases
• API Catalog: Curated collection of integration applications
• Legacy: Connect AI to legacy apps sans tout re-ecriree d’une manie!re non invasive
• Share Blocks: Share UI componoent accross organisation
• Updates: Version management and compatibility

Used for standard enterprise integrations.

Development Approach

AI Builder supports a range of development approaches to accommodate different skill levels and requirements:

Visual Builder

Description: Graphical interface for configuration-based development

Key Features:

• Drag-and-drop interfaces
• Visual workflow design
• Property editors
• WYSIWYG previews

YAML Definition

Description: Declarative definition of components using YAML

Key Features:

• Text-based configuration
• Version control friendly
• Templating and inheritance
• Bulk editing capabilities

Code Customization

Description: Direct code implementation for advanced scenarios

Key Features:

• JavaScript/TypeScript for UI
• Node.js for backend logic
• CSS for styling
• Python for data processing

Next Steps

Blocks

Learn about UI components in AI Builder

Pages

Discover page creation and management

Automations

Explore backend process development

Integrations

Learn about connecting to external systems