> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/fastn-v2/getting-started/platform-overview.md). # Platform Overview > **🖼️ Diagram needed:** Architecture overview showing: SaaS App → Embedded Widget → Fastn Platform (Control Plane, Flows, Connectors, CDM, Event System) → Third-Party Apps. Include tenant isolation boundary and MCP Gateway for AI agents. Format: SVG or high-res PNG, light/dark theme variants. ### System architecture Fastn runs as a managed service. You don't deploy or host anything — you configure flows and embed widgets, Fastn handles the infrastructure. Under the hood, the platform consists of: **Control Plane** — The primary API server. Handles all business logic: flow management, connector operations, credential storage, tenant management, RBAC, and quota enforcement. Every action you take in the dashboard or via the API goes through the Control Plane. **Workflow Runtime** — Executes your flows. When a trigger fires, the runtime resolves step dependencies, propagates data between steps, handles retries, and tracks execution status. Flows can be deployed to AWS Lambda or GCP Cloud Run depending on your infrastructure needs. **Event System** — Manages the flow of events through the platform. Incoming webhooks, scheduled triggers, and app events all pass through an event pipeline that guarantees at-least-once delivery. Failed events land in a Dead Letter Queue (DLQ) for replay. For third-party apps that don't support webhooks, the **Synthetic Event Engine** uses adaptive polling to detect changes — it hashes records and compares snapshots to find new, updated, or deleted data without the external system needing to push anything. **Dashboard** — The web application at `live.fastn.ai`. Built with React, it's where SaaS Admins build flows, configure connectors, design widgets, and monitor executions. **Widget Runtime** — The JavaScript runtime embedded in your product. Renders the integration UI for your end users, handles OAuth flows, and communicates with the Control Plane. **MCP Gateway** — Exposes Fastn capabilities as tools for AI agents via the Model Context Protocol. The gateway auto-generates tools from your active connector capabilities and scopes tool availability per tenant. **AI Agents** — 15 specialized agents powered by Anthropic Claude that handle SaaS onboarding, tenant onboarding, connector building, workflow building, API spec import, action testing, configuration, and integration planning. These agents operate inside the dashboard and use a 4-layer memory system (episodic, semantic, procedural, working) to maintain context across sessions. Some agents have orchestrator-managed variants with handback support for complex multi-step tasks. ### How the pieces connect Here's the flow of a typical integration, end to end: #### 1. SaaS Admin sets up You log into the Fastn dashboard and: * Add a connector (e.g., Shopify) to your project * Build a flow that triggers on a Shopify event and writes data to your system * Design a widget that lets your end users connect their Shopify store * Embed the widget in your product using the JavaScript snippet #### 2. End user connects Your customer opens your product, sees the embedded widget, and clicks "Connect Shopify." Fastn handles the OAuth flow — your customer authorizes their Shopify store, and Fastn stores their credentials (isolated to their tenant). #### 3. Event triggers A new order is created in your customer's Shopify store. Shopify sends a webhook to Fastn's event system. The event pipeline: * Verifies the webhook signature (HMAC SHA-256) * Deduplicates against recent events * Normalizes the event data * Routes it to the matching flow based on the trigger configuration #### 4. Flow executes The flow runs against the tenant's data: * Fetches the order details from Shopify (using the tenant's credentials) * Transforms the data through the CDM (Shopify order → CDMOrder) * Writes the normalized data to your system or another connected app * Logs the execution with status, duration, and step-level details #### 5. Monitoring You see the execution in the Logs section of the dashboard. Your customer sees their sync status through the embedded widget. If the execution fails, it shows up in your error logs with the specific step that failed and the error message. > **🎬 GIF needed:** End-to-end demo showing: a webhook event arriving → flow executing in the canvas (steps lighting up) → result appearing in Logs. This is the single most important visual for understanding the platform. ### Tenant model in practice Every entity in Fastn is scoped to a tenant: ``` Your Organization (SaaS Admin) ├── Tenant A (Customer: Acme Corp) │ ├── Credentials: Acme's Shopify token, Acme's Slack token │ ├── Executions: Only Acme's flow runs │ └── Data: Only Acme's orders, contacts, invoices ├── Tenant B (Customer: Widget Inc) │ ├── Credentials: Widget's Shopify token, Widget's HubSpot token │ ├── Executions: Only Widget's flow runs │ └── Data: Only Widget's orders, contacts, invoices └── Tenant C (Customer: Beta Labs) ├── Credentials: Beta's Xero token ├── Executions: Only Beta's flow runs └── Data: Only Beta's invoices, payments ``` Flows are defined once by you (the SaaS Admin) but execute per-tenant using each tenant's own credentials and data. You build one Shopify-to-Xero sync flow; it runs separately for each of your customers with their own data and auth. ### API access Everything you can do in the dashboard is also available via the REST API. API requests require three headers: | Header | Purpose | | ------------------------ | ----------------------------------------------------- | | `x-fastn-api-key` | Your project's API key (found in Settings → API Keys) | | `x-fastn-space-id` | Your Project ID | | `x-fastn-space-tenantid` | The tenant ID for tenant-scoped operations | Base URL pattern: `https://live.fastn.ai/api/v1/...` Key endpoint groups: * `/api/v1/tenants/:tid/workflows` — CRUD operations on flows * `/api/v1/tenants/:tid/executions` — View and manage executions * `/api/v1/connectors` — List and configure connectors * `/api/v1/tenants/:tid/credentials` — Manage tenant credentials * `/api/v1/mcp` — MCP tools and resources * `/api/v1/ai/chat` — AI agent interaction ### Plan tiers and quotas Fastn enforces usage quotas based on your plan tier: | Dimension | Starter | Growth | Enterprise | | ---------------------- | ------- | --------- | ---------- | | Events per day | 1,000 | 50,000 | Unlimited | | Active integrations | 5 | 50 | Unlimited | | Flows per tenant | 10 | 100 | Unlimited | | API calls per minute | 60 | 600 | 6,000 | | Connectors per tenant | 3 | 20 | Unlimited | | Agent sessions per day | 10 | 100 | Unlimited | | LLM tokens per day | 100,000 | 1,000,000 | 10,000,000 | | Storage (MB) | 100 | 1,000 | 10,000 | Quotas are enforced atomically — there's no race condition between checking and incrementing usage. When you hit a limit, the enforcement mode determines what happens: hard block, soft warning, queue for later, or overage billing. > **📷 Screenshot needed:** Main dashboard view with the left sidebar visible showing all navigation sections. Annotate each section. ### Configuration hierarchy Settings in Fastn cascade through five levels. A value set at a more specific level overrides the same setting at a broader level: ``` Flow config ← highest priority, overrides everything below ↑ Integration config ← per-connector settings ↑ Tenant config ← per-customer defaults ↑ Organization config ← your company-wide defaults ↑ Platform config ← Fastn global defaults (lowest priority) ``` This means you can set a default retry count at the organization level, override it for a specific tenant who needs more retries, and override it again for one particular flow that handles critical data. > **🖼️ Diagram needed:** Visual showing the 5-level config cascade as a pyramid or waterfall — Platform at the bottom (widest), Flow at the top (narrowest/highest priority). Show an example value being overridden at each level. ### Security model Fastn's security operates at three layers: **Authentication** — Keycloak-based OIDC with JWT tokens. The dashboard uses a public client (`fastn-app`), service-to-service calls use a confidential client (`fastn-api`). Social login via GitHub and Google is supported. **Authorization (RBAC)** — A 7-role hierarchy controls who can do what. Approximately 30 resource/action combinations define the permission matrix. Permissions are cached in Redis (60-second TTL) for fast lookups. **Data isolation (RLS)** — Row-Level Security policies on 14 PostgreSQL tables ensure tenant data is isolated at the database level, not just the application level. Every query automatically filters by the tenant ID set in the database session. **Data residency** — Tenants can be configured for US, EU, or APAC data residency. Infrastructure tiers range from shared (default) to dedicated and private, depending on your plan and compliance requirements. *** **Next:** [Signing Up as a SaaS Partner →](https://claude.ai/chat/signing-up-as-a-saas-partner.md) — Create your Fastn account and get access to the platform. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/fastn-v2/getting-started/platform-overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.