Greeting System — Architecture¶

Audience: Architects, tech leads, senior engineers evaluating design decisions and cross-module impact. This document answers "how is this module designed, and why?" Assumes technical fluency but explains domain-specific decisions.

This content was migrated from Documentation/GREETING_SYSTEM.md and restructured into audience sections. Review for accuracy against the current codebase.

Context and Purpose¶

The Greeting System exists as a separate, fast-path module outside the main LangGraph pipeline. Normal chat messages traverse the full Global Supervisor graph (intent classification → entity resolution → retrieval → planning → UI response), which takes 3–8 seconds. Greetings must appear instantly when the user opens the app — the latency budget is under 2 seconds to first token. This drives the key architectural decision: greetings bypass the orchestration graph entirely and call the greeting node directly from a dedicated API endpoint.

The second major architectural concern is fact selection intelligence. The system must pick the most relevant, timely, and engaging facts from potentially dozens of stored facts, while avoiding repetition across sessions. This is handled by a priority scoring formula with four configurable components, managed via a runtime-editable database configuration table.

Architecture Overview¶

graph TD
    subgraph Frontend ["Frontend"]
        OPEN["User Opens App"]
        SSE["SSE Stream\nDisplay"]
    end

    subgraph FrequencyGate ["Frequency Gate"]
        FG{"Last greeting\n>= 4 hours ago?"}
        DEFAULT["Return default\ngreeting"]
    end

    subgraph FactLoading ["Fact Preloading Pipeline"]
        FPS["Fact Preloading\nService"]
        SCORE["Priority Scoring\n(0-100 points)"]
        WARMTH["Warmth Fact\nSelection"]
        REDIS["Redis Cache\n(1h TTL)"]
    end

    subgraph Generation ["Greeting Generation"]
        LANG["Language\nDetection"]
        VARIANT{"Facts\navailable?"}
        FULL["greeting.md\n(personalized)"]
        SIMPLE["greeting_simple.md\n(generic)"]
        LLM["LLM Stream\n(greeting agent_type)"]
    end

    subgraph Config ["Configuration"]
        DB["fact_preloading_config\n(PostgreSQL JSONB)"]
        ADMIN["Admin API\n(PATCH endpoint)"]
    end

    OPEN -->|"POST /api/v1/chats/greeting"| FG
    FG -->|"No (< 4h)"| DEFAULT
    FG -->|"Yes"| FPS
    FPS --> SCORE
    SCORE --> WARMTH
    WARMTH --> REDIS
    REDIS --> LANG
    LANG --> VARIANT
    VARIANT -->|"1+ facts"| FULL
    VARIANT -->|"0 facts"| SIMPLE
    FULL --> LLM
    SIMPLE --> LLM
    LLM -->|"SSE chunks"| SSE
    DB -.->|"scoring params"| SCORE
    ADMIN -.->|"runtime updates"| DB

    DEFAULT --> SSE

The flow is: frontend triggers POST /api/v1/chats/greeting → frequency gate checks if enough time has passed → Fact Preloading Service queries facts from PostgreSQL and applies priority scoring using parameters from the fact_preloading_config table → warmth facts are appended → results cached in Redis → language detected → prompt variant selected → LLM streams greeting via SSE. The greeting time is recorded after streaming completes (to handle React StrictMode double-invocation).

Component Responsibilities¶

The Fact Scoring System¶

The scoring formula is the architectural core of the Greeting System. Every fact is scored using four components, all configurable at runtime:

PRIORITY_SCORE = TIME_URGENCY + FACT_TYPE_PRIORITY + CONFIDENCE_SCORE + RECENCY_MALUS
                  (0–50 pts)     (0–30 pts)           (0–20 pts)        (-60 to 0 pts)

Time Urgency (0–50 points)¶

Scores facts based on temporal proximity. Computed from the fact's time_anchor date relative to today.

Fact Type Priority (0–30 points)¶

Each of the 12 fact types has a configurable priority score:

Confidence Score (0–20 points)¶

CONFIDENCE_SCORE = fact.confidence × priority_weight_confidence_max

Facts below min_confidence (default: 0.7) are excluded entirely.

Recency Malus (Rotation)¶

A penalty applied to recently-used facts, ensuring greeting variety:

When a greeting is generated, all included fact IDs are marked with last_used_at = now via a fire-and-forget background task.

Warmth Facts¶

After selecting the top priority-scored facts (default: 3), the system adds up to 1 warmth fact — a stable personal detail from configurable types (warmth_types, default: ["Pet", "Hobby", "Relationship"]). Warmth facts must not have a time_anchor (they're stable, not events) and have their own recency malus applied.

Data Model¶

Key Design Decisions¶

Decision 1: Bypass LangGraph — direct node execution

• Chosen: Greeting triggers call greeting_node() directly from the API endpoint, bypassing the full Global Supervisor pipeline.
• Rejected: Running greetings through the standard LangGraph orchestration graph.
• Rationale: Greetings are single-turn with no user message, no intent to classify, and no agents to invoke. The full pipeline adds 3–5 seconds of overhead. Direct execution achieves <2 second time-to-first-token.

Decision 2: Dual fact injection — state + Redis

• Chosen: Facts are loaded into both the greeting node's state (for immediate use) and Redis (for cache warming).
• Rejected: State-only or Redis-only approaches.
• Rationale: The greeting node needs facts immediately (state injection). When the user replies to the greeting, the main chat pipeline needs those same facts without re-querying (Redis warm cache). Dual injection eliminates both latency and race conditions.

Decision 3: Database-driven scoring configuration

• Chosen: All scoring parameters stored in a single-row JSONB table (fact_preloading_config), editable via Admin API at runtime.
• Rejected: Hardcoded constants, environment variables, or YAML config files.
• Rationale: Scoring parameters need frequent tuning (e.g., adjusting how aggressively the recency malus suppresses facts). A database-backed config with 60-second cache allows product owners to experiment without deployments. The Admin API provides a safe, auditable change mechanism.

Decision 4: Record greeting time after streaming

• Chosen: last_greeting_time is written to the database after the SSE stream completes, not before.
• Rejected: Recording before streaming begins.
• Rationale: React StrictMode can trigger double-invocation of the greeting endpoint. If the time were recorded before streaming, the second invocation would hit the frequency gate and return a blank greeting. Recording after ensures at least one complete greeting is delivered.

Interfaces and Contracts¶

Known Trade-offs and Debt¶

• No conversation context in greetings: The greeting node has no access to previous chat history. It can only reference stored facts, not ongoing conversations. Adding conversation-aware greetings would require loading chat summaries, increasing latency.
• Frequency gate is avatar-scoped, not device-scoped: If a user opens Swisper on their phone and laptop within 4 hours, only the first device gets the personalized greeting. The second sees the default. This is acceptable for single-device usage patterns.
• Warmth fact selection is random within type: When multiple warmth facts exist, the selection is not deterministic. A more sophisticated approach could match warmth facts to the priority facts being mentioned (e.g., connect a pet fact to a health fact).
• No A/B testing for prompt variants: There's no mechanism to test different greeting styles or fact presentation formats on subsets of users.