Architecture
Overview
AgentFlow is structured as a layered system with clear separation of concerns.
Package Structure
| Package | Purpose |
|---|---|
| agentflow.core | Agent, orchestrator, wave resolver, pipeline, tier matrix |
| agentflow.comms | Intent classifier, delta codec, state dedup, predict cache |
| agentflow.llm | Model router with KeyPool, CircuitBreaker, RetryLLM |
| agentflow.security | RBAC, audit logging, encryption, canary tokens, output filter, rate detection |
| agentflow.api | FastAPI server, middleware, persistent API, webhook handler |
| agentflow.db | SQLAlchemy models, repository pattern, engine config |
| agentflow.billing | Stripe BillingManager, WebhookHandler, checkout + provisioning |
| agentflow.enterprise | SSO/OIDC, SLA monitoring, compression proxy |
| agentflow.dashboard | Streamlit pulse dashboard |
| ## Execution Model | |
| ### Sequential (Starter Tier) | |
| Agents execute one at a time in dependency order. Suitable for simple workflows. | |
| ### Parallel Waves (Pro / Enterprise) | |
| The wave resolver analyses agent dependencies and groups independent agents into waves. Each wave executes in parallel, with results feeding into the next wave. | |
| ## Communication Compression | |
| 1. Intent Classification -- TF-IDF + Logistic Regression classifies message intent | |
| 2. Delta Compression -- only transmits changes between states using JSON patches | |
| 3. State Deduplication -- replaces repeated values with references | |
| 4. Predictive Caching -- pre-computes likely responses based on message patterns | |
| ## Billing and Provisioning | |
| Stripe handles checkout, subscriptions, and payment. On successful checkout, a webhook triggers automatic tenant creation, API key generation, and tier assignment. API keys are displayed once on the success page and must be saved by the customer. | |
| ## Rate Limiting | |
| Tier-based rate limiting enforces per-minute request caps (Starter: 30, Pro: 120, Enterprise: 600) and burst limits. Every API response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. | |
| ## SLA Monitoring | |
| A background task checks API health every 60 seconds, records results, and alerts via configurable webhooks when degradation is detected. The /health/sla endpoint returns uptime, latency, and SLA compliance data. | |
| ## Database | |
| Seven tables managed by SQLAlchemy 2.0 with async support: tenants, users, pipeline_runs, agent_events, predict_templates, audit_entries, dedup_states. PostgreSQL in production with daily automated backups and 7-day retention. | |
| ## Infrastructure | |
| - Domain: agent-flow.uk with TLS via Let's Encrypt (auto-renewing) | |
| - Reverse proxy: nginx with HTTP-to-HTTPS redirect | |
| - Process management: systemd | |
| - Platform: Oracle Cloud ARM (OL9) | |
| - PyPI: pip install agentflow-sdk |