460 lines
28 KiB
HTML
460 lines
28 KiB
HTML
|
<!DOCTYPE HTML>
|
|||
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|||
|
|
<head>
|
|||
|
|
<!-- Book generated using mdBook -->
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<title>ADR Index - VAPORA Platform Documentation</title>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Custom HTML head -->
|
|||
|
|
|
|||
|
|
<meta name="description" content="Comprehensive documentation for VAPORA, an intelligent development orchestration platform built entirely in Rust.">
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|||
|
|
<meta name="theme-color" content="#ffffff">
|
|||
|
|
|
|||
|
|
<link rel="icon" href="../favicon.svg">
|
|||
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|||
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|||
|
|
<link rel="stylesheet" href="../css/general.css">
|
|||
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|||
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|||
|
|
|
|||
|
|
<!-- Fonts -->
|
|||
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|||
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|||
|
|
|
|||
|
|
<!-- Highlight.js Stylesheets -->
|
|||
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|||
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|||
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|||
|
|
|
|||
|
|
<!-- Custom theme stylesheets -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
<!-- Provide site root and default themes to javascript -->
|
|||
|
|
<script>
|
|||
|
|
const path_to_root = "../";
|
|||
|
|
const default_light_theme = "light";
|
|||
|
|
const default_dark_theme = "dark";
|
|||
|
|
</script>
|
|||
|
|
<!-- Start loading toc.js asap -->
|
|||
|
|
<script src="../toc.js"></script>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div id="mdbook-help-container">
|
|||
|
|
<div id="mdbook-help-popup">
|
|||
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|||
|
|
<div>
|
|||
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|||
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|||
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|||
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div id="body-container">
|
|||
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|||
|
|
<script>
|
|||
|
|
try {
|
|||
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|||
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|||
|
|
|
|||
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|||
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|||
|
|
}
|
|||
|
|
} catch (e) { }
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|||
|
|
<script>
|
|||
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|||
|
|
let theme;
|
|||
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|||
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|||
|
|
const html = document.documentElement;
|
|||
|
|
html.classList.remove('light')
|
|||
|
|
html.classList.add(theme);
|
|||
|
|
html.classList.add("js");
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|||
|
|
|
|||
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|||
|
|
<script>
|
|||
|
|
let sidebar = null;
|
|||
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|||
|
|
if (document.body.clientWidth >= 1080) {
|
|||
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|||
|
|
sidebar = sidebar || 'visible';
|
|||
|
|
} else {
|
|||
|
|
sidebar = 'hidden';
|
|||
|
|
}
|
|||
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|||
|
|
html.classList.remove('sidebar-visible');
|
|||
|
|
html.classList.add("sidebar-" + sidebar);
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|||
|
|
<!-- populated by js -->
|
|||
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|||
|
|
<noscript>
|
|||
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|||
|
|
</noscript>
|
|||
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|||
|
|
<div class="sidebar-resize-indicator"></div>
|
|||
|
|
</div>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
<div id="page-wrapper" class="page-wrapper">
|
|||
|
|
|
|||
|
|
<div class="page">
|
|||
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|||
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|||
|
|
<div class="left-buttons">
|
|||
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|||
|
|
<i class="fa fa-bars"></i>
|
|||
|
|
</label>
|
|||
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|||
|
|
<i class="fa fa-paint-brush"></i>
|
|||
|
|
</button>
|
|||
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|||
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|||
|
|
</ul>
|
|||
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|||
|
|
<i class="fa fa-search"></i>
|
|||
|
|
</button>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<h1 class="menu-title">VAPORA Platform Documentation</h1>
|
|||
|
|
|
|||
|
|
<div class="right-buttons">
|
|||
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|||
|
|
<i id="print-button" class="fa fa-print"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/vapora-platform/vapora" title="Git repository" aria-label="Git repository">
|
|||
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|||
|
|
</a>
|
|||
|
|
<a href="https://github.com/vapora-platform/vapora/edit/main/docs/src/../adrs/README.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|||
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div id="search-wrapper" class="hidden">
|
|||
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|||
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|||
|
|
</form>
|
|||
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|||
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|||
|
|
<ul id="searchresults">
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|||
|
|
<script>
|
|||
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|||
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|||
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|||
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|||
|
|
});
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
<div id="content" class="content">
|
|||
|
|
<main>
|
|||
|
|
<h1 id="vapora-architecture-decision-records-adrs"><a class="header" href="#vapora-architecture-decision-records-adrs">VAPORA Architecture Decision Records (ADRs)</a></h1>
|
|||
|
|
<p>Documentación de las decisiones arquitectónicas clave del proyecto VAPORA.</p>
|
|||
|
|
<p><strong>Status</strong>: Complete (27 ADRs documented)
|
|||
|
|
<strong>Last Updated</strong>: January 12, 2026
|
|||
|
|
<strong>Format</strong>: Custom VAPORA (Decision, Rationale, Alternatives, Trade-offs, Implementation, Verification, Consequences)</p>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-adrs-by-category"><a class="header" href="#-adrs-by-category">📑 ADRs by Category</a></h2>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-database--persistence-1-adr"><a class="header" href="#-database--persistence-1-adr">🗄️ Database & Persistence (1 ADR)</a></h2>
|
|||
|
|
<p>Decisiones sobre almacenamiento de datos y persistencia.</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>ID</th><th>Título</th><th>Decisión</th><th>Status</th></tr></thead><tbody>
|
|||
|
|
<tr><td><a href="./0004-surrealdb-database.html">004</a></td><td>SurrealDB como Database Único</td><td>SurrealDB 2.3 multi-model (relational + graph + document)</td><td>✅ Accepted</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-core-architecture-6-adrs"><a class="header" href="#-core-architecture-6-adrs">🏗️ Core Architecture (6 ADRs)</a></h2>
|
|||
|
|
<p>Decisiones fundamentales sobre el stack tecnológico y estructura base del proyecto.</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>ID</th><th>Título</th><th>Decisión</th><th>Status</th></tr></thead><tbody>
|
|||
|
|
<tr><td><a href="./0001-cargo-workspace.html">001</a></td><td>Cargo Workspace con 13 Crates</td><td>Monorepo con workspace Cargo</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0002-axum-backend.html">002</a></td><td>Axum como Backend Framework</td><td>Axum 0.8.6 REST API + composable middleware</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0003-leptos-frontend.html">003</a></td><td>Leptos CSR-Only Frontend</td><td>Leptos 0.8.12 WASM (Client-Side Rendering)</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0006-rig-framework.html">006</a></td><td>Rig Framework para LLM Agents</td><td>rig-core 0.15 para orquestación de agentes</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0008-tokio-runtime.html">008</a></td><td>Tokio Multi-Threaded Runtime</td><td>Tokio async runtime con configuración default</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0013-knowledge-graph.html">013</a></td><td>Knowledge Graph Temporal</td><td>SurrealDB temporal KG + learning curves</td><td>✅ Accepted</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-agent-coordination--messaging-2-adrs"><a class="header" href="#-agent-coordination--messaging-2-adrs">🔄 Agent Coordination & Messaging (2 ADRs)</a></h2>
|
|||
|
|
<p>Decisiones sobre coordinación entre agentes y comunicación de mensajes.</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>ID</th><th>Título</th><th>Decisión</th><th>Status</th></tr></thead><tbody>
|
|||
|
|
<tr><td><a href="./0005-nats-jetstream.html">005</a></td><td>NATS JetStream para Agent Coordination</td><td>async-nats 0.45 con JetStream (at-least-once delivery)</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0007-multi-provider-llm.html">007</a></td><td>Multi-Provider LLM Support</td><td>Claude + OpenAI + Gemini + Ollama con fallback automático</td><td>✅ Accepted</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-infrastructure--security-4-adrs"><a class="header" href="#-infrastructure--security-4-adrs">☁️ Infrastructure & Security (4 ADRs)</a></h2>
|
|||
|
|
<p>Decisiones sobre infraestructura Kubernetes, seguridad, y gestión de secretos.</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>ID</th><th>Título</th><th>Decisión</th><th>Status</th></tr></thead><tbody>
|
|||
|
|
<tr><td><a href="./0009-istio-service-mesh.html">009</a></td><td>Istio Service Mesh</td><td>Istio para mTLS + traffic management + observability</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0010-cedar-authorization.html">010</a></td><td>Cedar Policy Engine</td><td>Cedar policies para RBAC declarativo</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0011-secretumvault.html">011</a></td><td>SecretumVault Secrets Management</td><td>Post-quantum crypto para gestión de secretos</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0012-llm-routing-tiers.html">012</a></td><td>Three-Tier LLM Routing</td><td>Rules-based + Dynamic + Manual Override</td><td>✅ Accepted</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-innovaciones-vapora-8-adrs"><a class="header" href="#-innovaciones-vapora-8-adrs">🚀 Innovaciones VAPORA (8 ADRs)</a></h2>
|
|||
|
|
<p>Decisiones únicas que diferencian a VAPORA de otras plataformas de orquestación multi-agente.</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>ID</th><th>Título</th><th>Decisión</th><th>Status</th></tr></thead><tbody>
|
|||
|
|
<tr><td><a href="./0014-learning-profiles.html">014</a></td><td>Learning Profiles con Recency Bias</td><td>Exponential recency weighting (3× para últimos 7 días)</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0015-budget-enforcement.html">015</a></td><td>Three-Tier Budget Enforcement</td><td>Monthly + weekly limits con auto-fallback a Ollama</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0016-cost-efficiency-ranking.html">016</a></td><td>Cost Efficiency Ranking</td><td>Formula: (quality_score * 100) / (cost_cents + 1)</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0017-confidence-weighting.html">017</a></td><td>Confidence Weighting</td><td>min(1.0, executions/20) previene lucky streaks</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0018-swarm-load-balancing.html">018</a></td><td>Swarm Load-Balanced Assignment</td><td>assignment_score = success_rate / (1 + load)</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0019-temporal-execution-history.html">019</a></td><td>Temporal Execution History</td><td>Daily windowed aggregations para learning curves</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0020-audit-trail.html">020</a></td><td>Audit Trail para Compliance</td><td>Complete event logging + queryability</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0021-websocket-updates.html">021</a></td><td>Real-Time WebSocket Updates</td><td>tokio::sync::broadcast para pub/sub eficiente</td><td>✅ Accepted</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="-development-patterns-6-adrs"><a class="header" href="#-development-patterns-6-adrs">🔧 Development Patterns (6 ADRs)</a></h2>
|
|||
|
|
<p>Patrones de desarrollo y arquitectura utilizados en todo el codebase.</p>
|
|||
|
|
<div class="table-wrapper"><table><thead><tr><th>ID</th><th>Título</th><th>Decisión</th><th>Status</th></tr></thead><tbody>
|
|||
|
|
<tr><td><a href="./0022-error-handling.html">022</a></td><td>Two-Tier Error Handling</td><td>thiserror domain errors + ApiError HTTP wrapper</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0023-testing-strategy.html">023</a></td><td>Multi-Layer Testing Strategy</td><td>Unit tests (inline) + Integration (tests/) + Real DB</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0024-service-architecture.html">024</a></td><td>Service-Oriented Architecture</td><td>API layer (thin) + Services layer (thick business logic)</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0025-multi-tenancy.html">025</a></td><td>SurrealDB Scope-Based Multi-Tenancy</td><td>tenant_id fields + database scopes para defense-in-depth</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0026-shared-state.html">026</a></td><td>Arc-Based Shared State</td><td>Arc<RwLock<>> para read-heavy, Arc<Mutex<>> para write-heavy</td><td>✅ Accepted</td></tr>
|
|||
|
|
<tr><td><a href="./0027-documentation-layers.html">027</a></td><td>Three-Layer Documentation System</td><td>.coder/ (session) + .claude/ (operational) + docs/ (product)</td><td>✅ Accepted</td></tr>
|
|||
|
|
</tbody></table>
|
|||
|
|
</div>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="documentation-by-category"><a class="header" href="#documentation-by-category">Documentation by Category</a></h2>
|
|||
|
|
<h3 id="-database--persistence"><a class="header" href="#-database--persistence">🗄️ Database & Persistence</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>SurrealDB</strong>: Multi-model database (relational + graph + document) unifies all VAPORA data needs with native multi-tenancy support via scopes</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="-core-architecture"><a class="header" href="#-core-architecture">🏗️ Core Architecture</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Workspace</strong>: Monorepo structure with 13 specialized crates enables independent testing, parallel development, code reuse</li>
|
|||
|
|
<li><strong>Backend</strong>: Axum provides composable middleware, type-safe routing, direct Tokio ecosystem integration</li>
|
|||
|
|
<li><strong>Frontend</strong>: Leptos CSR enables fine-grained reactivity and WASM performance (no SEO needed for platform)</li>
|
|||
|
|
<li><strong>LLM Framework</strong>: Rig enables tool calling and streaming with minimal abstraction</li>
|
|||
|
|
<li><strong>Runtime</strong>: Tokio multi-threaded optimized for I/O-heavy workloads (API, DB, LLM calls)</li>
|
|||
|
|
<li><strong>Knowledge Graph</strong>: Temporal history with learning curves enables collective agent learning via SurrealDB</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="-agent-coordination--messaging"><a class="header" href="#-agent-coordination--messaging">🔄 Agent Coordination & Messaging</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>NATS JetStream</strong>: Provides persistent, reliable at-least-once delivery for agent task coordination</li>
|
|||
|
|
<li><strong>Multi-Provider LLM</strong>: Support 4 providers (Claude, OpenAI, Gemini, Ollama) with automatic fallback chain</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="-infrastructure--security"><a class="header" href="#-infrastructure--security">☁️ Infrastructure & Security</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Istio Service Mesh</strong>: Provides zero-trust security (mTLS), traffic management, observability for inter-service communication</li>
|
|||
|
|
<li><strong>Cedar Authorization</strong>: Declarative, auditable RBAC policies for fine-grained access control</li>
|
|||
|
|
<li><strong>SecretumVault</strong>: Post-quantum cryptography future-proofs API key and credential storage</li>
|
|||
|
|
<li><strong>Three-Tier LLM Routing</strong>: Balances predictability (rules-based) with flexibility (dynamic scoring) and manual override capability</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="-innovations-unique-to-vapora"><a class="header" href="#-innovations-unique-to-vapora">🚀 Innovations Unique to VAPORA</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Learning Profiles</strong>: Recency-biased expertise tracking (3× weight for last 7 days) adapts agent selection to current capability</li>
|
|||
|
|
<li><strong>Budget Enforcement</strong>: Dual time windows (monthly + weekly) with three enforcement states + auto-fallback prevent both long-term and short-term overspend</li>
|
|||
|
|
<li><strong>Cost Efficiency Ranking</strong>: Quality-to-cost formula <code>(quality_score * 100) / (cost_cents + 1)</code> prevents overfitting to cheap providers</li>
|
|||
|
|
<li><strong>Confidence Weighting</strong>: <code>min(1.0, executions/20)</code> prevents new agents from being selected on lucky streaks</li>
|
|||
|
|
<li><strong>Swarm Load Balancing</strong>: <code>success_rate / (1 + load)</code> balances agent expertise with availability</li>
|
|||
|
|
<li><strong>Temporal Execution History</strong>: Daily windowed aggregations identify improvement trends and enable collective learning</li>
|
|||
|
|
<li><strong>Audit Trail</strong>: Complete event logging for compliance, incident investigation, and event sourcing potential</li>
|
|||
|
|
<li><strong>Real-Time WebSocket Updates</strong>: Broadcast channels for efficient multi-client workflow progress updates</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="-development-patterns"><a class="header" href="#-development-patterns">🔧 Development Patterns</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Two-Tier Error Handling</strong>: Domain errors (<code>VaporaError</code>) separate from HTTP responses (<code>ApiError</code>) for reusability</li>
|
|||
|
|
<li><strong>Multi-Layer Testing</strong>: Unit tests (inline) + Integration tests (tests/ dir) + Real database connections = 218+ tests</li>
|
|||
|
|
<li><strong>Service-Oriented Architecture</strong>: Thin API layer delegates to thick services layer containing business logic</li>
|
|||
|
|
<li><strong>Scope-Based Multi-Tenancy</strong>: <code>tenant_id</code> fields + SurrealDB scopes provide defense-in-depth tenant isolation</li>
|
|||
|
|
<li><strong>Arc-Based Shared State</strong>: <code>Arc<RwLock<>></code> for read-heavy, <code>Arc<Mutex<>></code> for write-heavy state management</li>
|
|||
|
|
<li><strong>Three-Layer Documentation</strong>: <code>.coder/</code> (session) + <code>.claude/</code> (operational) + <code>docs/</code> (product) separates concerns</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="how-to-use-these-adrs"><a class="header" href="#how-to-use-these-adrs">How to Use These ADRs</a></h2>
|
|||
|
|
<h3 id="for-team-members"><a class="header" href="#for-team-members">For Team Members</a></h3>
|
|||
|
|
<ol>
|
|||
|
|
<li><strong>Understanding Architecture</strong>: Start with Core Architecture ADRs (001-013) to understand technology choices</li>
|
|||
|
|
<li><strong>Learning VAPORA's Unique Features</strong>: Read Innovations ADRs (014-021) to understand what makes VAPORA different</li>
|
|||
|
|
<li><strong>Writing New Code</strong>: Reference relevant ADRs in Patterns section (022-027) when implementing features</li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="for-new-hires"><a class="header" href="#for-new-hires">For New Hires</a></h3>
|
|||
|
|
<ol>
|
|||
|
|
<li>Read Core Architecture (001-013) first - ~30 minutes to understand the stack</li>
|
|||
|
|
<li>Read Innovations (014-021) - ~45 minutes to understand VAPORA's differentiators</li>
|
|||
|
|
<li>Reference Patterns (022-027) as you write your first contributions</li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="for-architectural-decisions"><a class="header" href="#for-architectural-decisions">For Architectural Decisions</a></h3>
|
|||
|
|
<p>When making new architectural decisions:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Check existing ADRs to understand previous choices and trade-offs</li>
|
|||
|
|
<li>Create a new ADR following the Custom VAPORA format</li>
|
|||
|
|
<li>Reference existing ADRs that influenced your decision</li>
|
|||
|
|
<li>Get team review before implementation</li>
|
|||
|
|
</ol>
|
|||
|
|
<h3 id="for-troubleshooting"><a class="header" href="#for-troubleshooting">For Troubleshooting</a></h3>
|
|||
|
|
<p>When debugging or optimizing:</p>
|
|||
|
|
<ol>
|
|||
|
|
<li>Find the ADR for the relevant component</li>
|
|||
|
|
<li>Review the "Implementation" section for key files</li>
|
|||
|
|
<li>Check "Verification" for testing commands</li>
|
|||
|
|
<li>Review "Consequences" for known limitations</li>
|
|||
|
|
</ol>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="format"><a class="header" href="#format">Format</a></h2>
|
|||
|
|
<p>Each ADR follows the Custom VAPORA format:</p>
|
|||
|
|
<pre><code class="language-markdown"># ADR-XXX: [Title]
|
|||
|
|
|
|||
|
|
**Status**: Accepted | Implemented
|
|||
|
|
**Date**: YYYY-MM-DD
|
|||
|
|
**Deciders**: [Team/Role]
|
|||
|
|
**Technical Story**: [Context/Issue]
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Decision
|
|||
|
|
[Descripción clara de la decisión]
|
|||
|
|
|
|||
|
|
## Rationale
|
|||
|
|
[Por qué se tomó esta decisión]
|
|||
|
|
|
|||
|
|
## Alternatives Considered
|
|||
|
|
[Opciones evaluadas y por qué se descartaron]
|
|||
|
|
|
|||
|
|
## Trade-offs
|
|||
|
|
**Pros**: [Beneficios]
|
|||
|
|
**Cons**: [Costos]
|
|||
|
|
|
|||
|
|
## Implementation
|
|||
|
|
[Dónde está implementada, archivos clave, ejemplos de código]
|
|||
|
|
|
|||
|
|
## Verification
|
|||
|
|
[Cómo verificar que la decisión está correctamente implementada]
|
|||
|
|
|
|||
|
|
## Consequences
|
|||
|
|
[Impacto a largo plazo, dependencias, mantenimiento]
|
|||
|
|
|
|||
|
|
## References
|
|||
|
|
[Links a docs, código, issues]
|
|||
|
|
</code></pre>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="integration-with-project-documentation"><a class="header" href="#integration-with-project-documentation">Integration with Project Documentation</a></h2>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>docs/operations/</strong>: Deployment, disaster recovery, operational runbooks</li>
|
|||
|
|
<li><strong>docs/disaster-recovery/</strong>: Backup strategy, recovery procedures, business continuity</li>
|
|||
|
|
<li><strong>.claude/guidelines/</strong>: Development conventions (Rust, Nushell, Nickel)</li>
|
|||
|
|
<li><strong>.claude/CLAUDE.md</strong>: Project-specific constraints and patterns</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="maintenance"><a class="header" href="#maintenance">Maintenance</a></h2>
|
|||
|
|
<h3 id="when-to-update-adrs"><a class="header" href="#when-to-update-adrs">When to Update ADRs</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>❌ Do NOT create new ADRs for minor code changes</li>
|
|||
|
|
<li>✅ DO create ADRs for significant architectural decisions (framework changes, new patterns, major refactoring)</li>
|
|||
|
|
<li>✅ DO update ADRs if a decision changes (mark as "Superseded" and create new ADR)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="review-process"><a class="header" href="#review-process">Review Process</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>ADRs should be reviewed before major architectural changes</li>
|
|||
|
|
<li>Use ADRs as reference during code reviews to ensure consistency</li>
|
|||
|
|
<li>Update ADRs if they don't reflect current reality (source of truth = code)</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="quarterly-review"><a class="header" href="#quarterly-review">Quarterly Review</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>Review all ADRs quarterly to ensure they're still accurate</li>
|
|||
|
|
<li>Update "Date" field if reviewed and still valid</li>
|
|||
|
|
<li>Mark as "Superseded" if implementation has changed</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="statistics"><a class="header" href="#statistics">Statistics</a></h2>
|
|||
|
|
<ul>
|
|||
|
|
<li><strong>Total ADRs</strong>: 27</li>
|
|||
|
|
<li><strong>Core Architecture</strong>: 13 (48%)</li>
|
|||
|
|
<li><strong>Innovations</strong>: 8 (30%)</li>
|
|||
|
|
<li><strong>Patterns</strong>: 6 (22%)</li>
|
|||
|
|
<li><strong>Production Status</strong>: All Accepted and Implemented</li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<h2 id="related-resources"><a class="header" href="#related-resources">Related Resources</a></h2>
|
|||
|
|
<ul>
|
|||
|
|
<li><a href="../README.html#architecture">VAPORA Architecture Overview</a></li>
|
|||
|
|
<li><a href="./../.claude/guidelines/rust.html">Development Guidelines</a></li>
|
|||
|
|
<li><a href="./operations/deployment-runbook.html">Deployment Guide</a></li>
|
|||
|
|
<li><a href="./disaster-recovery/README.html">Disaster Recovery</a></li>
|
|||
|
|
</ul>
|
|||
|
|
<hr />
|
|||
|
|
<p><strong>Generated</strong>: January 12, 2026
|
|||
|
|
<strong>Status</strong>: Production-Ready
|
|||
|
|
<strong>Last Reviewed</strong>: January 12, 2026</p>
|
|||
|
|
|
|||
|
|
</main>
|
|||
|
|
|
|||
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|||
|
|
<!-- Mobile navigation buttons -->
|
|||
|
|
<a rel="prev" href="../../architecture/roles-permissions-profiles.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../../adrs/0001-cargo-workspace.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<div style="clear: both"></div>
|
|||
|
|
</nav>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|||
|
|
<a rel="prev" href="../../architecture/roles-permissions-profiles.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|||
|
|
<i class="fa fa-angle-left"></i>
|
|||
|
|
</a>
|
|||
|
|
|
|||
|
|
<a rel="next prefetch" href="../../adrs/0001-cargo-workspace.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|||
|
|
<i class="fa fa-angle-right"></i>
|
|||
|
|
</a>
|
|||
|
|
</nav>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
window.playground_copyable = true;
|
|||
|
|
</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<script src="../elasticlunr.min.js"></script>
|
|||
|
|
<script src="../mark.min.js"></script>
|
|||
|
|
<script src="../searcher.js"></script>
|
|||
|
|
|
|||
|
|
<script src="../clipboard.min.js"></script>
|
|||
|
|
<script src="../highlight.js"></script>
|
|||
|
|
<script src="../book.js"></script>
|
|||
|
|
|
|||
|
|
<!-- Custom JS scripts -->
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|