Services Architecture

Overview

CROW is built on Cloudflare Workers with a TypeScript-based microservices architecture. Each service is a dedicated Worker with specific responsibilities, communicating through mTLS, Cloudflare Queues, and service bindings. AI inference runs through Cloudflare Workers AI models (@cf/meta/llama-3.3-70b-instruct-fp8-fast, @cf/meta/llama-3.1-8b-instruct, @cf/llava-hf/llava-1.5-7b-hf, @cf/baai/bge-m3) via the Cloudflare AI Gateway (crow-ai-gateway). Some services use the Vercel AI SDK workers-ai-provider adapter for structured generation (generateObject, streamText).

Service Architecture

API Gateway

The API Gateway is the single entry point for all client requests, centralizing cross-cutting concerns.

Purpose: Request routing, authentication verification, and rate limiting.

Responsibilities:

Route requests to appropriate backend services
Validate sessions and API keys
Convert sessions/API keys to JWTs for internal communication
Enforce rate limiting per key and per IP
Request validation and shaping
Add correlation IDs for distributed tracing

Technology:

TypeScript on Cloudflare Workers
mTLS for service-to-service communication

Bindings:

All backend services via mTLS
Auth Service for session/key validation

Core Services

Auth Service

Purpose: Critical service for all authentication and authorization.

Responsibilities:

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

Technology:

TypeScript on Cloudflare Workers
Better Auth library for session management
Drizzle ORM for database access

Bindings:

D1: User sessions, API keys
Queues: crow-product-crawl-queue (producer, for onboarding auto-crawl)

User Service

Purpose: User management and profile operations.

Responsibilities:

User signup, login
User profile management
Team member references
Chat creator tracking
Overview page data

Bindings:

D1: User data
R2: Profile pictures and assets

Organization Service

Purpose: Organization data and context management.

Responsibilities:

Organization CRUD operations
Maintains Vectorize store for organization context
Provides context to Interaction and Pattern services
Builds organization profiles from usage
GDPR-compliant data clearing

Technology:

TypeScript on Cloudflare Workers
Vercel AI SDK workers-ai-provider adapter for context building (streamText)
Workers AI via Cloudflare AI Gateway

Bindings:

D1: Organization data
R2: Organization assets
AI: Workers AI (context generation)
Queues: crow-organization-context-queue (producer + consumer)
Vectorize: Organization context embeddings

Product Service

Purpose: Product catalog and web scraping.

Responsibilities:

Product CRUD operations
Web scraping with Cloudflare Browser Rendering
Sitemap.xml analysis
Product refinement interface
Vectorize store for product data

Technology:

TypeScript on Cloudflare Workers
Vercel AI SDK workers-ai-provider adapter for product extraction (generateObject with Zod schemas)
Workers AI via Cloudflare AI Gateway
Cloudflare Browser Rendering for scraping

Bindings:

D1: Product data
R2: Product images and assets
AI: Workers AI (@cf/meta/llama-3.1-8b-instruct for extraction, @cf/baai/bge-m3 for embeddings)
Vectorize: Product embeddings
Browser Rendering: Web scraping
KV: Crawler state
Queues: crow-product-crawl-queue (producer + consumer)

Notification Service

Purpose: User notification and email management.

Responsibilities:

Store notification history
Queue-based notification and email creation
Email delivery via Resend
Trusted queue messages (no auth)
Notification display

Bindings:

Queues: email-queue (producer + consumer), crow-notification-queue (consumer)

Analytics Service

Purpose: Usage tracking and analytics.

Responsibilities:

Usage event tracking and summaries
Tracks interactions and patterns

Bindings:

D1: Usage data, analytics records
R2: Analytics assets

Data Processing Services

Interaction Service

Purpose: Core service for processing any input into insights.

Responsibilities:

Processes video, images, text from any source
Retrieves context from Organization and Product services
Generates interaction records with textual descriptions
Identifies products involved
Exposed via MCP server
Multi-agent analysis via Workers Containers (InteractionAnalyzerContainer)

