# Quick Start Guide

> Complete step-by-step setup instructions

This guide provides detailed instructions for setting up Izri. For a faster overview, see the [Getting Started](./README.md) page.

## 📋 Prerequisites

Ensure you have installed:

- **Node.js** 18+ 
- **pnpm** 8+
- **Docker & Docker Compose**
- **Git**
- **Python** 3.11+ (for AI service)

## 1️⃣ Clone Repository

```bash
# Using HTTPS
git clone https://github.com/your-org/izri.git
cd izri

# Or using SSH (if configured)
git clone git@github.com:your-org/izri.git
cd izri
```

## 2️⃣ Install Dependencies

```bash
pnpm install
```

This installs all dependencies for the monorepo and links workspace packages together. **Time: 2-5 minutes**

### Troubleshoot

```bash
# Clear cache if it fails
pnpm store prune
pnpm install

# Or full reset
rm -rf node_modules
pnpm install
```

## 3️⃣ Configure Environment

```bash
# Copy example file
cp .env.shared.example .env.shared

# Edit with your values (most defaults work for local dev)
# nano .env.shared  # or use your editor

# Generate project-specific .env files
pnpm env:generate
```

**Key variables** (defaults work for local development):

```bash
DATABASE_URL="postgresql://postgres:password@localhost:5433/izri"
API_URL="http://localhost:4000"
VITE_API_URL="http://localhost:4000"
AI_SERVICE_URL="http://localhost:8000"
```

> Run `pnpm env:generate` whenever you edit `.env.shared`

## 4️⃣ Start Infrastructure

```bash
pnpm dev:docker
```

This starts PostgreSQL (port 5433) and Redis (port 6379) in Docker containers.

**Verify**:

```bash
docker ps
# Should show postgres and redis containers
```

## 5️⃣ Setup Database

```bash
# Generate migrations from schema
pnpm db:generate

# Apply migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed
```

**Verify**:

```bash
pnpm db:studio
# Opens http://localhost:4983 - visual database explorer
# You should see tables: users, projects, organizations, test_runs, etc.
```

## 6️⃣ Start All Services

```bash
pnpm dev
```

This starts:

- **Web**: <http://localhost:5173> (React Router + Vite)
- **API**: <http://localhost:4000> (Hono + tRPC)
- **AI**: <http://localhost:8000> (FastAPI)

**Expected output**:

```
@izri/web:dev: VITE v5.0.0  ready in 1234 ms
@izri/web:dev: ➜  Local:   http://localhost:5173/
@izri/api:dev: 🚀 Server running on http://localhost:4000
ai-service:dev: INFO:     Uvicorn running on http://localhost:8000
```

## ✅ Verify Setup

### API Health

```bash
curl http://localhost:4000/health
# Expected: {"ok":true}
```

### Web Dashboard

1. Open <http://localhost:5173>
2. Click "Sign In with GitHub"
3. Authorise the OAuth app (requires `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` in `.env.shared`)
4. You should be redirected back and see the dashboard

> **Need a GitHub OAuth app?** See [docs/setup/GITHUB_OAUTH.md](../setup/GITHUB_OAUTH.md) for setup instructions.

### Database

```bash
pnpm db:studio
# Visual database explorer at http://localhost:4983
```

## 🎯 Next Steps

- **Learn**: Check [Architecture Overview](../architecture/overview.md)
- **Develop**: See [Development Guide](../development/README.md)

## 🆘 Common Issues

| Issue | Solution |
|-------|----------|
| Port in use | `lsof -ti:5173 \| xargs kill -9` |
| DB connection failed | `pnpm docker:down && pnpm dev:docker` |
| `pnpm install` fails | `pnpm store prune && pnpm install` |
| Python errors | `cd packages/ai-service && pip install -r requirements.txt` |

## 📚 All Commands

**Development**:

```bash
pnpm dev              # Start all services
pnpm dev:web          # Start web only
pnpm dev:api          # Start API only
pnpm dev:docker       # Start Docker services (PostgreSQL, Redis)
```

**Database**:

```bash
pnpm db:studio        # Open database UI
pnpm db:generate      # Generate migrations
pnpm db:migrate       # Apply migrations
pnpm db:seed          # Seed test data
```

**Build & Quality**:

```bash
pnpm build            # Build all packages
pnpm lint             # Lint code
pnpm format:all       # Format code
pnpm type:check       # Check types
pnpm test             # Run tests
pnpm clean            # Clean build artifacts
```

---

*Continue with the [Architecture Overview](../architecture/overview.md) to understand the system →*