Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

VAPORA Architecture Decision Records (ADRs)

Documentación de las decisiones arquitectónicas clave del proyecto VAPORA.

Status: Complete (27 ADRs documented) Last Updated: January 12, 2026 Format: Custom VAPORA (Decision, Rationale, Alternatives, Trade-offs, Implementation, Verification, Consequences)

📑 ADRs by Category

🗄️ Database & Persistence (1 ADR)

Decisiones sobre almacenamiento de datos y persistencia.

IDTítuloDecisiónStatus
004SurrealDB como Database ÚnicoSurrealDB 2.3 multi-model (relational + graph + document)✅ Accepted

🏗️ Core Architecture (6 ADRs)

Decisiones fundamentales sobre el stack tecnológico y estructura base del proyecto.

IDTítuloDecisiónStatus
001Cargo Workspace con 13 CratesMonorepo con workspace Cargo✅ Accepted
002Axum como Backend FrameworkAxum 0.8.6 REST API + composable middleware✅ Accepted
003Leptos CSR-Only FrontendLeptos 0.8.12 WASM (Client-Side Rendering)✅ Accepted
006Rig Framework para LLM Agentsrig-core 0.15 para orquestación de agentes✅ Accepted
008Tokio Multi-Threaded RuntimeTokio async runtime con configuración default✅ Accepted
013Knowledge Graph TemporalSurrealDB temporal KG + learning curves✅ Accepted

🔄 Agent Coordination & Messaging (2 ADRs)

Decisiones sobre coordinación entre agentes y comunicación de mensajes.

IDTítuloDecisiónStatus
005NATS JetStream para Agent Coordinationasync-nats 0.45 con JetStream (at-least-once delivery)✅ Accepted
007Multi-Provider LLM SupportClaude + OpenAI + Gemini + Ollama con fallback automático✅ Accepted

☁️ Infrastructure & Security (4 ADRs)

Decisiones sobre infraestructura Kubernetes, seguridad, y gestión de secretos.

IDTítuloDecisiónStatus
009Istio Service MeshIstio para mTLS + traffic management + observability✅ Accepted
010Cedar Policy EngineCedar policies para RBAC declarativo✅ Accepted
011SecretumVault Secrets ManagementPost-quantum crypto para gestión de secretos✅ Accepted
012Three-Tier LLM RoutingRules-based + Dynamic + Manual Override✅ Accepted

🚀 Innovaciones VAPORA (8 ADRs)

Decisiones únicas que diferencian a VAPORA de otras plataformas de orquestación multi-agente.

IDTítuloDecisiónStatus
014Learning Profiles con Recency BiasExponential recency weighting (3× para últimos 7 días)✅ Accepted
015Three-Tier Budget EnforcementMonthly + weekly limits con auto-fallback a Ollama✅ Accepted
016Cost Efficiency RankingFormula: (quality_score * 100) / (cost_cents + 1)✅ Accepted
017Confidence Weightingmin(1.0, executions/20) previene lucky streaks✅ Accepted
018Swarm Load-Balanced Assignmentassignment_score = success_rate / (1 + load)✅ Accepted
019Temporal Execution HistoryDaily windowed aggregations para learning curves✅ Accepted
020Audit Trail para ComplianceComplete event logging + queryability✅ Accepted
021Real-Time WebSocket Updatestokio::sync::broadcast para pub/sub eficiente✅ Accepted

🔧 Development Patterns (6 ADRs)

Patrones de desarrollo y arquitectura utilizados en todo el codebase.

IDTítuloDecisiónStatus
022Two-Tier Error Handlingthiserror domain errors + ApiError HTTP wrapper✅ Accepted
023Multi-Layer Testing StrategyUnit tests (inline) + Integration (tests/) + Real DB✅ Accepted
024Service-Oriented ArchitectureAPI layer (thin) + Services layer (thick business logic)✅ Accepted
025SurrealDB Scope-Based Multi-Tenancytenant_id fields + database scopes para defense-in-depth✅ Accepted
026Arc-Based Shared StateArc<RwLock<>> para read-heavy, Arc<Mutex<>> para write-heavy✅ Accepted
027Three-Layer Documentation System.coder/ (session) + .claude/ (operational) + docs/ (product)✅ Accepted

Documentation by Category

🗄️ Database & Persistence

  • SurrealDB: Multi-model database (relational + graph + document) unifies all VAPORA data needs with native multi-tenancy support via scopes

🏗️ Core Architecture

  • Workspace: Monorepo structure with 13 specialized crates enables independent testing, parallel development, code reuse
  • Backend: Axum provides composable middleware, type-safe routing, direct Tokio ecosystem integration
  • Frontend: Leptos CSR enables fine-grained reactivity and WASM performance (no SEO needed for platform)
  • LLM Framework: Rig enables tool calling and streaming with minimal abstraction
  • Runtime: Tokio multi-threaded optimized for I/O-heavy workloads (API, DB, LLM calls)
  • Knowledge Graph: Temporal history with learning curves enables collective agent learning via SurrealDB