Technology:

TypeScript on Cloudflare Workers
Workers AI (@cf/meta/llama-3.3-70b-instruct-fp8-fast for analysis, @cf/llava-hf/llava-1.5-7b-hf for vision, @cf/baai/bge-m3 for embeddings)
Cloudflare AI Gateway for LLM routing
Workers Containers for analysis orchestration

Trigger: Queue-based (crow-interaction-queue, crow-cctv-batch-queue)

Output: Interaction records with text, metadata, product associations

Bindings:

Queues: crow-interaction-queue (producer + consumer), crow-cctv-batch-queue (producer + consumer)
D1: Metadata
R2: Raw data
AI: Workers AI
Vectorize: Interaction embeddings
Durable Objects / Containers: InteractionAnalyzerContainer

Pattern Service

Purpose: Discovers patterns across interactions.

Responsibilities:

Cron-triggered at multiple intervals (hourly, daily at 02:00, weekly Monday 03:00, monthly 1st 04:00, yearly Jan 1st 05:00 UTC)
Finds patterns across sessions
Aggregates: day, week, month, year, all-time
Self-triggers via queues for multi-period aggregation
Uses Organization and Product context
Workers Containers (PatternAnalyzerContainer) for analysis

Technology:

TypeScript on Cloudflare Workers
Workers AI (@cf/baai/bge-m3 for embeddings)
Cloudflare AI Gateway for LLM routing
Workers Containers for pattern analysis

Trigger: Cron jobs (hourly + daily + weekly + monthly + yearly)

Output: Pattern records with text, metadata, product associations

Bindings:

Cron Triggers: Multi-schedule execution
D1: Metadata, pattern records
R2: Pattern assets
AI: Workers AI
Vectorize: Pattern embeddings (crow-patterns)
Durable Objects / Containers: PatternAnalyzerContainer

Core Chat Service

Purpose: Lightweight multi-agent chat with tool calling.

Responsibilities:

Chat history management
Message storage
Tool calling loop with search_products, get_interactions, get_patterns
Agentic loop (max 5 iterations)

Technology:

TypeScript on Cloudflare Workers
Workers AI (@cf/meta/llama-3.3-70b-instruct-fp8-fast)
Cloudflare AI Gateway for LLM routing

Bindings:

D1: Chat history
AI: Workers AI

BFF Chat Service (Dashboard BFF)

Purpose: Backend for Frontend for dashboard chat with rich tool support.

Responsibilities:

Chat session management
Extended tool calling (search_products, search_interactions, search_patterns, search_org_context, get_interaction_summary)
Agentic loop with tool execution and source reference tracking
Artifact and asset management

Technology:

TypeScript on Cloudflare Workers
Workers AI (@cf/meta/llama-3.3-70b-instruct-fp8-fast)
Cloudflare AI Gateway for LLM routing

Integration: Dashboard-specific, not generic

Bindings:

D1: Chat history
R2: Artifacts, assets
AI: Workers AI
Interaction/Pattern/QnA Services: Data access via API Gateway

BFF QnA Service

Purpose: RAG-based Q&A with Vectorize embeddings.

Responsibilities:

Document indexing from GitHub repositories
Cron-triggered index refresh (every 12 hours)
Semantic search over indexed documents via Vectorize
Q&A session management

Technology:

TypeScript on Cloudflare Workers
Workers AI (@cf/baai/bge-m3 for embeddings)
Cloudflare AI Gateway

Trigger: API + Cron (0 */12 * * *)

Bindings:

D1: Session data
AI: Workers AI
Vectorize: crow-qna-index (document embeddings)
Cron Triggers: Index refresh

Component Workers

Web Ingest Worker

Purpose: Receive events from JavaScript SDK and manage web sessions.

Responsibilities:

Event validation and transformation
API Gateway routing
Session management via Durable Objects
Hourly inactivity trigger (1 hour = session end)
Queue dispatch to Interaction Service

