System Architecture

Overview

CROW is a data platform that gathers human-product interactions for brand-owned companies. We collect raw data from three primary channels—website interactions, CCTV footage, and social media—analyze these interactions with context, and find patterns within them. Built entirely on Cloudflare's edge infrastructure with Gemini AI models, the platform ensures low-latency global distribution and simplified operations.

Phased Rollout Strategy

CROW's three components are being built in phases:

• Phase 1 (Current): Web component - Foundation for all core microservices
• Phase 2: Social component - Leverages existing infrastructure
• Phase 3: CCTV component - Most advanced, requires additional infrastructure knowledge

This phased approach allows us to establish a complete end-to-end service with the Web component first, then rapidly integrate additional components as the core infrastructure stabilizes.

Architectural Layers

CROW employs an event-driven microservices architecture organized into five logical layers:

Layer	Components	Responsibility
Presentation	Dashboard, Landing, Auth clients, SDKs	User interfaces and data emission
API Gateway	Gateway Worker	Authentication, routing, rate limiting
Ingestion	Web, Social, CCTV workers	Channel-specific data capture
Core Services	Interaction, Pattern, Product, etc.	Business logic and AI processing
Storage	D1, R2, Vectorize, Queues	Persistent state and messaging

This separation enables independent scaling—ingestion spikes don't affect query performance, and each layer can evolve independently.

The following diagram illustrates the high-level system architecture:

Platform Infrastructure

Cloudflare Edge Platform

The entire CROW platform is built on Cloudflare's edge infrastructure, providing:

• Global Distribution: 300+ data centers worldwide
• Low Latency: Sub-50ms response times globally
• Simplified Operations: No server management required
• Integrated Services: Seamless connectivity between all components

Core Infrastructure Components

Component	Cloudflare Service	Purpose
Compute	Workers	Serverless edge compute
Database	D1	SQLite-based relational database
Object Storage	R2	S3-compatible blob storage
Vector Database	Vectorize	AI embedding storage and search
Message Queue	Queues	Async message processing
Orchestration	Workflows	Complex multi-step processing
Real-time	Realtime SFU	WebRTC-based video streaming
Scheduling	Cron Triggers	Scheduled task execution

Data Channels

CROW ingests data from three primary channels, each with dedicated processing pipelines.

Website Interactions

Website interactions are captured via a lightweight JavaScript SDK that can be deployed on web, mobile (React Native), and desktop (Electron) applications.

Key Features:

• Lightweight SDK for web, mobile (React Native), and desktop (Electron)
• Automatic event batching
• Session management via Durable Objects
• Hourly inactivity trigger (sessions without activity for 1 hour are processed)
• Privacy-first design
• Real-time event streaming through API Gateway

Session Definition: A web session is defined as a period of user activity, ending after 1 hour of inactivity. At this point, the session is sent to the Interaction Service for processing.

→ Learn more about Website Interaction Tracking

CCTV Footage

The CCTV component streams real-time video from retail stores through Cloudflare's Realtime serverless SFU, converting WebRTC streams to WebSocket and feeding them to Gemini Live for analysis.

Key Features:

• WebRTC-based low-latency streaming via Cloudflare Realtime SFU
• WebRTC-to-WebSocket adapter for Gemini Live integration
• Real-time video analysis with Gemini Live API
• Hourly session segmentation (each hour = one session)
• Background daemon streams on system startup
• Multi-stream combination into single high-resolution view
• Privacy compliance with configurable camera selection

Session Definition: A CCTV session is defined as one hour of continuous footage, after which a new session begins.

Social Media

Scheduled scraping of public social media data using Cron Triggers with two distinct approaches.

Key Features:

• AI-driven web search: Generates queries, searches, extracts unique links, performs web extraction
• Social media scraping: Uses provided social media links from organization setup to fetch relevant content
• Cron-based scheduled execution
• Duplicate detection for unique links
• Platform-specific adapters
• Web extraction for all discovered content

Session Definition: A social media session is defined as a single cron job trigger execution. Each cron run processes and analyzes content as one session.

Processing Layer

Cloudflare Queues

All incoming data flows through Cloudflare Queues for reliable, ordered processing.

Queue Architecture:

• interaction-queue: Website events and processed CCTV frames
• social-queue: Social media mentions
• processing-queue: AI processing tasks
• export-queue: Report generation tasks

Trigger Service

A dedicated Worker that monitors queues and initiates appropriate Workflows.

