AI Chatbot Integration: Architecture & Design

Integrating an AI Chatbot into a static portfolio site presents a unique challenge: how do we provide a highly interactive, dynamic experience without compromising security or performance?

This document outlines my design decisions for building and integrating an AI Chatbot into this Astro portfolio.

1. The Core Objectives

When I set out to build this integration, I had a few non-negotiable requirements:

• Security: API keys (specifically for Google Gemini) must never be exposed to the client.
• Performance: The chat widget should not block the main thread or degrade the Core Web Vitals of the portfolio.
• Aesthetic: The chatbot must seamlessly blend into the dark-mode exclusive, Nord theme of the portfolio. It shouldn’t look like an embedded third-party iframe.

2. Architectural Choices

To meet these objectives, I designed a hybrid architecture using Astro, React, and Cloudflare Pages Functions.

The Frontend (React + Tailwind)

I chose React for the chat widget because of its robust state management. The chatbot needs to maintain conversational history, handle loading states while waiting for the AI response, and manage UI interactions (like opening and closing the chat window).

The component is styled using Tailwind CSS, pulling directly from our existing .theme-nord variables.

The Backend (Cloudflare Pages Functions)

Since this portfolio is hosted on Cloudflare Pages, we can leverage Cloudflare Functions to create serverless API endpoints. This is the crucial security layer.

Instead of the React frontend calling the Gemini API directly, it calls our Cloudflare Function. The Function securely holds the GEMINI_API_KEY, makes the request to Google, and proxies the response back to the client.

3. High-Level Data Flow

Here is how a single chat interaction flows through the system:

1. User Input: The visitor types a message in the React chat widget and hits send.
2. Client Request: The React component sends a POST request to our local API route (e.g., /api/chat).
3. Serverless Proxy: The Cloudflare Function intercepts the /api/chat request.
4. AI Processing: The Function securely appends the GEMINI_API_KEY and forwards the conversation history to the Google Gemini API.
5. Response: Gemini returns the generated text to the Cloudflare Function.
6. Client Update: The Function returns the text to the React component, which updates the UI.

4. Next Steps

With the architecture solidified, the next phase is to build the backend infrastructure: configuring the Cloudflare Function and securely connecting it to the Gemini API.