Architecture

Core Serving Pipeline

The Finkkle query engine executes requests through an ordered, 8-phase pipeline to ensure relevancy, safety, speed, and personalization.

Architecture guide · Finkkle documentation

The 8 Phased Ranking Levels

Incoming searches are routed through sequential stages before results return. Each phase performs a dedicated function:

Phase 0: Feature Flags & Analytics

Inspects the request context, matches flags, sets up logging telemetry, and schedules shadow reads if experimental paths are checked.

Phase 1: Ingestion & Frontier

Controls crawler workers and page schedules. During search execution, Phase 1 remains offline and operates strictly on index background pools.

Phase 2: Hybrid Retrieval

Retrieves lexical and semantic vector candidates in parallel. Uses index aliases to query SQLite and vector tables concurrently. (Disabled by default).

Phase 3: Query Understanding

Parses user queries. Extracts vertical intents (e.g. images, videos, shopping, translation, dictionary), corrects spelling errors, and rewrites noisy terms. (Enabled by default).

Phase 4: Personalization

Applies profile-aware session weights, semantic domain affinities, and tracking filters to sort search outputs relative to current user history. (Enabled by default).

Phase 5: Caching & Degradation

Queries Redis or in-memory tables for matches. If downstream APIs or databases are slow, Phase 5 activates circuit breakers to skip enrichments and serve cached outputs. (Enabled by default).

Phase 6: Trust & Safety

Runs safe-search filtering, identifies explicit results, demotes spam domains, and coordinates reports via OwlGuard moderation tables. (Enabled by default).

Phase 7: Evaluation & Interleaving

Performs live A/B tests and routes metrics into evaluation logs. Used mainly during relevance benchmarking. (Disabled by default).

Feature Flags Configuration

The serving logic resolves feature gates on start. Flags can be overridden via environment variables or matching API routes. Default configurations live in src/phase0/feature-flags.ts: