2025-11-09 12:27:37 +00:00
< div align = "center" >
< img src = "imgs/vapora.svg" alt = "Vapora Logo" width = "400" >
2025-11-10 11:45:23 +00:00
🌊 Intelligent Development Orchestration Platform < br >
🎯 Specialized agents orchestrate pipelines for your team < br >
🤖 Multi-IA router (Claude, OpenAI, Gemini, Ollama) < br >
⚡ Built with Rust from backend to frontend < br >
2025-11-09 12:27:37 +00:00
[](LICENSE)
[](https://www.rust-lang.org)
[](https://kubernetes.io)
[](https://istio.io)
2025-11-10 11:41:29 +00:00
[](PROJECT_COMPLETION_REPORT.md)
[](.coder/summaries/fase-5-deployment.md)
2025-11-09 12:27:37 +00:00
[Features ](#-features ) • [Quick Start ](#-quick-start ) • [Architecture ](#-architecture ) • [Docs ](docs/ ) • [Contributing ](#-contributing )
< / div >
2025-11-10 12:13:05 +00:00
2025-11-09 12:27:37 +00:00
---
```txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╦ ╦╔═╗╔═╗╔═╗╦═╗╔═╗
╚╗╔╝╠═╣╠═╝║ ║╠╦╝╠═╣
╚╝ ╩ ╩╩ ╚═╝╩╚═╩ ╩
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Vaporate complexity
Where ideas vaporize into reality
```
2025-11-10 12:13:05 +00:00
## 🌟 What is Vapora v1.0?
2025-11-09 12:27:37 +00:00
2025-11-10 11:41:29 +00:00
**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)
2025-11-09 12:27:37 +00:00
### Key Highlights
2025-11-10 11:41:29 +00:00
- **🎨 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
2025-11-09 12:27:37 +00:00
---
## ✨ 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
2025-11-10 11:41:29 +00:00
### 🤖 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
2025-11-09 12:27:37 +00:00
### 🏗️ 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
< pre >
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
2025-11-10 11:41:29 +00:00
fastembed Local embeddings for RAG
2025-11-09 12:27:37 +00:00
< / pre >
### Frontend
< pre >
Leptos Reactive Rust WASM framework
UnoCSS Instant on-demand atomic CSS
leptos-use Hooks and utilities
thaw Component library
< / pre >
### Infrastructure
< pre >
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
< / pre >
2025-11-10 11:41:29 +00:00
### Agents & LLM
2025-11-09 12:27:37 +00:00
< pre >
2025-11-10 11:41:29 +00:00
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.)
2025-11-09 12:27:37 +00:00
< / pre >
---
## 🚀 Quick Start
### Prerequisites
- **Rust 1.75+** ([rustup ](https://rustup.rs ))
- **Node.js 20+** (for UnoCSS)
- **Docker** (for local development)
- **Kubernetes cluster** (for production)
### Local Development
```bash
# 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
```
2025-11-10 11:41:29 +00:00
### Production Deployment (Kubernetes)
```bash
# Build and push Docker images
2025-11-10 12:13:05 +00:00
nu scripts/build-docker.nu --registry docker.io --tag v0.1.0 --push
2025-11-10 11:41:29 +00:00
# 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` ](DEPLOYMENT.md )
2025-11-09 12:27:37 +00:00
---
🏗️ 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
1. User interacts with Leptos UI (Kanban board)
2. API calls go through Istio Ingress with mTLS
3. Axum backend handles CRUD operations
4. SurrealDB stores projects, tasks, agents (multi-tenant scopes)
5. Agent jobs queued in NATS JetStream
6. Agent Runtime invokes MCP Gateway
7. MCP Gateway routes to OpenAI/Claude with plugin tools
8. Results streamed back to UI with optimistic updates
---
📸 Screenshots
Kanban Board with Glassmorphism
```
┌─────────────────────────────────────────────────────────┐
│ Vapora 🔍 Search Projects Agents + New │
├─────────────────────────────────────────────────────────┤
│ │
2025-11-10 12:23:35 +00:00
│ 📌 🔵 🟣 ✅ │
│ ┌─────────┬─────────┬─────────┬─────────┐ │
│ │ TODO │ DOING │ REVIEW │ DONE │ │
│ │ (5) │ (3) │ (2) │ (12) │ │
│ ├─────────┼─────────┼─────────┼─────────┤ │
│ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ ┌─────┐ │ │
│ │ │Task │ │ │Task │ │ │Task │ │ │Task │ │ │
│ │ │Card │ │ │Card │ │ │Card │ │ │Card │ │ │
│ │ └─────┘ │ └─────┘ │ └─────┘ │ └─────┘ │ │
│ │ │ │ │ │ │
│ │ Glass │ Neon │ Vapor │ Fluid │ │
│ │ Blur │ Glow │ Waves │ Motion │ │
│ └─────────┴─────────┴─────────┴─────────┘ │
2025-11-09 12:27:37 +00:00
└─────────────────────────────────────────────────────────┘
```
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 │ │
2025-11-10 12:18:34 +00:00
│ │ Semantic search over Vapora docs & code │ │
2025-11-09 12:27:37 +00:00
│ │ • Local embeddings (fastembed) │ │
2025-11-10 12:18:34 +00:00
│ │ • Indexes: guides/, FEATURES, .coder/ │ │
│ │ [✓ Installed] │ │
2025-11-09 12:27:37 +00:00
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
---
📦 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:
```rust
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.
---
2025-11-10 11:41:29 +00:00
🚢 Deployment with Provisioning
2025-11-09 12:27:37 +00:00
2025-11-10 11:41:29 +00:00
Using Provisioning (not Helm) for declarative K8s infrastructure:
2025-11-09 12:27:37 +00:00
```bash
2025-11-10 11:41:29 +00:00
# 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
2025-11-09 12:27:37 +00:00
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
```bash
# 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
2025-11-10 11:41:29 +00:00
---
📚 Documentation & Specifications
2025-11-10 12:13:05 +00:00
VAPORA v1.0 is built on comprehensive specifications organized by domain:
2025-11-10 11:41:29 +00:00
**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
2025-11-09 12:27:37 +00:00
---
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md.
Development Workflow
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. 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 ](README.md#-quick-start ) for setup instructions.
## Pull Request Process
1. Update documentation for any API changes
2. Add tests for new features
3. Ensure `cargo clippy` and `cargo fmt` pass
4. Update CHANGELOG.md
## Coding Standards
- **Rust**: Idiomatic Rust, avoid `unwrap()` , use `?` operator
- **Error Handling**: Use `anyhow::Result` for 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 ](https://www.conventionalcommits.org/ ):
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/` ](./imgs/ ) for complete brand system including logo variations, color palettes, and interactive preview → [Open Logo Preview ](./imgs/vapora_logo.html )
---
