Vendor Companion Chatbot

This project describes a Google Cloud Platform (GCP) architecture for a web application that acts as a conversational assistant for product vendors. The chatbot uses the Gemini model to capture business needs, guide the vendor through requirements, and produce a structured JSON export that other systems can ingest.

What the chatbot does

• Provides a friendly web UI where vendors can describe the product they need.
• Uses Gemini to ask clarifying questions, summarize vendor intent, and map it to structured fields.
• Proactively captures the vendor profile (company, contact, email, category, timeline, budget, notes) during the chat and fills the form for the user.
• Generates a JSON payload containing product specs, constraints, and contact information for downstream teams.
• Lets the vendor review, tweak, and export the JSON directly from the app.

Key architecture choices on GCP

• Frontend on Cloud Run – A lightweight web frontend (for example a Next.js or React SPA) is containerized and deployed to Cloud Run for automatic scaling and HTTPS out of the box.
• API Gateway + Cloud Run service – Vendor conversations and Gemini prompts are handled by a backend service on Cloud Run that exposes REST endpoints through API Gateway for authenticated access.
• Gemini access via Vertex AI – The backend calls Vertex AI’s Gemini APIs to craft prompts, maintain conversation context, and receive the structured responses that seed the JSON document.
• Firestore (Native mode) – Stores vendor sessions, chat transcripts, and intermediate JSON drafts so users can return and continue where they left off.
• Cloud Storage – Keeps exported JSON bundles and optional attachments (e.g., vendor reference documents) for longer-term retention and download links.
• Pub/Sub event bus – When a vendor finalizes an export, a message is published so downstream procurement or ERP adapters can act asynchronously without slowing the conversation flow.
• Cloud Functions adapters – Lightweight Cloud Functions subscribe to Pub/Sub topics to push JSON exports into other systems or notify stakeholders via email or chat.
• Cloud Build & Artifact Registry – Source code is built and container images are stored in Artifact Registry. Cloud Build triggers on main-branch commits to redeploy frontend and backend automatically.
• Cloud Monitoring & Logging – Centralized dashboards and alerting capture latency, prompt failures, and usage analytics to tune the experience.

Intended flow

1. A vendor opens the web app served through Cloud Run and authenticates (Google Identity Platform or Firebase Auth).
2. The frontend calls the backend API through API Gateway. The backend keeps session context in Firestore and crafts prompts for Gemini via Vertex AI.
3. Gemini responses are post-processed into a structured schema; the vendor can preview and edit.
4. When the vendor confirms, the JSON export is written to Firestore and Cloud Storage, then an event is pushed to Pub/Sub.
5. Cloud Functions or other subscribers propagate the export to ERP/CRM tools, while confirmation is shown to the vendor.

Why this setup

This architecture stays cloud-native, keeps the operational burden low, and still offers flexibility to bolt on downstream integrations. Automated scaling on Cloud Run handles spiky vendor traffic, Firestore gives real-time updates without heavy ops work, and Vertex AI’s Gemini model delivers the conversational intelligence. Together they deliver a simple experience for vendors while making the export ready for enterprise workflows.

---

Implementation overview

Path	Description
server/	Express + TypeScript API that talks to Vertex AI (Gemini), Firestore, and Cloud Storage. Handles session lifecycle, chat history, and JSON exports.
web/	Vite/React single-page app that lets a vendor chat, fill in profile metadata, and preview/download the structured JSON brief.

The backend expects the same environment variables that are already present in .env (PROJECT_ID, LOCATION, GOOGLE_APPLICATION_CREDENTIALS, MODEL_FLASH, MODEL_PRO, FIRESTORE_DATABASE_ID, MEDIA_BUCKET, VITE_API_URL, etc.). The frontend inherits those values automatically because vite.config.ts loads env files from the repository root.

Agentic profile capture

• The chat system prompt instructs Gemini to gather missing vendor profile attributes. When details are missing, it asks pointed follow-up questions before moving on.
• After each model response, the backend runs a lightweight structured-extraction prompt that returns candidate profile fields. Only blank fields are filled, so any manual edits remain untouched.
• The React profile form auto-populates with new facts and surfaces a toast like “Gemini captured company name, budget” so the user can confirm or edit before exporting.

Prerequisites

• Node.js 20+ and npm 10+.
• A Google Cloud project with Vertex AI, Firestore (Native mode), and Cloud Storage enabled.
• Service-account credentials pointed to by GOOGLE_APPLICATION_CREDENTIALS (already referenced in .env).
• Optional: A Cloud Storage bucket name in MEDIA_BUCKET if you want exports to persist in GCS.

Local development

# Backend
cd server
npm install
npm run dev

# Frontend (in a new shell)
cd web
npm install
# VITE_API_URL defaults to http://localhost:8080 but will respect the value in ../.env
# VITE_DEV_PORT controls the Vite dev port (default 5175)
npm run dev

The API listens on localhost:${PORT} (defaults to 8080). The Vite dev server runs on port 5175 by default (override with VITE_DEV_PORT) and proxies /api/* calls back to the API, so CORS is handled transparently in dev.

API surface

Method & Path	Description
POST /api/sessions	Create a new vendor session (optionally seed profile fields).
GET /api/sessions/:id	Fetch the latest transcript/profile/exports for a session.
PUT /api/sessions/:id/profile	Update vendor metadata (company, contact, constraints).
POST /api/chat	Append a vendor utterance and get the Gemini reply.
POST /api/export	Ask Gemini to condense the conversation into the JSON schema; optionally persists to Cloud Storage.
GET /healthz	Lightweight readiness probe.

The export schema includes vendor profile data, hard/soft requirements, compliance needs, integration targets, and Gemini’s confidence score.

UI snapshot

The React SPA keeps the experience simple for the vendor:

• Left pane: conversational transcript plus a textarea to nudge Gemini.
• Right pane: vendor profile form, export controls, and live JSON preview.
• Toast notifications surface profile saves, export success, and API errors.

All state is stored in Firestore/Cloud Storage via the API, so refreshing the page will reload the existing session.