Technology:

TypeScript on Cloudflare Workers
Durable Objects for session state

Bindings:

Durable Objects: CrowWebSession (session state with alarm)
Queues: crow-interaction-queue (producer), crow-session-expiry-queue (producer + consumer), crow-web-session-export (producer)
D1: Event storage
R2: Session data storage
AI: Workers AI

Session Definition: 1 hour of user inactivity triggers session processing.

Purpose: Collect social media data via cron-triggered search and discovery.

Responsibilities:

AI-generated search query creation
Social content discovery via Tavily web search API
Duplicate detection
Queue dispatch to social processor

Technology:

TypeScript on Cloudflare Workers
Workers AI for query generation
Tavily API for web search

Trigger: Cron-based scheduled execution (every 2 hours)

Bindings:

Cron Triggers: Scheduled execution (0 */2 * * *)
D1: Collection configs, seen links, scrape state
AI: Workers AI
Queues: crow-social-processing-queue (producer)

Purpose: Enrich and process collected social content.

Responsibilities:

Queue-based consumption of raw social items
AI-powered content enrichment and analysis
Forward processed items to interaction queue

Technology:

TypeScript on Cloudflare Workers
Workers AI for content enrichment

Trigger: Queue consumer (crow-social-processing-queue)

Bindings:

Queues: crow-social-processing-queue (consumer), crow-interaction-queue (producer)
AI: Workers AI

Pipeline: core-social-collector (cron) -> crow-social-processing-queue -> core-social-processor -> crow-interaction-queue -> core-interaction-service

CCTV Ingest Service

Purpose: Handle CCTV frame ingestion and vision analysis.

Responsibilities:

Receive CCTV frames via API
Run vision analysis with Workers AI
Store frames to R2
Queue dispatch to Interaction Service

Technology:

TypeScript on Cloudflare Workers
Workers AI (@cf/llava-hf/llava-1.5-7b-hf for vision analysis)
Cloudflare AI Gateway

Trigger: API-based frame ingestion

Bindings:

D1: Ingest metadata
R2: crow-cctv-frames (frame storage)
AI: Workers AI
Queues: crow-cctv-batch-queue (producer)

CCTV CLI

Purpose: CLI tool for capturing and streaming CCTV video+audio from local devices.

Technology:

TypeScript/Bash
Runs as a background daemon on CCTV servers

External Integration Services

MCP Service

Purpose: Model Context Protocol server for LLM integrations.

Responsibilities:

Exposes CROW data (interactions, patterns, products) as MCP tools
API key authentication (verifies via API Gateway)
Standard MCP protocol compliance

Technology:

TypeScript on Cloudflare Workers
MCP protocol specification

Integrations:

ChatGPT, Claude, other LLMs
Developer tools
External AI agents

Bindings:

D1: MCP session/state data
R2: crow-mcp-service-store
API Gateway: External auth and data access

Domain: mcp.crowai.dev (dev: dev.mcp.crowai.dev)

A2A Service

Purpose: Agent-to-agent communication via Google A2A protocol.

Responsibilities:

Implements Google A2A agent card and JSON-RPC transport
Delegates to BFF Chat Service for actual agent execution
Authentication via INTERNAL_GATEWAY_KEY
Enterprise AI agent integrations

Technology:

TypeScript on Cloudflare Workers
@a2a-js/sdk for A2A protocol
Hono for HTTP routing

Bindings:

AI: Workers AI
BFF Chat Service: Agent execution (via BFF_CHAT_URL)

Domain: a2a.crowai.dev (dev: dev.a2a.crowai.dev)

Infra Crawl Service

Purpose: Dedicated product catalog web crawler using Workers Containers.

Responsibilities:

Runs Playwright-based crawling in containers
Stores crawl results to R2
Async job management

Technology:

TypeScript on Cloudflare Workers
Workers Containers (CrawlerContainer with Playwright)
Hono for HTTP routing

