diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 0e8912767..157ce931a 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -1,20 +1,26 @@
-# SwimOS Development Guid
+# SwimOS Development Guide
## Dependencies
+
[Formatting](https://github.com/rust-lang/rustfmt): `rustup component add rustfmt`
[Clippy](https://github.com/rust-lang/rust-clippy): `rustup component add clippy`
[Tarpaulin](https://github.com/xd009642/tarpaulin) `cargo install cargo-tarpaulin`
## Unit tests
+
#### Basic: `cargo test`
+
#### With coverage: `cargo tarpaulin --ignore-tests -o Html -t 300`
## Lint
+
#### Manual
+
1) `cargo fmt --all -- --check`
2) `cargo clippy --all-features --workspace --all-targets -- -D warnings`
-#### Automatic (before commit):
+#### Automatic (before commit):
+
- Install hook: `sh ./install-commit-hook.sh`
- Remove hook: `sh ./remove-commit-hook.sh`
diff --git a/README.md b/README.md
index 1860e6f4a..0bc1b3857 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,11 @@
-
-
+# SwimOS
+
+
The Swim Rust SDK contains software framework for building stateful applications that can be interacted
with via multiplexed streaming APIs. It is built on top of the [Tokio asynchronous runtime](https://tokio.rs/)
and a Tokio runtime is required for any Swim application.
-Each application consists of some number of stateful agents, each of which runs as a separate Tokio task
-and can be individually addressed by a URI. An agent may have both public and private state which can either
-be held solely in memory or, optionally, in persistent storage. The public state of the agent consists of a
-number of lanes, analogous to a field in a record. There are multiple kinds of lanes that, for example, lanes
-containing single values and those containing a map of key-value pairs.
-
-The state of any lane can be observed by establishing a link to it (either from another agent instance or a
-dedicated client). A established link will push all updates to the state of that lane to the subscriber and
-will also allow the subscriber to request changes to the state (for lane kinds that support this). Links
-operate over a web-socket connection and are multiplexed, meaning that links to multiple lanes on the same
-host can share a single web-socket connection.
-
[![SwimOS Crates.io Version][swimos-badge]][swimos-crate]
[![SwimOS Client Crates.io Version][swimos-client-badge]][swimos-client-crate]
[![SwimOS Form Crates.io Version][swimos-form-badge]][swimos-form-crate]
@@ -35,6 +24,94 @@ host can share a single web-socket connection.
[Website](https://swimos.org/) | [Developer Guide](https://www.swimos.org/server/rust/developer-guide/) | [Server API Docs](https://docs.rs/swimos/latest/swimos/) | [Client API Docs](https://docs.rs/swimos_client/latest/swimos_client/)
+## What is SwimOS?
+
+SwimOS is a framework for building stateful applications from data streams and provides the ability to execute logic
+when the state changes and to observe only the data that you are interested in.
+
+SwimOS applications observes one, or more, streams of events and uses them to build up a model of some other system in
+the external world and it mains an internal state which in many cases will be bounded in size. As each event is observed
+by the application, it updates its knowledge of the system and records that information in the state.
+
+The state of the application is partitioned into a number of independent "agents" each of which consists of a collection
+of "lanes" which store either single values or maps of key-value pairs. For very large applications, the agents can be
+split across multiple processes over multiple hosts. Every lane is individually addressable, both from within the
+applications and externally using a websocket connection. It is possible for a client to both alter the state of a lane
+and to subscribe to a feed of changes from it. Subscribers receive push notifications each time a changes is made and do
+no need to poll to receive them.
+
+Agents are not passive repositories of state and can also have user-specified behaviour. Each agent, and lane, has a
+number of "lifecycle events" to which event handlers can be attached. For example, it would be possible to assign a
+handler to be executed each time the value of a lane changes. These event handlers can alter the values of other lanes
+within the agent, establish communication links to other agents or cause side effects external to the application.
+
+In addition to observing externally provided events, agents may also observe the states of the lanes of other agents. A
+common use of this is the build up a hierarchical view of a system by setting up a tree of agents where each node
+observes the state of its children. For example, consider an application that observes a stream of measurements from
+sensors on a fleet of buses. Each sensor could be represented by an agent which then aggregates to an agent representing
+a bus, then an agent for the bus route and one representing the city. At each level of the tree, aggregate statistics
+could be computed on the fly.
+
+### Demos
+
+#### [Ripple](ripple)
+
+
+
+Ripple is a real-time synchronous shared multiplayer experience built on the Swim platform.
+
+See a hosted version of this app [here](https://ripple.swim.inc).
+
+#### [Traffic](traffic)
+
+
+
+Traffic processes 30,000 data points per second from connected traffic intersections.
+
+See a hosted version of this app [here](https://traffic.swim.inc).
+
+#### [Transit](transit)
+
+
+
+Transit is a demo which monitors public transit vehicles and displays the vehicle's current position and information on
+a map in real-time.
+
+See a hosted version of this app [here](https://traffic.swim.inc).
+
+## Getting Started
+
+Getting started with a new framework isn't the same for everyone but our recommended journey is:
+
+1. Get familiarised with SwimOS concepts [here](https://www.swimos.org/swimos-concepts/).
+2. Read the developer guide [here](https://www.swimos.org/server/rust/developer-guide/).
+3. Read the reference documentation [here](https://www.swimos.org/server/rust/).
+
+The developer guide reference applications are
+available [here](https://github.com/swimos/swim-rust/tree/main/example_apps) and the directory also includes a number of
+extra example applications.
+
+## Sinks and Sources
+
+Swim servers may interact with external systems through the use of connectors. At present, only
+a [Kafka](https://docs.rs/swimos_connector_kafka/latest/swimos_connector_kafka/) ingress and
+egress connector is available but we are working on adding WebSockets, HTTP, and MQTT support.
+
+As SwimOS Agents are capable of executing arbitrary logic after state changes, they are capable of sinking data to any
+data source. Applications may elect to trigger alerts if state reaches a certain condition or to update metrics using
+Prometheus.
+
+## Community
+
+Contributions are welcome that close existing issues in the repository:
+
+- [Good first issues](https://github.com/swimos/swim-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) -
+ simple issues.
+- [Help wanted issues](https://github.com/swimos/swim-rust/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) -
+ issues that are more or less clear to begin working on.
+
+If you have a new idea for something to be implemented, please open an issue to discuss it first before making a PR.
+
## Usage Guides
[Implementing Swim Agents in Rust](docs/agent.md)
@@ -51,7 +128,7 @@ server.
```toml
[dependencies]
-swimos = { version = "0.1.1", features = ["server", "agent"] }
+swimos = { version = "0.1", features = ["server", "agent"] }
```
```rust
@@ -118,7 +195,7 @@ impl ExampleLifecycle {
}
```
-For example, if a Swim client sends an update, with the value `5`, to the agent at the URI `/examples/name` for the
+For example, if a Swim client sends an update with the value `5`, to the agent at the URI `/examples/name` for the
lane `lane`, an instance of `ExampleAgent`, using `ExampleLifecycle`, will be started by the server. The value of the
lane will then be set to `5` and the following will be printed on the console:
@@ -135,4 +212,4 @@ See the [development guide](DEVELOPMENT.md).
## License
-This project is licensed under the [Apache 2.0 License](LICENSE).
+This project is licensed under the [Apache 2.0 License](LICENSE).
\ No newline at end of file
diff --git a/docs/assets/ripple.png b/docs/assets/ripple.png
new file mode 100644
index 000000000..8264f0055
Binary files /dev/null and b/docs/assets/ripple.png differ
diff --git a/docs/assets/traffic.png b/docs/assets/traffic.png
new file mode 100644
index 000000000..ddb2bb708
Binary files /dev/null and b/docs/assets/traffic.png differ
diff --git a/docs/assets/transit.png b/docs/assets/transit.png
new file mode 100644
index 000000000..85edf5db5
Binary files /dev/null and b/docs/assets/transit.png differ