Rose Documentation¶

Welcome to the Rose platform documentation. Rose is an AI-first inbound marketing platform that automates the entire B2B buyer journey through specialized AI agents.

What is Rose?¶

Rose is not just a chat widget - it's a comprehensive platform of AI agents designed to attract, engage, qualify, and convert B2B buyers:

Stage	Agent	Status
Engage	Website Agent	Active
Qualify	Lead Intelligence Agent	Coming Soon
Nurture	Nurturing Agent	Beta
Reach	Outreach Agent	Coming Soon
Create	Content Agent	Coming Soon
Integrate	Agent 2 Agent	Coming Soon

See Agents Overview for detailed agent documentation.

Quick Start¶

Prerequisites¶

Python 3.12+ with Poetry installed
Node.js 18+ with npm
Docker (for containerized development)
Google Cloud SDK (gcloud CLI)
Terraform (for infrastructure management)
Just command runner (brew install just on macOS)

Creating a New Worktree¶

For developers using git worktrees with a bare repository:

# First time: copy the script to your home directory
cp scripts/setup/git-new-worktree.sh $HOME/bin/git-new-worktree.sh
chmod +x $HOME/bin/git-new-worktree.sh

# Then create new worktrees from anywhere
$HOME/bin/git-new-worktree.sh feature/my-branch

This script will:

Create a git worktree at $HOME/git/github/rose/<branch-name>
Authenticate with gcloud (if needed)
Run bootstrap.py
Open the workspace in Cursor IDE

Automated Setup (Recommended)¶

For quick setup of cloned worktrees:

# Full setup with environment download
./bootstrap.py

# Skip environment file download
./bootstrap.py --skip-env

# Force recreate Python venv
./bootstrap.py --force

This script will:

Setup backend (Python venv, dependencies, pre-commit hooks)
Setup frontend (npm dependencies for all packages)
Download environment files from Google Secret Manager (requires gcloud auth)

Project Structure¶

rose/
├── backend/                 # Python backend services
│   ├── apps/               # API applications
│   │   └── api/           # FastAPI services
│   │       └── search/    # Search API
│   ├── packages/          # Shared Python packages
│   │   ├── ixinfra/      # Common utilities
│   │   ├── ixrag/         # RAG processing
│   │   ├── ixchat/        # Chat functionality
│   │   ├── ixllm/         # LLM abstractions
│   │   ├── ixneo4j/       # Neo4j management
│   │   └── ixapi_helpers/ # API utilities
│   └── justfile           # Backend commands
├── frontend/              # TypeScript/React frontend
│   ├── shared/           # Shared components
│   ├── widget/           # Website widget
│   ├── preprod-ui/       # Testing interface
│   ├── chrome-plugin/    # Chrome extension
│   └── justfile          # Frontend commands
├── infrastructure/        # Terraform IaC
└── docs/                  # This documentation

Key Technologies¶

Layer	Technologies
Backend	Python 3.12+, Poetry, FastAPI, MongoDB, Neo4j, LightRAG
Frontend	TypeScript, React, Webpack, Vite
Infrastructure	Docker, Google Cloud Platform, Cloudflare
Testing	pytest, Vitest
Code Quality	Ruff, MyPy, Black

Documentation Sections¶

Agents - Rose AI agents and their capabilities
Architecture - System architecture and diagrams
Backend - Backend services and packages
Frontend - Frontend applications and components
R&D Journal - Research & Development documentation (CIR/JEI)
ADRs - Architecture Decision Records

Common Commands¶

Backend¶

cd backend
just dev staging          # Start development server
poetry run pytest         # Run all tests
poetry run ruff check     # Run linting

Frontend¶

cd frontend
just install              # Install dependencies
just dev-widget           # Widget development
just dev-preprod          # Pre-production UI
just test                 # Run tests

Environment Configuration¶

The project uses IX_ENVIRONMENT to control which configuration and secrets are loaded:

test - Local testing environment
staging - Staging environment
production - Production environment
development - Development environment

See the Backend Setup guide for detailed configuration instructions.