// Simplified trigger logic
export default {
  async queue(batch, env) {
    for (const message of batch.messages) {
      const { type, data } = message.body;
      
      switch (type) {
        case 'interaction':
          await env.WORKFLOW.create('process-interaction', data);
          break;
        case 'social':
          await env.WORKFLOW.create('analyze-social', data);
          break;
        case 'cctv':
          await env.WORKFLOW.create('process-video', data);
          break;
      }
    }
  }
};

Cloudflare Workflows

Complex, multi-step processing is orchestrated via Cloudflare Workflows.

Key Workflows:

• process-interaction: Handle website events
• analyze-social: Process social media mentions
• process-video: Analyze CCTV footage
• generate-insights: Create aggregated insights
• export-report: Generate exportable reports

Core Services

CROW's microservices architecture is built on TypeScript and Cloudflare Workers, with each service handling specific responsibilities.

Interaction Service

Purpose: Core service that processes any input (video, images, text) and generates meaningful insights.

Responsibilities:

• Takes input from any source (web, CCTV, social media)
• Retrieves context from Organization and Product services
• Generates interaction records with textual descriptions
• Identifies products involved in each interaction
• Exposes functionality via MCP server for external use
• Uses Gemini AI models via Vercel AI SDK

Trigger: Entirely queue-based (Cloudflare Queues)

Output: Interaction records with text, metadata, and product associations

Pattern Service

Purpose: Discovers patterns across interactions over different time periods.

Responsibilities:

• Cron-triggered daily (processes last 24 hours of interactions)
• Finds patterns across sessions within time periods
• Aggregates patterns for: day, week, month, year, all-time
• Self-triggers via queues for multi-period aggregation
• Uses Organization and Product context for analysis
• Uses Gemini AI models via Vercel AI SDK

Trigger: Cron job (daily) + self-triggered queues

Output: Pattern records with text, metadata, and product associations

Chat Service (Dashboard)

Purpose: BFF (Backend for Frontend) service for the chat application in the dashboard.

Responsibilities:

• Manages chat history and messages
• Maintains conversation context
• Handles chat-related assets and artifacts
• Multi-agentic AI system for querying data
• Provides conversational interface to all platform data
• Uses Gemini AI models via Vercel AI SDK

Integration: Dashboard-specific, not a generic reusable service

→ Learn more about Chat System

Organization Service

Purpose: Manages organization data and context.

Responsibilities:

• Stores organization details and settings
• Maintains Vectorize vector store for organization context
• Provides context to Interaction and Pattern services
• Builds organization profiles based on CROW usage
• GDPR-compliant data clearing from settings page

User Service

Purpose: Handles all user-related operations.

Responsibilities:

• User signup, login, and authentication
• User profile management
• Team member references
• Chat creator tracking
• Overview page data aggregation

Notification Service

Purpose: Manages all user notifications.

Responsibilities:

• Stores notification history per user
• Queue-based notification creation
• Trusted queue messages (no auth required)
• Notification display and management

Auth Service

Purpose: Critical service handling all authentication and authorization.

Responsibilities:

• Session-based authentication with Better Auth
• API key management and validation
• JWT token issuance for internal communication
• Public request JWT generation (per IP, rate-limited)
• System-level request authorization
• User session caching (1-5 min TTL)

→ Learn more about Authentication

Product Service

Purpose: Product catalog management and web scraping.

Responsibilities:

• Product CRUD operations
• Web scraping with Cloudflare Browser Rendering
• Sitemap.xml analysis for context
• Product data refinement
• Maintains Vectorize store for product data
• Uses Gemini AI models via Vercel AI SDK

→ Learn more about Product Scraping

Analytics Service

Purpose: Usage tracking, billing, and analytics.

Responsibilities:

• Queue-based event processing
• Tracks interactions and patterns for billing
• Usage analytics and reporting
• Billing calculations (per interaction/pattern pricing)

MCP Server

Purpose: Public MCP (Model Context Protocol) server for external integrations.

Responsibilities:

• Exposes Interaction and Pattern services via MCP standard
• Requires API key authentication
• Routes through API Gateway as external party
• Enables ChatGPT, Claude, and other LLM integrations
• Built on Cloudflare MCP Workers

A2A (Agent-to-Agent)

Purpose: External agent communication service.

Responsibilities:

• Calls MCP Server for data access
• Provides agent-to-agent communication protocol
• Requires authentication
• Enables enterprise AI agent integrations

Data Storage

D1 Database

Primary relational database for structured data.

Schema Overview:

• Organizations, Users, API Keys
• Products and Categories
• Interaction metadata
• Processing jobs and status
• Configuration and settings

Key Features:

