Vapora/docs/adrs/0001-cargo-workspace.md

# ADR-001: Cargo Workspace con 13 Crates Especializados

**Status**: Accepted | Implemented
**Date**: 2024-11-01
**Deciders**: VAPORA Architecture Team
**Technical Story**: Determining optimal project structure for multi-agent orchestration platform

---

## Decision

Adoptar un **Cargo workspace monorepo con 13 crates especializados** en lugar de un monolito único o multi-repositorio.

```text
crates/
├── vapora-shared/           # Core models, types, errors
├── vapora-backend/          # REST API (40+ endpoints)
├── vapora-agents/           # Agent orchestration + learning
├── vapora-llm-router/       # Multi-provider LLM routing
├── vapora-swarm/            # Swarm coordination + metrics
├── vapora-knowledge-graph/  # Temporal KG + learning curves
├── vapora-frontend/         # Leptos WASM UI
├── vapora-mcp-server/       # MCP protocol gateway
├── vapora-tracking/         # Task/project storage abstraction
├── vapora-telemetry/        # OpenTelemetry integration
├── vapora-analytics/        # Event pipeline + usage stats
├── vapora-worktree/         # Git worktree management
└── vapora-doc-lifecycle/    # Documentation management
```

---

## Rationale

1. **Separation of Concerns**: Each crate owns a distinct architectural layer (backend API, agents, routing, knowledge graph, etc.)
2. **Independent Testing**: 218+ tests can run in parallel across crates without cross-dependencies
3. **Code Reusability**: Common utilities (`vapora-shared`) used by all crates without circular dependencies
4. **Team Parallelization**: Multiple teams can develop on different crates simultaneously
5. **Dependency Clarity**: Explicit `Cargo.toml` dependencies prevent accidental coupling
6. **Version Management**: Centralized in root `Cargo.toml` via workspace dependencies prevents version skew

---

## Alternatives Considered

### ❌ Monolithic Single Crate
- All code in `/src/` directory
- **Pros**: Simpler build, familiar structure
- **Cons**: Tight coupling, slow compilation, testing all-or-nothing, hard to parallelize development

### ❌ Multi-Repository
- Separate Git repos for each component
- **Pros**: Independent CI/CD, clear boundaries
- **Cons**: Complex synchronization, dependency management nightmare, monorepo benefits lost (atomic commits)

### ✅ Workspace Monorepo (CHOSEN)
- 13 crates in single Git repo
- **Pros**: Best of both worlds—clear boundaries + atomic commits + shared workspace config

---

## Trade-offs

**Pros**:
- ✅ Clear architectural boundaries prevent accidental coupling
- ✅ Parallel compilation and testing (cargo builds independent crates concurrently)
- ✅ 218+ tests distributed across crates, faster feedback
- ✅ Atomic commits across multiple components
- ✅ Single CI/CD pipeline, shared version management
- ✅ Easy debugging: each crate is independently debuggable

**Cons**:
- ⚠️ Workspace compilation overhead: must compile all dependencies even if using one crate
- ⚠️ Slightly steeper learning curve for developers new to workspaces
- ⚠️ Publishing to crates.io requires publishing each crate individually (not a concern for internal project)

---

## Implementation

**Cargo.toml Workspace Configuration**:
```toml
[workspace]
resolver = "2"

members = [
    "crates/vapora-backend",
    "crates/vapora-frontend",
    "crates/vapora-shared",
    "crates/vapora-agents",
    "crates/vapora-llm-router",
    "crates/vapora-mcp-server",
    "crates/vapora-tracking",
    "crates/vapora-worktree",
    "crates/vapora-knowledge-graph",
    "crates/vapora-analytics",
    "crates/vapora-swarm",
    "crates/vapora-telemetry",
]

[workspace.package]
version = "1.2.0"
edition = "2021"
rust-version = "1.75"
```

**Shared Dependencies** (defined once, inherited by all crates):
```toml
[workspace.dependencies]
tokio = { version = "1.48", features = ["rt-multi-thread", "macros"] }
serde = { version = "1.0", features = ["derive"] }
surrealdb = { version = "2.3", features = ["kv-mem"] }
```

**Key Files**:
- Root: `/Cargo.toml` (workspace definition)
- Per-crate: `/crates/*/Cargo.toml` (individual dependencies)

---

## Verification

```bash
# Build entire workspace (runs in parallel)
cargo build --workspace

# Run all tests across workspace
cargo test --workspace

# Check dependency graph
cargo tree

# Verify no circular dependencies
cargo tree --duplicates

# Build single crate (to verify independence)
cargo build -p vapora-backend
cargo build -p vapora-agents
cargo build -p vapora-llm-router
```

**Expected Output**:
- All 13 crates compile without errors
- 218+ tests pass
- No circular dependency warnings
- Each crate can be built independently

---

## Consequences

### Short-term
- Initial setup requires understanding workspace structure
- Developers must navigate between crates
- Testing must run across multiple crates (slower than single tests, but faster than monolith)

### Long-term
- Easy to add new crates as features grow (already added doc-lifecycle, mcp-server in later phases)
- Scaling to multiple teams: each team owns 2-3 crates with clear boundaries
- Maintenance: updating shared types in `vapora-shared` propagates to all dependent crates automatically

### Maintenance
- **Dependency Updates**: Update in `[workspace.dependencies]` once, all crates use new version
- **Breaking Changes**: Require coordination across crates if shared types change
- **Documentation**: Each crate should document its dependencies and public API

---

## References

- [Cargo Workspace Documentation](https://doc.rust-lang.org/cargo/reference/workspaces.html)
- Root `Cargo.toml`: `/Cargo.toml`
- Crate list: `/crates/*/Cargo.toml`
- CI validation: `.github/workflows/rust-ci.yml` (builds `--workspace`)

---

**Architecture Pattern**: Monorepo with clear separation of concerns
**Related ADRs**: ADR-002 (Axum), ADR-006 (Rig), ADR-013 (Knowledge Graph)