Skip to content

Rose Documentation

Welcome to the Rose platform documentation. Rose is an AI-powered conversational widget for B2B websites.

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)

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:

  1. Setup backend (Python venv, dependencies, pre-commit hooks)
  2. Setup frontend (npm dependencies for all packages)
  3. 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

  • Architecture - System architecture and diagrams
  • Backend - Backend services and packages
  • Frontend - Frontend applications and components

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.