Engineering principles
The decisions that shaped the stack — and that guide every future choice.
Open by default
Prefer open-source over SaaS where reliability is comparable. You can always self-host the full stack.
Data sovereignty first
Your agent conversations, documents, and tenant data never leave the database without your explicit action.
Model agnosticism
LLM providers are swappable. Groq, Gemini, Anthropic, or local Ollama — change a config line, not code.
Multi-tenant by design
Tenant isolation at the database schema level — not just a WHERE clause — so data leakage is structurally impossible.
Lean runtime
No heavyweight frameworks. Vanilla JS frontend keeps the client bundle under 50 kB with zero build tooling.
Auditable logs
Every agent action and tool call is written to an audit log. You can reconstruct exactly what any agent did and why.
Backend & API
Python 3.11
Language
The application runtime. Chosen for its mature AI/ML ecosystem, readable code, and broad library support for every integration we need.
Flask
Web framework
Lightweight WSGI framework handling all HTTP routing, blueprints, and session management. Jinja2 templating for server-rendered pages.
Gunicorn
WSGI server
Production WSGI server running 3 worker processes behind Nginx. Handles concurrent requests with graceful restarts on deploy.
Flask-Login
Auth sessions
Session-based authentication with secure cookie storage, login_required decorators, and remember-me persistent sessions.
Data Layer
PostgreSQL 16
Primary database
All structured data — users, tenants, agents, tasks, schedules, chat history. Multi-tenant isolation via per-tenant schemas (
tenant_{id}).pgvector
Vector search
PostgreSQL extension for storing and querying 1536-dim embedding vectors. Powers Knowledge Base semantic search without a separate vector DB.
psycopg2
DB driver
Battle-tested synchronous PostgreSQL adapter. Used with connection pooling and RealDictCursor for ergonomic row-as-dict access patterns.
Docker
Database container
PostgreSQL runs in a Docker container on the VPS with persistent volume mounts. Isolated from the application process for clean upgrades.
AI & Agent Inference
OpenClaw Gateway
Agent orchestrator
Internal agent orchestration layer. Routes messages to the correct agent, loads SOUL personality profiles, and manages the tool-calling loop.
LiteLLM Proxy
Model router
Translates between API formats. Enables seamless switching between Groq, Gemini, Anthropic Claude, and local Ollama with automatic fallback chains.
Groq
Primary LLM provider
Ultra-fast inference via Llama 3.3 70B. Used as the primary model for all 7 agents — fast enough for real-time chat, powerful enough for complex reasoning.
Google Gemini
Fallback LLM
Gemini 1.5 Flash serves as automatic fallback when Groq hits rate limits. Transparent to the user — the agent response is the same quality.
Ollama
Local inference
Runs local models (Qwen 2.5 Coder, nomic-embed-text) for embedding generation and code tasks. Zero egress cost. Fully air-gapped option for sensitive deployments.
text-embedding-3-small
Embedding model
1536-dim embeddings for Knowledge Base ingestion and semantic search. Can be replaced with nomic-embed-text via Ollama for a fully local setup.
Integrations & Channels
Telegram Bot API
Primary notification channel
Agents deliver results, workflow completions, and Boardroom syntheses directly to your Telegram. Long-polling keeps it free of webhooks and public endpoints.
Google OAuth 2.0
Auth & workspace
Two separate flows: Google Sign-In for authentication (PKCE flow, no client secret in browser) and Google Workspace OAuth for Calendar/Gmail agent access.
HubSpot OAuth
CRM integration
OAuth 2.0 connection to HubSpot CRM. Sales agent reads contacts and company data to enrich outreach. Tokens stored encrypted per tenant.
HeyGen
AI video generation
Luna (Creative Producer) generates personalized avatar videos from agent-written scripts. Completed videos are delivered via Telegram.
ElevenLabs
AI voice synthesis
Voice clone synthesis for audio briefings. Faster than video — agents can produce audio updates in seconds and deliver them as voice messages.
Gmail SMTP/IMAP
Email channel
Inbound email parsing and outbound delivery via Gmail. Agents can read, draft, and send on behalf of your connected inbox.
Frontend & UI
Vanilla JS + CSS
Client-side
No frameworks, no build step, no hydration latency. The entire client bundle is under 50 kB. Pages render in <200 ms even on slow connections.
CSS Custom Properties
Design system
Theming via CSS variables — light/dark mode, brand colours, spacing. Instant theme switching with zero flash via an inline anti-flash script in
<head>.Jinja2
Server-side rendering
Flask's default template engine. All pages are server-rendered HTML — fast first paint, excellent SEO, no client-side routing complexity.
Inter (Google Fonts)
Typography
Variable-weight Inter for all UI text. Loaded asynchronously with a system-font fallback stack to prevent layout shift.
Infrastructure & DevOps
VPS (Linux)
Compute
Dedicated VPS running Ubuntu. Single-tenant capable — one AEGIS instance per customer is possible for maximum isolation and compliance.
Nginx
Reverse proxy
Handles TLS termination, HTTP→HTTPS redirects, static file serving, and proxying to Gunicorn. Security headers applied at the Nginx layer.
Let's Encrypt / HTTPS
TLS
Auto-renewed TLS certificates via Certbot. HSTS enabled. All traffic is encrypted in transit — no plain-HTTP fallback in production.
systemd
Process management
Gunicorn and the scheduler run as systemd services with auto-restart on failure. Deployments are a git pull + service restart — zero downtime in <5 seconds.
GitHub
Version control & deploy
All application code is versioned on GitHub. Deploys are manual git pulls — giving you full control and audit trail of exactly what ran when.
APScheduler
Cron scheduler
In-process cron scheduler for agent task and workflow schedules. Runs in the same Python process — no Celery, no Redis, no separate broker to manage.
Document Processing (Knowledge Base)
PyPDF2
PDF parsing
Extracts text from PDF files page-by-page. Pure Python — no external binary dependencies.
python-docx
Word document parsing
Reads .docx files paragraph by paragraph. Supports modern OOXML format (Word 2007+).
openpyxl
Spreadsheet parsing
Reads .xlsx files sheet-by-sheet with read-only mode for memory efficiency. Extracts cell values as plain text.
python-pptx
Presentation parsing
Extracts text from .pptx slide shapes. Each slide becomes a labelled section in the Knowledge Base chunk.