---
title: Vapora - START HERE
date: 2025-11-10
status: READY
version: 1.0
type: entry-point
---

# 🌊 Vapora - START HERE

**Welcome to Vapora! This is your entry point to the intelligent development orchestration platform.**

Choose your path below based on what you want to do:

---

## ⚡ I Want to Get Started NOW (15 minutes)

👉 **Read:** [`QUICKSTART.md`](./QUICKSTART.md)

This is the fastest way to get up and running:
- Prerequisites check (2 min)
- Build complete project (5 min)
- Run backend & frontend (3 min)
- Verify everything works (2 min)
- Create first tracking entry (3 min)

**Then:** Try using the tracking system: `/log-change`, `/add-todo`, `/track-status`

---

## 🛠️ I Want Complete Setup Instructions

👉 **Read:** [`SETUP.md`](./SETUP.md)

Complete step-by-step guide covering:
- Prerequisites verification & installation
- Workspace configuration (3 options)
- Building all 8 crates
- Running full test suite
- IDE setup (VS Code, CLion)
- Development workflow
- Troubleshooting guide

**Time:** 30-45 minutes for complete setup with configuration

---

## 🚀 I Want to Understand the Project

👉 **Read:** [`README.md`](./README.md)

Project overview covering:
- What is Vapora (intelligent development orchestration)
- Key features (agents, LLM routing, tracking, K8s, RAG)
- Architecture overview
- Technology stack
- Getting started links
- Contributing guidelines

**Time:** 15-20 minutes to understand the vision

---

## 📚 I Want Deep Technical Understanding

👉 **Read:** [`.coder/TRACKING_DOCUMENTATION_INDEX.md`](./.coder/TRACKING_DOCUMENTATION_INDEX.md)

Master documentation index covering:
- All documentation files (8+ docs)
- Reading paths by role (PM, Dev, DevOps, Architect, User)
- Complete architecture and design decisions
- API reference and integration details
- Performance characteristics
- Troubleshooting strategies

**Time:** 1-2 hours for comprehensive understanding

---

## 🎯 Quick Navigation by Role

| Role | Start with | Then read | Time |
|------|-----------|-----------|------|
| **New Developer** | QUICKSTART.md | SETUP.md | 45 min |
| **Backend Dev** | SETUP.md | crates/vapora-backend/ | 1 hour |
| **Frontend Dev** | SETUP.md | crates/vapora-frontend/ | 1 hour |
| **DevOps / Ops** | SETUP.md | INTEGRATION.md | 1 hour |
| **Project Lead** | README.md | .coder/ docs | 2 hours |
| **Architect** | .coder/TRACKING_DOCUMENTATION_INDEX.md | All docs | 2+ hours |
| **Tracking System User** | QUICKSTART_TRACKING.md | SETUP_TRACKING.md | 30 min |

---

## 📋 Projects and Components

### Main Components

**Vapora is built from 8 integrated crates:**

| Crate | Purpose | Status |
|-------|---------|--------|
| **vapora-shared** | Shared types, utilities, errors | ✅ Core |
| **vapora-agents** | Agent orchestration framework | ✅ Complete |
| **vapora-llm-router** | Multi-LLM routing (Claude, GPT, Gemini, Ollama) | ✅ Complete |
| **vapora-tracking** | Change & TODO tracking system (NEW) | ✅ Production |
| **vapora-backend** | REST API server (Axum) | ✅ Complete |
| **vapora-frontend** | Web UI (Leptos + WASM) | ✅ Complete |
| **vapora-mcp-server** | MCP protocol support | ✅ Complete |
| **vapora-doc-lifecycle** | Document lifecycle management | ✅ Complete |

### System Architecture

```
┌─────────────────────────────────────────────────┐
│           Vapora Platform (You are here)        │
├─────────────────────────────────────────────────┤
│                                                 │
│  Frontend (Leptos WASM)                         │
│  └─ http://localhost:8080                       │
│                                                 │
│  Backend (Axum REST API)                        │
│  └─ http://localhost:3000/api/v1/*              │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │  Core Services                          │   │
│  │  • Tracking System (vapora-tracking)    │   │
│  │  • Agent Orchestration (vapora-agents)  │   │
│  │  • LLM Router (vapora-llm-router)       │   │
│  │  • Document Lifecycle Manager           │   │
│  └─────────────────────────────────────────┘   │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │  Infrastructure                         │   │
│  │  • SQLite Database (local dev)          │   │
│  │  • SurrealDB (production)               │   │
│  │  • NATS JetStream (messaging)           │   │
│  │  • Kubernetes Ready                     │   │
│  └─────────────────────────────────────────┘   │
│                                                 │
└─────────────────────────────────────────────────┘
```

---

## 🚀 Quick Start Options

### Option 1: 15-Minute Build & Run

