Architecture

System Overview

Rose is built as a distributed system with the following key components:

• Frontend: React-based widget deployable to any website
• Backend: FastAPI services running on Google Cloud Run
• API Gateway: Cloudflare Workers for routing and security
• Databases: MongoDB (vectors), Neo4j (knowledge graph), Redis (sessions)
• External Services: LLM providers, Langfuse, PostHog, Sentry

Architecture Diagram

flowchart LR User[User] --> ReactApp[React App] subgraph CF[Cloudflare Workers] APIProxy[API Proxy] Webhook[Webhook] end subgraph GCP[GCP Cloud Run] FastAPI[FastAPI] Chat[Chatbot] RAG[LightRAG] end subgraph DB[Databases] Redis[(Redis)] Neo4j[(Neo4j)] Mongo[(MongoDB)] end subgraph Ext[External APIs] LLM[Azure OpenAI] Analytics[PostHog] end ReactApp --> APIProxy APIProxy --> FastAPI APIProxy --> Analytics FastAPI --> Chat Chat --> RAG Chat --> LLM Chat --> Redis RAG --> Neo4j RAG --> Mongo Analytics --> Webhook

Component Details

Frontend Layer

The frontend consists of multiple deployment targets sharing common components:

Component	Purpose	Technology
shared	Core React components and services	TypeScript, React
widget	Embeddable website widget	Webpack UMD bundle
chrome-plugin	Browser extension	Chrome Extension API
preprod-ui	Testing interface	Vite
backend_ui	Admin dashboard	Vite

API Gateway (Cloudflare Workers)

All frontend requests route through api.userose.ai:

• /rose/* → Backend FastAPI services
• /analytics/* → PostHog EU
• /db/* → Supabase
• /monitoring → Sentry

Backend Services

Built as a Python monorepo with specialized packages:

Package	Responsibility
ixinfra	Configuration, logging, utilities
ixchat	LangGraph chatbot with conversation memory
ixrag	LightRAG integration for document retrieval
ixllm	LLM client abstraction with retry logic
ixneo4j	Neo4j multi-tenant database management
ixmongo	MongoDB multi-tenant storage
ixapi_helpers	FastAPI middleware and auth

Data Layer

MongoDB (Vector Storage)

• Shared collections with tenant isolation via tenantId field
• Single shared vector index supports unlimited tenants
• Composite IDs format: tenant_id:original_id

Neo4j (Knowledge Graph)

• Property-based tenant isolation using tenantId on all nodes/edges
• Wraps LightRAG's Neo4JStorage for multi-tenancy

Redis (Session Storage)

• Conversation history and session management
• Fast key-value storage for real-time chat

External Integrations

Service	Purpose
Azure OpenAI	Primary LLM provider
Cohere	Reranking for RAG
Langfuse	LLM observability and prompt management
PostHog	Product analytics
Sentry	Error tracking
Enrich.so	IP-based company enrichment
n8n	Workflow automation

Data Flow

Chat Request Flow

1. User sends message via widget
2. Request routes through Cloudflare API proxy
3. FastAPI receives and validates request
4. ChatService initializes LangGraph chatbot
5. Chatbot retrieves context via LightRAG
6. LLM generates response with retrieved context
7. Response streams back to user
8. Conversation stored in Redis

Analytics Flow

1. Widget tracks events (impressions, clicks, messages)
2. Events sent to PostHog via API proxy
3. Webhook triggers on specific events (CTA clicks, form submissions)
4. Cloudflare Worker processes webhook
5. Supabase updated with conversion data