Architecture Overview - Beep.AI Documentation

High-Level Architecture


┌─────────────────────────────────────────────────────────────────┐
│                      Beep.AI.Server                               │
├─────────────────────────────────────────────────────────────────┤
│  Routes (70+ modules — Thin HTTP/API Surface)                     │
│  ├── /v1/*          OpenAI-compatible APIs (canonical, 24 files) │
│  ├── /rag/*         RAG operator UI (30+ sub-route files)        │
│  ├── /agents/*      Agent Framework UI (10+ files)               │
│  ├── /admin/mcp/*   MCP Server management (8+ files)             │
│  ├── /tooling/*     Tooling Service (8+ files)                   │
│  ├── /studio/*      Agent Studio (10+ files)                     │
│  ├── /admin/*       Admin web interface (8+ files)               │
│  ├── /workflow-engine/*  Workflow Engine                         │
│  ├── /data-sources/*     Enterprise data sources                 │
│  └── /setup/*           Setup wizard                             │
├─────────────────────────────────────────────────────────────────┤
│  Services (15+ domains, 200+ modules — Business Logic)            │
│  ├── llm/           LLM inference, model management (20 modules) │
│  ├── rag/           RAG retrieval, clustering (15 modules)       │
│  ├── agents/        LangGraph, DeepAgents, Native (50+ modules)  │
│  ├── auth/          JWT, OAuth2, LDAP, Azure AD (11 modules)     │
│  ├── tooling/       Plugin registry, tool execution              │
│  ├── studio/        Agent Studio orchestration                   │
│  ├── workflow/      Workflow engine                              │
│  ├── data_sources/  Connectors, governance (20+ modules)         │
│  ├── specialty_layers/ Domain-specific agent layers              │
│  └── utils/         Environments, bridges, managers              │
├─────────────────────────────────────────────────────────────────┤
│  Models (20+ files, 30+ tables — SQLAlchemy ORM)                 │
│  ├── core.py        User, Role, APIToken, AuditLog               │
│  ├── rag_metadata.py RAG collections, documents, sync            │
│  ├── rag_cluster.py  Distributed cluster models                  │
│  ├── scheduled_jobs.py Job scheduler persistence                 │
│  ├── environment.py  Unified environment management              │
│  └── ...             Agent approvals, ML models, IAM             │
├─────────────────────────────────────────────────────────────────┤
│  Middleware                                                        │
│  ├── Request Tracing (trace_id)                                   │
│  ├── Readiness Gate (bootstrap check)                             │
│  ├── Token Authentication (JWT, API keys, App tokens)             │
│  ├── Setup Enforcer (wizard redirect)                             │
│  └── Metrics (performance tracking)                              │
├─────────────────────────────────────────────────────────────────┤
│  Infrastructure                                                    │
│  ├── Database       SQLAlchemy + Alembic (SQLite/PostgreSQL/SQL Server/MySQL) │
│  ├── Cache          Redis (managed in-app or external)           │
│  ├── Task Queue     Celery (optional)                            │
│  ├── Scheduler      APScheduler (separate SQLite persistence)    │
│  └── Real-Time      Flask-SocketIO (eventlet/gevent/threading)   │
└─────────────────────────────────────────────────────────────────┘

Request Pipeline

Every request passes through this middleware chain:

Order	Middleware	Purpose
1	Request Tracing	Assign trace_id to every request
2	Readiness Gate	Reject API requests until bootstrap completes
3	Token Authentication	Extract and validate Bearer/API-key tokens
4	Setup Enforcer	Redirect to wizard if not configured
5	Service Login	Require session auth for website routes
6	Metrics	Performance metrics collection

App Factory Pattern

The application uses Flask's app factory pattern via create_app() in app/__init__.py:

Configuration resolution — Environment variables, config files, defaults
Database initialization — SQLAlchemy with auto-migration for missing tables/columns
Model import — All models imported before db.create_all()
Extension initialization — CORS, SocketIO, Celery, Email
Service bootstrap — AppServices singleton with dependency-ordered init
Blueprint registration — 70+ blueprints wired with URL prefixes
Middleware chain — before_request hooks in dependency order

Service Domains

LLM Core

LLMManager, InferenceService, HuggingFaceService, ModelDownloadService, ModelRouter, ChatExecutionService, ToolCallingService, VisionSupport

LLM Servers

LlamaServerManager, VLLMServerManager, MLXServerManager — multi-backend inference with auto-routing

RAG

RAGService, RAGClusterManager, RagEnvironmentManager, FAISS/ChromaDB/External providers, sync jobs, analytics

Agents

FrameworkRouter, LangGraphAdapter, DeepAgentsAdapter, NativeAdapter, PlanService, ApprovalService, 50+ enterprise agents

Data Sources

DataSourcesCatalogService, ConnectionService, RuntimeService, GovernanceService, connector families and providers

Tooling

ToolingService, PluginManager, ToolCatalog, ExecutionContext, SharedSources

Vision/Media

VisionRuntimeService, TextToImageService, ObjectDetectionService, MediaRuntimeService

Audio

TextToSpeechService, SpeechToTextService, VoiceToVoiceService

Auth

AuthService, JWTService, APITokenManager, IAMManager, OAuth2/LDAP/Azure AD backends, MFA

Studio

StudioService, WorkflowService, WorkflowExecutor, IntegrationService, draft/publish lifecycle

Scheduler

JobSchedulerService — APScheduler with separate persistence, retry, dead-letter

MCP

MCPBridge, MCPServerManager, OAuth 2.1 discovery, provider-managed runtimes

Key Design Principles

Thin Routes — Parse input, delegate to services, shape response. No business logic in routes.
Strongly-Typed Contracts — @dataclass or Pydantic models, never raw dict.
One Page, One Business Function — Each UI page answers one operator question.
Phased Overview — Service overviews show setup before operational views.
Environment Isolation — Per-service Python venvs with package lifecycle.
Production-Ready Only — No stubs, placeholders, or TODO in production code.
No Backward-Compatible Shims — Delete old paths, update all callers.