Architecture

Platform Overview

Rose is an AI-first inbound marketing platform built as a distributed system. The production Website Agent combines a browser widget, Cloudflare edge routing, FastAPI services on Cloud Run, LangGraph orchestration, retrieval infrastructure, and external model and enrichment providers.

Agent Architecture

Rose agents follow a common four-layer pattern:

flowchart TB UI[Frontend interface] --> API[API service] API --> Core[Agent core] Core --> Shared[Shared infrastructure]

Layer	Purpose	Website Agent example
Frontend interface	User-facing surface	React widget
API service	Authentication, validation, and transport	Search API
Agent core	Business logic and orchestration	ixchat LangGraph
Shared infrastructure	Retrieval, models, storage, and configuration	ixrag, ixllm, Redis, MongoDB, Neo4j

Active Agents

Agent	Frontend	Backend API	Core package
Website Agent	frontend/widget/	backend/apps/api/search/	ixchat

See Agents Overview for beta and roadmap agents.

Supporting Services

Service	Responsibility
Admin API	Authenticated backoffice BFF for privileged operations
Knowledge API	Durable knowledge workflow owner, dispatcher, recovery endpoint, and status API
Knowledge content worker	Executes discovery, scrape, and clean stages and writes immutable GCS artifacts
Integrations API	HubSpot OAuth, webhooks, and integration task handling
IXVector API	Identity and enrichment webhook ingestion
Rose MCP	Hosted MCP interface for external agent clients

System Components

• Product surfaces: Astro marketing website, React widget, client backoffice, playground, and Chrome extension.
• Cloudflare edge: Astro website Worker, the api.userose.ai unified proxy, Cloudflare Pages, GCS widget assets, and R2 GEO pages.
• Cloud Run services: Search, Admin, Knowledge, knowledge content worker, Integrations, IXVector, and Rose MCP.
• Async execution: Cloud Tasks queues, Cloud Scheduler recovery, document loading, tagging, website mapping, PostHog batch processing, HubSpot sync, the fenced FAQ rollback job, and GEO publishing.
• Data: Supabase Postgres, Redis, MongoDB, Neo4j, the rose-scraping GCS bucket, the widget CDN bucket, and Cloudflare R2.
• Providers: model and embedding vendors, Cohere reranking, visitor enrichment providers, observability and analytics products, and CRM/tools.

Architecture Diagram

The diagram reads top-to-bottom through seven layers: users, product surfaces, Cloudflare edge, Cloud Run services, asynchronous orchestration, data, and external providers. Detailed arrows are limited to the real-time chat lane and the knowledge-ingestion control plane so the operational paths remain legible.

Source of truth: docs/diagrams/rose-system-architecture.dot. just dev and just build render the SVG into src/_generated/; do not edit or commit that generated asset. See the diagram inventory for ownership rules.

Component Details

Product Surfaces

Component	Purpose	Technology
Marketing website	userose.ai	Astro 6 with @astrojs/cloudflare
Widget	Embeddable Website Agent	React, TypeScript, UMD bundle
Client backoffice	Analytics, configuration, content, and operations	React, Vite, Cloudflare Pages
Playground	Internal testing across clients and environments	React, Vite, Firebase Hosting
Chrome extension	Inject and test Rose on arbitrary sites	WXT / Chrome Extension APIs

The standalone stats opt-out extension is a developer tool and is intentionally not shown in the hosted runtime diagram. See Frontend Overview.

Backend Packages

Package	Responsibility
ixchat	Website Agent LangGraph, skills, memory, and response routing
ixrag	LightRAG retrieval and tenant-aware storage integration
ixllm	Multi-provider model routing and fallback
ixknowledge	Knowledge workflow contracts and domain logic
ixscraping	Website discovery, scraping, and cleaning logic
ixconfig	Typed unified configuration models and resolver
ixskills	Global and per-client agent skill system
ixmongo / ixneo4j	Tenant-aware MongoDB and Neo4j adapters
ixdata / ixinfra / ixweb	Data access, shared runtime utilities, and web boundaries
ixgeo	GEO content generation and publishing
ixtagging / ixevaluation	Conversation classification and evaluation tooling

