Developer Docs

Intelligence Subgraph

The Intelligence subgraph is a background worker and recommendation engine written in Rust. It performs non-destructive analysis on Malet catalogs via the federated GraphQL gateway to compute vertical fit scores, suggest reclassifications, and recommend better tags.

Port: 3026 · Federation: async-graphql v7 · Database: PostgreSQL (ngwenya_intelligence)

Architecture

The service operates on a scheduled cron pattern using tokio-cron-scheduler:

  1. Extraction: At 2:00 AM daily, it queries the Gateway to fetch catalogs across all Malets (including Products and Services).
  2. Analysis: The analyzer uses keyword heuristics to compute a verticalFitScore (0-100) across 10 verticals (e.g., fashion, tech, wellness) and suggests sectionTags.
  3. Persistence: The resulting IntelligenceResult is stored in PostgreSQL via SQLx.
  4. Action: It fires an HTTP POST back to the Malets internal endpoint, which updates the intelligenceMetadata on the Malet and dispatches a notification via the Alerts TCP pipeline to the Organization owner.

GraphQL API

The intelligence service exposes its data to the federation supergraph:

  • intelligenceReport(maletId: ID!): Fetch the latest analysis report, including suggestedVertical and suggestedSectionTags.
  • triggerIntelligenceRun(maletId: ID!): Manually trigger an analysis run for a specific Malet (admin/owner only).

Configuration

The service uses an .env file for configuration:

  • INTELLIGENCE_SERVICE_PORT: HTTP server port (default 3026).
  • DATABASE_URL: PostgreSQL connection string.
  • GATEWAY_URL: Endpoint for fetching federated catalog data.
  • MALETS_INTERNAL_URL: Internal REST endpoint for pushing metadata updates.
  • ALERTS_INTERNAL_URL: URL for the alerts service.
  • CRON_SCHEDULE: Schedule for batch analysis (default "0 0 2 * * *").
  • RUST_LOG: Tracing log levels (e.g., intelligence=debug).