```bash
# Build entire project
cargo build

# Run backend (Terminal 1)
cargo run -p vapora-backend

# Run frontend (Terminal 2, optional)
cd crates/vapora-frontend && trunk serve

# Visit http://localhost:3000 and http://localhost:8080
```

### Option 2: Test Everything First

```bash
# Build
cargo build

# Run all tests
cargo test --lib

# Check code quality
cargo clippy --all -- -W clippy::all

# Format code
cargo fmt

# Then run: cargo run -p vapora-backend
```

### Option 3: Step-by-Step Complete Setup

See [`SETUP.md`](./SETUP.md) for:
- Detailed prerequisites
- Configuration options
- IDE setup
- Development workflow
- Comprehensive troubleshooting

---

## 📖 Documentation Structure

### In Vapora Root

| File | Purpose | Time |
|------|---------|------|
| **START_HERE.md** | This file - entry point | 5 min |
| **QUICKSTART.md** | 15-minute full project setup | 15 min |
| **SETUP.md** | Complete setup guide | 30 min |
| **README.md** | Project overview & features | 15 min |

### In `.coder/` (Project Analysis)

| File | Purpose | Time |
|------|---------|------|
| **TRACKING_SYSTEM_STATUS.md** | Implementation status & API reference | 30 min |
| **TRACKING_DOCUMENTATION_INDEX.md** | Master navigation guide | 15 min |
| **OPTIMIZATION_SUMMARY.md** | Code improvements & architecture | 20 min |

### In Crate Directories

| Crate | README | Integration | Other |
|-------|--------|-------------|-------|
| vapora-tracking | Feature overview | Full guide | Benchmarks |
| vapora-backend | API reference | Deployment | Tests |
| vapora-frontend | Component docs | WASM build | Examples |
| vapora-shared | Type definitions | Utilities | Tests |
| vapora-agents | Framework | Examples | Agents |
| vapora-llm-router | Router logic | Config | Examples |

### Tools Directory (`~/.Tools/.coder/`)

| File | Purpose | Language |
|------|---------|----------|
| **BITACORA_TRACKING_DONE.md** | Implementation summary | Spanish |

---

## ✨ Key Features at a Glance

### 🎯 Project Management
- Kanban board (Todo → Doing → Review → Done)
- Change tracking with impact analysis
- TODO system with priority & estimation
- Real-time collaboration

### 🤖 AI Agent Orchestration
- 12+ specialized agents (Architect, Developer, Reviewer, Tester, etc.)
- Parallel pipeline execution with approval gates
- Multi-LLM routing (Claude, OpenAI, Gemini, Ollama)
- Customizable & extensible agent system

### 🧠 Intelligent Routing
- Automatic LLM selection per task
- Manual override capability
- Fallback chains
- Cost tracking & budget alerts

### 📚 Knowledge Management
- RAG integration for semantic search
- Document lifecycle management
- Team decisions & docs discoverable
- Code & guide integration

### ☁️ Infrastructure Ready
- Kubernetes native (K3s, RKE2, vanilla)
- Istio service mesh
- Self-hosted (no SaaS)
- Horizontal scaling

---

## 🎬 What You Can Do After Getting Started

✅ **Build & Run**
- Build complete project: `cargo build`
- Run backend: `cargo run -p vapora-backend`
- Run frontend: `trunk serve` (in frontend dir)
- Run tests: `cargo test --lib`

✅ **Use Tracking System**
- Log changes: `/log-change "description" --impact backend`
- Create TODOs: `/add-todo "task" --priority H --estimate M`
- Check status: `/track-status --limit 10`
- Export reports: `./scripts/export-tracking.nu json`

✅ **Use Agent Framework**
- Orchestrate AI agents for tasks
- Multi-LLM routing for optimal model selection
- Pipeline execution with approval gates

✅ **Integrate & Extend**
- Add custom agents
- Integrate with external services
- Deploy to Kubernetes
- Customize LLM routing

✅ **Develop & Contribute**
- Understand codebase architecture
- Modify agents and services
- Add new features
- Submit pull requests

---

## 🛠️ System Requirements

**Minimum:**
- macOS 10.15+ / Linux / Windows
- Rust 1.75+
- 4GB RAM
- 2GB disk space
- Internet connection

**Recommended:**
- macOS 12+ (M1/M2) / Linux
- Rust 1.75+
- 8GB+ RAM
- 5GB+ disk space
- NuShell 0.95+ (for scripts)

---

## 📚 Learning Paths

### Path 1: Quick User (30 minutes)
1. Read: QUICKSTART.md (15 min)
2. Build: `cargo build` (8 min)
3. Run: Backend & frontend (5 min)
4. Try: `/log-change`, `/track-status` (2 min)

### Path 2: Developer (2 hours)
1. Read: README.md (15 min)
2. Read: SETUP.md (30 min)
3. Setup: Development environment (20 min)
4. Build: Full project (5 min)
5. Explore: Crate documentation (30 min)
6. Code: Try modifying something (20 min)

