diff --git a/SUMMARY.md b/SUMMARY.md
index e5e30a1..5a3a49c 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -46,10 +46,12 @@
## Developing With NATS
* [Concepts](developer/concepts/intro.md)
+ * [Subject-Based Messaging](developer/concepts/subjects.md)
* [Publish-Subscribe](developer/concepts/pubsub.md)
* [Request-Reply](developer/concepts/reqreply.md)
- * [Using Queues to Share Work](developer/concepts/queue.md)
- * [Subject-Based Messaging](developer/concepts/subjects.md)
+ * [Queue Groups](developer/concepts/queue.md)
+ * [Acknowledgements](developer/concepts/acks.md)
+ * [Sequence Numbers](developer/concepts/seq_num.md)
* [Connecting](developer/connecting/intro.md)
* [Connecting to the Default Server](developer/connecting/default_server.md)
diff --git a/developer/concepts/acks.md b/developer/concepts/acks.md
new file mode 100644
index 0000000..fe5ff27
--- /dev/null
+++ b/developer/concepts/acks.md
@@ -0,0 +1,31 @@
+# Acknowledgements
+
+In a system with at-most-once semantics, there are times when messages are lost. If your application is doing request-reply then it can simply use timeouts to handle network and application failures. When you are using one-way messaging the easiest way to insure message delivery is to turn it into a request-reply with the concept of an acknowledgement message, or ACKS. In NATS an ACK can simply be an empty message, a message with no body.
+
+
+digraph nats_request_reply {
+ rankdir=LR
+
+ subgraph {
+ publisher [shape=box, style="rounded", label="Publisher"];
+ }
+
+ subgraph {
+ subject [shape=circle, label="Subject"];
+ reply [shape=circle, label="Reply"];
+ {rank = same subject reply}
+ }
+
+ subgraph {
+ sub1[shape=box, style="rounded", label="Subscriber"];
+ }
+
+ publisher -> subject [label="msg1"];
+ publisher -> reply [style="invis", weight=2];
+ subject -> sub1 [label="msg1"];
+ sub1 -> reply [label="ack"];
+ reply -> publisher;
+}
+
+
+Because the ACK can be empty it can take up very little network bandwidth, but the idea of the ACK turns a simple fire-and-forget into a fire-and-know world where the sender can be sure that the message was received by the other side, or with [scatter-gather](reqreply.md), several other sides.
\ No newline at end of file
diff --git a/developer/concepts/intro.md b/developer/concepts/intro.md
index 54fc1b7..23724c7 100644
--- a/developer/concepts/intro.md
+++ b/developer/concepts/intro.md
@@ -1,6 +1,8 @@
# NATS Messaging Concepts
-NATS messaging involves the electronic exchange of data among computer applications and provides a layer between the application and the underlying physical network. Application data is encoded as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers. A subscriber can process a NATS message synchronously or asynchronously, depending on the client library used.
+NATS messaging involves the electronic exchange of data among computer applications and provides a layer between the application and the underlying physical network. Application data is encoded as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers.
+
+By providing a central, easily discovered broker, NATS makes it easy for programs to communicate across different environments, languages, and systems. All clients have to do is connect to the broker, subscribe or publish to a subject and process messages. With this simple design, NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume.
graph nats {
@@ -17,8 +19,4 @@ graph nats {
}
-Asynchronous processing uses a callback message handler to process messages. When a message arrives, the registered callback handler receives control to process the message. The client or the consuming application is not blocked from performing other work while it is waiting for a message. Asynchronous processing lets you create multi-threaded dispatching designs.
-
-Synchronous processing requires that application code explicitly call a method to process an incoming message. Typically the message request is a blocking call that suspends processing until a message becomes available and if no message is available, the period for which the message processing call blocks, would be set by the client. Synchronous processing is typically used by a server whose purpose is to wait for and process incoming request messages and to send replies to the requesting application.
-
-NATS makes it easy for programs to communicate across different environments, languages, and systems because all a client has to do is parse the message. NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume.
\ No newline at end of file
+NATS core offers an **at most once** quality of service. If a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. By default, NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use NATS Streaming, or build the additional reliability into your client(s) yourself.
diff --git a/developer/concepts/pubsub.md b/developer/concepts/pubsub.md
index f4145b7..04137f8 100644
--- a/developer/concepts/pubsub.md
+++ b/developer/concepts/pubsub.md
@@ -1,10 +1,6 @@
-# Publish Subscribe
+# Publish-Subscribe and Fan-Out
-NATS implements a publish subscribe message distribution model as a one-to-many communication. A publisher sends a message on a subject and any active subscriber listening on that subject receives the message. Subscribers can also register interest in wildcard subjects that work a bit like a regular expression (but only a bit). NATS and NATS Streaming combine to offer two qualities of service:
-
-- **At Most Once Delivery (NATS w/TCP reliability)** - In the basic NATS platform, if a subscriber is not listening on the subject (no subject match), or is not active when the message is sent, the message is not received. NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use NATS Streaming, or build the additional reliability into your client(s) yourself.
-
-- **At Least Once Delivery (NATS Streaming)** - Some applications require higher levels of service and more stringent delivery guarantees but at the potential cost of lower message throughput and higher end-to-end delivery latency. These applications rely on the underlying messaging transport to ensure that messages are delivered to subscribers irrespective of network outages or whether or not a subscriber is offline at a particular point in time.
+NATS implements a publish-subscribe message distribution model for one-to-many communication. A publisher sends a message on a subject and any active subscriber listening on that subject receives the message. Subscribers can also register interest in wildcard subjects that work a bit like a regular expression (but only a bit). This one-to-many pattern is sometimes called fan-out.
digraph nats_pub_sub {
diff --git a/developer/concepts/queue.md b/developer/concepts/queue.md
index e5617f1..7331ef2 100644
--- a/developer/concepts/queue.md
+++ b/developer/concepts/queue.md
@@ -4,6 +4,8 @@ NATS provides a load balancing feature called queue subscriptions. Using queue s
To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. As messages on the registered subject are published, one member of the group is chosen randomly to receive the message. Although queue groups have multiple subscribers, each message is consumed by only one.
+One of the great features of NATS is that queue groups are defined by the subscribers, not on the server. Applications can create new queue groups without any server change.
+
Queue subscribers are ideal for auto scaling as you can add or remove them anytime, without any configuration changes or restarting the server or clients.
diff --git a/developer/concepts/reqreply.md b/developer/concepts/reqreply.md
index b26ea39..e9f3ac9 100644
--- a/developer/concepts/reqreply.md
+++ b/developer/concepts/reqreply.md
@@ -1,6 +1,6 @@
-# Request Reply
+# Request-Reply and Scatter-Gather
-NATS supports two flavors of request reply messaging: point-to-point or one-to-many. Point-to-point involves the fastest or first to respond. In a one-to-many exchange, you can set a limit on the number of responses the requestor may receive or use a timeout to limit on the speed of the response.
+NATS supports two flavors of request reply messaging: point-to-point or one-to-many. Point-to-point involves the fastest or first to respond. In a one-to-many exchange, you can set a limit on the number of responses the requestor may receive or use a timeout to limit on the speed of the response. One-to-many request reply is sometimes called *scatter gather*.
In a request-response exchange the publish request operation publishes a message with a reply subject expecting a response on that reply subject. Many libraries allow you to use a function that will automatically wait for a response with a timeout. You can also handle that waiting process yourself.
diff --git a/developer/concepts/seq_num.md b/developer/concepts/seq_num.md
new file mode 100644
index 0000000..81501c9
--- /dev/null
+++ b/developer/concepts/seq_num.md
@@ -0,0 +1,25 @@
+# Sequence Numbers
+
+A common problem for one-to-many messages is that a message can get lost or dropped due to a network failure. A simple pattern for resolving this situation is to include a sequence id with the message. Receivers can check the sequence id to see if they miss anything.
+
+
+digraph nats_pub_sub {
+ rankdir=LR
+ publisher [shape=box, style="rounded", label="Publisher"];
+ subject [shape=circle, label="Subject"];
+ sub [shape=box, style="rounded", label="Subscriber"];
+
+ publisher -> subject [label="updates.1"];
+ publisher -> subject [label="updates.2"];
+ publisher -> subject [label="updates.3"];
+
+ subject -> sub [label="updates.*"];
+}
+
+
+In order to really leverage sequence ids there are a few things to keep in mind:
+
+* Each sender will have to use their own sequence
+* If possible, receivers should be able to ask for missing messages by id
+
+With NATS you can embed sequence ids in the message, or you can include them in the subject. For example, a sender can send messages to `updates.1`, `updates.2`, etc... and the subscribers can listen to `updates.*` and optionally parse the subject to determine the sequence id.
\ No newline at end of file
diff --git a/developer/concepts/subjects.md b/developer/concepts/subjects.md
index 1c4323e..1fe94f0 100644
--- a/developer/concepts/subjects.md
+++ b/developer/concepts/subjects.md
@@ -73,3 +73,7 @@ digraph g {
subject -> sub3 [label="msg"];
}