# PitchProof — Server Setup

Local setup guide for the Laravel product app and its integrated local Python sidecar processes (Kokoro TTS + NLP Pitch Analysis) and Ollama.

**Related docs:** [SYSTEM_DESIGN_HLD_LLD.md](./SYSTEM_DESIGN_HLD_LLD.md)

---

## Architecture (local)

| Process | Default URL / port | Required for |
|---------|-------------------|--------------|
| Laravel (PHP) | `http://localhost:8080` | App UI, auth, scoring, persistence, local process orchestrations |
| Vite (HMR) | `http://localhost:5173` | Frontend assets in development |
| Queue worker | — | Avatar AI asset generation (`GenerateTrainingAiAssets`) |
| Integrated Python Subprocesses | Local Invocation | Kokoro ONNX TTS & NLTK VADER/Sentence-Transformers NLP calculations |
| Ollama | `http://127.0.0.1:11434` | Buyer roleplay, scripts, conversation critique |

There is **no external FastAPI backend dependency** required. The PHP application invokes the local Python runtime directly.

```mermaid
flowchart TD
  Browser --> Laravel
  Laravel --> DB[(SQLite / MySQL)]
  Laravel --> Ollama
  Laravel -->|Symfony Process| PythonTTS[scripts/tts_generate.py]
  Laravel -->|Symfony Process| PythonNLP[scripts/analyze_pitch.py]
  PythonTTS -->|Generates| Audio[.wav Audio]
  PythonNLP -->|Returns| Scoring[Sentiment & Sales Concepts JSON]
```

---

## Prerequisites

| Tool | Version / notes |
|------|-----------------|
| PHP | **8.2+** with common extensions (`pdo`, `mbstring`, `openssl`, `tokenizer`, `xml`, `ctype`, `json`, `bcmath`, `fileinfo`) |
| Composer | 2.x |
| Node.js | 18+ (npm) |
| Database | SQLite (simplest) **or** MySQL 8+ / MariaDB |
| Python Runtime | Python 3.10+ (specifically configured for `/opt/anaconda3/bin/python3`) |
| Ollama | [ollama.com](https://ollama.com) — for AI roleplay & critiques |

---

## 1. Laravel & Python Integration

From the project root (`pitch_proof`):

### Install PHP & Javascript dependencies

```bash
composer install
npm install
```

### Install Python NLP & TTS dependencies

Install the required ML libraries into your local python environment:

```bash
/opt/anaconda3/bin/pip install nltk sentence-transformers kokoro-onnx soundfile
```

### Download ML Models & Corpora

Download the Kokoro TTS voice files, ONNX weights, and NLTK VADER corpora automatically:

```bash
php scripts/download_models.php
```

### Environment Config

```bash
cp .env.example .env
php artisan key:generate
```

Edit `.env` for your machine. Minimum PitchProof-specific values:

```env
APP_NAME=PitchProof
APP_URL=http://localhost:8080

OLLAMA_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2
OLLAMA_TIMEOUT=30

QUEUE_CONNECTION=database
SESSION_DRIVER=database
CACHE_STORE=database
```

*(Note: `FASTAPI_URL` is deprecated and no longer used.)*

### Database

**Option A — SQLite (matches `.env.example`)**

```bash
touch database/database.sqlite
```

Keep:

```env
DB_CONNECTION=sqlite
```

**Option B — MySQL**

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=pitchproof
DB_USERNAME=root
DB_PASSWORD=
```

Create the database first (`CREATE DATABASE pitchproof;`), then migrate.

### Migrate & seed

```bash
php artisan migrate
php artisan db:seed
```

Seeded accounts (`database/seeders/UserSeeder.php`):

| Role | Email | Password |
|------|-------|----------|
| Admin | `admin@pitchproof.com` | `password123` |
| Sales user | `user@pitchproof.com` | `password123` |

### Build frontend (production-style assets)

```bash
npm run build
```

Or use the combined one-shot setup script (installs deps, downloads ML models/nltk resources, generates key, migrates, builds):

```bash
composer run setup
```

Then run `php artisan db:seed` separately if you need the demo users.

---

## 2. Ollama Setup

```bash
ollama serve
ollama pull llama3.2
```

Confirm:

```bash
curl http://127.0.0.1:11434/api/tags
```

Match `OLLAMA_MODEL` in `.env` to a model you have pulled.

---

## 3. Run the Laravel stack

### Recommended (one command)

Starts HTTP server, queue worker, log tail (`pail`), and Vite:

```bash
composer run dev
```

By default `php artisan serve` binds **port 8080**:

```bash
php artisan serve --port=8080
```

Or run processes manually in separate terminals:

```bash
# Terminal A — Laravel on 8080
php artisan serve --host=127.0.0.1 --port=8080

# Terminal B — queue (required for AI avatar trainings)
php artisan queue:listen --tries=1 --timeout=0

# Terminal C — Vite HMR
npm run dev
```

Keep Ollama (`:11434`) running while using AI features.

---

## 4. Verify

| Check | How |
|-------|-----|
| App loads | Open `http://localhost:8080` and sign in |
| Ollama | `GET http://127.0.0.1:11434/api/tags` |
| Queue | Create an AI buyer avatar training; status should move past `processing` to `ready` |
| NLP & TTS | Run integration tests: `php artisan test tests/Feature/PitchNlpIntegrationTest.php` |

---

## Environment reference

| Variable | Purpose | Typical value |
|----------|---------|---------------|
| `APP_URL` | Public app URL | `http://localhost:8080` |
| `DB_*` | Database connection | sqlite or mysql |
| `QUEUE_CONNECTION` | Job backend | `database` |
| `SESSION_DRIVER` / `CACHE_STORE` | Session & cache | `database` |
| `OLLAMA_URL` | Local LLM | `http://127.0.0.1:11434` |
| `OLLAMA_MODEL` | Chat / critique model | `llama3.2` |
| `OLLAMA_TIMEOUT` | HTTP timeout (seconds) | `30` |

Full template: [`.env.example`](../.env.example).

---

## Common issues

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Python Process Failed error on Analysis/TTS | Missing python packages or python path mismatch | Run `/opt/anaconda3/bin/pip install` check and verify `/opt/anaconda3/bin/python3` works |
| NLTK resources not found | NLTK corpora did not download | Run `php scripts/download_models.php` |
| Avatar training stuck on `processing` | Queue worker not running | `php artisan queue:listen` |
| Empty / heuristic buyer replies | Ollama down or wrong model | `ollama serve` + `ollama pull` matching `OLLAMA_MODEL` |
| `APP_KEY` / encryption errors | Missing `.env` key | `php artisan key:generate` |
| Migration failures on SQLite | Missing DB file | `touch database/database.sqlite` |

---

## Quick start checklist

1. `composer install` && `npm install`
2. Run `/opt/anaconda3/bin/pip install nltk sentence-transformers kokoro-onnx soundfile`
3. Copy `.env`, set `APP_URL`, DB, Ollama vars; `php artisan key:generate`
4. Run `php scripts/download_models.php` to fetch TTS voice binaries & NLTK datasets
5. `php artisan migrate --seed`
6. Start Ollama + pull `llama3.2`
7. Start Laravel on port **8080** + queue worker + Vite (`composer run dev` or manual terminals)
8. Sign in as `admin@pitchproof.com` / `password123`