• SQLite compatibility
• Automatic replication
• Point-in-time recovery
• Global read distribution

R2 Object Storage

S3-compatible storage for binary data and archives.

Storage Buckets:

• raw-interactions: Original event data
• cctv-frames: Video frame extracts
• exports: Generated reports
• assets: Static assets

Key Features:

• Zero egress fees
• S3 API compatibility
• Lifecycle policies
• Automatic CDN integration

Vectorize

AI-native vector database for semantic search.

Vector Indexes:

• interaction-embeddings: Interaction text embeddings
• product-embeddings: Product description embeddings
• social-embeddings: Social media content embeddings

Key Features:

• High-dimensional vector storage
• Fast similarity search
• Metadata filtering
• Automatic index optimization

→ Learn more about Data Lake Architecture

API Layer

REST API

Standard RESTful endpoints for CRUD operations.

Endpoint Groups:

• /api/v1/organizations - Organization management
• /api/v1/products - Product catalog
• /api/v1/interactions - Interaction data
• /api/v1/insights - Generated insights
• /api/v1/exports - Export management

GraphQL API (Optional/Future)

Status: Not currently implemented, potential future optimization.

GraphQL support could be added for optimized frontend-service communication, but is not part of the current architecture. The REST API provides all necessary functionality.

Agent2Agent (A2A) Protocol

Enterprise integration for AI agent communication.

Capabilities:

• Standardized agent messaging
• Capability discovery
• Task delegation
• Result aggregation
• Authentication required

MCP Server

Model Context Protocol server for LLM integrations.

Supported Operations:

• Data retrieval for context
• Tool execution via Interaction and Pattern services
• Resource access with API key authentication
• ChatGPT, Claude, and other LLM tool integrations

→ Learn more about Integration API

Authentication

CROW employs a multi-layered authentication strategy optimized for security and performance.

Service-to-Service Authentication (mTLS)

Purpose: Secure communication between internal services.

Implementation:

• Mutual TLS (mTLS) for bidirectional service verification
• Natively supported by Cloudflare Workers
• API Gateway and services configured for mutual trust
• Additional verification layer beyond mTLS for defense in depth

Rationale: While Cloudflare Service Bindings exist, mTLS provides platform independence and prevents vendor lock-in.

Session-Based Authentication

Purpose: User authentication for frontend applications.

Implementation:

• Better Auth library with Drizzle ORM integration
• Session tokens stored in frontend
• Token sent with every request
• Initialized in auth client, passed to dashboard client
• Cookie caching in Better Auth for optimization

JWT Tokens

Purpose: Efficient inter-service communication without database lookups.

Implementation:

• API Gateway converts sessions/API keys to JWTs
• JWTs used for service-to-service calls
• No TTL/expiration (unrevokable by design)
• Optimized for speed at scale
• Prioritizes performance over revocability for data workloads

Caching Strategy:

• Session/API key to JWT mapping cached (1-5 min TTL)
• Minimizes database calls for high-frequency operations
• Drizzle-level caching + Better Auth cookie caching

Public Requests

Purpose: Unauthenticated access to public features (e.g., public chat).

Implementation:

• JWT issued per IP address
• Heavily rate-limited
• Reused across requests from same IP
• Automatic JWT generation for public endpoints

System Requests

Purpose: Internal system operations and event-driven workflows.

Implementation:

• Specific system-level access permissions
• Event-driven queue-based communication
• Trusted internal service authentication
• Restricted to specific operations

API Keys

Purpose: External client authentication.

Features:

• Organization-scoped keys
• Configurable expiration
• Revokable through dashboard
• Permission-based access control
• Managed by Auth Service

Frontend Architecture

Split Application Design

Three separate frontend clients optimized for their specific purposes, designed as building blocks that can be placed in any order.

Landing Client:

• Public-facing marketing and information
• SEO optimized
• Fast initial load
• Separate from authentication

Auth Client:

• Dedicated authentication application
• Sign up and login flows
• Session initialization
• Passed to dashboard client

Dashboard Client:

• React SPA
• Real-time updates
• Rich interactivity
• Complex visualizations

Rationale for Split Design:

• Building block approach - clients can be rearranged as needed
• Future flexibility (e.g., mobile/desktop home page different from landing)
• Better SEO split across different pages
• Enables different tech stacks per client if needed
• Cleaner separation of concerns

→ Learn more about Frontend Architecture

Security & Compliance

Authentication

• Session-Based Auth: Better Auth with Drizzle ORM
• API Keys: Machine-to-machine access with expiration
• JWT Tokens: Internal service communication (no TTL)
• mTLS: Service-to-service mutual verification