Bindings:

R2: crow-crawl-results (crawl result storage)
Durable Objects / Containers: CrawlerContainer

Service Communication

mTLS (Mutual TLS)

Services communicate via mTLS for secure bidirectional verification:

API Gateway configured to trust internal services
Each service validates calling service
Additional verification layer beyond mTLS
Prevents vendor lock-in (alternative to Service Bindings)

JWT Tokens

API Gateway issues JWTs for internal communication:

// API Gateway converts session/API key to JWT
const jwt = await issueJWT({
  userId: session.userId,
  orgId: session.orgId,
  permissions: session.permissions
});

// Services validate JWT
const decoded = await validateJWT(request.headers.get('Authorization'));

JWT Characteristics:

No TTL/expiration (performance optimization)
Contains user, org, permissions
Cached mapping (1-5 min TTL)
Optimized for high-volume data workloads

Queue-based Communication

Asynchronous communication via Cloudflare Queues:

// Producer (Web Ingest Worker)
await env.INTERACTION_QUEUE.send({
  type: 'web_session',
  sessionId: '...',
  events: [...],
  orgId: '...'
});

// Consumer (Interaction Service)
export default {
  async queue(batch, env) {
    for (const message of batch.messages) {
      await processInteraction(message.body, env);
    }
  }
};

Service Bindings (Limited Use)

While Cloudflare Service Bindings exist, CROW primarily uses mTLS to avoid vendor lock-in. Service Bindings may be used for specific internal-only services where portability is not a concern.

Technology Stack

Service Type	Language	AI Framework	Key Libraries
All Services	TypeScript	N/A	Hono / OpenAPIHono, Drizzle ORM
Chat/Agent Services	TypeScript	Workers AI (`@cf/meta/llama-3.3-70b-instruct-fp8-fast`)	Cloudflare AI Gateway
Product Extraction	TypeScript	Workers AI via Vercel AI SDK `workers-ai-provider`	`generateObject`, Zod schemas
Org Context	TypeScript	Workers AI via Vercel AI SDK `workers-ai-provider`	`streamText`
Vision Analysis	TypeScript	Workers AI (`@cf/llava-hf/llava-1.5-7b-hf`)	Cloudflare AI Gateway
Embeddings	TypeScript	Workers AI (`@cf/baai/bge-m3`)	Vectorize
Web Scraping	TypeScript	N/A	Browser Rendering, Playwright (containers)
Auth	TypeScript	N/A	Better Auth
A2A Protocol	TypeScript	N/A	`@a2a-js/sdk`

Note on Hono: Hono is a lightweight, fast web framework used across all CROW microservices. It provides routing, middleware, and request handling optimized for Cloudflare Workers.

Programming Language Selection

Language	Use Case	Justification
TypeScript	All core services on Cloudflare Workers	Native Worker support, strong ecosystem, type safety
Python	AI/ML services (if needed)	Strong ML tooling, useful for experiments
Go	Container-based services (future)	High performance, good concurrency

Note: TypeScript is the primary language. Python services may be required if AI libraries lack TypeScript support. Go remains a future option if container-based services become necessary.

Repository Naming Conventions

Core Services: core-auth-service, core-user-service, core-organization-service, core-product-service, core-billing-service, core-notification-service, core-analytics-service
Processing Services: core-interaction-service, core-pattern-service, core-chat-service
Social Pipeline: core-social-collector, core-social-processor
BFF Services: bff-chat-service, bff-qna-service
Ingestion: web-ingest-service, cctv-ingest-service
Infrastructure: infra-crawl-service
Integration: mcp-service, a2a-service
CLI: cctv-cli
Clients: landing-client, auth-client, dashboard-client, rogue-store

Deployment

Wrangler Configuration

Each service has its own wrangler.jsonc with environment-specific overrides (dev, local, production):

