Vapora/docs/quickstart.md

---
title: Vapora Project - Quick Start Guide
date: 2025-11-10
status: READY
version: 1.0
---

# 🚀 Vapora - Quick Start Guide

**⏱️ Time to get running: 15-20 minutes**

This guide walks you through building and running the complete Vapora project in the simplest way possible.

---

## 📋 Prerequisites

You need:
- ✅ Rust 1.75+ (install from https://rustup.rs)
- ✅ Cargo (comes with Rust)
- ✅ Git
- ✅ NuShell 0.95+ (for scripts)
- ✅ 2GB free disk space
- ✅ Bash or Zsh shell

**Check if you have everything:**
```bash
rustc --version      # Should show Rust 1.75+
cargo --version      # Should show Cargo 1.75+
which git            # Should show /usr/bin/git or similar
nu --version         # Should show NuShell 0.95+
```

**Install NuShell if needed:**
```bash
# Using Homebrew (macOS)
brew install nu

# Or download from: https://www.nushell.sh/
```

---

## 🎯 15-Minute Quick Start

### Step 1: Navigate to Vapora
```bash
# Verify structure
ls crates/
# Should show: vapora-backend, vapora-frontend, vapora-shared, vapora-agents, vapora-llm-router, vapora-mcp-server, vapora-tracking
```

### Step 2: Install Dependencies

```bash
# Update Rust (optional but recommended)
rustup update stable

# Install workspace dependencies
cargo fetch
```

### Step 3: Build All Crates

```bash
# Build the complete workspace
cargo build

# This builds all 7 crates:
# - vapora-shared (shared utilities)
# - vapora-agents (agent framework)
# - vapora-llm-router (LLM routing)
# - vapora-tracking (change tracking system)
# - vapora-backend (REST API)
# - vapora-frontend (WASM UI)
# - vapora-mcp-server (MCP protocol support)
```

**Build time:** 2-5 minutes (first time)

**Expected output:**
```
    Finished `dev` profile [unoptimized + debuginfo] target(s) in XXXs
```

### Step 4: Run Tests

```bash
# Run all tests in the workspace
cargo test --lib

# Run tests for specific crate
cargo test -p vapora-backend --lib
cargo test -p vapora-tracking --lib

# Expected output:
# test result: ok. XXX passed; 0 failed
```

### Step 5: Start the Backend Service

```bash
# Run the backend server (development mode)
cargo run -p vapora-backend

# Expected output:
# 🚀 Vapora Backend Server running on http://127.0.0.1:3000
# Available endpoints:
#   GET    /api/v1/health
#   GET    /api/v1/tracking/summary
#   POST   /api/v1/agents/orchestrate
#   GET    /api/v1/projects
```

**The server will be available at:** `http://localhost:3000`

### Step 6: (In Another Terminal) Start Frontend Development

```bash
cd crates/vapora-frontend

# Install frontend dependencies
cargo install trunk

# Run frontend with hot-reload
trunk serve

# Expected output:
# 🦕 Listening on http://127.0.0.1:8080
```

**The UI will be available at:** `http://localhost:8080`

### Step 7: Verify Everything Works

```bash
# Check health of backend
curl http://localhost:3000/api/v1/health

# Expected response:
# {
#   "status": "ok",
#   "service": "vapora-backend",
#   "timestamp": "2025-11-10T14:30:00Z"
# }

# Check tracking system
curl http://localhost:3000/api/v1/tracking/summary

# Expected response:
# {
#   "total_entries": 0,
#   "changes": 0,
#   "todos": 0
# }
```

---

## 🏗️ Project Structure Overview

```
├── Cargo.toml (workspace config)
├── crates/
│   ├── vapora-shared/          ← Shared utilities & types
│   ├── vapora-agents/          ← Agent orchestration framework
│   ├── vapora-llm-router/      ← Multi-LLM routing (Claude, OpenAI, Gemini, Ollama)
│   ├── vapora-tracking/        ← Change & TODO tracking system (NEW)
│   ├── vapora-backend/         ← REST API (Axum)
│   ├── vapora-frontend/        ← Web UI (Leptos + WASM)
│   └── vapora-mcp-server/      ← MCP protocol server
├── scripts/
│   ├── sync-tracking.nu        ← Sync tracking data
│   ├── export-tracking.nu      ← Export reports
│   └── start-tracking-service.nu ← Start tracking service
└── docs/
    └── (API docs, architecture, etc.)
```

---

## 📊 Available Commands

### Build Commands

```bash
# Build specific crate
cargo build -p vapora-backend
cargo build -p vapora-tracking

# Build for production (optimized)
cargo build --release

# Check without building
cargo check

# Clean build artifacts
cargo clean
```

### Test Commands

```bash
# Run all tests
cargo test --lib

# Run tests for specific crate
cargo test -p vapora-tracking --lib

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test -p vapora-backend test_health_endpoint -- --exact
```

### Development Commands

```bash
# Run backend server
cargo run -p vapora-backend

# Run with verbose logging
RUST_LOG=debug cargo run -p vapora-backend

# Format code
cargo fmt

# Lint code
cargo clippy -- -W clippy::all
```

### Documentation

```bash
# Generate and open documentation
cargo doc -p vapora-backend --open

# Generate for specific crate
cargo doc -p vapora-tracking --open
```

---

## 🎯 What You Can Do Now

After the quick start, you have:

✅ **Backend API running** at `http://localhost:3000`
- Health checks
- Tracking system endpoints
- Agent orchestration API

✅ **Frontend UI running** at `http://localhost:8080`
- Real-time project dashboard
- Agent status monitoring
- Change tracking interface

✅ **Tracking System**
- Log changes: `/log-change "description"`
- Create TODOs: `/add-todo "task"`
- Check status: `/track-status`
- Export reports: `./scripts/export-tracking.nu`

✅ **Agent Framework**
- Orchestrate AI agents
- Multi-LLM routing
- Parallel pipeline execution

---

## 🔗 Integration Points

### Using the Tracking System

The tracking system integrates with the backend:

```bash
# Log a change
/log-change "Implemented user authentication" \
  --impact backend \
  --files 5

# Create a TODO
/add-todo "Review code changes" \
  --priority H \
  --estimate M

# Check tracking status
/track-status --limit 10

# Export to report
./scripts/export-tracking.nu json --output report.json
```

### Using the Agent Framework

```bash
# Orchestrate agents for a task
curl -X POST http://localhost:3000/api/v1/agents/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Code review",
    "agents": ["developer", "reviewer"],
    "context": "Review the authentication module"
  }'
```

### Using the LLM Router

```bash
# Query the LLM router for optimal model selection
curl http://localhost:3000/api/v1/llm-router/select \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "code_implementation",
    "complexity": "high"
  }'
```

---

## 🐛 Troubleshooting

### Build Fails

```bash
# Update Rust
rustup update stable

# Clean and rebuild
cargo clean
cargo build

# Check specific error
cargo build --verbose
```

### Tests Fail

```bash
# Run with output
cargo test --lib -- --nocapture --test-threads=1

# Check Rust version
rustc --version  # Should be 1.75+
```

### Backend Won't Start

```bash
# Check if port 3000 is in use
lsof -i :3000

# Use different port
VAPORA_PORT=3001 cargo run -p vapora-backend

# Check logs
RUST_LOG=debug cargo run -p vapora-backend
```

### Frontend Build Issues

```bash
# Update trunk
cargo install --locked trunk

# Clear build cache
rm -rf crates/vapora-frontend/target

# Rebuild
cargo run -p vapora-frontend
```

---

## 📚 Next Steps

### Short Term (This Session)
1. ✅ Build and run the complete project
2. ✅ Visit frontend at `http://localhost:8080`
3. ✅ Test API endpoints
4. ✅ Create first tracking entry

### Medium Term (This Week)
1. Read [`SETUP.md`](./SETUP.md) - Complete setup with configuration
2. Explore crate documentation: `cargo doc --open`
3. Set up development environment
4. Configure tracking system

### Long Term (Ongoing)
1. Contribute to the project
2. Deploy to production (see [`INTEGRATION.md`](./crates/vapora-tracking/INTEGRATION.md))
3. Customize agents and LLM routing
4. Integrate with external services

---

## 📖 Learning Resources

| Resource | Location | Time |
|----------|----------|------|
| Project README | [`README.md`](./README.md) | 10 min |
| Complete Setup | [`SETUP.md`](./SETUP.md) | 20 min |
| Tracking System | [`QUICKSTART_TRACKING.md`](./QUICKSTART_TRACKING.md) | 10 min |
| Architecture | [`.coder/`](./.coder/) | 30 min |
| Source Code | [`crates/`](./crates/) | varies |
| API Docs | `cargo doc --open` | varies |

---

## 🎬 Quick Reference

```bash
# One-command build and test
cargo build && cargo test --lib

# Run backend in one terminal
cargo run -p vapora-backend

# Run frontend in another terminal
cd crates/vapora-frontend && trunk serve

# Check everything is working
curl http://localhost:3000/api/v1/health

# View logs
RUST_LOG=debug cargo run -p vapora-backend

# Format and lint all code
cargo fmt && cargo clippy --all -- -W clippy::all
```

---

## 🆘 Getting Help

**Issues during quick start?**
1. Check [`SETUP.md`](./SETUP.md) - Troubleshooting section
2. Read crate-specific docs in `crates/*/README.md`
3. Check inline code documentation: `cargo doc --open`
4. Review `.coder/` documentation

---

## ✅ Success Checklist

- [ ] Rust 1.75+ installed
- [ ] Git repository available
- [ ] `cargo build` succeeds
- [ ] `cargo test --lib` shows all tests passing
- [ ] Backend runs at `http://localhost:3000`
- [ ] Frontend runs at `http://localhost:8080`
- [ ] Health endpoint responds
- [ ] Can create tracking entries

**All checked? ✅ You're ready to develop with Vapora!**

---

**For complete setup with configuration options:** See [`SETUP.md`](./SETUP.md)

**For tracking system specific guide:** See [`QUICKSTART_TRACKING.md`](./QUICKSTART_TRACKING.md)