Authorization

• Permission Levels: Granular access control (see User Permission Levels)
• Organization Scoping: 1:1 user-organization mapping
• API Rate Limiting: Abuse prevention
• Audit Logging: Compliance tracking

Data Protection

• Encryption at Rest: All storage encrypted
• Encryption in Transit: TLS 1.3 everywhere
• Data Residency: Regional data storage options
• GDPR Compliance: Privacy by design

Deployment & Operations

CI/CD Pipeline

Monitoring & Observability

• Cloudflare Analytics: Built-in metrics
• Worker Logs: Structured logging
• Error Tracking: Automatic error capture
• Performance Monitoring: Real-time latency tracking

Disaster Recovery

• Multi-region Replication: Automatic data replication
• Point-in-time Recovery: D1 database backups
• Failover: Automatic traffic rerouting
• Incident Response: Defined runbooks

Technology Stack Summary

Category	Technology	Purpose
Edge Compute	Cloudflare Workers	Serverless functions
Container Runtime	Workers Containers	Python workloads requiring longer execution
Database	Cloudflare D1	Relational data
Object Storage	Cloudflare R2	Binary data & archives
Vector DB	Cloudflare Vectorize	AI embeddings
Queues	Cloudflare Queues	Message passing
Workflows	Cloudflare Workflows	Orchestration
Real-time	Cloudflare Realtime SFU	Video streaming (CCTV)
Browser Rendering	Cloudflare Browser Rendering	Web scraping
Durable Objects	Cloudflare Durable Objects	Session state management
AI Gateway	Cloudflare AI Gateway	LLM request routing
Frontend	React + Next.js	User interfaces
Language	TypeScript	Services and frontend
Agent Framework	Vercel AI SDK	AI orchestration (chat, dashboard)
Agent Orchestration	Multi-agent patterns	Advanced workflows (product extraction, social search)
AI Models	Google Gemini	All AI processing
Auth Library	Better Auth	Session management
ORM	Drizzle	Database queries
API	REST + MCP + A2A	Data access
Local Dev	Kubernetes (Kind)	Docker-based local env

Key Architectural Decisions

Gemini Model Usage

All AI processing in CROW uses Google Gemini models exclusively:

• High volume support: Handles large amounts of interaction data
• Large context windows: Processes extensive contextual information
• Gemini Live API: Used for CCTV real-time video analysis
• Vercel AI SDK: Agent framework for all Gemini interactions

Model Selection

Model	Use Case	Capabilities
Gemini Pro	General processing, insight generation	1M token context, multimodal reasoning
Gemini Deep Think	Complex analysis, trend identification	Enhanced reasoning, longer chains of thought
Gemini Live	CCTV streaming analysis	Real-time multimodal streaming

Cloudflare AI Gateway

All LLM requests route through Cloudflare AI Gateway for centralized management:

Feature	Benefit
Request caching	Reduces redundant API calls and costs
Rate limiting	Prevents budget overruns
Fallback routing	Automatic failover between providers
Analytics	Usage tracking and cost monitoring

Organization:User (1:1) Mapping

CROW maintains a strict 1:1 relationship between users and organizations:

• Users must have an organization-based email
• Simplifies authorization and data scoping
• Each user belongs to exactly one organization
• Invited users join the same organization
• Critical constraint: Changing this requires significant architectural refactoring

Sessions Concept

Sessions define processing boundaries for each component:

• Web: User inactivity for 1 hour triggers session processing
• CCTV: 1 hour of continuous footage = one session
• Social: One cron job execution = one session

Repository Naming Conventions

• Core APIs: organization-service, user-service, product-service
• Component Workers: web-ingest-worker, cctv-worker, social-worker
• Services: Named with -service suffix
• Clients: Named with -client suffix

Local Development

• Kubernetes with Kind: Docker-based local development environment
• Future cloud deployment: K8s setup enables cloud migration if needed
• Consistency: Same configuration for local and production (Cloudflare)

Optional/Future Features

• GraphQL: Not currently implemented, marked as optional future optimization
• Webhooks: Marked as optional, not part of core architecture
• Python services: May be required for AI libraries lacking TypeScript support

Related Documentation

• Frontend Architecture - UI design and deployment
• Data Lake Architecture - Storage design
• Integration API - API design and protocols
• Services Architecture - Service architecture
• Website Interaction Tracking - SDK and ingestion
• Product Scraping - AI-powered scraping
• Chat System - Conversational interface
• User Signup Flow - Onboarding process