Vapora/docs/quickstart.md

title, date, status, version

title	date	status	version
Vapora Project - Quick Start Guide	2025-11-10	READY	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