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

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

    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:

    [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):

    [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

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