Developer Docs

Vertical Intelligence Reindexer — Developer Guide

Overview

The Intelligence service is a Rust-native microservice (apps/intelligence) that periodically analyzes Malet catalog content — products, services, and metadata — to compute vertical fit scores, suggest reclassification, and recommend additional section tags. All suggestions are non-destructive — the Malet Owner must explicitly approve any changes.

Component Purpose Technology
Keyword Analyzer Extracts keywords and scores content against vertical maps Rust (in-process)
Gateway Client Reads federated Malet/Product/Service data from the gateway reqwest (GraphQL client)
Cron Scheduler Triggers batch analysis runs at configurable intervals tokio-cron-scheduler
IntelligenceResult Persistent analysis record PostgreSQL (SQLx)
IntelligenceMetadata Embedded suggestions on the Malet entity MongoDB (via malets NestJS)
MaletAlertsController Delivers owner notifications for actionable suggestions NestJS TCP (alerts subgraph)

Architecture

The intelligence service operates as an independent Rust microservice within the federation, following the same architectural pattern as auth, uchat, and scim.

sequenceDiagram
    participant Cron as Intelligence Cron (Rust)
    participant GW as Gateway (GraphQL)
    participant DB as Postgres (intelligence)
    participant Malets as Malets (NestJS)
    participant Mongo as MongoDB (malets)
    participant Alerts as Alerts (NestJS)
    participant Owner as Malet Owner

    Cron->>GW: Query malets, products, services
    GW-->>Cron: Federated data
    Cron->>Cron: Analyze keywords, compute verticalFitScore
    Cron->>DB: INSERT IntelligenceResult
    Cron->>Malets: POST /internal/intelligence-update
    Malets->>Mongo: Update intelligenceMetadata
    Malets->>Alerts: TCP vertical_intelligence_suggestion
    Alerts->>Owner: IN_APP + Email notification

Scoring Algorithm

The analyzer uses a keyword frequency heuristic as a Phase 1 foundation. For each Malet, it:

  1. Collects text from all products and services (names + descriptions)
  2. Builds a corpus by concatenating and lowercasing all text
  3. Scores against 10 verticals — each vertical has a curated keyword list (e.g., restaurant: "menu", "dish", "cuisine", "chef")
  4. Computes verticalFitScore = (matchedKeywords / totalKeywords) × 100
  5. Suggests reclassification if the declared vertical scores below 60% AND another vertical scores 10%+ higher
  6. Suggests section tags based on keyword matches (e.g., if "organic" and "natural" appear → suggest "organic" tag)

Supported Verticals

Vertical Example Keywords
Restaurant menu, dish, cuisine, chef, catering
Fashion clothing, designer, runway, boutique
Tech specs, warranty, firmware, software
Photographer photo, portrait, gallery, lens
Tour itinerary, travel, destination, safari
Author book, novel, publish, manuscript
Entertainment event, ticket, concert, venue
Professional consultation, client, contract, retainer
Wellness spa, therapy, fitness, meditation
Culture art, exhibition, gallery, museum

GraphQL API

Queries

# Latest intelligence report for a Malet
query {
  intelligenceReport(maletId: "malet-abc") {
    verticalFitScore
    declaredVertical
    suggestedVertical
    suggestedSectionTags
    keywordSummary
    analyzedAt
    status
  }
}

Mutations

# Manually trigger analysis (admin use)
mutation {
  triggerIntelligenceRun(maletId: "malet-abc") {
    verticalFitScore
    suggestedVertical
    suggestedSectionTags
  }
}

Malet Entity Integration

The IntelligenceMetadata subdocument is embedded on the Malet entity in the malets subgraph:

type IntelligenceMetadata {
  verticalFitScore: Float!
  suggestedVerticalType: String
  suggestedSectionTags: [String!]!
  lastAnalyzedAt: DateTime!
  status: String!  # PENDING | ACCEPTED | DISMISSED
}

This field is read-only from the Malet Owner's perspective — they can view suggestions in their dashboard but the intelligence service is the sole writer.

Owner Notification Flow

When the intelligence service detects actionable suggestions (reclassification or new tags), the malets service emits a vertical_intelligence_suggestion TCP event to alerts:

  • IN_APP notification: Always delivered to the Malet Owner
  • Email notification: Delivered if the owner has email notifications enabled (respects quiet hours)
  • Template: "Your Malet {name} may benefit from reclassification — current fit score: {score}%"

Future Roadmap

Phase Feature Status
Phase 1 Keyword heuristic scoring ✅ Complete
Phase 2 ML model inference (ONNX/Candle) 📋 Planned
Phase 3 Semantic vector embeddings 📋 Planned
Phase 4 Personalized recommendations 📋 Planned