diff --git a/lib/store/localstorage.js b/lib/store/localstorage.js
index b138a7180..2804d3e4c 100644
--- a/lib/store/localstorage.js
+++ b/lib/store/localstorage.js
@@ -1,11 +1,32 @@
 "use strict";
 /**
- * This is an internal module.
+ * This is an internal module. Implementation details:
+ *
+ * Room data is stored as follows:
+ *   room_data_$ROOMID : { event_id1: Event, event_id2: Event, ... }
+ *   room_timeline_$ROOMID : [event_id1, event_id2, event_id3, ...]
+ * User data is stored as follows:
+ *   user_$USERID : User
+ * Sync token:
+ *   sync_token : $TOKEN
+ *
+ * Retrieving earlier messages requires a Room which then finds the earliest
+ * event_id in the timeline. Then, room_timeline_$ROOMID is inspected to grab
+ * the N earlier event_ids. The event data is then extracted from
+ * room_data_$ROOMID.
+ *
+ * TODO: room_data_$ROOMID may get Large. Should we shard the data off the event
+ *       ID? E.g. hash event ID mod 10 and extract from buckets? We really want
+ *       events close together to be in the same bucket, so perhaps abusing the
+ *       origin_server_ts (which is fine since it's just for optimisation) would
+ *       be a better approach?
+ *
  * @module store/localstorage
  */
 
 /**
- * Construct a localstorage store.
+ * Construct a local storage store, capable of storing rooms and users.
+ *
  * @constructor
  * @throws if the global 'localStorage' does not exist.
  */