Skip to main content
AI Engineering
12 min read

Autonomous Hybrid RAG Architecture: In-Browser Vector Retrieval, Generative UI & Next.js 16 SSG

Complete architectural case study of the yusupovartur.com platform: engineering a sub-5ms Hybrid RAG assistant (Okapi BM25 + Damerau-Levenshtein + Cosine Similarity), multi-turn conversational memory, Generative UI tool cards, and 213+ localized Next.js 16 SSG routes with zero vector database fees.

AY
Artur Yusupov
Fullstack Web Engineer & AI Developer
Autonomous Hybrid RAG Architecture: In-Browser Vector Retrieval, Generative UI & Next.js 16 SSG

1. Executive Summary: The Cloud Vector Database Anti-Pattern

Over the past two years, tutorials across the industry have preached a uniform dogma: *To build a RAG chatbot, you must subscribe to Pinecone, Weaviate, or Qdrant, spin up an embedding microservice, and query a remote vector index on every user prompt.*

While this architecture is mandatory for enterprise search systems indexing millions of legal files or medical records, it is complete architectural overkill for engineering portfolios, documentation portals, and SaaS knowledge bases containing under 10,000 documents.

  • Latency Tax: Every remote vector lookup introduces 150ms - 400ms of network roundtrips before LLM token generation even begins.
  • Cost Tax: Managed vector databases cost $70 - $250 / month in idle base charges.
  • Single Point of Failure: If the remote vector DB experiences downtime or API quotas expire, your website assistant breaks completely.

When engineering the flagship Next.js 16 & Hybrid RAG Portfolio Platform (`yusupovartur.com`), we designed an Autonomous Hybrid RAG Engine that executes both on the Vercel Serverless Edge and directly in the browser, indexing 71 commercial and personal project case studies and 9 architectural deep-dives across 3 languages (`EN`, `UA`, `ES`) in under 5ms with $0/month in database overhead.


2. Architecture Decision Records (ADR)

Architectural Decision
Build-Time In-Memory Index (Okapi BM25 + Pre-Computed Vectors)
Alternative Considered
Cloud Vector DB (Pinecone / Qdrant)
Why We Chose This Path (Trade-off Analysis)
Eliminates 150-400ms network roundtrips and $70+/mo recurring bills. The entire 80+ chunk knowledge base compiles into a lazy-loaded Rollup/Webpack chunk (22.1 KB gzip).
Architectural Decision
Dual-Mode Execution (`/api/chat` Streaming + Autonomous Client Fallback)
Alternative Considered
Server-Only LLM Endpoint
Why We Chose This Path (Trade-off Analysis)
On yusupovartur.com, Next.js streams responses via POST /api/chat. If the network drops, rate limits trigger, or the code runs on a static host, the client seamlessly synthesizes deterministic answers locally with zero error screens.
Architectural Decision
7-Intent Deterministic Router (`detectQueryIntent`)
Alternative Considered
LLM-Only Tool Calling
Why We Chose This Path (Trade-off Analysis)
Classifies queries into 7 intents (project-aspect, blog, service, profile, contact, methodology, general) in < 0.2ms, preventing active project context from hijacking general B2B pricing or contact questions.
Architectural Decision
In-Chat Generative UI Orchestration
Alternative Considered
Plain-Text Markdown Replies
Why We Chose This Path (Trade-off Analysis)
Dynamically renders interactive React 19 components (ProjectToolCard, StackComparisonCard, ProjectEstimateCalculatorCard, ContactActionCard) directly inside assistant replies to drive B2B conversion.
Architectural Decision
Unified `projectRegistry` Single Source of Truth
Alternative Considered
Separate CMS / JSON Duplication
Why We Chose This Path (Trade-off Analysis)
One strongly typed TypeScript registry simultaneously powers Next.js generateStaticParams (213+ SSG routes), dynamic Schema.org JSON-LD, llms-full.txt for external AI crawlers, and the internal RAG knowledge base.

3. Core Mechanisms: How the Platform Works Under the Hood

Mechanism 1: The Three-Stage Hybrid Scoring Pipeline (Okapi BM25 + Damerau-Levenshtein + Cosine Similarity)

Pure semantic vector search often fails on exact version numbers (Next.js 16 vs Next.js 14) or specific brand names (IT-Magic, Unitrition, Fullstack AI Lab). Conversely, pure keyword matching fails on conceptual prompts like *"How do you optimize mobile loading speed?"*.

