Add peer awareness design document

design/peer-awareness.md

@@ -0,0 +1,42 @@
+# Peer Awareness
+
+Target version: Yorkie 0.1.2
+
+## Use case
+
+When multiple users edit a single document, the users want to know who is connected and what is being edited by the peers. For example, in Google Docs, the ID and profile of the user editing together are displayed in the upper-right.
+
+## How to use
+
+Users can pass metadata along with client options when creating a client.
+
+```typescript
+const client = yorkie.createClient('https://yorkie.dev/api', {
+  metadata: {
+    username: 'hackerwins'
+  }
+});
+```
+
+Then the users create a document in the usual way and attach it to the client.
+
+```typescript
+const doc = yorkie.createDocument('examples', 'codemirror');
+await client.attach(doc);
+```
+
+When a new peer registers or leaves, `peers-changed` event is fired, and the other peer's clientID and metadata can be obtained from the event.
+
+```typescript
+client.subscribe((event) => {
+  if (event.name === 'peers-changed') {
+    const peers = event.value[doc.getKey().toIDString()];
+    for (const [clientID, metadata] of Object.entries(peers)) {
+      console.log(clientID, metadata);
+    }
+  }
+});
+```
+
+## Implementation
+...