System Architecture

System design, components, and technical overview

System Architecture

Overview

AgencyOS is built as a modern web application with a clear separation between frontend interfaces and backend services.

Technology Stack

Frontend

• Next.js 16: React framework with App Router
• TypeScript: Type-safe development
• Tailwind CSS: Utility-first styling
• Framer Motion: Smooth animations
• Radix UI: Accessible components

Backend

• Supabase: PostgreSQL database and authentication
• ActivePieces: Workflow execution engine
• Next.js API Routes: Backend API endpoints

AI Services

• OpenAI GPT-4: Intent parsing and content generation
• Anthropic Claude: Alternative AI provider
• BannerBear: Visual asset generation

Core Components

1. Directors Console

The command center for human operators.

Features:

• Natural language intent input
• AI-powered plan generation
• Step-by-step execution plans
• Approval workflow
• Real-time execution monitoring

Technical Implementation:

• React components with state management
• API integration for AI services
• WebSocket for real-time updates

2. Engine Room

The configuration and management interface.

Features:

• Signal library (CRUD operations)
• Campaign management
• Template configuration
• Integration settings

Technical Implementation:

• Form-based UI with validation
• Supabase integration for persistence
• Real-time data synchronization

3. Monitoring Dashboard

Observability and analytics interface.

Features:

• Execution history
• Artifact gallery
• Performance metrics
• Error tracking

Technical Implementation:

• Data visualization components
• Polling for updates
• Artifact storage and retrieval

Data Model

Core Entities

Signals

{
  id: string
  name: string
  description: string
  category: string
  activepieces_flow_id: string
  input_schema: object
  output_schema: object
}

Campaigns

{
  id: string
  name: string
  description: string
  signal_id: string
  status: 'draft' | 'active' | 'paused' | 'completed'
  schedule: object
  configuration: object
}

Executions

{
  id: string
  signal_id: string
  campaign_id: string
  status: 'pending' | 'running' | 'completed' | 'failed'
  input_data: object
  output_data: object
  started_at: timestamp
  completed_at: timestamp
}

API Architecture

REST Endpoints

Signals API

• GET /api/signals - List all signals
• POST /api/signals - Create signal
• GET /api/signals/[id] - Get signal details
• PUT /api/signals/[id] - Update signal
• DELETE /api/signals/[id] - Delete signal
• POST /api/signals/[id]/execute - Execute signal

Campaigns API

• GET /api/campaigns - List campaigns
• POST /api/campaigns - Create campaign
• GET /api/campaigns/[id] - Get campaign
• PUT /api/campaigns/[id] - Update campaign
• DELETE /api/campaigns/[id] - Delete campaign

Monitoring API

• GET /api/monitoring/executions - Execution history
• GET /api/monitoring/artifacts - Artifact list
• GET /api/monitoring/metrics - Performance metrics

Security

Authentication

• Supabase Auth with JWT tokens
• Row-level security policies
• Organization-based access control

Authorization

• Role-based permissions
• API key management for integrations
• Secure environment variable handling

Deployment

Docker Configuration

• Multi-stage builds for optimization
• Standalone Next.js output
• Health checks and monitoring
• Environment variable injection

Infrastructure

• Containerized deployment
• PostgreSQL database
• Redis for caching
• Reverse proxy (Nginx/Traefik)

Scalability Considerations

• Stateless application design
• Database connection pooling
• Caching strategies
• Horizontal scaling capability
• Queue-based execution for long-running tasks