An interactive Next.js frontend for exploring and explaining the gdelt-knowledge-base project. Query GDELT documentation with AI-powered retrieval, explore evaluation metrics, analyze datasets, and understand the multi-layer RAG architecture.

• Submit natural language questions about GDELT documentation
• Real-time AI responses via LangGraph Server (GPT-4.1-mini)
• Retrieved context documents with relevance scores and metadata
• Query history with localStorage persistence (last 10 queries)
• Toast notifications for success/error feedback

• Real RAGAS metrics (Faithfulness, Relevancy, Precision, Recall)
• Retriever comparison table across 4 strategies
• Interactive bar charts and radar visualizations (Recharts)
• SHA-256 data provenance fingerprints
• Model configuration details (LLM, embeddings, vector store)

• 4 Hugging Face datasets with live metadata
• Direct links to HF dataset pages
• Ingestion manifest with environment tracking
• SHA-256 fingerprint verification
• Data lineage visualization

• Browse 38 GDELT documentation pages used for RAG retrieval
• Full-text search across content, titles, and authors
• Pagination support for navigating documents
• Document metadata display (page numbers, creation dates, file paths)
• Direct link to HuggingFace dataset

• Explore 48 synthetic Q&A pairs used for evaluation
• View questions, reference answers, and reference contexts
• Collapsible context display for detailed inspection
• Full-text search across questions and answers
• Track data synthesizer information

• 5-layer architecture breakdown
• Module inventory with descriptions
• Design patterns (Factory, Singleton, Strategy)

• Node.js 18.x or later (Download)
• npm, yarn, pnpm, or bun package manager

• Python 3.11+
• gdelt-knowledge-base repository cloned as sibling directory
• LangGraph Server running on port 2024
• OpenAI API Key (required for queries)
• Cohere API Key (optional, for reranking)

Navigate to the project directory and install the required packages:

npm install # or yarn install # or pnpm install # or bun install

Start the Next.js development server:

npm run dev # or yarn dev # or pnpm dev # or bun dev

The application will be available at http://localhost:3000.

Open your browser and navigate to the URL to see the application. The page will automatically reload when you make changes to the code.

To create an optimized production build:

npm run build # or yarn build # or pnpm build # or bun build

After building, you can start the production server:

npm start # or yarn start # or pnpm start # or bun start

gdelt-ui-demo/ ├── app/ # Next.js App Router pages │ ├── api/ # Next.js API routes │ │ ├── evaluation/ # Evaluation metrics endpoints │ │ ├── datasets/ # Dataset metadata endpoints │ │ ├── sources/ # Source documents API │ │ └── testset/ # Golden testset API │ ├── architecture/ # Architecture documentation │ ├── datasets/ # Dataset explorer │ ├── docs/ # Documentation pages │ ├── evaluation/ # Evaluation metrics │ ├── query/ # Query console │ ├── sources/ # Source documents browser │ ├── testset/ # Golden test set viewer │ ├── layout.tsx # Root layout │ └── page.tsx # Home page ├── components/ # React components │ ├── ui/ # shadcn/ui components (19 components) │ ├── app-sidebar.tsx # Application sidebar │ ├── backend-status.tsx # Backend health monitor │ ├── providers.tsx # React Query provider │ └── top-nav.tsx # Top navigation ├── hooks/ # Custom React hooks │ ├── use-backend-health.ts # Backend health polling │ ├── use-datasets.ts # React Query dataset hooks │ └── use-evaluation.ts # React Query evaluation hooks ├── lib/ # Utility functions │ ├── api-client.ts # LangGraph API client │ ├── huggingface.ts # HuggingFace API integration │ ├── types.ts # TypeScript type definitions │ └── utils.ts # Utility helpers ├── tests/ # Playwright integration tests │ ├── query-console.spec.ts # Query console tests (11) │ ├── evaluation.spec.ts # Evaluation dashboard tests (15) │ ├── datasets.spec.ts # Datasets page tests (14) │ └── backend-health.spec.ts # Backend health tests (11) ├── public/ # Static assets └── package.json # Dependencies and scripts 

The UI integrates with two types of endpoints:

Used for live query processing:

POST http://localhost:2024/threads - Create conversation thread POST http://localhost:2024/threads/{id}/runs/wait - Execute query (synchronous) GET http://localhost:2024/ok - Health check 

Used for serving evaluation and dataset data from HuggingFace:

