π 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
[](LICENSE)
[](https://www.rust-lang.org)
[](https://kubernetes.io)
[](https://istio.io)
[](PROJECT_COMPLETION_REPORT.md)
[](.coder/summaries/fase-5-deployment.md)
[Features](#-features) β’ [Quick Start](#-quick-start) β’ [Architecture](#-architecture) β’ [Docs](docs/) β’ [Contributing](#-contributing)
---
```txt
βββββββββββββββββββββββββββββββββββ
β¦ β¦ββββββββββ¦βββββ
βββββ ββ£β βββ ββ β¦ββ ββ£
ββ β© β©β© ββββ©βββ© β©
βββββββββββββββββββββββββββββββββββ
Vaporate complexity
Where ideas vaporize into reality
```
## π What is Vapora v1.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](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
```
### Production Deployment (Kubernetes)
```bash
# Build and push Docker images
nu scripts/build-docker.nu --registry docker.io --tag v0.1.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`](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
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 β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β π π΅ π£ β
β
β βββββββββββ¬ββββββββββ¬ββββββββββ¬ββββββββββ β
β β 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:
```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 {
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 {
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:
```bash
# 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
```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
---
π Documentation & Specifications
VAPORA v1.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
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)
---