## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

## 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:

    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:

    # Using Homebrew (macOS)
    brew install nu

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

## 🎯 15-Minute Quick Start

### Step 1: Navigate to Vapora

    # 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

    # Update Rust (optional but recommended)
    rustup update stable

    # Install workspace dependencies
    cargo fetch

### Step 3: Build All Crates

    # 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

    # 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

    # 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

    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

    # 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

    # 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

    # 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

    # 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

    # 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:

    # 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

    # 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

    # 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

    # Update Rust
    rustup update stable

    # Clean and rebuild
    cargo clean
    cargo build

    # Check specific error
    cargo build --verbose

### Tests Fail

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

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

### Backend Won't Start

    # 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

    # 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` - 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`)
3. Customize agents and LLM routing
4. Integrate with external services

## 📖 Learning Resources

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

## 🎬 Quick Reference

    # 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` - 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`

For tracking system specific guide: See `QUICKSTART_TRACKING.md`