# Getting Started

> Quick setup and first steps with Izri

Welcome! This section has everything you need to get Izri running and make your first contribution.

## 📋 Prerequisites

Before you start, ensure you have:

- **Node.js** 18+ - [Install](https://nodejs.org/)
- **pnpm** 8+ - `npm install -g pnpm`
- **Docker & Docker Compose** - [Install](https://www.docker.com/products/docker-desktop)
- **Git** - [Install](https://git-scm.com/)
- **Python** 3.11+ (for AI service) - [Install](https://python.org/)

Verify your setup:

```bash
node --version      # v18+
pnpm --version      # 8+
docker --version    # 20+
git --version       # 2+
python3 --version   # 3.11+
```

## 🚀 Quick Start (5 Minutes)

```bash
# 1. Clone repository
git clone https://github.com/your-org/izri.git
cd izri

# 2. Install dependencies
pnpm install

# 3. Setup environment
cp .env.shared.example .env.shared
pnpm env:generate

# 4. Start infrastructure
pnpm dev:docker

# 5. Setup database
pnpm db:generate
pnpm db:migrate
pnpm db:seed

# 6. Start all services
pnpm dev
```

That's it! 🎉

## 🌐 Access Your Services

| Service | URL | Purpose |
|---------|-----|---------|
| **Web App** | <http://localhost:5173> | React Router frontend |
| **API** | <http://localhost:4000> | Hono + tRPC backend |
| **AI Service** | <http://localhost:8000> | Python FastAPI |
| **Database UI** | Run `pnpm db:studio` | Drizzle Studio |

### Verify Everything Works

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

# Web dashboard
# Open http://localhost:5173 in browser
# Try signing in with any email/password (mock auth enabled)
```

## 📚 Documentation

- **[Detailed Setup](./quick-start.md)** - Step-by-step installation guide

## 🎯 Next Steps

1. **Complete Setup** - Follow the detailed [Quick Start Guide](./quick-start.md)
2. **Learn Architecture** - Check [Architecture Overview](../architecture/overview.md)
3. **Start Developing** - Review [Development Guide](../development/README.md)

## 🆘 Troubleshooting

### Port Already in Use

```bash
# Kill process using port
lsof -ti:5173 | xargs kill -9  # Web
lsof -ti:4000 | xargs kill -9  # API
lsof -ti:8000 | xargs kill -9  # AI
```

### Database Connection Failed

```bash
# Restart Docker services
pnpm docker:down
pnpm dev:docker

# Verify DATABASE_URL in .env
cat apps/api/.env | grep DATABASE_URL
```

### `pnpm install` Fails

```bash
# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install
```

### Python AI Service Error

```bash
cd packages/ai-service
python3 -m pip install -r requirements.txt
python3 main.py
```

## ⚙️ Environment Variables

Essential variables in `.env.shared`:

```bash
# Database
DATABASE_URL="postgresql://postgres:password@localhost:5433/izri"

# API
API_PORT=4000
API_URL="http://localhost:4000"
VITE_API_URL="http://localhost:4000"

# AI Service
AI_SERVICE_URL="http://localhost:8000"

# Optional (for later)
# GITHUB_CLIENT_ID="..."
# OPENAI_API_KEY="..."
```

Run `pnpm env:generate` after editing `.env.shared` to generate project-specific env files.

---

*Ready to dive in? Start with the [Detailed Quick Start Guide →](./quick-start.md)*