# Architecture Principles

## 1. Preserve Contracts, Not Old Shapes

The old BioVault and SyftBox systems are useful as evidence, not as a blueprint.

Preserve:

- explicit trust boundaries
- local-first collaboration
- file-backed coordination
- approval-mediated protected execution

Do not preserve:

- historical repo boundaries
- daemon sprawl
- naming drift
- oversized orchestration objects

## 2. One Concept, One Name

Rho should aggressively normalize its vocabulary.

Preferred terms:

- `identity`
- `repo`
- `tool`
- `message`
- `request`
- `approval`
- `run`
- `agent`
- `mock data`
- `private data`

Avoid introducing overlapping terms for the same thing.

## 3. Files Are The Protocol

Rho should prefer stable, inspectable file contracts over hidden service protocols.

This means:

- versioned schemas
- explicit ownership of who writes each file
- explicit ownership of who consumes each file
- easy manual inspection and replay

## 4. Agents Are Not The Policy Engine

Agents can interpret, summarize, and propose.

They should not be the final authority for:

- sensitive data access
- protected tool execution
- result release
- identity trust decisions

Those decisions belong to deterministic code plus optional human approval.

## 5. Protected Actions Must Be Host-Executed

If an action is sensitive, Rho should:

1. let the agent request it
2. validate the request deterministically
3. route it through middleware if required
4. execute it in deterministic host code
5. write status back as a file artifact

This is the cleanest lesson from the earlier approval-mediated architecture.

## 6. Local-First Before Network-First

V1 should work well with:

- a local repo
- local files
- local sandboxes
- optional GitHub remotes

Realtime distributed infrastructure can come later.

## 7. Thin Adapters, Thick Contracts

Integrations like Telegram and GitHub should be adapters.

They should not own core product semantics.

Core semantics belong in Rho’s shared manifests and deterministic policy layer.

## 8. Keep Crypto Separate From Identity And Repo Policy

Identity, crypto, and repo policy are related but distinct.

- `rho id` should own who an actor is
- `rho crypto` should own signing and encryption
- `rho auth` should own authorization and trust decisions
- `rho repo` should own collaboration-space policy data

This keeps cryptographic operations from bleeding into every other command.

## 9. Trust And Authorization Must Stay Explicit

Rho should not hide trust and authorization inside ad hoc command behavior.

It should make explicit:

- first-contact trust decisions
- TOFU pairing records
- per-action authorization checks
- permanent deny or block records

The old systems had approval and policy ideas spread across multiple layers.
V1 should give those decisions one obvious home.

## 10. Mock And Private Data Must Be Explicit

The old Twin idea is worth preserving in a simplified form.

Rho v1 should model:

- mock/shareable data
- private/local data
- release-approved outputs

Do not hide these transitions behind convenience wrappers.

## 11. Rust By Default

New command surfaces should be written in Rust by default.

This gives:

- strong typing for request and policy schemas
- better control over process and sandbox management
- easier composition in one workspace
- compilation to unlimited targets such as mobile and web

## 12. V1 Should Deliberately Leave Things Out

The first version should omit features that create conceptual drag before the core trust contracts are stable.

Examples:

- secure compute
- notebook-specialized runtime magic
- event buses
- daemon-first architectures
- broad workflow systems

## 13. Keep Setup And Diagnostics Separate From Core Logic

Commands like `rho id`, `rho crypto`, `rho run`, and `rho agent` should not each reinvent setup and environment validation.

`rho doctor` should provide:

- install guidance
- dependency checks
- readiness checks
- safe repair suggestions

This keeps the core commands narrower and easier to reason about.

## CLI first
we want a light weight cli tool that is easy to run on all platforms.
During development the user should be able to run `./rho` as a shim script that lets them run a debug build of the cargo cli tool for easy development.

Auto update checking should be built in and plugins shoud be updateable independently.

All tools should have the option to speak via json or other well known formats to make agentic use / mcp tools easier.

## Multi-identity from the start
Testing things usually requires at least 2 identities sometimes 3, so these tools should all work with multiple identities by default, either by detecting the one to use based on a context or via a -- cli switch

## Testing
There should be high unit test coverage as well as scenario based testing for multi-user flows and finally we should generate security testing which actively attempts a variety of exploits to ensure that these components compose. That should be able to be run in both automatic mode (using the agents to act as human in the loop, and potentially able to be fooled or with humans during the test suite for human in the loop checks).

Its critical that we find ways to make testing as fast and non-flakey as possible but as real as possible so that applies to e2e and scenario testing.

## OS Support
We should add windows, mac and linux support from day 1 which means running clippy and all tests in CI for all three operating systems and supporting things like windows path normalization, or docker to run linux software etc where needed.
