Welcome! This repository is an Nx-based monorepo containing full-stack applications, CLI indexers, and shared libraries demonstrating how to build modern, AI-enhanced web applications using LLMs and generative AI.
| Application | Source Code | Deploy URL | Description |
|---|---|---|---|
| Astra Document Summary | apps/astra-document-summary |
🚀 Live Demo | Next.js-based conversational AI assistant for document parsing and summarization. Supports PDF/DOCX file uploads or raw text inputs. |
| Astra Aviation RAG | apps/astra-aviation-rag |
🚀 Live Demo | Next.js-based conversational AI safety assistant. Queries NTSB aviation accident reports using RAG backed by a local HNSW vector index. |
| Astra Interview Assistant | apps/astra-interview-assistant |
🚀 Live Demo | Next.js-based conversational AI assistant simulating real-world job interviews with personalized feedback. |
Note
Experimental MCP Server: The Interview Assistant integrates with an experimental standalone NestJS server (apps/astra-mcp-server) via the Model Context Protocol (MCP). It uses the StreamableHTTPTransport to dynamically fetch mock frontend technical questions based on the user's selected difficulty level.
Important
Authentication & Session Isolation: For the optimal experience, log in to one application at a time. To switch between applications, log out of the current one first. This is because a custom shared domain has not been set up across the three deployments, and Clerk.js satellite domain configurations (to share sessions across distinct domains) are a paid Clerk Pro feature.
.png) |
.png) |
.png) |
|---|---|---|
| Initial View | Chatting with Astra Document Summary | Full Conversation History |
Ensure you have the following installed:
- Node.js (v18+)
- Google Cloud SDK (for Vertex AI authentication)
- Infisical CLI (for secrets management)
Authenticate your local environment to Vertex AI using Application Default Credentials (ADC):
gcloud auth application-default loginClone the repository and install the dependencies:
npm installIf you are managing your environment variables and API keys (Vertex AI, Clerk, Upstash Redis) using Infisical, all commands that access external services require secrets injection via the infisical run -- wrapper.
If you are running the Astra Aviation RAG app, build its local database index. Running the indexer requires Vertex AI credentials:
# Build the indexer CLI
npx nx build rag-indexer
# Run the indexer CLI (injecting secrets)
infisical run -- npx nx execute rag-indexerStart the Next.js development servers (secrets must be injected for dynamic routing, rate limiting, and model access):
-
Run Document Summary (Default port:
4300):infisical run -- npx nx dev astra-document-summary
-
Run Aviation RAG (Default port:
4400):infisical run -- npx nx dev astra-aviation-rag
-
Run Interview Assistant (Default port:
4500):infisical run -- npx nx dev astra-interview-assistant
-
Production Build & Start (if building static pages that require credentials):
infisical run -- npx nx build astra-document-summary infisical run -- npx nx start astra-document-summary
- apps/astra-document-summary: Next.js 15+ conversational AI web assistant.
- apps/astra-aviation-rag: Next.js 15+ conversational AI safety assistant.
- apps/astra-interview-assistant: Next.js 15+ conversational AI job interview practice assistant.
- apps/standalone/rag-indexer: NestJS CLI to index source reports to local HNSW vector stores.
- libs/chat-ui: Reusable React presentation components (Radix, Tailwind CSS).
- libs/chat-hooks: React hooks for chat logic, submission shortcuts, response streaming and stream decoding (
useDocumentSummary), and model-to-UI message mappings (useAviationChat). - libs/shared-types: Shared TypeScript API contracts.
- libs/shared-utils: Tailwind merging helpers, static prompts, and AI model configs.
- libs/rag: Shared LCEL search chains and vector indexes.
- libs/logger: Unified Pino logging wrapper.
| Library | Use Case |
|---|---|
ai (Vercel AI SDK Core) |
Unified provider-agnostic interface for text generation, embeddings, and tool calling. |
@ai-sdk/google-vertex |
Adapter for enterprise Google Cloud Vertex AI services. |
@ai-sdk/openai |
Adapter for OpenAI models (e.g. gpt-4o). |
@ai-sdk/react & @ai-sdk/rsc |
Frontend streaming hooks (useChat, useCompletion) and server action wrappers. |
@clerk/nextjs |
User authentication, session management, and page/route protection. |
@langchain/core |
Abstraction layer for LangChain LCEL sequences and output parsers. |
@langchain/google-vertexai |
Integration for Vertex AI models and vector embeddings in LangChain workflows. |
hnswlib-node |
C++ binder for extremely fast local Hierarchical Navigable Small World vector search. |
pino & pino-pretty |
Core high-performance logging suite. |
@upstash/redis & @upstash/ratelimit |
HTTP REST Redis client and sliding-window rate limiter for serverless Edge runtimes. |
Both web applications implement Next.js 16+ compliant proxy.ts Edge middleware files. They intercept incoming requests and execute a composed chain of:
- User Authentication (Clerk.js): Verifies user session and protects internal routes (like
/), automatically redirecting unauthenticated users to/sign-in. - CORS Handling: Cross-Origin resource settings for pre-flight requests on API paths.
- IP-based Rate Limiting: Sliding-window rate limit checks (5 requests per 10 seconds) powered by Upstash Redis on API paths.
- User-based Message Quotas: Enforces daily message quota limits (10 queries per day per authenticated user) powered by Upstash Redis on API paths.
- Security Headers: Standard response header protection (
X-Frame-Options: DENY,X-Content-Type-Options: nosniff,Referrer-Policy, etc.).
The proxy logic is encapsulated inside the shared workspace utility and exposed via the sub-path export @ai-enhanced-web-apps/shared-utils/middleware to keep Edge-only dependencies isolated, while Clerk-specific route checks run at the application level in proxy.ts.
We route all workspace logs through a unified logging pipeline powered by Pino:
- Development Mode: Output is colorized and pretty-printed using
pino-prettyto be highly readable. - Production Mode: Emitted as raw JSON lines optimized for ingestion by cloud log routing agents.
import { logger } from '@ai-enhanced-web-apps/logger';
// Standard structured log
logger.info({ route: '/api/chat' }, 'Processing query...');
// Logging errors with structured context
logger.error({ err: error }, 'RAG pipeline execution failed');- Generative AI Web Architecture: Transitioning from model-agnostic prompt setups to robust full-stack layouts separating UI and AI state cleanly.
- RAG Pipelines: Semantic chunking of PDF documents, compiling databases using local HNSWLib indexes, and injecting factual search results into prompts to ground generated responses.
- Autonomous Tool Loop: Triggering client-side UI updates (like live weather widgets) and database lookups dynamically through LLM tool/function calling schemas.
- Production Hardening: Securing APIs using rate limiters (Upstash Redis), mocking provider calls during test execution, and keeping tests isolated from external networks.
Nx commands can be prefixed with npx or the workspace package manager:
- Build a Project:
npx nx build astra-document-summary
- Run Unit & Integration Tests:
npx nx run-many -t test - Lint All Code:
npx nx run-many -t lint
This workspace and the applications within are inspired by the book Building AI-Enhanced Web Apps by Theo Despoudis, focusing on Google Vertex AI, Next.js, and the Vercel AI SDK.
This project is licensed under the MIT License.