Prerequisites

Make sure the following tools are installed on your machine before proceeding.

1. Clone and Start

git clone https://github.com/your-org/recomnext.git
cd recomnext/recom

# Build and start all services in the background
docker compose up -d --build

The first build takes a few minutes as Docker downloads base images, installs dependencies, and pre-downloads the ML model for the embeddings service. Subsequent starts are much faster.

# Watch the build progress
docker compose logs -f

# Check that all containers are running
docker compose ps

2. Verify Services

# Health check
curl http://localhost:3000/health
# Expected: {"status":"ok"}

# Embeddings health check
curl http://localhost:8001/health
# Expected: {"status":"ok","model":"all-MiniLM-L6-v2","collection":"recomnext_embeddings"}

3. Seed Demo Data

cd demo
npm install
npm run seed

# Or with a custom engine URL:
ENGINE_URL=http://localhost:3000 npm run seed

After seeding, open the Demo Store at http://localhost:3002 and the Admin Panel at http://localhost:3001 to see the catalog and interaction data.

4. Generate Embeddings

# Fetch all items from the catalog
ITEMS=$(curl -s http://localhost:3000/catalog/items \
  -H "X-Tenant-Id: demo-ecommerce" | \
  python3 -c "import sys,json; \
    d=json.load(sys.stdin); \
    items=[{'externalId':i['externalId'],'category':i.get('category',''),'attributes':i.get('attributes',{})} for i in d['data']]; \
    print(json.dumps({'items':items,'tenantId':'demo-ecommerce'}))")

# Index into Qdrant via the embeddings service
curl -X POST http://localhost:8001/index \
  -H "Content-Type: application/json" \
  -d "$ITEMS"
# Expected: {"indexed": 46}

5. Your First API Calls

Ingest an Item

curl -X POST http://localhost:3000/ingestion/items \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: demo-ecommerce" \
  -d '{
    "items": [{
      "externalId": "new-001",
      "category": "electronics",
      "attributes": {
        "name": "Noise-Canceling Earbuds",
        "price": 149.99,
        "brand": "SoundMax",
        "rating": 4.6
      }
    }]
  }'

Get Personalized Recommendations

curl -X POST http://localhost:3000/recommendations \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: demo-ecommerce" \
  -d '{
    "logicType": "user-to-item",
    "userId": "alice",
    "count": 5
  }'

Hybrid Search

Natural language search that combines vector similarity with automatic filter extraction. The query "wireless headphones under $100" will search semantically for "wireless headphones" and apply a 'price' < 100 nextQL filter automatically.

curl "http://localhost:3000/recommendations/search?query=wireless+headphones+under+%24100&count=5" \
  -H "X-Tenant-Id: demo-ecommerce"

# Response includes results + facets for dynamic filter UI:
# {
#   "items": [...],
#   "facets": {
#     "categories": [{"value":"electronics","count":2}],
#     "priceRanges": [{"value":"$50 - $100","count":1}]
#   },
#   "query": {
#     "original": "wireless headphones under $100",
#     "semanticText": "headphones",
#     "extractedFilters": "'price' < 100.0"
#   }
# }

6. Explore the Admin Panel

• Browse and search the ingested item catalog
• Create and manage Scenarios — named recommendation configurations with nextQL filters, boosters, and constraints
• Define Segmentations to enforce diversity in results
• View Analytics dashboards — interaction volume, top items, scenario funnels (CTR, conversion)
• Manage Embedding Templates for customizing how items are vectorized
• Test nextQL expressions in the built-in playground

Architecture Overview

RecomNext runs as a set of Docker containers connected via a shared bridge network. The engine is the central API service that coordinates all data stores and the embeddings sidecar.

┌─────────────────────────────────────────────────────────────┐
│                        Docker Network                       │
│                                                             │
│  ┌─────────┐   ┌─────────┐   ┌──────────┐   ┌───────────┐  │
│  │  Admin   │   │  Demo   │   │ Landing  │   │ Embeddings│  │
│  │  :3001   │   │  :3002  │   │  :3003   │   │  :8001    │  │
│  └────┬─────┘   └────┬────┘   └──────────┘   └─────┬─────┘  │
│       │              │                              │        │
│       └──────┬───────┘                              │        │
│              ▼                                      │        │
│       ┌──────────────┐         ┌──────────┐         │        │
│       │    Engine     │────────▶│ Consumer │         │        │
│       │    :3000      │         │ (Kafka)  │         │        │
│       └──┬──┬──┬──┬───┘         └────┬─────┘         │        │
│          │  │  │  │                  │               │        │
│    ┌─────┘  │  │  └──────┐    ┌─────┘               │        │
│    ▼        ▼  ▼         ▼    ▼                     ▼        │
│ ┌───────┐┌─────┐┌───────┐┌───────┐            ┌────────┐   │
│ │MongoDB││Redis││ Kafka ││Qdrant │            │ Qdrant │   │
│ │:27017 ││:6379││ :9092 ││:6333  │◀───────────│(shared)│   │
│ └───────┘└─────┘└───────┘└───────┘            └────────┘   │
│                    │                                        │
│                    ▼                                        │
│              ┌───────────┐                                  │
│              │ClickHouse │                                  │
│              │  :8123    │                                  │
│              └───────────┘                                  │
└─────────────────────────────────────────────────────────────┘

Environment Variables

Each service reads its configuration from environment variables. The defaults work out-of-the-box for the Docker Compose setup. Override these when deploying to a custom environment or connecting to external managed services.

Engine

The central NestJS API service that handles ingestion, recommendations, scenarios, and analytics.

Consumer

A separate process that reads interaction events from Kafka and writes them to ClickHouse in batches. Uses the same engine Docker image with a different entrypoint.

Embeddings Service

Python FastAPI service that generates text embeddings using SentenceTransformers, indexes vectors into Qdrant, and parses natural language search queries.

Infrastructure Services

Default credentials and configurations for the backing data stores. Change these for production deployments.

Next Steps

Now that you have RecomNext running locally, explore the platform further:

• nextQL Guide — Learn the query language for writing filters, boosters, and segmentation expressions.
• API Reference — Full REST API documentation for ingestion, recommendations, scenarios, and analytics.
• SDK Docs — Browser and Node.js SDK guides for integrating recommendations into your applications.