Architecture

The pipeline behind every Ask Oracle answer — classification, grounding, generation, then a typed renderer. Built so the knowledge layer can grow independently of the LLM.

User
 |
 v
Next.js UI  (app/ask)
 |
 v
Question Classifier          lib/ai/classify.ts
 |
 v
Intent + Product + Module Detection
 |
 v
Retrieval Layer              lib/oracle/retrieval.ts
 |-- Curated Oracle Metadata  data/oracle/*
 |-- Verified SQL Patterns    data/oracle/sql-patterns.ts
 `-- (future) Oracle Documentation via pgvector
 |
 v
LLM                          lib/ai/provider.ts (Gemini, provider-agnostic)
 |
 v
Structured JSON              lib/ai/schemas.ts (zod-validated)
 |
 v
Answer Renderer              components/oracle/answer-renderer.tsx

“The LLM explains. The Oracle knowledge layer establishes the facts.”

Frontend

Next.js App Router with React Server Components by default; the Ask Oracle experience and interactive controls (theme toggle, mobile nav, chat state) are client components. Tailwind CSS v4 + shadcn/ui (Base UI primitives) for the design system.

Backend

A single Route Handler (app/api/ask) receives the question and conversation history, runs the pipeline server-side, and returns a validated JSON answer. No separate backend service — Next.js server runtime is the backend.

AI

lib/ai/ is provider-agnostic: an LLMProvider interface with a Gemini implementation behind it, selected via LLM_PROVIDER. The system prompt forces a structured JSON contract; the model is never trusted as the sole source of Oracle facts.

RAG

Today, retrieval is keyword matching over curated Oracle metadata (data/oracle/) — same call shape a vector-backed implementation would have. Swapping in pgvector means replacing lib/oracle/retrieval.ts; nothing upstream changes.

Database

No database is wired up yet — the curated knowledge layer ships as versioned TypeScript data. The schema is designed to move to Postgres (Neon-compatible) with pgvector for embeddings without changing the retrieval interface.

Deployment

Built for Vercel: static pages (marketing, Learn, Docs, Projects) are prerendered; /api/ask and /ask run dynamically. No infrastructure beyond the Next.js app and an LLM API key.

Caching

Static content (Learn/Docs/Projects/Architecture/About) is prerendered at build time. AI answers are intentionally not cached — every question hits the live pipeline so grounding context stays current as the knowledge layer grows.

Security

LLM API keys never reach the client — all provider calls happen inside server-only modules (lib/ai/provider.ts is marked server-only). Request bodies are validated with zod before touching the pipeline; errors never leak raw stack traces to the UI.