A full-stack AI-powered customer support agent that automates e-commerce refund processing. The system uses an LLM (via Ollama) with a tool-calling architecture to evaluate refund eligibility against configurable business policies, check for fraud, and make automated decisions — all while maintaining a complete audit trail.
- AI Chat Interface — Natural language conversational support with the AI agent, including voice input (SpeechRecognition) and voice output (SpeechSynthesis)
- Admin Dashboard — Real-time analytics, refund management, policy configuration, and audit log viewer with 4 tabbed views
- Tool-Calling Architecture — 13 registered tools the LLM can invoke to query customers, orders, policies, fraud scores, and create refund requests
- Policy Engine — 9 configurable refund policies covering eligibility, exclusions, and fraud detection that the AI agent evaluates in real-time
- Audit Logs — Every agent decision is logged with full tool-call history, decision path, token usage, and execution duration
- Voice Input/Output — Browser-native speech recognition and text-to-speech for hands-free customer interaction
- Rule-Based Fallback — When Ollama is unavailable, the system falls back to a deterministic rule-based agent that still calls real tools
- Role-Based Access — Admin and customer roles with scoped API access
- Seeded Demo Data — 15 customers, 30 products, 50 orders, 9 policies, and sample conversations pre-loaded
┌──────────────────────────────────────────────────────────────┐
│ Next.js 16 Frontend (Port 3000) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Login │ │ Chat │ │ Refunds │ │ Admin Dashboard │ │
│ │ Page │ │ Page │ │ Page │ │ (4 tabs) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───────┬──────────┘ │
│ └─────────────┴────────────┴────────────────┘ │
│ Zustand + TanStack Query │
└──────────────────────────┬───────────────────────────────────┘
│ HTTP (XTransformPort=8000)
┌──────────────────────────▼───────────────────────────────────┐
│ FastAPI Backend (Port 8000) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Auth │ │ Chat │ │ Refunds │ │ Customers │ │
│ │ (JWT) │ │ (Agent) │ │ CRUD │ │ CRUD │ │
│ └──────────┘ └────┬─────┘ └──────────┘ └──────────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ AI Agent │ │
│ │ (13 tools) │ │
│ └───────┬───────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ ┌──────▼──────┐ ┌───▼────┐ ┌────▼────┐ │
│ │ SQLite │ │ Ollama │ │ Tools │ │
│ │ Database │ │(LLM) │ │ Layer │ │
│ └─────────────┘ └────────┘ └─────────┘ │
└──────────────────────────────────────────────────────────────┘
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16, TypeScript | React SPA with App Router |
| UI Components | shadcn/ui, Tailwind CSS 4 | Professional UI components and styling |
| State Management | Zustand | Client-side auth and chat state |
| Data Fetching | TanStack Query | Server-state management with caching |
| Animations | Framer Motion | Smooth page transitions and UI animations |
| Backend | FastAPI, Python 3.12 | REST API with async support |
| ORM | SQLAlchemy | Database models and queries |
| Database | SQLite | Lightweight embedded database |
| AI/LLM | Ollama (llama3.1) | Local LLM with tool-calling support |
| Authentication | python-jose (JWT) | Stateless token-based auth |
| HTTP Client | httpx | Async HTTP calls to Ollama |
# Clone the repository
git clone <repo-url> && cd <project-dir>
# Start all services
docker-compose up -d
# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# Ollama: http://localhost:11434# 1. Start Ollama and pull the model
ollama pull llama3.1
# 2. Start the backend
cd mini-services/refund-backend
pip install -r requirements.txt
python -m uvicorn main:app --host 0.0.0.0 --port 8000
# 3. Start the frontend (in a separate terminal)
cd ../..
npm install
npm run devThe backend auto-creates tables and seeds data on startup.
| Role | Password | Customer | |
|---|---|---|---|
| Admin | admin@shopmart.com |
admin123 |
— |
| Customer | sarah.johnson@email.com |
password1 |
CUST-001 (Platinum) |
| Customer | bob.martinez@email.com |
password2 |
CUST-002 (Gold) |
| Customer | carol.williams@email.com |
password3 |
CUST-003 (Gold) |
| Customer | david.brown@email.com |
password4 |
CUST-004 (Gold) |
| Customer | eva.chen@email.com |
password5 |
CUST-005 (Silver) |
.
├── docs/ # Documentation
│ ├── README.md
│ ├── ARCHITECTURE.md
│ ├── API.md
│ ├── TESTING.md
│ ├── DEPLOYMENT.md
│ ├── SECURITY.md
│ ├── DEMO-SCENARIOS.md
│ └── LOOM_SCRIPT.md
├── mini-services/
│ └── refund-backend/
│ ├── main.py # FastAPI app entry, CORS, lifespan
│ ├── config.py # Settings (DB URL, Ollama, JWT)
│ ├── database.py # SQLAlchemy engine, session, Base
│ ├── models.py # 10 ORM models
│ ├── schemas.py # Pydantic request/response schemas
│ ├── agent.py # AI agent: Ollama loop + rule fallback
│ ├── tools.py # 13 tool functions + TOOL_DEFINITIONS
│ ├── seed.py # Demo data (15 customers, 50 orders, etc.)
│ ├── requirements.txt # Python dependencies
│ ├── refund.db # SQLite database (auto-created)
│ └── routes/
│ ├── __init__.py
│ ├── auth.py # POST /auth/login, GET /auth/me
│ ├── chat.py # POST /chat
│ ├── refunds.py # GET/POST /refunds
│ ├── customers.py # GET /customers
│ ├── orders.py # GET /orders
│ ├── policies.py # GET/PUT /policies
│ └── logs.py # GET /logs, /logs/agent-executions
├── src/
│ ├── app/
│ │ ├── layout.tsx # Root layout with metadata
│ │ ├── page.tsx # Main SPA entry with view switching
│ │ ├── globals.css # Tailwind CSS
│ │ └── api/route.ts # API gateway proxy
│ ├── components/
│ │ ├── login-page.tsx # Login form with demo hints
│ │ ├── chat-page.tsx # AI chat with voice, tool badges
│ │ ├── refund-status-page.tsx # Customer refund history
│ │ ├── admin-dashboard.tsx # Admin panel (4 tabs)
│ │ ├── layout-header.tsx # Navigation header
│ │ └── ui/ # shadcn/ui components
│ └── lib/
│ ├── types.ts # TypeScript interfaces
│ ├── store.ts # Zustand store
│ ├── api.ts # API client module
│ ├── db.ts # Prisma client (unused by backend)
│ └── utils.ts # Utility functions
├── package.json
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
└── worklog.md # Development worklog
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /health |
No | Health check with Ollama connectivity |
| POST | /auth/login |
No | Login and receive JWT token |
| GET | /auth/me |
Yes | Get current user info |
| POST | /chat |
Yes | Send message to AI agent |
| GET | /refunds |
Yes | List refunds (scoped by role) |
| GET | /refunds/{id} |
Yes | Get refund details |
| POST | /refunds |
Yes | Create refund request |
| GET | /customers |
Admin | List all customers |
| GET | /customers/{id} |
Admin | Get customer details |
| GET | /orders |
Yes | List orders (scoped by role) |
| GET | /orders/{id} |
Yes | Get order details |
| GET | /policies |
Admin | List all refund policies |
| PUT | /policies/{id} |
Admin | Update a refund policy |
| GET | /logs |
Admin | List audit logs (paginated) |
| GET | /logs/agent-executions |
Admin | List agent executions |
| GET | /logs/agent-executions/{id} |
Admin | Get execution detail with tool history |
Full API documentation with request/response schemas: API.md
The system includes 8 pre-designed demo scenarios covering all decision paths:
- Standard Approval — Eligible customer, delivered order, within refund window
- Outside Refund Window — Order delivered > 30 days ago
- High Fraud Score Denial — Customer with fraud score above 0.7 threshold
- Excessive Refunds Denial — Customer exceeding quarterly refund limit
- Digital Product Denial — Attempting to refund a non-refundable digital product
- Clearance Item Denial — Attempting to refund a clearance item
- Undelivered Order Denial — Requesting refund for a shipped (not delivered) order
- Policy Engine Modification — Admin changes a policy and retries a previously denied request
See DEMO-SCENARIOS.md for detailed walkthroughs.
MIT