# Feature requirements for Radicle

**Definition 1**: Radicle network is build of users. There are two kinds of users: *radicle users*, running radicle node, and *git users*, which do not run radicle node.

**Requirement 2**: ordinary *git users* must be able to have an access to **public** git repositories hosted in the radicle network - and must not be able to access **private** repositories.

*Prerequisites*: git users
- must have a git installed locally;
- may be behind NAT;
- may or may not use Tor;
- must know radicle-specific project ID;
- must know IPv4 (what about IPv6) address of the radicle node seeding that repository; the node must be exposed to the public network;
- do not get access to issues, PRs, discussions etc.

Access to the repository for git users is performed by running
`git clone <protocol>://<seeding-radicle-node-ip>/<radicle-project-id>`

How the ordinary git users discover radicle seed node IP address and project id remains outside of the scope of radicle protocol design and feature requirements.

**Requirement 3**: radicle users must run radicle nodes on the server or their desktop (but never on a mobile)

**Definition 4**: radicle node may be a *seeding* node if it is the primary source for at least one of the repositories for the network. Otherwise it is called *leecher*.

**Requirement 5**: radicle nodes may run behind Tor and/or NAT and still remain fully operational (except access by git users, as specified above in the claim 1 prerequisites).

> **Consequence 5.1**: Seeding nodes must either:
> - be using Tor and do not being accessible by ordinary git users
> - be behind NAT and do not being accessible by ordinary git users - but connect to bootstrap node to be accessible to other radicle nodes via NAT traversal mechanisms
> - be publicly avaliable without NAT and Tor.
>
> **Consequence 5.2**: radicle nodes seeding repositories are required to be permanently online, i.e. run on private servers or in a cloud. The rest of radicle nodes ("leechers") may go offline and can be run on a desktop.

**Requirement clarification 6**: Do we need "leeching" radicle nodes to be able to be embedded into mobile apps?

**Requirement 7**: Radicle nodes at launch connect to bootstrap nodes via P2P protocol and extract inventory, providing delta between the full list of the projects and their seeders known to the bootstrap node and the list known to the connecting node. The same procedure is repeat with several bootstrap nodes, thus a new peer synchronizes its network topology.

> **Requirement clarification 7.1**: how the seeders synchronize their network map between themselves? How they acquire trust to the information sources about new projects?

**Requirement 8**: radicle nodes ("leechers") can pull git repository from a seeder and subscribe for new updates. The updates will come as a notifications which will require leechers to perform a pro-active pull request to the seeder repository to get the actual update data.

> Subscription is an active process triggered by the user running radicle node. It is performed via trusted RPC connection.

> **Consequence 8.1**: radicle nodes are not required to maintain permanent connections to each other; however propagation of repository updates in the network between seeders - and with leachers - may happen in a "push"-style only when permanent connections are present.

> **Requirement clarification 8.2**: if the users can't embed radicle node into mobile app than will require an encrypted RPC transport protocol with authentication.

**Requirement clarification 9**: Does a radicle node need to expose Web UI to the repository, issues etc?

**Requirement 10**: leeching radicle nodes must be able to connect to the seeders hidden behind NAT (even if both the leecher and seeder are behind NAT) and/or by using Tor.

---

digraph {
  boot [label = "bootstrap node" color = red]
  seed [label = "seed node" color = red]
  leech [label = "leech node"]
  user
  
  seed -> boot [label = "P2P"]
  leech -> seed [label = "P2P, Git", color = red]
  leech -> boot [label = "P2P"]
  user -> leech [label = "RPC"]
}

red denotes permament connection or runtime