Our retriever in src/lib/ai/rag.ts combines three mathematical signals for every knowledge chunk d and query Q:

TS
FinalScore(d, Q) = (w_bm25 * BM25(d, Q)) + (w_sem * CosineSimilarity(q, d)) + FieldBoost(d, Q) + ContextBoost(d)
1
Stage 1 - Trilingual Tokenization, Synonym Expansion & Typo Tolerance:

The query is normalized via foldForSearch(), stripped of English, Ukrainian, and Spanish stopwords, and expanded through a bilingual/trilingual domain synonym dictionary (expandTokens()). If a token does not match directly, a bounded Damerau-Levenshtein distance matrix (distance <= 1 for short words, <= 2 for longer technical terms) corrects user typos in real time (e.g., matching wpskilz to wpskills or untrition to unitrition).

2
Stage 2 - Okapi BM25 Lexical Ranking (`k1 = 1.5, b = 0.75`):

Each chunk is scored using Inverse Document Frequency (IDF) weighted by document length normalization against the corpus average length (avgDocLength):

TS
   const idf = Math.log(1 + (totalDocs - docFreq + 0.5) / (docFreq + 0.5))
   const tfNorm = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLength / avgDocLength)))
   bm25Score += idf * tfNorm
3
Stage 3 - Vectorized Cosine Similarity & Contextual Boost:

Dense float embeddings are compared via normalized dot product (calculateCosineSimilarity). If the visitor opened the chat from a specific project page (e.g., Active Case Study: IT-Magic), chunks matching currentProjectSlug receive a deterministic +18.0 context boost when the query intent is project-aspect or general.


Mechanism 2: Multi-Turn Conversational Memory & Anti-Repetition State Machine

A major weakness of stateless RAG bots is losing context on follow-up questions like *"What tech stack was used there?"* or *"And what challenges did you solve?"*, or repeating the exact same overview paragraph three times in a row.

Our engine solves this via a deterministic state machine in src/lib/ai/rag.ts:

1
Entity Resolution Across Dialogue History (`resolveTargetProject` & `resolveBlogFromQueryOrContext`):

If the current message does not explicitly name a project, the engine scans options.history in reverse chronological order to recover the active project or blog article from previous turns, updating the pinned UI context bar automatically.

2
Aspect-Specific Extraction (`detectProjectAspects`):

The synthesizer inspects whether the user is asking about Stack (technologies), Architecture (architecture.rows), Challenges & Solutions (challenges / solutions), Metrics (detailMetrics), or Live Links (liveUrl / githubUrl), returning only the requested slice of the case study rather than dumping the entire document.

3
Anti-Repetition Guard (`answeredQuestions`):

Every user prompt is recorded in answeredQuestions, allowing getContextualFollowUps() to dynamically filter out already-asked questions and suggest the next logical engineering question for that specific project.


Mechanism 3: Generative UI Orchestration Inside the Chat Stream

Rather than returning walls of plain Markdown text, ChatModal.tsx evaluates intent detectors alongside the RAG response and mounts interactive React 19 components directly inside the assistant message bubble:

  • `ProjectToolCard` (`getRelevantProjectCards`): Renders rich visual project cards with WebP thumbnails, category badges, top 4 technology tags, and direct View Case Study / Live Site links.
  • `StackComparisonCard` (`isStackComparisonQuery`): Triggered when a CTO or client asks *"Next.js vs WordPress"* or *"Which stack should I choose?"*. Renders an interactive tab-switching matrix comparing TCO, Time-to-Market, CWV performance, and ideal use cases across Next.js 16, Headless WP, and Custom PHP.
  • `ProjectEstimateCalculatorCard` (`isEstimateOrCalculatorQuery`): Triggered on pricing/timeline queries. Lets the user interactively toggle project type, scope, and AI features to calculate real-time delivery phases and week estimates.
  • `ContactActionCard` (`isHireOrContactQuery`): Renders a zero-trust contact card that decodes Base64 channels (Email, WhatsApp, Telegram, LinkedIn) only upon explicit user interaction, plus a direct CV PDF download button.

Mechanism 4: Next.js 16 App Router (213+ SSG Routes) & GEO (llms.txt) Synchronization

Because this article serves as the architectural case study for `yusupovartur.com`, it is important to see how the web platform and the AI engine share a single unified data pipeline:

