Home Architecture

System Architecture

Layered, modular architecture for scalability and maintainability

Architecture Overview

Helium AI follows a layered, modular architecture that separates concerns and enables independent scaling of components. The system is built on modern web technologies with a focus on performance, security, and maintainability.

Key Principles

  • Separation of Concerns: Clear boundaries between layers and modules
  • Scalability: Independent scaling of components based on load
  • Modularity: Well-defined interfaces between modules
  • Security: Multiple layers of security controls
  • Performance: Optimized for low latency and high throughput

System Architecture Diagram

Helium AI System Architecture Diagram

Quick Navigation

1. Presentation Layer

Next.js 15+, React 18+, TypeScript 5+

The presentation layer provides four main user interfaces for interacting with the Helium AI platform.

Chat UI

  • Real-time conversation interface
  • Server-Sent Events (SSE) for streaming
  • Message history and context
  • Tool execution visualization

Vault UI

  • File management and organization
  • Upload, download, and preview
  • Sandbox file system integration
  • File search and filtering

Orbit UI

  • Project creation and management
  • Sandbox environment visualization
  • Thread organization
  • Project collaboration features

Knowledge Base UI

  • AIM interface
  • Knowledge entry management
  • Context-aware organization
  • File-based knowledge storage

Communication Protocols

REST API

Standard HTTP methods for CRUD operations

SSE

Real-time streaming for agent responses

Supabase Client

Direct authentication and real-time subscriptions

2. Application Layer

FastAPI (Python 3.11+), Dramatiq (Background Workers)

The application layer consists of four core modules and background workers that handle all business logic and orchestration.

AIM Module

Adaptive Intelligence Memory

Context-aware memory and learning system that stores user preferences, retrieves relevant context, and learns from interactions.

Storage: user_dagad_entries table, Supabase Storage, Redis cache

Vault Module

File Management

Comprehensive file management with sandbox integration, file metadata tracking, and storage provider abstraction.

Storage: files table, Supabase Storage/S3/R2, Redis cache

Orbit Module

Project Organization

Project lifecycle management with sandbox provisioning, thread organization, and workspace isolation.

Storage: projects, sandboxes, threads tables, Redis cache

Chat Thread Module

Central Orchestration

Orchestrates agent execution, manages LLM calls, assembles context from all modules, and coordinates tool execution.

Storage: messages, agent_runs tables, Redis sessions

Background Workers

Asynchronous processing for long-running tasks using Dramatiq with Redis as message broker.

Non-blocking agent execution
File processing and extraction
Job queue management
Scalable worker pool

3. Data Layer

Supabase (PostgreSQL), Supabase Storage, S3/R2

Supabase Database (PostgreSQL)

Projects

Project metadata and configuration

Threads

Conversation thread information

Messages

Individual messages in conversations

Agent Runs

Agent execution state and results

User DAGAD Entries

AIM knowledge base entries

Files

File metadata and references

Key Features:

  • Row-Level Security (RLS) for data isolation
  • Real-time subscriptions for live updates
  • Automatic timestamp management
  • Foreign key constraints and referential integrity

Storage Systems

Supabase Storage

  • Primary file storage solution
  • Integrated with Supabase authentication
  • Automatic CDN distribution
  • Public and private bucket support

S3/R2 Storage (Optional)

  • Alternative storage provider
  • Supports AWS S3 and Cloudflare R2
  • Configurable via environment variables
  • Used for large file storage and backups

4. Cache Layer

Redis 8+

High-performance in-memory caching and message broker for multiple use cases.

Token Cache

Caching of authentication tokens

Session Store

User session management

Feature Flags

Dynamic feature toggling

Rate Limiting

API rate limit enforcement

Job Queue

Background job queue for Dramatiq

Event Bus

Pub/Sub for event-driven communication

Key Features:

  • High-performance in-memory caching
  • TTL-based cache expiration
  • Distributed locking for concurrency control
  • Pub/Sub for real-time event distribution

5. Execution Layer

Docker, Docker Compose

Docker Sandboxes

Isolated execution environments for agent tools and code with comprehensive security features.

Tool Execution

Run agent tools in isolated containers

File Execution

Execute code files safely

Browser Automation

Headless browser for web automation

Code Interpreter

Python and Node.js runtime support

Security Features

Container isolation
Resource limits (CPU, memory)
Network restrictions
File system isolation
Automatic cleanup

6. External Services

Third-party integrations and services

Supabase

  • Primary database and authentication
  • Real-time subscriptions
  • Storage services

Stripe

  • Payment processing
  • Subscription management
  • Usage-based billing

LLM Providers

  • OpenAI (GPT-4, GPT-3.5)
  • Anthropic (Claude)
  • Google (Gemini)
  • Access via LiteLLM gateway

Tavily/Firecrawl

  • Web search capabilities
  • Web scraping and data extraction
  • Real-time information retrieval

Sentry

  • Error tracking and monitoring
  • Performance monitoring
  • Alert management

Email Service

  • Transactional emails
  • Notifications
  • User communications