Note : This document describes the original API-first architecture with a REST backend. The project has shifted to a TUI-first, dual-target architecture (native terminal + WASM web). This document is kept for reference but the current approach does not use a web framework like Axum.
After evaluating the options, here are the recommended technologies for robit:
Component Choice Rationale
Web Framework Axum Tokio-native, excellent middleware, type-safe Note N/A Not needed for TUI architecture - see revised stackAsync Runtime Tokio Industry standard, comprehensive ecosystem Serialization Serde Standard, zero-cost abstractions Error Handling thiserror + anyhow Structured errors where needed, ergonomic elsewhere
Component Choice Rationale
Database PostgreSQL Robust, ACID, JSON support Database Client SQLx Compile-time checked, async-native Cache Redis Fast, pub/sub, rate limiting Redis Client redis (with tokio-comp features)Native async Migrations sqlx-cli Integrated with SQLx
Component Choice Rationale
LLM Trait System Custom Multi-provider support, unified interface HTTP Client reqwest Built on hyper, async-native, widely used Streaming futures + tokio-stream Async stream handling JSON Schema schemars Generate schemas from types Validation validator Input validation with derives
Component Choice Rationale
Primary Sandbox Wasmtime Fast, capability-based, safe Secondary Sandbox gVisor Strong isolation for complex code Authentication jsonwebtoken + custom API keyFlexible auth strategies Hashing argon2 Modern, secure password hashing Secrets HashiCorp Vault clientProduction secret management
Component Choice Rationale
Logging tracing Structured, async-aware Log Output tracing-subscriber Flexible formatting Metrics metrics + metrics-exporter-prometheus Standard observability Distributed Tracing tracing-opentelemetry Jaeger/Zipkin compatible
Component Choice Rationale
Configuration config Layered config (file, env, CLI) CLI Parsing clap v4Derive macros, comprehensive Environment dotenvy Development environment variables Testing HTTP wiremock Mock HTTP servers Testing DB testcontainers Real database in tests Property Tests proptest Fuzzing and edge cases Linting clippy Rust best practices Formatting rustfmt Consistent style
Component Choice Rationale
Container Distroless or Alpine Minimal attack surface Orchestration Kubernetes Industry standard Service Mesh Linkerd or Istio (optional)mTLS, observability TLS rustls Pure Rust, audited
[package]
name = "robit"
version = "0.1.0"
edition = "2021"
rust-version = "1.75"
[dependencies]
# Core async runtime
tokio = { version = "1", features = ["full"] }
tokio-stream = "0.1"
# Web framework
axum = { version = "0.7", features = ["ws"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["trace", "cors", "limit"] }
# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
# Database
sqlx = { version = "0.7", features = ["runtime-tokio", "tls-rustls", "postgres", "uuid", "chrono"] }
redis = { version = "0.24", features = ["tokio-comp", "connection-manager"] }
# HTTP client
reqwest = { version = "0.11", features = ["json", "stream", "rustls-tls"] }
# Validation
validator = { version = "0.16", features = ["derive"] }
schemars = "0.8"
# Security
jsonwebtoken = "9"
argon2 = "0.5"
# Sandboxing
wasmtime = "16"
wasmtime-wasi = "16"
# Observability
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
metrics = "0.22"
metrics-exporter-prometheus = "0.13"
# Error handling
thiserror = "1.0"
anyhow = "1.0"
# Utilities
config = "0.14"
clap = { version = "4.5", features = ["derive", "env"] }
uuid = { version = "1.6", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
once_cell = "1.19"
[dev-dependencies]
tokio-test = "0.4"
wiremock = "0.6"
testcontainers = "0.15"
proptest = "1.4"
robit/
├── Cargo.toml
├── README.md
├── docs/ # mdbook documentation
│ ├── book.toml
│ └── src/
├── crates/ # Workspace members
│ ├── robit-core/ # Core engine
│ ├── robit-api/ # HTTP API server
│ ├── robit-cli/ # Command-line tool
│ ├── robit-sandbox/ # Sandboxing implementations
│ ├── robit-llm/ # LLM provider abstractions
│ └── robit-types/ # Shared types
├── migrations/ # SQLx migrations
├── scripts/ # Development scripts
├── docker/ # Container configurations
└── tests/ # Integration tests
Initialize Cargo workspace
Set up development environment
Create core types crate
Implement LLM trait system
Build basic API server scaffold
Add first sandbox implementation (WASM)
Implement conversation management
Add authentication layer
Create CLI tool
Write integration tests
See Phase 1: Foundation for detailed implementation plan.