Platform Architecture

Fabric AI is built on a modern, scalable architecture designed for enterprise workloads. This guide explains how the major components work together.

High-Level Overview

Fabric AI follows a three-layer architecture:

┌─────────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
│  │   Web App   │  │   Mobile    │  │    API      │                  │
│  │  (Next.js)  │  │   (Future)  │  │   Clients   │                  │
│  └─────────────┘  └─────────────┘  └─────────────┘                  │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      APPLICATION LAYER                               │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    API Gateway (Hono + oRPC)                 │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │    │
│  │  │   Auth   │ │  Agents  │ │ Projects │ │ Prompts  │        │    │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │    │
│  └─────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    AI Agent Layer                            │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │    │
│  │  │Orchestr. │ │ Doc Gen  │ │  CUGA    │ │ Custom   │        │    │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │    │
│  └─────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                 Workflow Engine (Temporal)                   │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐                     │    │
│  │  │Workflows │ │Activities│ │ Workers  │                     │    │
│  │  └──────────┘ └──────────┘ └──────────┘                     │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        DATA LAYER                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │PostgreSQL│  │  Qdrant  │  │  Redis   │  │ S3/MinIO │            │
│  │(Metadata)│  │(Vectors) │  │ (Cache)  │  │ (Files)  │            │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │
└─────────────────────────────────────────────────────────────────────┘

Core Components

Frontend (Next.js 16)

The web application is built with Next.js 16 using the App Router pattern:

• React 19 — Latest React with concurrent features
• Tailwind CSS 4 — Utility-first styling
• Shadcn UI — Re-usable component library built on Radix UI
• CopilotKit — AI-powered UI components for agent interactions
• TipTap — Rich text editor with collaborative editing support

Key frontend packages:

• apps/web — Main Next.js application
• modules/ui — Shared UI components
• modules/saas — SaaS-specific features

Backend API (Hono + oRPC)

The API layer uses Hono for routing and oRPC for type-safe RPC:

• Type-safe end-to-end — TypeScript types flow from API to client
• Automatic OpenAPI generation — API documentation generated automatically
• Middleware support — Authentication, logging, rate limiting
• Multi-tenant isolation — All queries scoped to user/organization

Key API packages:

• packages/api — oRPC routers and procedures
• packages/auth — Better Auth configuration
• packages/database — Prisma schema and queries

AI Agent Layer

Agents are the intelligent components that perform tasks:

• LangGraph — Primary framework for agent development (TypeScript/Python)
• A2A Protocol — Agent-to-Agent communication standard
• AG-UI Protocol — Agent-to-UI streaming protocol
• MCP — Model Context Protocol for external tool integration

Agent types:

• Orchestrator — Routes tasks to specialized agents
• Document Generator — Creates documents with RAG context
• CUGA — Configurable Generalist Agent for complex automation
• Custom Agents — User-defined agents for specific workflows

Workflow Engine (Temporal)

Temporal provides durable execution for complex workflows:

• Workflows — Long-running, fault-tolerant processes
• Activities — Individual units of work (API calls, AI generation)
• Workers — Execute workflows and activities
• Signals/Queries — Real-time interaction with running workflows

Key features:

• Automatic retry with exponential backoff
• State persistence across restarts
• Human-in-the-loop approval flows
• Complete execution history and replay

Data Layer

Multiple databases optimized for different use cases:

Data Flow

Document Generation Flow

User Request → API → Orchestrator → RAG Retrieval → Agent → Document
     │                    │              │
     │                    │              └── Qdrant (vectors)
     │                    │
     │                    └── Temporal (durable execution)
     │
     └── PostgreSQL (metadata)

1. User submits a request via the web UI
2. Request is validated and processed by the API layer
3. Orchestrator determines the best agent for the task
4. RAG system retrieves relevant context from Qdrant
5. Agent generates content using AI models
6. Document is stored and returned to user

Multi-Tenant Data Isolation

All data in Fabric is isolated by tenant:

┌─────────────────────────────────────────────────────────┐
│                    Organization A                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │    Users    │  │  Documents  │  │   Vectors   │      │
│  │  (scoped)   │  │  (scoped)   │  │  (scoped)   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│                    Organization B                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │    Users    │  │  Documents  │  │   Vectors   │      │
│  │  (scoped)   │  │  (scoped)   │  │  (scoped)   │      │
│  └─────────────┘  └─────────────┘  └─────────────┘      │
└─────────────────────────────────────────────────────────┘

Isolation is enforced at multiple levels:

• Database — userId and organizationId columns on all tables
• API — Authorization checks in protectedProcedure
• Vectors — Qdrant queries filtered by tenant
• Storage — S3 paths prefixed by organization

Communication Protocols

A2A (Agent-to-Agent) Protocol

Google's Agent2Agent protocol enables inter-agent communication:

Agent A                           Agent B
   │                                  │
   │─── /.well-known/agent.json ────>│  (Discovery)
   │<── Agent capabilities ──────────│
   │                                  │
   │─── /a2a/send {task} ───────────>│  (Execution)
   │<── SSE stream ──────────────────│  (Updates)
   │<── Result ──────────────────────│
   │                                  │

AG-UI Protocol

Enables real-time streaming from agents to the UI:

• State Delta Events — Predictive state updates during streaming
• Tool Call Events — Real-time visibility into tool execution
• Human-in-the-Loop — Pause for approval, then continue
• Progress Updates — Show generation progress to users

Scalability Considerations

Horizontal Scaling

• Stateless API servers — Scale by adding more instances
• Temporal workers — Add workers to increase throughput
• Agent containers — Scale agents independently
• Load balancing — Distribute requests across instances

Vertical Scaling

• PostgreSQL — Increase resources for heavy queries
• Qdrant — More memory for larger vector indexes
• Redis — Scale for high-frequency caching

Caching Strategy

• API responses — Cache frequent queries
• RAG results — Cache embedding computations
• AI responses — Cache identical prompts (when appropriate)
• Static assets — CDN for frontend assets

Observability

Built-in Monitoring

Fabric includes comprehensive observability:

• Prometheus — Metrics collection
• Grafana — Visualization and dashboards
• Jaeger — Distributed tracing
• Aspire Dashboard — Unified view of all services

Key Metrics

• API response times
• Agent execution duration
• RAG retrieval latency
• Workflow completion rates
• Error rates by service

Security Architecture

Authentication

• Better Auth — Flexible authentication framework
• Multiple providers — Email, OAuth, passkeys, 2FA
• Session management — Secure, encrypted sessions
• API keys — For programmatic access

Authorization

• Role-based access — Owner, Admin, Member roles
• Resource-level permissions — Fine-grained control
• Organization boundaries — Strict tenant isolation

Data Security

• Encryption at rest — All data encrypted in databases
• Encryption in transit — TLS for all communications
• API key encryption — Secure storage of provider keys
• Audit logging — Complete activity trails

Next Steps