1
Static Generation Across 3 Locales (`app/[locale]/projects/[slug]/page.tsx`):

At build time, generateStaticParams() iterates over all 71 projects and 9 blog articles across ['en', 'ua', 'es'], pre-rendering 240+ static HTML pages on the Vercel Edge Network with zero runtime database queries.

2
Programmatic SEO & Dynamic Schema.org JSON-LD:

Every route automatically generates localized <title>, Open Graph metadata, canonical hreflang alternates (en, uk, es, x-default), and structured JSON-LD graphs (Person, CreativeWork, TechArticle, BreadcrumbList).

3
Generative Engine Optimization (GEO - `/llms.txt` & `/llms-full.txt`):

To ensure external AI search engines (ChatGPT Search, Perplexity, Claude, Google AI Overviews) cite accurate engineering facts about Artur Yusupov's portfolio, the platform exposes structured Markdown context files at the root domain following the 2026 llms.txt standard.


4. Engineering Glossary: Key Terms Explained Simply

  • Hybrid RAG (Retrieval-Augmented Generation):
  • *What it is:* Combining exact keyword scoring (Okapi BM25) with mathematical vector embeddings (Cosine Similarity) to retrieve verified project facts before generating an AI answer.
  • *Why it matters:* Eliminates AI hallucinations and guarantees 100% factual accuracy on project names, metrics, and technology versions.
  • Okapi BM25 (Best Matching 25):
  • *What it is:* A probabilistic information-retrieval ranking formula used by search engines that scores how well a document matches query keywords while penalizing overly common words and normalizing document length.
  • *Why it matters:* Ensures rare technical tokens like WPGraphQL, useSyncExternalStore, or IT-Magic rank at the top immediately.
  • Damerau-Levenshtein Distance:
  • *What it is:* A string-similarity algorithm that counts the minimum number of insertions, deletions, substitutions, or adjacent character transpositions needed to turn one word into another.
  • *Why it matters:* Makes both the RAG assistant and the portfolio search bar resilient to human typos without requiring external search servers.
  • Cosine Similarity:
  • *What it is:* A geometric calculation measuring the cosine of the angle between two multi-dimensional vectors to determine semantic closeness regardless of text length.
  • *Why it matters:* Allows the assistant to understand conceptual intent across English, Ukrainian, and Spanish in under 2ms.
  • Generative UI:
  • *What it is:* An AI interface pattern where the assistant responds not just with text, but by dynamically rendering interactive UI widgets (calculators, comparison tables, project cards) inside the chat stream.
  • *Why it matters:* Turns a passive Q&A chatbot into an interactive B2B product discovery and lead-qualification experience.

5. Defense-in-Depth Security Architecture (/api/chat & Client Isolation)

Publishing the full retrieval and synthesis architecture of yusupovartur.com is completely safe because security is enforced through strict server and client boundaries rather than obscurity:

1
Sliding-Window IP Rate Limiting with Bounded LRU Memory (`src/lib/ratelimit.ts`):

The POST /api/chat route enforces strict per-IP quotas (15 requests per hour) backed by Upstash Redis in production and a bounded 5,000-entry LRU in-memory store that prevents memory-exhaustion DDoS attacks under IP-spoofing floods.

2
Prompt Injection Sanitization Shield (`sanitizeUserPrompt`):

All incoming user messages are truncated to safe bounds (max 600 chars) and stripped of system-override patterns (ignore previous instructions, system:, <|im_start|>) before reaching the synthesis pipeline.

3
Zero-Secret Client Bundle & Autonomous Fallback:

All LLM API keys (OPENAI_API_KEY) reside strictly inside Vercel encrypted server environment variables. The browser bundle contains only public portfolio case studies and deterministic math functions.

4
Zero-Trust Base64 Contact Obfuscation (`src/utils/contacts.ts`):

Personal email, phone, WhatsApp, and Telegram endpoints are never rendered in plaintext HTML or SSR output; they are decoded from Base64 exclusively on explicit client-side user interaction.

Battle-Tested Production Proof

Where This Architecture is Deployed in Production

These architectural patterns are not abstract theory - they are fully deployed and benchmarked in these live production builds:

Architecture Consulting

Planning a tech stack migration or new build?

Discuss architectural requirements with my interactive RAG AI assistant or connect directly for an engineering assessment.

Contact Directly