TLOChatBot

A Next.js chat application that connects a Genkit-powered AI assistant (Google/Genkit) with a Firebase-backed knowledge base. This repository provides a polished chat UI, Genkit flows for generating and regenerating AI responses, and a seed script to upload local knowledge-base files into Firebase Storage and Firestore.

This README explains how the project is structured and gives step-by-step reproduction instructions so you can run the app locally, seed the knowledge base, and run the AI flows.

What this repo is

TLOChatBot is a Next.js (App Router) front-end for a Genkit-based conversational assistant. Key features:

• Chat UI with message bubbles, attachments, and regenerate functionality.
• Genkit flows that call the Google/Genkit plugin to generate responses.
• A simple knowledge-base implementation: local files are uploaded to Firebase Storage and indexed in Firestore by the seed script.
• Server actions (Next.js) that validate input with Zod, call Genkit flows, and return formatted responses to the UI.

Quick architecture overview

• Next.js (app) — UI and server actions (entry at src/app/page.tsx).
• Genkit + Google AI — configured in src/ai/genkit.ts; flows live in src/ai/flows/.
• Firebase (client SDK) — initialization in src/lib/firebase.ts; Storage + Firestore host knowledge-base files and metadata.
• Seed script — scripts/seed-knowledge-base.ts uploads local files to Storage and creates Firestore documents.
• UI components — src/components/* (chat interface, input, header, message bubbles, and UI atoms under src/components/ui).

Prerequisites

• Node.js (recommended 18+).
• npm (or a compatible package manager).
• A Firebase project with Firestore and Storage configured.
• Google Cloud credentials or API key for the Google generative AI access (Gemini) if you plan to run Genkit flows that call Google.

Environment variables

Create a .env file in the repository root (do NOT commit real credentials). Example:

# Firebase web SDK configuration (from Firebase Console -> Project settings -> Your apps)
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_DATABASE_URL=https://your_project.firebaseio.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# Google / Genkit credentials (one of these approaches)
# Option 1: API key
GOOGLE_API_KEY=your_google_api_key

# Option 2: Service account JSON (recommended for server-side / admin operations)
# Set this to an absolute path on the machine where Genkit or server-side code runs
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# Optional: used by local Genkit code
GENKIT_ENV=dev

Notes:

• The app uses the client Firebase SDK; the seed script also uses the client SDK by default. For production or privileged operations, use the Firebase Admin SDK with a service account.
• If you use GOOGLE_APPLICATION_CREDENTIALS, ensure the service account has the required permissions for the Google generative AI APIs.

Quick start (copy/paste)

1. Install dependencies

npm install

2. Create .env (see example above) and fill with your Firebase and Google credentials.

3. Start the Next.js dev server (the project config sets port 9002):

npm run dev
# open http://localhost:9002

4. (Optional) Run Genkit locally to activate flows that the server actions call:

npm run genkit:dev

5. (Optional) Seed the knowledge base from local files in src/knowledge-base/:

npm run db:seed

6. Interact with the chat UI in the browser and test responses.

Knowledge base seeding

Place any .txt or .docx files into src/knowledge-base/ (create that folder if required). The seed script will:

• Read local files.
• Upload each file to Firebase Storage under a knowledge-base/ path.
• Create a Firestore document (collection: knowledgeBaseFiles) with metadata for each uploaded file.

Run the seed script:

npm run db:seed

Implementation notes:

• The seed script uses the Firebase client SDK configured from NEXT_PUBLIC_... environment variables. If you encounter permission errors, either adjust Firebase Storage/Firestore rules or switch to using the Firebase Admin SDK with a service account.
• .docx extraction uses mammoth in the flow to pull plaintext.

Genkit and AI flows

• Configuration: src/ai/genkit.ts — sets up Genkit runtime and configures the @genkit-ai/googleai plugin.
• Chat flow: src/ai/flows/chat-flow.ts — builds prompts, fetches knowledge-base content from Firestore + Storage, and asks the model to produce a Markdown response.
• Regeneration: src/ai/flows/regenerate-ai-response.ts — small flow to re-evaluate or improve a previous response.

To develop or test flows locally, keep the Genkit runtime running (npm run genkit:dev). Genkit will execute the TypeScript flow definitions in src/ai/ and expose them to server actions.

Model and plugin details:

• The repository includes @genkit-ai/googleai and defaults to a Gemini-class model in genkit.ts (e.g., googleai/gemini-2.0-flash). Change the model name in src/ai/genkit.ts if needed.

Frontend behavior and server actions

• UI: src/components/chat-interface.tsx — wires the chat UI to server-side handlers.
• Input + attachments: src/components/chat-input.tsx — attachments are converted to data URIs and voice input uses the Web Speech API where supported.
• Server actions: src/lib/actions.ts — validate requests with Zod (src/lib/ai-schemas.ts), call the Genkit flows, and return structured responses.

Deployment

Recommended options:

• Vercel: easiest for Next.js — connect the repository, set the environment variables in the dashboard, and deploy. Ensure Genkit flows are available (you may run Genkit as a separate service or adapt flows to a server environment).
• Firebase Hosting + Cloud Run: you can build the app and serve static assets via Firebase Hosting with rewrites to Cloud Run for server-side behavior.
• Any host: build and run with:

npm run build
npm run start

Important deployment notes:

• Genkit flows may require a running Genkit runtime or alternate server-side integration for the model calls in production.
• Keep credentials secure: do not store private keys or service account JSON in the repo.

File map (important files)

• package.json — scripts and dependencies (dev port: 9002).
• src/app/page.tsx — app entry that mounts the chat UI.
• src/ai/genkit.ts — Genkit runtime and plugin configuration.
• src/ai/flows/chat-flow.ts — main chat flow.
• src/ai/flows/regenerate-ai-response.ts — regenerate flow.
• src/lib/firebase.ts — Firebase initialization.
• scripts/seed-knowledge-base.ts — seed script to upload local KB files.
• src/components/chat-interface.tsx, src/components/chat-input.tsx — frontend chat behavior.

Troubleshooting

• Error: Firebase permission denied when running db:seed — check Storage and Firestore rules or run an Admin-based seed.
• Genkit flow errors or missing responses — ensure npm run genkit:dev is running if flows are executed locally, and check src/ai/genkit.ts for correct credentials.
• Model authorization errors — verify GOOGLE_API_KEY or GOOGLE_APPLICATION_CREDENTIALS and their permission scopes.

Contributing

If you'd like to extend the project:

• Add flows under src/ai/flows/ (follow Genkit flow patterns).
• Add UI components under src/components/ or src/components/ui/.
• Update the seed script if you want different indexing behavior or to use the Admin