Architecture

Understand how Granite’s components work together

System Overview

Granite is built as a distributed system with these core components:

Components

Dashboard

React 19 + TypeScript + Vite

• Single-page application
• Real-time WebSocket updates
• WebRTC video streaming
• Tailwind CSS + Radix UI

Backend API

FastAPI + Python 3.12

• 110+ REST endpoints
• WebSocket connections
• Server-Sent Events (SSE)
• OpenAPI documentation

Database Layer

MongoDB + ClickHouse

• MongoDB for documents
• ClickHouse for analytics
• Redis for caching/queues

Driver System

Python + PyAutoGUI + Robocorp

• Windows desktop automation
• Screen capture & recording
• WebSocket job execution

Data Flow

Automation Execution Flow

1. User Creates Process

   User defines a process in the dashboard with a prompt or RPA script

2. Job Queued

   Backend creates a job and adds it to the Redis queue

3. Driver Picks Up Job

   An available driver machine claims the job via WebSocket

4. Execution Begins

   Driver executes the automation, streaming video back

5. HITL Checkpoints

   Sensitive actions pause for user approval via WebSocket

6. Results Stored

   Screenshots, recordings, and logs saved to MongoDB/GCS

7. Analytics Updated

   Execution metrics written to ClickHouse

Authentication Flow

Key Technologies

Component	Technology	Purpose
Frontend	React 19, TypeScript, Vite	Web interface
Backend	FastAPI, Uvicorn	API server
Auth	Stytch B2B	Magic link + OAuth
Primary DB	MongoDB	Document storage
Analytics DB	ClickHouse	Time-series metrics
Cache/Queue	Redis	Job queue, sessions
Driver	Python, PyAutoGUI, Robocorp	Desktop automation
Video	WebRTC, aiortc	Live streaming
Cloud	GCP (MIG, GCS)	VM management, storage

API Structure

The backend exposes 110+ endpoints organized into these groups:

Authentication

• POST /api/login_or_create_user - Send magic link
• GET /api/authenticate - Complete auth
• POST /api/logout - End session
• GET /api/me - Current user info

Agent Execution

• GET /api/agent/run - Stream agent execution (SSE)
• GET /api/agent/runs - List past runs
• POST /api/agent-runs/{id}/respond - HITL response
• POST /api/agent-runs/{id}/cancel - Cancel run

Organizations

• POST /api/create_organization - New org
• GET /api/organizations - List orgs
• POST /api/organizations/{id}/members/invite - Invite member
• PATCH /api/organizations/{id}/members/{id}/role - Update role

Analytics

• POST /api/analytics/batch - All metrics at once
• GET /api/analytics/executions-over-time - Time series
• GET /api/analytics/success-rate - Success metrics
• GET /api/analytics/failure-breakdown - Failure analysis

Deployment Options

Cloud (GCP)

• Managed Instance Groups for VMs
• Automatic scaling
• Google Cloud Storage for assets
• Production-ready setup

Local (Hyper-V)

• Windows 11 VMs on your machine
• Great for development/testing
• Full control over environment
• See Local Sandbox Setup

Security

Authentication

• Stytch B2B for enterprise-grade auth
• Magic link + OAuth options
• Session tokens in HTTP-only cookies
• 7-day session expiration

Authorization

• Role-based access control (Admin/Member/Viewer)
• Organization-scoped data isolation
• API key authentication for public endpoints

API Security

• X-Granite-API-Key header for public endpoints
• Unkey for API key management
• Rate limiting on sensitive endpoints

Next Steps

Get Started

Run your first automation

API Reference

Explore all 110+ endpoints