Expand architecture section to introduce room IDs, room aliases, user IDs, events and federation.

1 files changed, 68 insertions, 33 deletions

diff --git a/docs/specification.rst b/docs/specification.rst
index d650683efc..c1559c886c 100644
--- a/docs/specification.rst
+++ b/docs/specification.rst
@@ -9,7 +9,9 @@ TODO(Introduction) : Matthew
 
 Architecture
 ============
-- Sending a message from A to B
+
+Clients transmit data to other clients through home servers (HSes). Clients do not communicate with each
+other directly.
 
 ::
 
@@ -26,39 +28,42 @@ Architecture
        |                  |<--------( HTTP )-----------|                  |
        +------------------+        Federation          +------------------+
 
-- Client is an end-user (web app, mobile app) which uses C-S APIs to talk to the home server.
-  A given client is typically responsible for a single user.
-- A single user is represented by a User ID, scoped to the home server which allocated the account.
-  User IDs MUST have @ prefix; looks like @foo:domain - domain indicates the user's home
-  server. 
-- Home server provides C-S APIs and has the ability to federate with other HSes.
-  Typically responsible for N clients.
-- Federation's purpose is to share content between interested HSes; no SPOF. 
-- Events are actions within the system. Typically each action (e.g. sending a message)
-  correlates with exactly one event. Each event has a ``type`` string. 
-- ``type`` values SHOULD be namespaced according to standard Java package naming conventions, 
-  with a ``.`` delimiter e.g. ``com.example.myapp.event``
-- Events are typically send in the context of a room.
+A "Client" is an end-user, typically a human using a web application or mobile app. Clients use the
+"Client-to-Server" (C-S) API to communicate with their home server. A single Client is usually
+responsible for a single user account. A user account is represented by their "User ID". This ID is
+namespaced to the home server which allocated the account and looks like::
+
+  @localpart:domain
+
+The ``localpart`` of a user ID may be a user name, or an opaque ID identifying this user.
+
+
+A "Home Server" is a server which provides C-S APIs and has the ability to federate with other HSes.
+It is typically responsible for multiple clients. "Federation" is the term used to describe the
+sharing of data between two or more home servers.
+
+Data in Matrix is encapsulated in an "Event". An event is an action within the system. Typically each
+action (e.g. sending a message) correlates with exactly one event. Each event has a ``type`` which is
+used to differentiate different kinds of data. ``type`` values SHOULD be namespaced according to standard
+Java package naming conventions, e.g. ``com.example.myapp.event``. Events are usually sent in the context
+of a "Room".
 
 Room structure
 --------------
 
-A room is a conceptual place where users can send and receive messages. Rooms 
-can be created, joined and left. Messages are sent to a room, and all 
-participants in that room will receive the message. Rooms are uniquely 
-identified via a room ID. There is exactly one room ID for each room. Each
-room can also have an alias. Each room can have many aliases.
+A room is a conceptual place where users can send and receive events. Rooms 
+can be created, joined and left. Events are sent to a room, and all 
+participants in that room will receive the event. Rooms are uniquely 
+identified via a "Room ID", which look like::
 
-- Room IDs MUST have ! prefix; looks like !foo:domain - domain is simply for namespacing,
-  the room does NOT reside on any one domain. NOT human readable.
+  !opaque_id:domain
 
-- Room Aliases MUST have # prefix; looks like #foo:domain - domain indicates where this
-  alias can be mapped to a room ID. Key point: human readable / friendly.
+There is exactly one room ID for each room. Whilst the room ID does contain a
+domain, it is simply for namespacing room IDs. The room does NOT reside on the
+domain specified. Room IDs are not meant to be human readable.
 
-- Aliases can be queried on the domain they specify, which will return a room ID if a
-  mapping exists. These mappings can change.
-
-::
+The following diagram shows an ``m.room.message`` event being sent in the room 
+``!qporfwt:matrix.org``::
 
        { @alice:matrix.org }                             { @bob:domain.com }
                |                                                 ^
@@ -73,18 +78,48 @@ room can also have an alias. Each room can have many aliases.
        |   matrix.org     |<-------Federation------->|   domain.com     |
        +------------------+                          +------------------+
                 |       .................................        |
-                |______|         Shared State            |_______|
-                       |  Room ID: !qporfwt:matrix.org   |
+                |______|     Partially Shared State      |_______|
+                       | Room ID: !qporfwt:matrix.org    |
                        | Servers: matrix.org, domain.com |
                        | Members:                        |
                        |  - @alice:matrix.org            |
                        |  - @bob:domain.com              |
                        |.................................|
 
-- Federation's goal is to maintain the shared state. Don't need FULL state in order
-  to be a part of a room.
-- Introduce the DAG.
-- Events are wrapped in PDUs.
+Federation maintains shared state between multiple home servers, such that when an event is
+sent to a room, the home server knows where to forward the event on to, and how to process
+the event. Home servers do not need to have completely shared state in order to participate 
+in a room. State is scoped to a single room, and federation ensures that all home servers 
+have the information they need, even if that means the home server has to request more 
+information from another home server before processing the event.
+
+Room Aliases
+------------
+
+Each room can also have multiple "Room Aliases", which looks like::
+
+  #room_alias:domain
+
+A room alias "points" to a room ID. The room ID the alias is pointing to can be obtained
+by visiting the domain specified. Room aliases are designed to be human readable strings
+which can be used to publicise rooms. Note that the mapping from a room alias to a 
+room ID is not fixed, and may change over time to point to a different room ID. For this
+reason, Clients SHOULD resolve the room alias to a room ID once and then use that ID on
+subsequent requests.
+
+::
+
+          GET    
+   #matrix:domain.com      !aaabaa:matrix.org
+           |                    ^
+           |                    |
+    _______V____________________|____
+   |          domain.com            |
+   | Mappings:                      |
+   | #matrix >> !aaabaa:matrix.org  |
+   | #golf >> !wfeiofh:sport.com    |
+   | #bike >> !4rguxf:matrix.org    |
+   |________________________________|
 
        
 Identity