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

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`

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`

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`

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

    # 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

    # 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` 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 - 15-minute setup
- SETUP.md - Complete setup guide
- README.md - Project overview

### Documentation

- QUICKSTART_TRACKING.md - Tracking system quick start
- SETUP_TRACKING.md - Tracking system detailed setup
- .coder/TRACKING_DOCUMENTATION_INDEX.md - Master guide

### Code & Architecture

- Source code - Implementation
- API endpoints - REST API
- Tracking system - Tracking crate
- Integration guide - System integration

### Project Management

- Roadmap - Future features
- Contributing - How to contribute
- Issues - Bug reports & features

## 🆘 Quick Help

### "I'm stuck on installation"

→ See SETUP.md Troubleshooting

### "I don't know how to use the tracking system"

→ See QUICKSTART_TRACKING.md Usage

### "I need to understand the architecture"

→ See .coder/TRACKING_DOCUMENTATION_INDEX.md

### "I want to deploy to production"

→ See 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)

    # Read and follow
    # QUICKSTART.md

    # Expected outcome: Project running, first tracking entry created

### 2. Complete Setup (45 minutes)

    # Read and follow:
    # SETUP.md (complete with configuration and IDE setup)

    # Expected outcome: Full development environment ready

### 3. Understanding First (1-2 hours)

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

    # 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