Async and Batch Execution

Execution unit	Trigger	Responsibility
Knowledge content worker	Discovery, scrape, and clean Cloud Tasks queues	Produce immutable artifacts and report fenced results to Knowledge API
Document loader	Knowledge API / approved on-demand execution	Write controlled snapshots to LightRAG, MongoDB, and Neo4j
Tagging	Cloud Scheduler	Classify and score conversations
Website mapping	Scheduled Cloud Run Job	Refresh website mapping data
PostHog batch processor	Scheduled Cloud Run Job, production only	Convert raw batch exports into analytics tables
HubSpot contacts sync	Jobs API / on demand	Synchronize CRM contacts and Rose data
FAQ update	Scheduled, production-only rollback path	Legacy direct knowledge_faqs ingestion; fenced during controlled cutover
GEO pipeline	On demand	Generate geo.faqs publishing content and deploy static R2 pages

config.knowledge_faqs is chat retrieval knowledge. geo.faqs is generated publishing content and never enters the chat ingestion path.

Data Layer

• Supabase Postgres: configuration, conversations, analytics, GEO content, knowledge workflow state, immutable snapshot metadata, and freshness state.
• Redis: LangGraph checkpoints, conversation memory, locks, and caches.
• MongoDB: LightRAG chunks, vectors, key-value state, and document status.
• Neo4j: tenant-aware knowledge graph nodes and relationships.
• GCS rose-scraping: immutable source and processing artifacts for the knowledge control plane.
• GCS inboundx-cdn and Cloudflare R2: widget assets and published GEO pages.

External Providers

Model selection is role-based rather than one global default:

Role	Providers
Answer generation and fallbacks	Azure OpenAI and OpenAI
Fast routing, signals, and suggestions	Cerebras with configured fallbacks
Query rewriting	Mistral
Scraping decisions and selectable routes	OpenRouter routes, including Anthropic, Gemini, and Groq
Embeddings and reranking	Azure/OpenAI embeddings and Cohere
Identity and enrichment	Reveal, Snitcher, RB2B, Vector, and Enrich.so
Observability and analytics	Langfuse, Sentry, and PostHog EU
CRM and tools	HubSpot, n8n, Linear, Google Drive, and IndexNow

The authoritative per-task model routing lives in backend/packages/ixchat/ixchat/chat_routing.py; the diagram deliberately avoids model-version labels that change frequently.

Primary Data Flows

Chat Request

1. The widget sends a chat request through api.userose.ai.
2. The Search API validates the request and invokes ixchat.
3. LangGraph starts retrieval, enrichment, and profiling work and routes the turn through the appropriate response path.
4. ixrag reads MongoDB and Neo4j; ixllm selects the configured model route.
5. Tokens stream back through the API proxy while checkpoints remain in Redis and conversation/profile data is persisted in Supabase.

The complete graph is generated from code on the IXChat package page.

Knowledge Ingestion

1. Backoffice producers call the Admin API, which authorizes the user and calls the private Knowledge API with service-to-service OIDC.
2. The Knowledge API records durable operation state in Supabase before dispatching discovery, scrape, or clean work to Cloud Tasks.
3. The content worker writes immutable artifacts to GCS and reports fenced results to the Knowledge API.
4. After snapshots converge, the Knowledge API admits the document-loader job, the only controlled writer to LightRAG stores.
5. Cloud Scheduler invokes the same API dispatcher to recover pending or ambiguous work.

See Knowledge ingestion control plane for state transitions and operational details.

Analytics

1. The widget sends events to PostHog through the unified analytics proxy.
2. PostHog exports batches into posthog_events_raw in Supabase.
3. The production-only PostHog batch processor updates visitor sessions, page views, session events, conversations, and analytics marts.
4. Backoffice pages read those tables and RPCs directly through RLS-protected Supabase access.

The proposed first-party self-capture replacement is not deployed. Its phased design is recorded in the PostHog cost and removal ADR.