VolleyTransfers.ai

AI-assisted recruiting intelligence tool for NCAA Division I women's volleyball coaches.

Overview

VolleyTransfers.ai helps coaches research currently rostered D1 players and identify potential transfer or recruiting targets. The system uses structured filtering, natural language search (RAG), and LLM-powered summaries—all strictly grounded in existing database records.

Tech Stack

• Backend: Node.js + TypeScript + Express
• Database: PostgreSQL + pgvector
• Frontend: Next.js 14 (App Router) + TypeScript + Tailwind CSS
• AI: Anthropic Claude Haiku (configurable to OpenAI GPT-4o mini)
• Data: 2025 season only (pre-populated mock data)

Project Structure

volleytransfers.ai/
├── backend/               # Express REST API
│   ├── src/
│   │   ├── db/           # Database client, migrations, seed scripts
│   │   ├── routes/       # API endpoints
│   │   ├── services/     # Business logic (PlayerService, etc.)
│   │   └── index.ts      # Express server
│   └── package.json
├── frontend/             # Next.js UI
│   ├── app/              # App Router pages
│   └── package.json
├── shared/               # Shared TypeScript types
│   └── src/types.ts
├── docker-compose.yml    # PostgreSQL + pgvector
└── package.json          # Root workspace config

Prerequisites

Before running the application, make sure you have installed:

• Node.js (v18 or higher): Download here
• Docker Desktop: Download here
  • Required for running PostgreSQL with pgvector extension

Setup Instructions

1. Install Dependencies

First, verify Node.js is installed:

node --version  # Should show v18.x or higher
npm --version

If Node.js is not installed, download and install it from nodejs.org, then return to this step.

Install all project dependencies:

npm install

This will install dependencies for the root workspace, backend, frontend, and shared packages.

2. Start the Database

Make sure Docker Desktop is running, then start PostgreSQL:

npm run db:up

This will:

• Pull the ankane/pgvector Docker image
• Start PostgreSQL on port 5432
• Enable the pgvector extension for vector similarity search

3. Configure Environment Variables

Copy the example environment file:

cp backend/.env.example backend/.env

Edit backend/.env and add your API key:

# For Anthropic Claude (recommended - cheaper)
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_actual_api_key_here

# OR for OpenAI (alternative)
LLM_PROVIDER=openai
OPENAI_API_KEY=your_actual_api_key_here

Note: RAG and AI features are implemented in Phase 2. For Phase 1, the API keys are not required—the app will work without them.

4. Run Database Migrations

Create the database schema:

npm run db:migrate

This creates tables for schools, players, season_stats, watch_list, and embeddings.

5. Seed the Database

Generate mock data (~30 schools, ~450 players, 2025 stats):

npm run db:seed

6. Start the Development Servers

Start both backend and frontend simultaneously:

npm run dev

Or start them separately:

# Terminal 1: Backend (port 3001)
npm run dev:backend

# Terminal 2: Frontend (port 3000)
npm run dev:frontend

7. Access the Application

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

API Endpoints

Example API Calls

Filter players by position:

curl "http://localhost:3001/api/players?position=OH&limit=10"

Filter by conference and graduation year:

curl "http://localhost:3001/api/players?conference=SEC&graduationYear=2027"

Get single player:

curl "http://localhost:3001/api/players/<player-id>"

Add to watch list:

curl -X POST http://localhost:3001/api/watch-list \
  -H "Content-Type: application/json" \
  -d '{"playerId": "<player-id>", "notes": "Strong offensive player"}'

Database Management

Stop the database:

npm run db:down

Re-seed the database:

npm run db:seed

Reset everything:

npm run db:down
npm run db:up
npm run db:migrate
npm run db:seed

Troubleshooting

Database connection errors:

• Make sure Docker Desktop is running
• Check if PostgreSQL container is healthy: docker ps
• Try restarting: npm run db:down && npm run db:up

Port conflicts:

• Backend uses port 3001, frontend uses port 3000
• Check if ports are in use: lsof -i :3000 or lsof -i :3001
• Kill conflicting processes or change ports in .env and package.json

Node.js not found:

• Install Node.js from nodejs.org
• Restart your terminal after installation
• Verify with node --version

Project Constraints

• Single-user: No multi-user authentication
• Local-only: Not designed for production deployment yet
• 2025 season only: No historical data tracking
• Read-only data: No data scraping or updates
• Research tool: Not for outreach or NCAA compliance automation

License

Internal tool for research purposes.