{
  "name": "crow-core-interaction-service",
  "main": "src/index.ts",
  "compatibility_date": "2025-12-17",
  "compatibility_flags": ["nodejs_compat"],
  "ai": { "binding": "AI" },
  "d1_databases": [
    { "binding": "DB", "database_name": "crow-core-interaction-service-db", "database_id": "..." }
  ],
  "r2_buckets": [
    { "binding": "R2_BUCKET", "bucket_name": "crow-core-interaction-service-store" }
  ],
  "vectorize": [
    { "binding": "INTERACTION_VECTORIZE", "index_name": "crow-interaction-index" }
  ],
  "queues": {
    "consumers": [
      { "queue": "crow-interaction-queue", "max_batch_size": 10, "max_retries": 3 }
    ]
  },
  "env": {
    "dev": { /* dev overrides */ },
    "local": { /* local overrides */ }
  }
}

Local Development

Kubernetes with Kind: Docker-based local environment
Consistency: Same config for local and production
Future-ready: Enables cloud migration if needed

CI/CD Pipeline

Pipeline Stages

Stage	Action
Lint	ESLint, Prettier, TypeScript checking
Test	Bun test runner with coverage reporting
Deploy Dev	Staging deployment on pull requests
Deploy Prod	Production deployment on main branch merge
Notify	Slack notifications for deployment status

Deployments use Wrangler CLI for Workers and Containers with environment-specific configuration managed through Cloudflare's secrets store.

Observability and Monitoring

Metrics Collection

Cloudflare Analytics Engine provides edge-native metrics collection without impacting request latency:

Request volumes and throughput
Latency distributions (p50, p95, p99)
Error rates by service
AI processing times

Logging

Structured logs stream to Axiom for centralized analysis:

Debugging: Trace requests across services
Audit trails: Compliance and access logging
Performance analysis: Identify bottlenecks
Long-term retention: Historical analysis

Alerting

Real-time alerts on error rate thresholds
Latency degradation notifications
Queue depth monitoring
AI Gateway usage alerts

System Architecture - Overall platform architecture
Integration API - API details
Data Storage Architecture - Storage design
Frontend Architecture - Client applications
User Permission Levels - Access control

Overview​

Service Architecture​

API Gateway​

Core Services​

Auth Service​

User Service​

Organization Service​

Product Service​

Notification Service​

Analytics Service​

Data Processing Services​

Interaction Service​

Pattern Service​

Core Chat Service​

BFF Chat Service (Dashboard BFF)​

BFF QnA Service​

Component Workers​

Web Ingest Worker​

Social Collector​

Social Processor​

CCTV Ingest Service​

CCTV CLI​

External Integration Services​

MCP Service​

A2A Service​

Infra Crawl Service​

Service Communication​

mTLS (Mutual TLS)​

JWT Tokens​

Queue-based Communication​

Service Bindings (Limited Use)​

Technology Stack​

Programming Language Selection​

Repository Naming Conventions​

Deployment​

Wrangler Configuration​

Local Development​

CI/CD Pipeline​

Pipeline Stages​

Observability and Monitoring​

Metrics Collection​

Logging​

Alerting​

Related Documentation​

Overview

Service Architecture

API Gateway

Core Services

Auth Service

User Service

Organization Service

Product Service

Notification Service

Analytics Service

Data Processing Services

Interaction Service

Pattern Service

Core Chat Service

BFF Chat Service (Dashboard BFF)

BFF QnA Service

Component Workers

Web Ingest Worker

Social Collector

Social Processor

CCTV Ingest Service

CCTV CLI

External Integration Services

MCP Service

A2A Service

Infra Crawl Service

Service Communication

mTLS (Mutual TLS)

JWT Tokens

Queue-based Communication

Service Bindings (Limited Use)

Technology Stack

Programming Language Selection

Repository Naming Conventions

Deployment

Wrangler Configuration

Local Development

CI/CD Pipeline

Pipeline Stages

Observability and Monitoring

Metrics Collection

Logging

Alerting

Related Documentation