@@ -1,186 +0,0 @@
1−+++
2−title = "Overview"
3−weight = 1
4−template = "doc.html"
5−+++
6−
7−
8−
9−The architecture of Landscape’s userspace application suite has gone through a
10−number of overhauls in the past few years, and each iteration has gotten closer
11−to a point where Urbit’s userspace can truly perform as a next-generation social
12−suite built entirely on distributed networking and individual-owned personal
13−servers.
14−
15−As of this year, this application suite has arrived at a point where we’re
16−confident both in how all the parts fit together, and confident in the
17−individual parts.
18−
19−## What is Landscape Intended to Be?
20−
21−Landscape is a single suite of userspace applications built to run on top of
22−Urbit. Landscape is maintained by [Tlon](https://tlon.io), a for-profit corporation that helps
23−research Urbit. Landscape is one of many possible application suites for Urbit,
24−and we hope many others emerge that build on top of the Arvo kernel. We plan on
25−making Landscape itself more extensible for user-developers in late 2021.
26−
27−Landscape is specifically a social suite of applications, meant to enable
28−communication and socializing in many forms.
29−
30−## What is Landscape technically composed of?
31−
32−Landscape is composed of two primary parts: its backend, which runs as a suite of userspace applications (also known as Gall agents), and its frontend interface, which runs as a single-page web application. Both the backend and the frontend may be decomposed into their constituent parts for further understanding.
33−
34−### Backend
35−
36−The Landscape backend is implemented as a collection of long-running
37−microservices known as [Gall agents](/docs/arvo/gall/gall). They can be divided into the following,
38−though this is a simplification:
39−
40−- **Graph**: handles storing messages / posts in a non-relational database
41−- **Groups**: organizes people into groups and roles and handles permissioning
42−- **Metadata**: a database join between graphs and groups, it also provides
43− titles and descriptions for graphs and groups
44−- **Contacts**: handles nicknames, profile pictures, and ship-related metadata
45−- **Invites**: a generic inviting subsystem that is used for joining graphs or groups
46−- **Hark**: a notification subsystem for keeping track of read state and
47− notifying users
48−
49−Each of these components are built out using a few microservices that handle
50−more specific responsibilities. These responsibilities can be subdivided into
51−two main categories: [stores](#stores) and [hooks](#hooks). To simply describe
52−the separation of responsibilities, stores are dumb databases (models in MVC)
53−and hooks are for processing data (controllers in MVC).
54−
55−### Stores {#stores}
56−
57−Concisely defined, a store is a dumb database. It does not send outgoing pokes,
58−watches, or peeks, except in an `+on-load` to migrate its state. It does store
59−permanent and/or temporary state, allows incoming peeks/watches to read that
60−data, and allows pokes to modify that data. A store may only accept local reads
61−and writes, not remote ones. It may or may not interact with various kernel
62−modules. Examples include:
63−[graph-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/graph-store.hoon),
64−[group-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/group-store.hoon),
65−[metadata-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/metadata-store.hoon),
66−[contact-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/contact-store.hoon),
67−and
68−[invite-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/invite-store.hoon).
69−
70−### Hooks {#hooks}
71−
72−A hook is a more loosely-defined agent that performs business logic. It should
73−only keep track of a minimal amount of state (_e.g._ active subscriptions). Hooks
74−are used for a variety of purposes in the system, but there are a few important
75−hook patterns to be aware of:
76−
77−#### Pull Hooks
78−
79−A pull-hook syncs data from a remote resource down to a local resource. There is
80−a
81−[pull-hook](https://github.com/urbit/urbit/blob/master/pkg/arvo/lib/pull-hook.hoon)
82−library that drastically simplifies the implementation of such a hook, and is
83−the defacto standard for how to sync down remote data to your ship.
84−
85−#### Push Hooks
86−
87−A push-hook allows remote ships to subscribe to and sync down the information
88−from a local resource. There is a [push-hook
89−library](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/lib/push-hook.hoon)
90−that drastically simplifies the implementation of such a hook, and is the
91−defacto standard for how to make local data available to remote ships.
92−
93−#### Observe Hook
94−
95−The observe-hook subscribes to data coming in from another agent, and starts up
96−a thread of computation every time a subscription update from that agent is
97−received.
98−
99−#### Poke-Proxy Hook
100−
101−The poke-proxy-hook conditionally forwards a poke from a foreign ship to a store
102−on the local ship if the foreign ship has permission to do so.
103−
104−### Major Components
105−
106−#### Groups
107−
108−Groups are the core building block of data permissioning within Landscape. A
109−group is made up of the following fields:
110−
111−```
112−+$ group
113− $: members=(set ship)
114− =tags
115− =policy
116− hidden=?
117− ==
118−```
119−
120−- `members` is a set of ships that are at present in the group
121−- `tags` are strings that may define additional permissions or roles within the
122− group
123−- The `policy` defines whether a group is open to new members, is invite-only, or
124− has some other scheme
125−- `hidden` is a boolean flag that determines whether the group’s lifecycle is
126− attached to a single external resource (such as a chat DM, which when the DM
127− is deleted, the group is deleted too), or whether it has an independent life
128− of its own. This flag also determines whether the group should show up in
129− interfaces as something that may be managed and edited.
130−
131−The `%group-store` holds a map of these groups and allows subscriptions to their
132−data. The group-store may be accessed from foreign ships through the use of the
133−`%group-pull-hook` and `%group-push-hook`. Groups may be joined either by
134−manually discovering and pasting in a group name into the “join group” dialogue
135−in the interface for an open group, or by accepting an invite to an invite-only
136−group. When a group is deleted, all data related to it is deleted or archived as
137−well.
138−
139−#### Graphs
140−
141−Graphs are the core place where we store social user-generated content: chat
142−messages, social network posts, blog posts, links, and eventually multimedia.
143−Graph store is built to be flexible enough to support many different types of
144−“apps” built on top of it, whether you want to have a forum with some friends, a
145−Pinterest equivalent, a more private version of Facebook, a decentralized
146−Reddit, or an even more distributed version of Mastodon. You can read more about
147−graph-store by [viewing the
148−source](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/graph-store.hoon)
149−or reading our [API Reference](/docs/userspace/landscape/reference/graph-store) documentation.
150−
151−The `%graph-store` may be accessed from foreign ships through the use of the
152−`%graph-pull-hook` and `%graph-push-hook`.
153−
154−#### Metadata
155−
156−Metadata is stored in the `%metadata-store`, and is where we store metadata
157−about resources (ex: graphs or groups). We store their display name,
158−description, a color, and the date they were added. We also store what group the
159−resource is associated with, what app the resource is associated with, and what
160−module (display mode) the resource should be used with.
161−
162−Metadata within the broader context of the userspace application suite can best
163−be thought of as a database join between the `%group-store` and the
164−`%graph-store`, as it provides bidirectional indices for querying all of the
165−graphs that a group has, or which group a particular graph is associated with.
166−
167−#### Contacts
168−
169−Contacts are your address book. Individual ships (people) you talk to may have a
170−nickname, a profile picture, or a colored sigil background that helps you
171−identify them in groups, chatrooms, blogs, and collections.
172−
173−#### Invites
174−
175−Invites is a simple subsystem that allows you to send all the details of a given
176−resource (_e.g._ graph or group) to some other ship so that they may join it if
177−they desire to. Invite acceptance is handled with threads that listen to the
178−`%invite-store` using the `%observe-hook` and invite sending is handled with the
179−`%invite-hook`, which allows any ship to send you an invite without any
180−permissions involved.
181−
182−#### Hark
183−
184−Hark is a generic notification and unread-tracking subsystem that currently
185−keeps track of all unread functionality for the system. The `%hark-graph-hook`
186−sends data about `%graph-store` events to `%hark-store`.