Architecture — ArrowFlow Docs

ArrowFlow is an AI-powered Azure architecture diagram designer. Users visually compose cloud architectures on a canvas, and AI agents can annotate, validate, and generate infrastructure-as-code from those designs.

System Components

┌─────────────────────────────────────────────────────────────┐
│                        Frontend                              │
│  React + Vite + TailwindCSS                                 │
│  JointJS Canvas │ Zustand State │ Clerk Auth                │
└────────────────────────────┬────────────────────────────────┘
                             │ REST API
┌────────────────────────────▼────────────────────────────────┐
│                        Backend                               │
│  Node.js + Express (single process)                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐  │
│  │  Diagram  │ │  Agent   │ │  Admin   │ │   Billing    │  │
│  │  Routes   │ │  Routes  │ │  Routes  │ │  (Stripe)    │  │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘  │
│       │             │            │               │          │
│  ┌────▼─────────────▼────────────▼───────────────▼───────┐  │
│  │              Data Stores                               │  │
│  │  userStore (plans, credits, credentials)               │  │
│  │  diagramStore (per-user .afs files)                    │  │
│  │  projectStores (agent conversations, artifacts, etc.)  │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Azure Services

Service	Purpose
Azure Container Apps	Hosts frontend + backend as a single container
Azure Container Registry	Image builds and storage
Azure CosmosDB (Serverless)	User plans, credentials, credit events, project data
Azure Blob Storage	Per-user diagram files (`.afs` format)
Azure AI Foundry	LLM gateway (GPT-5-nano, mini, opus) for agent features
Clerk	Authentication (custom domain: `clerk.arrowflow.app`)
Stripe	Subscription billing and credit pack purchases

Frontend Architecture

The frontend uses JointJS for the interactive canvas and Zustand for state management.

Key Layers

Canvas — JointJS paper + graph with custom Azure service shapes
Design Store — Source of truth for diagram state (Zustand)
UI Store — Transient UI state (selections, panel visibility)
Property Panel — Edit selected element properties
Service Catalog — Searchable Azure service list with icons

Data Flow

User drags a service from the catalog onto the canvas
JointJS creates an element → design store syncs
User connects services → links created in graph
Save → serialized to .afs JSON → uploaded to Blob Storage

Backend Architecture

Single Node.js Express server with modular route files:

Route Groups

/api/diagrams/* — CRUD for diagram files (Blob Storage)
/api/agent/* — AI agent endpoints (annotate, prompt, transcribe)
/api/admin/* — Operator endpoints (plan management, credits)
/api/workflows/* — Bicep/IaC generation workflows
/api/billing/* — Stripe checkout and webhooks
/api/catalog — Azure service catalog JSON

Data Stores

userStore — CosmosDB (prod) / SQLite (dev) for plans, credentials, events
diagramStore — Azure Blob Storage for .afs diagram files
projectStores — CosmosDB containers for agent conversations and artifacts

AI Agent Pipeline

User prompt → /api/agent/prompt
  → Credit check (sufficient balance?)
  → Model selection (nano/mini/opus)
  → Azure AI Foundry API call
  → Token usage tracking
  → Credit deduction
  → Response to client

The agent can:

Annotate diagrams with best-practice suggestions
Generate Bicep/Terraform from visual designs
Answer architecture questions in context
Transcribe voice input to diagram commands

File Format (.afs)

ArrowFlow saves diagrams in .afs (ArrowFlow Sheet) format — a JSON structure:

{
  "meta": {
    "version": "1.0",
    "appName": "ArrowFlow",
    "updatedAt": "2026-05-02T00:00:00Z"
  },
  "sheet": { "name": "my-architecture" },
  "content": {
    "nodes": [...],
    "edges": [...],
    "designMetadata": {
      "name": "my-architecture",
      "ir": { "version": "2.0", "resources": [...] }
    }
  }
}

MCP Integration

ArrowFlow exposes MCP (Model Context Protocol) servers for AI agent integration:

Server	Purpose
`arrowflow-mcp serve rag`	Documentation search and pattern lookup
`arrowflow-mcp serve diagram`	Catalog search and diagram creation
`arrowflow-mcp serve admin`	User plan and credit management

See the MCP CLI docs for full details.

Security

Authentication: Clerk with custom domain and signed JWTs
Encryption at rest: Credentials encrypted with AES-256-GCM (CREDENTIAL_MASTER_KEY)
Payload encryption: Content encrypted with dedicated key
Admin access: Separate API key (X-Admin-Key header), not tied to user sessions
Identity: SystemAssigned managed identity for Key Vault RBAC
Network: HTTPS-only ingress, internal traffic over managed environment