## AI-Powered Order & Returns Support Bot This is a small full-stack demo that mimics an Amazon-style customer support bot for orders and returns. It uses: - **React** frontend with a modern chat UI - **Express** backend - **Groq** for AI-generated responses - **Supabase** to store **all chat history** (user and bot messages) - **Dummy order/return data** to simulate real lookups The bot can answer questions like: - **"Where is my order?"** - **"What is the status of ORDER-1001?"** - **"How do I return an item?"** - **"What’s the status of my return RETURN-5001?"** ### 1. Project structure - `server/` - `index.js`: Express API, calls Groq, logs to Supabase - `dummyData.js`: In-memory dummy orders/returns and lookup helpers - `package.json`: Server dependencies - `client/` - `index.html`: Vite entry - `src/main.jsx`: React entry - `src/App.jsx`: Chat UI - `src/styles.css`: Styling - `.env.example`: Example environment variables ### 2. Environment variables Create a `.env` file **in the project root** (same folder as this `README.md`) based on `.env.example`: ```bash cp .env.example .env ``` Fill in: - **`SUPABASE_URL`**: Your Supabase project URL (e.g. `https://xyzcompany.supabase.co`) - **`SUPABASE_SERVICE_ROLE_KEY`**: Your **service role** key (keep this secret; only used on the server) - **`GROQ_API_KEY`**: Your Groq API key > Do **not** commit the real `.env` file or your real keys to version control. ### 3. Supabase table setup Create a table called `chat_messages` in Supabase with (at least) these columns: - **`id`**: `uuid`, primary key, default `uuid_generate_v4()` (or use Supabase default) - **`conversation_id`**: `text` (or `uuid`) – groups messages into conversations - **`role`**: `text` – e.g. `"user"` or `"assistant"` - **`content`**: `text` – the full message text - **`metadata`**: `jsonb`, nullable – optional extra context (e.g. tools context, errors) - **`created_at`**: `timestamptz`, default `now()` You can generate a simple SQL migration like: ```sql create table if not exists public.chat_messages ( id uuid primary key default gen_random_uuid(), conversation_id text not null, role text not null, content text not null, metadata jsonb, created_at timestamptz not null default now() ); ``` ### 4. Installing dependencies From the project root: ```bash cd server npm install cd ../client npm install ``` ### 5. Running the app In one terminal, start the **server**: ```bash cd server npm run start ``` By default it listens on `http://localhost:4000`. In another terminal, start the **React client**: ```bash cd client npm run dev ``` Vite will show a local URL (usually `http://localhost:5173`). The client is configured to proxy `/api` calls to `http://localhost:4000`. ### 6. How the backend works - `POST /api/chat` - Accepts `{ message, conversationId? }` - If `conversationId` is missing, a new one is generated - Logs the **user message** into `chat_messages` - Fetches recent history for this `conversationId` from Supabase - Uses simple helpers from `dummyData.js` to: - Try to resolve an **order** from the text (`ORDER-1001`, etc.) - Try to resolve a **return** (`RETURN-5001`, etc.) - Sends conversation + JSON order/return context to **Groq** (OpenAI-compatible API) - Logs the **assistant response** into `chat_messages` - Responds with `{ conversationId, reply, toolsContext }` - `GET /api/history/:conversationId` - Returns all messages for that conversation from Supabase, ordered by `created_at` - `GET /api/health` - Simple health check – shows whether Supabase and Groq are configured. ### 7. How the frontend works The React app in `client/src/App.jsx`: - Maintains local `messages`, `conversationId`, `input`, and loading state. - When you send a message: - It **optimistically** adds the user message to the UI. - Calls `POST /api/chat`. - Appends the bot’s response when it returns. - When there is a `conversationId`: - It fetches the full history via `GET /api/history/:conversationId` and renders it. - Shows a **typing indicator** while the backend is generating a response. - Provides quick-start example prompts for: - “Where is my order?” - “What is the status of ORDER-1001?” - “How do I return an item?” - “What’s the status of my return RETURN-5001?” ### 8. Dummy data behavior Dummy data is defined in `server/dummyData.js`: - A few orders: `ORDER-1001`, `ORDER-1002`, `ORDER-1003` - A few returns: `RETURN-5001`, `RETURN-5002` - Simple helpers: - Try to extract order/return IDs from the user’s text. - Look up the order/return and pass structured JSON to the model. This makes the bot feel like it’s doing **real order lookups** while staying fully local and safe. ### 9. Notes on keys and security - Always keep Supabase **service role keys** and Groq API keys on the **server only**. - Use environment variables and **never** hardcode real keys into the codebase. - The example `.env.example` exists just to show names; replace with your own values locally. # agentchatbot