Skip to content
TheChatArchiveThe Chat Archive
GLMGLM-5 / Pony Alpha· unknownHugging Face Frontier Reasoning Traces

Architect a help surface unifying guided tours, contextual docs, and generative chat…

  1. User

    Architect a help surface unifying guided tours, contextual docs, and generative chat within product.

  2. GLM Assistant

    I need to architect a help surface that unifies three distinct components:

    1. Guided Tours: Product walkthroughs, onboarding flows (often linear, UI-focused).
    2. Contextual Docs: Knowledge base articles, FAQs, tooltips (static content, specific to the current page/context).
    3. Generative Chat: An AI assistant (LLM-powered) capable of answering complex questions, synthesizing info, and performing actions.

    The goal is "unifying" them into a single "help surface" (likely a sidebar, a modal, or a floating widget system) so the user doesn't feel like they are jumping between three different tools.

    1. Deconstruct the Request:

    • Core Problem: Fragmented help experiences. Users don't know if they should read docs, start a tour, or ask support.
    • Solution: A unified interface that dynamically serves the right modality (tour, doc, chat) based on context and intent.
    • Key Components:
      • Tours: High guidance, low autonomy. Good for "how do I do X step-by-step?"
      • Docs: High information, low interaction. Good for "what does this field mean?" or "explain the policy."
      • Chat: High flexibility, high interaction. Good for "summarize this" or "help me write this."

    2. High-Level Architecture Strategy: I need to design this across four layers:

    • The User Interface (The "Surface"): How does it look/feel? (Entry points, the container).
    • The Experience Layer (Orchestration): How do we decide what to show? (The brain).
    • The Data/AI Layer: Where does the info come from? (Vector DBs, Graph RAG, Tool use).
    • The Platform/Integration Layer: How does it hook into the product? (SDK, Events).

    3. Detailed Component Design:

    • The Surface (UI):

      • Entry: Global "Help" button (FAB) + embedded empty states + tooltips.
      • The Hub: A sidebar is usually best. It keeps context.
      • The Tabs/Feed: Instead of "Tabs" (Tours | Docs | Chat), it should be a unified feed. "Suggested for you here."
      • Interaction: The chat needs to be central because it's the natural language interface.
    • The Brain (Orchestration/Context Awareness):

      • This is the critical part. We need to know where the user is (URL, DOM element) and what they are doing (event history).
      • Routing: When a user asks "How do I export?", the system needs to decide: Show the doc? Start the tour? Or let the AI explain? The AI should likely be the router.
    • The Data (Backend):

      • Docs: Embeddings (Vector DB).
      • Tours: Metadata (Start node, trigger conditions).
      • Chat: LLM (GPT-4/Claude/etc) + Function Calling (so the AI can start a tour).

    4. Unification Concepts (The "Secret Sauce"):

    • Concept 1: AI as the Conductor. The Chat interface isn't just for Q&A; it's the command line for help. If you ask "How to setup," the AI should reply and offer a button to "Start Tour."
    • Concept 2: Contextual Injection. The sidebar shouldn't be empty. It should pre-load "Contextual Cards" based on the current route.
    • Concept 3: Visual Synchronization. If the AI explains a button, it should highlight that button in the UI (UI tethering).

    5. Structuring the Proposal: A good architecture document follows a logical flow:

    • Executive Summary: What is it?
    • The User Experience (UX Paradigm): Visualizing the surface.
    • The "Intention Engine" (Logic): How it works under the hood.
    • Integration Architecture: Technical components.
    • Data Flow: How a user request moves through the system.
    • Implementation Phases: How to build it without failing.

    6. Refining the Technical Details:

    • Docs vs. Chat: "RAG" (Retrieval Augmented Generation). The Chat searches the Docs.
    • Tours vs. Chat: "Function Calling". The Chat triggers a start_tour(tour_id) function.
    • UI: React components, likely a Portal.
    • Context: Global state manager (Redux/Zustand) listening to route changes.

    7. Drafting the Content (Iterative refinement during drafting):

    • Initial thought: Just have a sidebar with tabs.
    • Correction: No, tabs separate the experience. It needs to be a stream. "Unified Feed." The AI is the primary interface, but it surfaces "Cards" for Docs and Tours.
    • The "Hybrid" approach: The AI answer might contain a link to a Doc and a "Play" button for a Tour. That is true unification.

    8. Final Polish:

    • Use professional terminology (Headless, RAG, Semantic Router, UI Tethering).
    • Ensure accessibility is considered (Keyboard nav).
    • Add a diagram description (since I can't draw).

    (Self-Correction during drafting): Make sure to emphasize Context. A help surface that shows billing help when I'm on the settings page is bad. It needs page_context.

    Let's write the structure:

    1. Concept: The "Assistive Sidecar."
    2. Architecture Diagram (Mental Model).
    3. Layer 1: The Interface (Surface).
    4. Layer 2: The Orchestration (Context Engine).
    5. Layer 3: The Backend (AI & Data).
    6. Key Interactions (The Unification).
    7. Tech Stack Recommendation.

    This looks solid. Proceeding with generation. This architecture defines a Unified Help Layer (UHL), designed to act not as a separate destination, but as an intelligent "Sidecar" that travels with the user across the product.

    The core philosophy is "Input implies Intent." The system treats a user’s query (whether typed or clicked) as a signal to dynamically route them to the best content modality—whether that is a generative answer, a static document, or an interactive guided tour.

    Here is the architectural blueprint.


    1. The Concept: The "Assistive Sidecar"

    Instead of a static widget, the UHL is a persistent, sliding pane (or modal overlay) that exists on the right-hand side of the application viewport.

    • State 1 (Dormant): A minimal "Help" FAB (Floating Action Button) or a "Search for help" bar embedded in the global navigation.
    • State 2 (Active): A slide-out pane (480px width) that overlays the main content but does not fully obscure it, preserving context.

    2. The User Experience (UX) Model

    The surface unifies the three distinct modalities through Adaptive Cards.

    1. Universal Input: A single input field at the top: "Ask a question, find a guide, or search docs..."
    2. Contextual Awareness: The system automatically parses the user’s current location (e.g., Settings > Billing) to weight results.
    3. Hybrid Response: When a user asks "How do I upgrade?", the system returns a unified card:
      • Gen AI Summary: "To upgrade, you need to navigate to billing and select a plan."
      • Deep Link: [Go to Billing Now] (Action).
      • Tour Prompt: [Play "Billing Setup" Walkthrough].
      • Doc Reference: [Read full billing documentation].

    3. System Architecture

    The backend relies on an Orchestrator Layer (an Agentic Router) that determines which source to query and how to combine the results.

    A. The Frontend (The Shell)

    • Tech: React/Web Component wrapper (Shadow DOM) to isolate styles from the host app.
    • DOM Observation: Uses MutationObservers to watch the host app’s URL and UI state to update the "Context Bucket."
    • UI Tethering: The ability for the Help Surface to highlight specific DOM elements in the host app when a Guided Tour is active.

    B. The Orchestrator (The Brain)

    This is a middleware service (Python/Node.js) that handles the logic.

    • Semantic Router: Classifies the user's intent.
      • Informational intent →\rightarrow RAG Pipeline (Docs).
      • Procedural intent →\rightarrow Tour Engine.
      • Debug/Analysis intent →\rightarrow Gen Chat (LLM).
    • Context Injection: Merges user intent with system context (Current Page, User Role, Account Status).

    C. The Knowledge Layer (The Sources)

    1. Docs Index (Vector DB):
      • Standard RAG setup. Documentation is chunked, embedded, and stored.
      • Metadata: Tags for specific pages (e.g., page: "/dashboard").
    2. Tour Manifest (JSON/Graph DB):
      • Tours are not just UI scripts; they are semantic objects.
      • Schema: { "tour_id": "setup-2fa", "trigger_keywords": ["security", "2fa", "login issues"], "start_url": "/security" }.
    3. LLM (Generative Chat):
      • Connects to the host application's API (read-only endpoints) to analyze user data.
      • Use Case: "Why did my export fail?" →\rightarrow LLM checks recent job logs →\rightarrow Generates a specific answer.

    4. Detailed Interaction Flows

    Scenario 1: Proactive Help (Contextual)

    • User Action: User lands on the "API Integration" page.
    • System: The Frontend Context Bucket updates to page: api.
    • Response: The Help Surface "pulses" subtly.
    • Content:
      • Gen AI: "Looking for API keys?"
      • Tour: [Start "Generate API Key" Tour].
      • Docs: "API Rate Limits".

    Scenario 2: The "Fix It" Interaction (Generative + Action)

    • User Input: "My dashboard is loading slowly."
    • Orchestrator: Detects potential performance issue.
    • Gen Chat: Queries internal diagnostic tools (simulated).
    • Response: "I see you are loading 50,000 rows. Try reducing the date range."
    • Action Button: [Apply Recommended Filters] (The LLM triggers a host app function via a secured API bridge).

    Scenario 3: The "Show Me" Interaction (Tours)

    • User Input: "How do I invite my team?"
    • Orchestrator: Matches high confidence to a "Team Invitation" Tour.
    • Response: The AI provides a text summary, but prioritizes a "Start Guide" button.
    • Execution: Clicking "Start Guide" launches the Guided Tour driver, which overrides the UI and walks the user step-by-step.

    5. Technical Requirements & Risks

    ComponentRequirementMitigation Strategy
    LatencyResponse time < 1s for search, < 3s for Gen AI.Implement "Streaming" for AI responses so text appears immediately. Cache common queries (e.g., "How do I login").
    Context DriftUser is on Page A, but asks about Page B.The Orchestrator must prioritize Query Intent over Page Context, but use Page Context as a tie-breaker.
    UI CollisionTour highlights obscure the Help Surface.Z-Index Management Layer. When a Tour starts, the Help Surface collapses to a minimized "Tour Controls" bar.
    Data PrivacyLLM seeing sensitive data.Sanitize inputs before sending to LLM. Use "Function Calling" where the LLM decides what to fetch, but the backend performs the actual fetch.

    6. The Visual Hierarchy (UI Layout)

    Inside the Sidecar Pane:

    1. Header: Global Search Bar (Input).
    2. Default View (Home):
      • Suggested Actions: Based on current page context (Cards).
      • Recent History: "Continue where you left off."
    3. Active View (Chat/Result):
      • The Answer: (Gen AI text).
      • The "Do It" Button: (Start Tour / Perform Action).
      • The "Read More" Links: (References to Docs).

    Summary

    This architecture succeeds by demoting the modality and promoting the intent. The user does not choose between "Chat" or "Docs"; they simply ask for help. The system architecture invisibly routes that request to the static documentation, the interactive tour, or the generative model based on which will solve the problem fastest.

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.