jesus/Vapora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Vapora/README.md

511 lines
18 KiB
Markdown
Raw Normal View History

init project
2025-11-09 12:27:37 +00:00
<div align="center">
<img src="imgs/vapora.svg" alt="Vapora Logo" width="400">
- 🌊 Cloud-native project management with AI agents
- 🎯 Kanban workflows with glassmorphism UI
- 🤖 Unified agent runtime powered by MCP
- ⚡ Built with Rust from backend to frontend
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org)
[![Kubernetes](https://img.shields.io/badge/kubernetes-ready-326CE5.svg)](https://kubernetes.io)
[![Istio](https://img.shields.io/badge/istio-service%20mesh-466BB0.svg)](https://istio.io)
[Features](#-features) • [Quick Start](#-quick-start) • [Architecture](#-architecture) • [Docs](docs/) • [Contributing](#-contributing)
</div>
---
```txt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╦ ╦╔═╗╔═╗╔═╗╦═╗╔═╗
╚╗╔╝╠═╣╠═╝║ ║╠╦╝╠═╣
╚╝ ╩ ╩╩ ╚═╝╩╚═╩ ╩
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Vaporate complexity
Where ideas vaporize into reality
```
## 🌟 What is Vapora?
**Vapora** is a next-generation project management platform that combines elegant Kanban workflows with intelligent AI agents. Built entirely in Rust, it offers a cloud-native
architecture designed for teams that demand both beauty and performance.
### Key Highlights
- **🎨 Tron-Inspired UI**: Glassmorphism design with vaporwave aesthetics powered by UnoCSS
- **🤖 AI-First**: Unified agent runtime using Model Context Protocol (MCP)
- **🚀 Full-Stack Rust**: From frontend (Leptos WASM) to backend (Axum) to infrastructure
- **☁️ Cloud-Agnostic**: Runs on any Kubernetes cluster with Istio service mesh
- **🔌 Extensible**: Plugin system for custom agents and integrations
- **🔒 Multi-Tenant**: Enterprise-grade isolation with namespace-level security
---
## ✨ 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
### 🤖 AI Agent Runtime
- **MCP Gateway Integration**: Unified interface for OpenAI, Claude, and custom agents
- **Plugin Architecture**: Extend functionality with MCP-compatible plugins
- **Built-in Capabilities**:
- 🔍 **Code Analysis**: Tree-sitter parsing + LLM semantic review
- 📚 **RAG Search**: Semantic search over knowledge base with local embeddings
- 📝 **Doc Generation**: Auto-generate technical documentation from code
- ⚙️ **Task Execution**: Automate GitHub PRs, Jira updates, webhooks
### 🏗️ 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
</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>
### Agents
<pre>
MCP Gateway Docker MCP gateway for unified agents
OpenAI AgentKit OpenAI agent integration
Claude Agent SDK Anthropic Claude integration
fastembed Local embeddings (privacy-first)
tree-sitter Code parsing
</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
```
---
🏗️ 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 knowledge base │ │
│ │ • Local embeddings (fastembed) │ │
│ │ • Top-k retrieval │ │
│ │ [Install] │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
---
📦 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.
---
🚢 Deployment
Kubernetes (Production)
```bash
# Setup cluster with Istio + Rook Ceph
./scripts/setup-cluster.sh
# Deploy platform services (Vault, Gitea, Zot, etc.)
./scripts/deploy-platform.sh
# Deploy Vapora application
kubectl apply -k kubernetes/overlays/production
# Create a tenant
./scripts/create-tenant.sh acme
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
---
🤝 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)
---
Reference in New Issue Copy Permalink