### Path 3: Architect (3+ hours)
1. Read: README.md (15 min)
2. Read: .coder/TRACKING_DOCUMENTATION_INDEX.md (30 min)
3. Deep dive: All architecture docs (1+ hour)
4. Review: Source code (1+ hour)
5. Plan: Extensions and modifications

### Path 4: Tracking System Focus (1 hour)
1. Read: QUICKSTART_TRACKING.md (15 min)
2. Build: `cargo build -p vapora-tracking` (5 min)
3. Setup: Tracking system (10 min)
4. Explore: Tracking features (20 min)
5. Try: /log-change, /track-status, exports (10 min)

---

## 🔗 Quick Links

### Getting Started
- [QUICKSTART.md](./QUICKSTART.md) - 15-minute setup
- [SETUP.md](./SETUP.md) - Complete setup guide
- [README.md](./README.md) - Project overview

### Documentation
- [QUICKSTART_TRACKING.md](./QUICKSTART_TRACKING.md) - Tracking system quick start
- [SETUP_TRACKING.md](./SETUP_TRACKING.md) - Tracking system detailed setup
- [.coder/TRACKING_DOCUMENTATION_INDEX.md](./.coder/TRACKING_DOCUMENTATION_INDEX.md) - Master guide

### Code & Architecture
- [Source code](./crates/) - Implementation
- [API endpoints](./crates/vapora-backend/README.md) - REST API
- [Tracking system](./crates/vapora-tracking/README.md) - Tracking crate
- [Integration guide](./crates/vapora-tracking/INTEGRATION.md) - System integration

### Project Management
- [Roadmap](./README.md#-roadmap) - Future features
- [Contributing](./README.md#-contributing) - How to contribute
- [Issues](https://github.com/vapora/vapora/issues) - Bug reports & features

---

## 🆘 Quick Help

### "I'm stuck on installation"
→ See [SETUP.md Troubleshooting](./SETUP.md#troubleshooting)

### "I don't know how to use the tracking system"
→ See [QUICKSTART_TRACKING.md Usage](./QUICKSTART_TRACKING.md#-first-time-usage)

### "I need to understand the architecture"
→ See [.coder/TRACKING_DOCUMENTATION_INDEX.md](./CODER/TRACKING_DOCUMENTATION_INDEX.md)

### "I want to deploy to production"
→ See [INTEGRATION.md Deployment](./crates/vapora-tracking/INTEGRATION.md#deployment)

### "I'm not sure where to start"
→ Choose your role from the table above and follow the reading path

---

## 🎯 Next Steps

**Choose one:**

### 1. Fast Track (15 minutes)
```bash
# Read and follow
# QUICKSTART.md

# Expected outcome: Project running, first tracking entry created
```

### 2. Complete Setup (45 minutes)
```bash
# Read and follow:
# SETUP.md (complete with configuration and IDE setup)

# Expected outcome: Full development environment ready
```

### 3. Understanding First (1-2 hours)
```bash
# Read in order:
# 1. README.md (project overview)
# 2. .coder/TRACKING_DOCUMENTATION_INDEX.md (architecture)
# 3. SETUP.md (setup with full understanding)

# Expected outcome: Deep understanding of system design
```

### 4. Tracking System Only (30 minutes)
```bash
# Read and follow:
# QUICKSTART_TRACKING.md

# Expected outcome: Tracking system running and in use
```

---

## ✅ Installation Checklist

**Before you start:**
- [ ] Rust 1.75+ installed
- [ ] Cargo available
- [ ] Git installed
- [ ] 2GB+ disk space available
- [ ] Internet connection working

**After quick start:**
- [ ] `cargo build` succeeds
- [ ] `cargo test --lib` passes
- [ ] Backend runs on port 3000
- [ ] Frontend loads on port 8080 (optional)
- [ ] Can create tracking entries
- [ ] Code formats correctly

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

---

## 💡 Pro Tips

- **Start simple:** Begin with QUICKSTART.md, expand later
- **Use the docs:** Every crate has README.md with examples
- **Check status:** Run `/track-status` frequently
- **IDE matters:** Set up VS Code or CLion properly
- **Ask questions:** Check documentation first, then ask the community
- **Contribute:** Once comfortable, consider contributing improvements

---

## 🌟 Welcome to Vapora!

You're about to join a platform that's changing how development teams work together. Whether you're here to build, contribute, or just explore, you've come to the right place.

**Choose your starting point above and begin your Vapora journey! 🚀**

---

**Quick decision guide:**
- ⏱️ **Have 15 min?** → QUICKSTART.md
- ⏱️ **Have 45 min?** → SETUP.md
- ⏱️ **Have 2 hours?** → README.md + Deep dive
- ⏱️ **Just tracking?** → QUICKSTART_TRACKING.md

---

**Last updated:** 2025-11-10 | **Status:** ✅ Production Ready | **Version:** 1.0