# 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
