Architecture¶
Platform Overview¶
Rose is an AI-first inbound marketing platform built as a distributed system. The platform consists of multiple specialized AI agents, each designed to automate a specific part of the B2B buyer journey.
Agent Architecture¶
Each Rose agent follows a common architecture pattern:
| Layer | Purpose | Example |
|---|---|---|
| Frontend Interface | User-facing component | Widget, email, dashboard |
| API Service | Request handling | FastAPI endpoints |
| Agent Core | Business logic | LangGraph orchestration |
| Shared Infrastructure | Common services | RAG, LLM, storage |
Active Agents¶
| Agent | Frontend | Backend API | Core Package |
|---|---|---|---|
| Website Agent | frontend/widget/ |
backend/apps/api/search/ |
ixchat |
Staff-only services¶
| Service | Frontend | Backend API | Core Package |
|---|---|---|---|
| Admin API (GEO republish, custom hostname) | frontend/client-backoffice/ |
backend/apps/api/admin/ |
ixadmin_api |
See Agents Overview for the full agent roadmap.
System Components¶
The platform consists of:
- Agent Frontends: React/Next.js interfaces (widget, chrome extension, backoffice, playground, marketing website)
- API Gateway: Cloudflare Workers for routing, security and static delivery
- Agent APIs: FastAPI services on Google Cloud Run (search/chat, admin, integrations, ixvector)
- Async / Batch: Cloud Run Jobs (tagging, FAQ update, document loader, HubSpot sync) + GEO pipeline, triggered by Cloud Scheduler / Cloud Tasks
- Databases: MongoDB (vectors/chunks), Neo4j (knowledge graph), Redis (sessions), Supabase Postgres (config/conversations/GEO — one shared project), plus GCS and Cloudflare R2 object storage
- External Providers: LLM providers (Azure OpenAI, OpenAI, Cerebras, Mistral, OpenRouter/Anthropic/Gemini/Groq), Cohere (rerank), enrichment cascade (Reveal, Snitcher, RB2B, Enrich.so), Langfuse, PostHog, Sentry, HubSpot, n8n, Linear
Architecture Diagram¶
The diagram below reads top-to-bottom through the seven layers of the platform — visitors, frontends, the Cloudflare edge, the Cloud Run backend (with the agent core's request pipeline), the async/batch jobs, the data layer, and every external provider grouped by role. Arrows are kept at the block level (one summary arrow between blocks) so the high-level flow stays legible; every provider and store node is still shown inside its labelled group.
Source of truth:
docs/diagrams/rose-system-architecture.dot(Graphviz). The embedded SVG is rendered intosrc/_generated/by thegenerate-diagramsstep ofjust dev/just build— no manual copy needed. Seedocs/diagrams/README.mdfor the diagram versioning convention.
Component Details¶
Frontend Layer¶
The frontend consists of multiple deployment targets sharing common components:
| Component | Purpose | Technology |
|---|---|---|
| shared | Core React components and services, consumed via scoped entrypoints | TypeScript, React |
| widget | Embeddable website widget | Vite bundle |
| chrome-plugin | Browser extension | WXT / Chrome Extension API |
| preprod-ui | Testing playground | Vite (Firebase Hosting) |
| client-backoffice | Client administration dashboard | Vite SPA |
| website | Marketing site (userose.ai) |
Next.js 15 · OpenNext on Cloudflare Workers |
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 | Multi-provider LLM client abstraction with routing + retry |
| ixneo4j | Neo4j multi-tenant database management |
| ixmongo | MongoDB multi-tenant storage |
| ixconfig | Unified configuration system — typed models and resolver |
| ixdata | Data access layer for external data sources |
| ixweb | FastAPI web/HTTP boundary for the search service (Clean Architecture) |
| ixapi_helpers | FastAPI middleware and auth |
| ixskills | Skill system for chatbot response endings |
| ixgeo | GEO Content Agent — FAQ generation from visitor questions |
| ixtagging | Conversation classification and tagging service |
| ixpromptclassifier | Prompt complexity classifier (NVIDIA prompt-task-and-complexity model) |
| ixevaluation | Evaluation utilities for classification and LLM testing |
| ixadmin_api | Staff-only admin Cloud Run service (GEO republish, custom hostname) — see backend/apps/api/admin/README.md |
Cloud Run service URL mapping¶
Each environment runs its own admin Cloud Run service, paired with the matching backoffice domain:
| Backoffice domain | Branch | Admin Cloud Run service |
|---|---|---|
apptest.userose.ai |
develop |
admin-api-test |
appstaging.userose.ai |
staging |
admin-api-staging |
app.userose.ai |
main |
admin-api-production |
The backoffice resolves the right service via the VITE_ADMIN_API_BASE_URL
env var, set per environment in frontend/.env.{test,staging,production}.
Async / Batch Jobs¶
Work that does not belong on the request path runs as Cloud Run Jobs, triggered by Cloud Scheduler (cron) or Cloud Tasks (on-demand):
| Job | Trigger | Responsibility |
|---|---|---|
| Tagging | Cloud Scheduler | Classify + score conversations into Supabase |
| FAQ update | Cloud Scheduler | Ingest knowledge_faqs into LightRAG (prod-only) |
| Document loader | On-demand | Pull Google Drive KB docs into LightRAG (per-tenant) |
| HubSpot sync | On-demand (Jobs API) | Sync CRM contacts ⇄ Supabase |
| GEO pipeline | On-demand | Generate FAQs and publish static pages to Cloudflare R2 |
Data Layer¶
MongoDB (Vector Storage)¶
- Shared collections with tenant isolation via
tenantIdfield - Single shared vector index supports unlimited tenants
- Composite IDs format:
tenant_id:original_id
Neo4j (Knowledge Graph)¶
- Property-based tenant isolation using
tenantIdon 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 | Role | Purpose |
|---|---|---|
| Azure OpenAI | Chat LLM | Primary / default LLM provider |
| OpenAI | Chat LLM | Fallback + skill selection; embeddings |
| Cerebras | Chat LLM | Fast inference for signals / suggestions |
| Mistral AI | Chat LLM | Query rewriting |
| OpenRouter · Anthropic · Google Gemini · Groq | Chat LLM | Supported, selectable providers |
| OpenAI / Azure Embeddings | Embeddings | text-embedding-3-small for LightRAG |
| Cohere | Rerank | rerank-v4.0-fast for RAG |
| NVIDIA prompt classifier | Classify | Prompt task/complexity model (runs locally) |
| Reveal · Snitcher · RB2B · Enrich.so | Enrichment | Tiered visitor → company identification cascade |
| Langfuse | Observability | LLM traces and prompt management |
| Sentry | Observability | Error tracking |
| PostHog | Analytics | Product analytics (EU) |
| HubSpot | CRM | Contact sync and email-capture |
| n8n | Automation | Workflow automation |
| Linear | Integrations | Issue tracking (support tickets from backoffice) |
| Google Drive | Sources | Knowledge-base document source |
| IndexNow | Sources | Search-engine recrawl pings for published GEO pages |
Data Flow¶
Chat Request Flow¶
- User sends message via widget
- Request routes through Cloudflare API proxy
- FastAPI receives and validates request
- ChatService initializes LangGraph chatbot
- Chatbot retrieves context via LightRAG
- LLM generates response with retrieved context
- Response streams back to user
- Conversation stored in Redis
Analytics Flow¶
- Widget tracks events (impressions, clicks, messages)
- Events sent to PostHog via API proxy
- Webhook triggers on specific events (CTA clicks, form submissions)
- Cloudflare Worker processes webhook
- Supabase updated with conversion data