From f9dbd54ca66dec804e5e85646b0bb1b303a39e3b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jesu=CC=81s=20Pe=CC=81rez?= <jpl@jesusperez.com>
Date: Sun, 9 Nov 2025 12:27:37 +0000
Subject: [PATCH] init project

---
 README.md | 510 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 510 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a9875c4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,510 @@
+<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)
+
+---