# Architecture Overview
## Purpose
Rho v1 is a local-first collaboration system for secure human and agent interaction around repositories, tools, messages, and protected execution.
It is designed to start small:
- GitHub-backed identity and repos
- repo-local file protocols
- text-file messaging
- sandboxed tool and agent execution
- middleware hooks for human approval
- synthetic/mock data generation from real inputs
## System Shape
Rho should be built as one Rust workspace with a shared core and multiple CLI entry points.
At the conceptual level, the system has eight layers:
1. Identity layer
`rho id`
2. Crypto layer
`rho crypto`
3. Authorization and trust layer
`rho auth`
4. Collaboration substrate
`rho repo`, `rho messages`, `rho tools`
5. Execution layer
`rho run`, `rho agent`
6. Data layer
`rho data`
7. Diagnostics and setup layer
`rho doctor`
8. Policy and integration layer
`rho middleware`, `rho telegram`
## Core Architectural Bet
Rho should use:
- repos as collaboration spaces
- files as protocol
- deterministic host-side executors for protected actions
- agents as untrusted planners unless explicitly proven otherwise
- crypto as a separate seam from identity and repo policy
- authorization and trust as a separate seam from both repo structure and execution
## What Counts As A Collaboration Space
A repo is the primary unit of collaboration in v1.
A repo may contain:
- identity metadata
- tool definitions
- messages
- requests
- approvals
- manifests
- mock or shareable data
- released outputs
The repo is not trusted just because it exists.
Protected reads and writes still pass through Rho policy, tool contracts, and sandbox rules.
## Diagnostics And Setup
Rho also needs one operational command that helps users get to a working baseline without turning setup logic into every other command.
`rho doctor` should handle:
- dependency checks
- guided install help
- key and identity setup checks
- repo layout validation
- agent health checks
- sandbox readiness checks
It is an operator utility, not a policy engine.
## Authorization And Trust
Rho needs a distinct command that decides whether an actor is allowed to do something.
`rho auth` should handle:
- repo policy evaluation
- trust-on-first-use pairing
- first-connection approval hooks
- allow and deny decisions
- permanent block lists
This is separate from:
- `rho id`, which says who an actor claims to be
- `rho crypto`, which proves possession of keys
- `rho repo`, which defines repo-local rules
`rho auth` decides whether those claims and rules permit an action.
## Main Runtime Split
The most important split in Rho is:
- planning and proposing
- protected execution and release
Agents can:
- read allowed files
- propose messages
- propose tool calls
- request protected actions
Agents should not directly:
- self-approve access to protected inputs
- self-approve release of sensitive outputs
- bypass sandbox and middleware policy
## Ideas Explicitly Deferred
- rich realtime sync transport
- low latency tcp connectivity
- heavy GUI-driven orchestration
- eager execution notebook interface
- broad workflow engine abstraction
- multi-party secure compute
- multiple overlapping execution modes
- multi-repo manifest orchestration
- daemon/control-plane architecture
- publisher ACL plus subscriber materialization model
- encrypted shadow or vault filesystem materialization
- Nextflow-style workflow backends
- bioscript-style domain packaging and generation