CROW Internal Documentation

Internal documentation for CROW (Cognitive Reasoning Observation Watcher) by B3.

About CROW

CROW is a unified customer interaction intelligence platform that collects behavioral signals across digital storefronts (web SDK), physical retail (CCTV), and social media, then consolidates them into a searchable natural language data layer. Built entirely on Cloudflare's edge infrastructure with Workers AI models. External AI systems can access CROW data via standard AI interoperability protocols -- MCP (Model Context Protocol) for LLM tool-use integrations and A2A (Agent-to-Agent) for autonomous agent collaboration.

Three Data Channels

1. Web Component -- JavaScript SDK captures user interactions on web, mobile (React Native), and desktop (Electron) applications. Sessions are defined by 1 hour of user inactivity.
2. Social Component -- AI-driven web search agents and social media link scraping via Cron Triggers. Each cron execution equals one session.
3. CCTV Component -- Real-time video frame analysis via Cloudflare Workers AI vision models. Each hour of footage equals one session.

Quick Links

Task	Link
Deploy a service	Deployment Guide
Bootstrap the workspace	Local Development
Add a new API endpoint	API Reference
Understand the architecture	System Architecture
MCP / A2A protocols	Integration API
Coding conventions	Coding Conventions
AI model inventory	AI Models

Documentation Overview

Architecture

• System Architecture -- Service map, routing, auth flow, BOLA pattern, gateway trust model
• AI Models -- Workers AI model inventory and processing pipelines
• Frontend Architecture -- Landing, auth, and dashboard clients
• Services Architecture -- Service communication and deployment patterns
• Data Storage -- D1, R2, Vectorize, and Queue architecture
• Integration API -- REST, MCP, and A2A protocols

Services

Per-service documentation covering schema, routes, environment variables, secrets, queue bindings, and dependencies:

API Gateway

• core-api-gateway -- Routing, auth middleware, org resolution, cache

Core Services

• core-auth-service -- Better Auth, onboarding, API keys, team invitations
• core-user-service -- User CRUD, profile, search, permissions
• core-organization-service -- Org CRUD, AI context generation
• core-product-service -- Crawler jobs, product extraction, R2 images, Vectorize
• core-interaction-service -- Interaction ingestion, CCTV batch processing, Workers Container
• core-pattern-service -- Cron-triggered pattern analysis, Python Workers Container
• core-billing-service -- Stripe checkout, webhooks, subscriptions
• core-notification-service -- Email via Resend, notification queues
• core-analytics-service -- Usage event tracking
• core-chat-service -- Multi-agent chat with tool calling and A2A

AI Protocol Services

• mcp-service -- MCP server exposing CROW data as LLM tools
• a2a-service -- A2A protocol server for agent-to-agent collaboration

Social Media Pipeline

• core-social-collector -- Cron-triggered social media data collection via Tavily
• core-social-processor -- Queue consumer that processes collected social data into interactions

BFF (Backend for Frontend) Services

• bff-chat-service -- CrewAI multi-agent chat, Workers Containers
• bff-qna-service -- RAG Q&A with Vectorize

Ingestion Services

• cctv-ingest-service -- CCTV frame analysis, Durable Objects
• web-ingest-service -- Website interaction tracking SDK backend, Durable Objects

Infrastructure Services

• infra-crawl-service -- Web crawling via Workers Containers (headless browser)

Frontend Clients

• dashboard-client -- Next.js dashboard SPA (OpenNext on Cloudflare)
• auth-client -- Next.js auth pages (OpenNext on Cloudflare)
• landing-client -- Astro + Preact marketing/landing pages
• rogue-store -- Demo e-commerce store (OpenNext on Cloudflare)

CLI Tools

• cctv-cli -- CLI tool for CCTV streaming

Deployment

• Deployment Guide -- Wrangler commands, secrets, D1 databases, environments, Workers Containers, OpenNext, Durable Objects, Queues

Reference

• Local Development -- Multi-repo bootstrap, sync, branch checkout, and cleanup workflows
• Coding Conventions -- No comments, max 1 indent, FP first, 20-40 line functions
• AI Models -- Model choices, dimensions, and justifications
• API Reference -- Per-service endpoint documentation

Features

• Website Tracking -- JavaScript SDK and interaction ingestion
• Social Media -- AI-driven web search and social scraping
• CCTV -- Real-time video analysis
• Product Scraping -- AI-powered product catalog scraping
• Chat System -- Conversational AI interface
• User Signup Flow -- Registration and onboarding
• Dashboard Features -- Dashboard pages and functionality