🏀 Hooper - Basketball Chatbot

A full-stack basketball chatbot powered by Ollama and React, featuring real-time streaming responses and a modern chat interface.

🎯 Features

• Basketball-Focused AI: Powered by local Ollama LLM with custom basketball personality
• Real-Time Streaming: Live token-by-token response streaming
• Modern Chat UI: Responsive design with smooth animations
• Comprehensive Testing: 80%+ test coverage with Jest and Vitest
• Clean Architecture: Following software engineering best practices

🏗️ Architecture

Backend (Express.js)

• Layered Architecture: Clear separation of concerns
• Ollama Integration: Local LLM with streaming responses
• RESTful API: Clean endpoints with proper error handling
• Comprehensive Testing: Jest test suite with mocking

Frontend (React + Vite)

• Component-Based Design: Reusable, testable components
• Modern React Patterns: Hooks, controlled components, event handling
• Responsive Design: Mobile-first approach
• Vitest Testing: Component and integration tests

🚀 Quick Start

Prerequisites

• Node.js 18+
• Ollama installed and running
• Model pulled: ollama pull llama3

Development Setup

1. Clone and setup

git clone <repository>
cd Hooper

2. Setup Backend

cd server
npm install
npm run dev

3. Setup Frontend (in new terminal)

cd client
npm install
npm run dev

4. Start Ollama

ollama serve
ollama pull llama3

5. Open Application

• Frontend: http://localhost:3000
• Backend: http://localhost:3001
• Health Check: http://localhost:3001/health

🧪 Testing

Backend Testing

cd server
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Frontend Testing

cd client
npm test              # Run all tests
npm run test:ui       # UI test runner
npm run test:coverage # Coverage report

📁 Project Structure

/Hooper
├── server/                    # Backend (Express.js)
│   ├── services/             # Business logic
│   ├── utils/                # Utility functions
│   ├── tests/                # Jest test suite
│   └── index.js              # Main server file
├── client/                    # Frontend (React + Vite)
│   ├── src/
│   │   ├── components/       # React components
│   │   └── hooks/            # Custom hooks
│   ├── tests/                # Vitest test suite
│   └── vite.config.js       # Vite configuration
└── README.md                 # This file

🎨 Design Principles

Code-Level Design

• Use Good Names: Clear, descriptive variable and function names
• Make Data Meaningful: Proper data structures and types
• One Method/One Job: Single responsibility principle
• Don't Repeat Yourself: DRY principle with reusable functions
• Don't Hardcode: Configuration over hardcoded values

Interaction Patterns

• Demand-Pull: Client requests data when needed
• Data-Push: Server streams responses in real-time
• Callback Pattern: Event-driven component communication
• Typed Events: Type-safe message passing

Application Architecture

• Layered Architecture: Clear separation of concerns
• RESTful Communication: HTTP/REST for API endpoints
• Component Composition: Reusable React components
• Error Handling: Graceful failure management

🔧 Configuration

Environment Variables

# server/.env
PORT=3001
OLLAMA_URL=http://localhost:11434
MODEL_NAME=llama3
CLIENT_URL=http://localhost:3000

Ollama Setup

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve

# Pull the model
ollama pull llama3

📊 API Endpoints

Backend API

• GET /health - Health check
• POST /chat - Chat with Hooper (streaming response)
• GET /ollama/status - Ollama service status

Example Usage

// Chat with Hooper
const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Who is the best basketball player?' })
});

// Stream response
const reader = response.body.getReader();
// Handle streaming data...

🧪 Test Coverage

Backend Tests

• Unit Tests: Individual functions and methods
• Integration Tests: API endpoints with Supertest
• Mock Testing: External dependencies properly mocked
• Coverage: 80%+ for all business logic

Frontend Tests

• Component Tests: React components with user interactions
• Integration Tests: Component communication
• User Interaction Tests: Form handling, event simulation
• Coverage: 80%+ for all components

🚀 Deployment

Development

# Backend
cd server && npm run dev

# Frontend
cd client && npm run dev

Production

# Build frontend
cd client && npm run build

# Start backend
cd server && npm start