GET /api/evaluation/metrics - RAGAS metrics summary GET /api/evaluation/detailed/[retriever] - Per-query evaluation results GET /api/datasets/manifest - Ingestion manifest GET /api/datasets/info - Dataset metadata GET /api/sources?offset&length&search - Source documents browser GET /api/testset?offset&length&search - Golden testset browser 

All data is fetched from real sources with zero simulated data:

• Query responses: LangGraph Server API (real-time RAG execution)
• Evaluation metrics: HuggingFace Dataset Viewer API (dwb2023/gdelt-rag-evaluation-metrics)
• Source documents: HuggingFace Dataset Viewer API (dwb2023/gdelt-rag-sources-v2)
• Golden testset: HuggingFace Dataset Viewer API (dwb2023/gdelt-rag-golden-testset-v2)
• Dataset metadata: Static metadata (matches HuggingFace datasets)
• Ingestion manifest: Static provenance data (SHA-256 fingerprints)

Copy .env.local.example to .env.local and configure:

cp .env.local.example .env.local

Required Variables:

Optional Variables:

Note: Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

For the query console to work, you need the LangGraph Server running:

# Clone the backend repository (sibling directory) cd .. git clone https://github.com/aie8-cert-challenge/gdelt-knowledge-base.git cd gdelt-knowledge-base # Configure backend environment (see backend README) # Then start the LangGraph server langgraph dev

The backend will be available at http://localhost:2024. Verify with:

curl http://localhost:2024/ok

• Framework: Next.js 16.0.0 (App Router, React 19)
• Language: TypeScript (strict mode, ES2017 target)
• Styling: Tailwind CSS 4.x
• UI Components: Radix UI primitives via shadcn/ui (19 components)
• State Management: TanStack React Query v5 (caching, background refetching)
• Icons: Lucide React
• Charts: Recharts (bar charts, radar charts)
• Forms: React Hook Form + Zod validation
• Notifications: Sonner (toast notifications)
• Error Handling: React Error Boundary

• Framework: LangGraph 0.6.7 + LangChain 0.3.19
• LLM: OpenAI GPT-4.1-mini (temperature=0)
• Embeddings: text-embedding-3-small (1536 dims)
• Vector Store: Qdrant (cosine distance)
• Retrieval: 4 strategies (naive, BM25, ensemble, cohere_rerank)
• Evaluation: RAGAS 0.2.10 (pinned)

• npm run dev - Start development server
• npm run build - Build for production
• npm start - Start production server
• npm run lint - Run ESLint
• npm test - Run integration tests (Playwright)
• npm run test:ui - Run tests in interactive UI mode
• npm run test:headed - Run tests with visible browser
• npm run test:debug - Run tests in debug mode
• npm run test:report - View test results report

This project uses Playwright for end-to-end integration testing.

Prerequisites:

# Install Playwright browsers (first time only) npx playwright install chromium # Start the dev server (in another terminal) npm run dev

Run Tests:

# Headless mode (CI) npm test # Interactive UI mode (recommended for development) npm run test:ui # Watch execution in browser npm run test:headed

• ✅ Query Console - Query submission, history, backend integration
• ✅ Evaluation Dashboard - Metrics loading, charts, drill-down modal
• ✅ Datasets Page - Dataset metadata, manifests, fingerprints
• ✅ Backend Health - Real-time status monitoring, troubleshooting

See tests/README.md for detailed documentation.

The easiest way to deploy this Next.js app is using the Vercel Platform:

1. Push your code to a Git repository (GitHub, GitLab, or Bitbucket)
2. Import your repository on Vercel
3. Vercel will automatically detect Next.js and configure the build settings
4. Click "Deploy" and your app will be live!

For more details, check out the Next.js deployment documentation.

• Automatic HTTPS
• Global CDN
• Serverless functions
• Automatic deployments on git push
• Preview deployments for pull requests

• The app uses the Next.js App Router with TypeScript
• Components are located in the components/ directory
• UI components use shadcn/ui (Radix UI primitives)
• Styling is done with Tailwind CSS
• The app supports dark/light mode via next-themes

• Next.js Documentation - Learn about Next.js features and API
• Learn Next.js - Interactive Next.js tutorial
• Tailwind CSS Documentation - Utility-first CSS framework
• shadcn/ui Documentation - Re-usable components built with Radix UI

This project is private.