24 KiB
24 KiB
🌊 Intelligent Development Orchestration Platform
🎯 Specialized agents orchestrate pipelines for your team
🤖 Multi-IA router (Claude, OpenAI, Gemini, Ollama)
⚡ Built with Rust from backend to frontend
Features • Quick Start • Architecture • Docs • Contributing
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╦ ╦╔═╗╔═╗╔═╗╦═╗╔═╗
╚╗╔╝╠═╣╠═╝║ ║╠╦╝╠═╣
╚╝ ╩ ╩╩ ╚═╝╩╚═╩ ╩
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Vaporate complexity
Where ideas vaporize into reality
🌟 What is Vapora v2.0?
VAPORA is an intelligent development orchestration platform where teams and AI agents collaborate seamlessly to solve the 4 critical problems in parallel:
- ✅ Context Switching (Developers unified in one system instead of jumping between tools)
- ✅ Knowledge Fragmentation (Team decisions, code, and docs discoverable with RAG)
- ✅ Manual Coordination (Specialized agents orchestrate pipelines automatically)
- ✅ Dev-Ops Friction (Unified visibility from code changes through deployment)
Additional capabilities:
- 🤖 Specialized agents (Architect, Developer, Reviewer, Tester, Documenter, Marketer, Presenter, DevOps, Monitor, Security, ProjectManager, DecisionMaker - customizable & extensible)
- 🧠 Multi-IA intelligent routing (Claude, OpenAI, Gemini, Ollama selected per task)
- ☁️ Self-hosted on Kubernetes (no SaaS, complete control, Provisioning-based deployment)
Key Highlights
- 🎨 Glassmorphism UI: Vaporwave aesthetics with UnoCSS, Leptos reactive WASM
- 🤖 Specialized Agent Orchestration: NATS JetStream coordination, parallel pipeline execution with approval gates
- 🧠 Multi-IA Router: Hybrid routing (rules + dynamic + manual override) for optimal LLM per task
- 🚀 Full-Stack Rust: Frontend (Leptos), Backend (Axum), Agents, Infrastructure
- ☁️ K8s Native: Istio service mesh, Rook Ceph storage, Cedar policy engine RBAC
- 📚 RAG Integration: Semantic search over Vapora docs, guides, code, and project materials
- 🔒 Multi-Tenant: SurrealDB scope isolation, fine-grained Cedar policies, complete audit trails
✨ Features
📋 Project Management
- Kanban Board: Drag-and-drop tasks across Todo → Doing → Review → Done columns
- Real-time Collaboration: Optimistic updates for instant UI feedback
- Smart Organization: Feature tags, priority levels, task ordering
- Responsive Design: Works seamlessly from mobile to ultra-wide displays
🤖 Specialized AI Agents (Customizable & Extensible)
Select, tune, or extend agents for your pipeline orchestration needs. Default agents include:
Parallel Agent Coordination:
- 🏗️ Architect (Claude Opus): System design & ADRs
- 💻 Developer (Claude Sonnet): Code implementation [scales 5-20]
- 👀 CodeReviewer (Claude Sonnet): Quality assurance & CR
- 🧪 Tester (Claude Sonnet): Tests & benchmarks
- 📚 Documenter (GPT-4): Docs & root files
- 📢 Marketer (Claude Sonnet): Marketing content
- 🎤 Presenter (Claude Sonnet): Presentations & slides
- ⚙️ DevOps (Claude Sonnet): CI/CD & deployment
- 👁️ Monitor (Gemini Flash): Health & alerting [real-time]
- 🔒 Security (Claude Opus): Audit & compliance [can block]
- 📊 ProjectManager (Claude Sonnet): Roadmap & tracking
- 🎯 DecisionMaker (Claude Opus): Conflict resolution
Multi-IA Router: Transparent LLM selection per task context
- ✅ Automatic selection based on task complexity/latency/cost
- ✅ Manual override capability with audit logging
- ✅ Fallback chains (e.g., Claude Opus → GPT-4 → Claude Sonnet)
- ✅ Cost tracking & budget alerts per agent role
🏗️ Infrastructure
- Kubernetes Native: Built for K8s (K3s, RKE2, or vanilla)
- Istio Service Mesh: mTLS, circuit breakers, rate limiting out of the box
- Secrets Management: RustyVault or Cosmian KMS (Rust-native)
- Storage: Rook Ceph for distributed persistent volumes
- CI/CD: Tekton Pipelines with Gitea integration
- Registry: Zot for lightweight OCI artifact storage
- Observability: Prometheus + Grafana + Loki + Tempo + Kiali
🛠️ Tech Stack
Backend
Rust Async runtime with Tokio Axum Fast, ergonomic web framework SurrealDB Multi-model database with scopes NATS JetStream Message queue for agent jobs Rig AI agent framework fastembed Local embeddings for RAG
Frontend
Leptos Reactive Rust WASM framework UnoCSS Instant on-demand atomic CSS leptos-use Hooks and utilities thaw Component library
Infrastructure
Kubernetes Orchestration (K3s/RKE2) Istio Service mesh + ingress Rook Ceph Distributed storage Tekton Cloud-native CI/CD RustyVault Secrets management Zot OCI registry Gitea Self-hosted Git
Agents & LLM
Rig LLM agent framework with tool calling fastembed Local embeddings for semantic search (RAG) NATS JetStream Message queue for async agent coordination Cedar Policy engine for fine-grained RBAC MCP Gateway Model Context Protocol plugin system Claude API Anthropic Claude (Opus, Sonnet, Haiku) OpenAI API GPT-4, GPT-4o, GPT-3.5-turbo Gemini API Google Gemini (2.0 Pro, Flash, 1.5 Pro) Ollama Local LLMs (Llama 2, Mistral, etc.)
🚀 Quick Start
Prerequisites
- Rust 1.75+ (rustup)
- Node.js 20+ (for UnoCSS)
- Docker (for local development)
- Kubernetes cluster (for production)
Local Development
# Clone the repository
git clone https://github.com/vapora-platform/vapora
cd vapora
# Install dependencies
cargo build
# Setup SurrealDB (Docker)
docker run -d --name surrealdb \
-p 8000:8000 \
surrealdb/surrealdb:latest \
start --bind 0.0.0.0:8000 file://data/database.db
# Run migrations
cd migrations && surrealdb import --conn http://localhost:8000 *.surql
# Start backend
cd ../vapora-backend
cargo run
# Start frontend (new terminal)
cd ../vapora-frontend
trunk serve
Visit http://localhost:3000 🎉
Docker Compose (Full Stack)
docker compose up -d
Includes: Backend, Frontend, SurrealDB, NATS, MCP Gateway
Production Deployment (Kubernetes)
# Build and push Docker images
nu scripts/build-docker.nu --registry docker.io --tag v0.2.0 --push
# Update secrets
edit kubernetes/03-secrets.yaml # Add your API keys
# Deploy to Kubernetes
nu scripts/deploy-k8s.nu
# Or use Provisioning (advanced)
cd provisioning/vapora-wrksp
provisioning workflow run workflows/deploy-full-stack.yaml
See full deployment guide: DEPLOYMENT.md
🏗️ Architecture
┌─────────────────────────────────────────────────────┐
│ Frontend (Leptos + UnoCSS) │
│ Glassmorphism UI • Kanban Board • Drag & Drop │
└────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Istio Ingress Gateway │
│ mTLS • Rate Limiting • Circuit Breaker • Telemetry │
└────────────────────┬────────────────────────────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌───────────────┐
│ Axum │ │ Agent │ │ MCP Gateway │
│ API │ │ Runtime │ │ │
└───┬────┘ └────┬─────┘ └───────┬───────┘
│ │ │
│ │ ▼
│ │ ┌──────────────┐
│ │ │ MCP Plugins │
│ │ │ - Code │
│ │ │ - RAG │
│ │ │ - GitHub │
│ │ │ - Jira │
│ │ └──────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────┐
│ SurrealDB Cluster │
│ (Rook Ceph Persistent Vol) │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ RustyVault / Cosmian KMS │
│ (Secrets + Key Management) │
└─────────────────────────────────────┘
Data Flow
- User interacts with Leptos UI (Kanban board)
- API calls go through Istio Ingress with mTLS
- Axum backend handles CRUD operations
- SurrealDB stores projects, tasks, agents (multi-tenant scopes)
- Agent jobs queued in NATS JetStream
- Agent Runtime invokes MCP Gateway
- MCP Gateway routes to OpenAI/Claude with plugin tools
- Results streamed back to UI with optimistic updates
📸 Screenshots
Kanban Board with Glassmorphism
┌─────────────────────────────────────────────────────────┐
│ Vapora 🔍 Search Projects Agents + New │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┬─────────┬─────────┬─────────┐ │
│ │ 📌 TODO 🔵 DOING 🟣 REVIEW ✅ DONE │ │
│ │ (5) │ (3) │ (2) │ (12) │ │
│ ├─────────┼─────────┼─────────┼─────────┤ │
│ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ │
│ │ │Task │ │ │Task │ │ │Task │ │ │Task │ │ │
│ │ │Card │ │ │Card │ │ │Card │ │ │Card │ │ │
│ │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │ │
│ │ │ │ │ │ │
│ │ Glass │ Neon │ Vapor │ Fluid │ │
│ │ Blur │ Glow │ Waves │ Motion │ │
│ └─────────┴─────────┴─────────┴─────────┘ │
└─────────────────────────────────────────────────────────┘
Agent Plugin Marketplace
┌─────────────────────────────────────────────────────────┐
│ MCP Plugins 🔌 Install New │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────┐ │
│ │ 🔍 Code Analysis Plugin │ │
│ │ Analyze code with tree-sitter + LLM │ │
│ │ • Rust, TypeScript, Python │ │
│ │ • Complexity metrics │ │
│ │ [✓ Installed] │ │
│ └──────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 📚 RAG Search Plugin │ │
│ │ Semantic search over Vapora docs & code │ │
│ │ • Local embeddings (fastembed) │ │
│ │ • Indexes: guides/, FEATURES, .coder/ │ │
│ │ [✓ Installed] │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
📦 Project Structure
vapora/
├── vapora-backend/ # Axum API server
├── vapora-agents/ # Agent runtime + MCP integration
├── vapora-mcp-plugins/ # MCP plugin collection
│ ├── code-plugin/
│ ├── rag-plugin/
│ ├── github-plugin/
│ └── jira-plugin/
├── vapora-shared/ # Shared models and utilities
├── vapora-frontend/ # Leptos CSR application
├── kubernetes/ # K8s manifests
│ ├── base/
│ ├── overlays/
│ └── platform/
├── tekton/ # CI/CD pipelines
├── migrations/ # SurrealDB migrations
└── docs/ # Documentation
🔌 MCP Plugin Development
Create custom agents with the MCP plugin system:
use vapora_mcp::{Plugin, Tool, Resource};
#[derive(Plugin)]
pub struct MyCustomPlugin;
impl Plugin for MyCustomPlugin {
fn name(&self) -> &str {
"my-custom-plugin"
}
fn tools(&self) -> Vec<Tool> {
vec![
Tool::new("my_tool")
.description("Does something cool")
.parameter("input", "string")
]
}
}
#[async_trait]
impl ToolExecutor for MyCustomPlugin {
async fn execute_tool(
&self,
tool: &str,
params: serde_json::Value
) -> Result<serde_json::Value> {
match tool {
"my_tool" => {
// Your logic here
Ok(json!({"result": "success"}))
}
_ => Err(anyhow!("Unknown tool"))
}
}
}
See docs/mcp-plugins.md for full guide.
🚢 Deployment with Provisioning
Using Provisioning (not Helm) for declarative K8s infrastructure:
# Navigate to Provisioning workspace
cd provisioning/vapora-wrksp
# Deploy full VAPORA stack (KCL + Taskservs + Workflows)
provisioning workflow run workflows/deploy-full-stack.yaml
# This creates:
# - K8s cluster (K3s/RKE2) with Cilium CNI
# - Istio service mesh with mTLS
# - Rook Ceph storage
# - SurrealDB (3 replicas, 50Gi storage)
# - Redis (3 replicas, 20Gi storage)
# - NATS JetStream (3 replicas, 30Gi storage)
# - Axum backend (3-10 replicas)
# - Leptos frontend (2 replicas)
# - Agent runtime (3-50 replicas, HPA enabled)
# - LLM Router (2-5 replicas)
# - MCP Gateway (2-5 replicas)
# Access UI
open https://vapora.example.com
# Scale developer agents
provisioning taskserv scale vapora-agents --agent developer --replicas 15
# Monitor health
provisioning health-check --services all
Environment Variables
# Backend
SURREAL_URL=http://surrealdb:8000
NATS_URL=nats://nats:4222
MCP_GATEWAY_URL=http://mcp-gateway:8080
RUSTYVAULT_ADDR=https://rustyvault:8200
# Frontend
VITE_API_URL=https://api.vapora.dev
# Secrets (stored in RustyVault)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
🧪 Testing
# Backend tests
cd vapora-backend
cargo test
# Frontend tests
cd vapora-frontend
cargo test --target wasm32-unknown-unknown
# Integration tests
cargo test --workspace
# E2E tests (requires running services)
./scripts/run-e2e-tests.sh
📊 Monitoring
Access Grafana dashboards:
kubectl port-forward -n observability svc/grafana 3000:80
Pre-configured dashboards:
- Vapora Overview: Request rates, latencies, errors
- Agent Metrics: Job queue depth, execution times, token usage
- Istio Service Mesh: Traffic flows, mTLS status
- Ceph Storage: Capacity, IOPS, health
📚 Documentation & Specifications
VAPORA v2.0 is built on comprehensive specifications organized by domain:
Core Specifications (guides/core/):
- VAPORA-ARCHITECTURE-V2.md: 4-layer architecture (Frontend, API, Service, Data, Infrastructure)
- AGENT-REGISTRY-COORDINATION.md: 12 agent roles, NATS message patterns, health checking
- MULTI-IA-ROUTER.md: Hybrid routing system (rules + dynamic + override), cost tracking
- MULTI-AGENT-WORKFLOWS.md: End-to-end workflows with parallel execution & approval gates
- ROLES-PERMISSIONS-PROFILES.md: Cedar policy engine, team profiles, fine-grained RBAC
- TASK-AGENT-DOC-MANAGER-V2.md: Multi-agent task orchestration & decision extraction
Integration Specifications (guides/integration/):
- DOC-LIFECYCLE-INTEGRATION.md: Dual-mode (plugin + standalone) documentation management
- PROVISIONING-INTEGRATION.md: KCL schemas, taskservs, workflows for K8s deployment
- RAG-INTEGRATION.md: Semantic search with hybrid retrieval & embedding strategy
Component Specifications (guides/):
- SESSION-LIFECYCLE-MANAGER.md: .coder/ organization, metadata extraction, decision capture
- ROOT-FILES-KEEPER.md: Keep README, CHANGELOG, ROADMAP always updated
- MIGRATION-PLAN.md: Gradual migration path for existing projects
Deployment Guide (provisioning/vapora-wrksp/):
- workspace.toml: Master configuration (agents, LLM, monitoring, backup)
- taskservs/: Service definitions for backend, frontend, agents, LLM router, MCP gateway
- kcl/: Infrastructure as Code schemas (cluster, services, storage, agents, multi-ia)
- workflows/: Batch operations (deploy, scale, upgrade, disaster-recovery)
- README.md: Quick start and operation guide
Implementation Roadmap:
- Phase 1 (Weeks 1-4): Foundation (Axum backend, SurrealDB, JWT auth, Leptos frontend)
- Phase 2 (Weeks 5-8): Agents (Registry, NATS, 12 agent implementations)
- Phase 3 (Weeks 9-10): Multi-IA (LLM Router, cost tracking, fallback logic)
- Phase 4 (Weeks 11-13): Workflows (Orchestrator, parallel execution, dashboard)
- Phase 5 (Weeks 14-16): K8s & Provisioning (KCL, taskservs, CI/CD)
References:
- CLAUDE.md: Complete project overview with version history
- guides/archive/v1-single-agent/: Legacy v1.0 specifications for historical reference
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md.
Development Workflow
- Fork the repository
- Create a feature branch (git checkout -b feature/amazing)
- Commit your changes (git commit -m 'Add amazing feature')
- Push to branch (git push origin feature/amazing)
- Open a Pull Request
Code Style
- Rust: Follow rustfmt and clippy recommendations
- Frontend: Use UnoCSS shortcuts, avoid inline styles
- Commits: Conventional commits (feat:, fix:, docs:, etc.)
📄 License
Dual-licensed under:
- MIT License (LICENSE-MIT)
- Apache License 2.0 (LICENSE-APACHE)
You may choose either license.
🙏 Acknowledgments
Inspired by:
- https://github.com/transcend-engineering/archon - Original glassmorphism UI concept
- https://github.com/docker/mcp-gateway - MCP integration pattern
- https://rook.io - Ceph storage operator
- https://istio.io - Service mesh architecture
Built with ❤️ using Rust 🦀
🔗 Links
- Website: https://vapora.dev
- Documentation: https://docs.vapora.dev
- GitHub: https://github.com/vapora-platform/vapora
- Discord: https://discord.gg/vapora
- Twitter: https://twitter.com/VaporaPlatform
#readme
Made with vaporwave dreams and Rust reality ✨
Archivos Adicionales Recomendados
CONTRIBUTING.md
Contributing to Vapora
Thank you for your interest in contributing to Vapora!
Code of Conduct
Be respectful, inclusive, and constructive.
Development Setup
See README.md for setup instructions.
Pull Request Process
- Update documentation for any API changes
- Add tests for new features
- Ensure
cargo clippyandcargo fmtpass - Update CHANGELOG.md
Coding Standards
- Rust: Idiomatic Rust, avoid
unwrap(), use?operator - Error Handling: Use
anyhow::Resultfor services, custom errors for API - Documentation: All public items must have doc comments
- Tests: Unit tests for services, integration tests for API
Commit Messages
Follow Conventional Commits:
feat: add code analysis plugin fix: resolve race condition in task reordering docs: update MCP plugin guide chore: bump dependencies
LICENSE-MIT y LICENSE-APACHE
⚠️ Brand Assets Location: See ./imgs/ for complete brand system including logo variations, color palettes, and interactive preview → Open Logo Preview