🔄 Agent Coordination & Messaging

  • NATS JetStream: Provides persistent, reliable at-least-once delivery for agent task coordination
  • Multi-Provider LLM: Support 4 providers (Claude, OpenAI, Gemini, Ollama) with automatic fallback chain

☁️ Infrastructure & Security

  • Istio Service Mesh: Provides zero-trust security (mTLS), traffic management, observability for inter-service communication
  • Cedar Authorization: Declarative, auditable RBAC policies for fine-grained access control
  • SecretumVault: Post-quantum cryptography future-proofs API key and credential storage
  • Three-Tier LLM Routing: Balances predictability (rules-based) with flexibility (dynamic scoring) and manual override capability

🚀 Innovations Unique to VAPORA

  • Learning Profiles: Recency-biased expertise tracking (3× weight for last 7 days) adapts agent selection to current capability
  • Budget Enforcement: Dual time windows (monthly + weekly) with three enforcement states + auto-fallback prevent both long-term and short-term overspend
  • Cost Efficiency Ranking: Quality-to-cost formula (quality_score * 100) / (cost_cents + 1) prevents overfitting to cheap providers
  • Confidence Weighting: min(1.0, executions/20) prevents new agents from being selected on lucky streaks
  • Swarm Load Balancing: success_rate / (1 + load) balances agent expertise with availability
  • Temporal Execution History: Daily windowed aggregations identify improvement trends and enable collective learning
  • Audit Trail: Complete event logging for compliance, incident investigation, and event sourcing potential
  • Real-Time WebSocket Updates: Broadcast channels for efficient multi-client workflow progress updates

🔧 Development Patterns

  • Two-Tier Error Handling: Domain errors (VaporaError) separate from HTTP responses (ApiError) for reusability
  • Multi-Layer Testing: Unit tests (inline) + Integration tests (tests/ dir) + Real database connections = 218+ tests
  • Service-Oriented Architecture: Thin API layer delegates to thick services layer containing business logic
  • Scope-Based Multi-Tenancy: tenant_id fields + SurrealDB scopes provide defense-in-depth tenant isolation
  • Arc-Based Shared State: Arc<RwLock<>> for read-heavy, Arc<Mutex<>> for write-heavy state management
  • Three-Layer Documentation: .coder/ (session) + .claude/ (operational) + docs/ (product) separates concerns

How to Use These ADRs

For Team Members

  1. Understanding Architecture: Start with Core Architecture ADRs (001-013) to understand technology choices
  2. Learning VAPORA's Unique Features: Read Innovations ADRs (014-021) to understand what makes VAPORA different
  3. Writing New Code: Reference relevant ADRs in Patterns section (022-027) when implementing features

For New Hires

  1. Read Core Architecture (001-013) first - ~30 minutes to understand the stack
  2. Read Innovations (014-021) - ~45 minutes to understand VAPORA's differentiators
  3. Reference Patterns (022-027) as you write your first contributions

For Architectural Decisions

When making new architectural decisions:

  1. Check existing ADRs to understand previous choices and trade-offs
  2. Create a new ADR following the Custom VAPORA format
  3. Reference existing ADRs that influenced your decision
  4. Get team review before implementation

For Troubleshooting

When debugging or optimizing:

  1. Find the ADR for the relevant component
  2. Review the "Implementation" section for key files
  3. Check "Verification" for testing commands
  4. Review "Consequences" for known limitations

Format

Each ADR follows the Custom VAPORA format:

# 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]

Integration with Project Documentation

  • docs/operations/: Deployment, disaster recovery, operational runbooks
  • docs/disaster-recovery/: Backup strategy, recovery procedures, business continuity
  • .claude/guidelines/: Development conventions (Rust, Nushell, Nickel)
  • .claude/CLAUDE.md: Project-specific constraints and patterns

Maintenance

When to Update ADRs

  • ❌ Do NOT create new ADRs for minor code changes
  • ✅ DO create ADRs for significant architectural decisions (framework changes, new patterns, major refactoring)
  • ✅ DO update ADRs if a decision changes (mark as "Superseded" and create new ADR)

Review Process

  • ADRs should be reviewed before major architectural changes
  • Use ADRs as reference during code reviews to ensure consistency
  • Update ADRs if they don't reflect current reality (source of truth = code)

Quarterly Review

  • Review all ADRs quarterly to ensure they're still accurate
  • Update "Date" field if reviewed and still valid
  • Mark as "Superseded" if implementation has changed

Statistics

  • Total ADRs: 27
  • Core Architecture: 13 (48%)
  • Innovations: 8 (30%)
  • Patterns: 6 (22%)
  • Production Status: All Accepted and Implemented

Generated: January 12, 2026 Status: Production-Ready Last Reviewed: January 12, 2026