Skip to content

Commit d44e7df

Browse files
committed
Make final changes to developer README
1 parent 1aa8749 commit d44e7df

File tree

1 file changed

+25
-19
lines changed

1 file changed

+25
-19
lines changed

src/README.md

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
1-
# Reactime v4 Architecture
1+
# Developer README
22

33
## Brief
44
Our mission at Reactime is to maintain and iterate constantly, but never at the expense of future developers.<br />We know how hard it is to quickly get up to speed and onboard in a new codebase.<br />So, here are some helpful pointers to help you hit the ground running. 🏃🏾💨
55

6-
## Main Structure
6+
## Quick Tips
7+
- _Before_ beginning development, especially on teams, make sure to configure your linter and code formatting to conform to one unified setting (We recommend [the Airbnb style guide](https://github.com/airbnb/javascript)!) This will make reviewing PRs much more readable and less error-prone.
8+
9+
## File Structure
710

811
In the *src* folder, there are three directories we care about: *app*, *backend*, and *extension*.
912
```
@@ -53,9 +56,26 @@ src/
5356
- Like regular web apps, Chrome Extensions are event-based. The background script is where one typically monitors for browser triggers (e.g. events like closing a tab, for example). The content script is what allows us to read or write to our target web application, usually as a result of [messages passed](https://developer.chrome.com/extensions/messaging) from the background script.
5457
- These two files help us handle requests both from the web browser and from the Reactime extension itself
5558

56-
Still unsure about what contents scripts and background scripts do for Reactime, or for a chrome extensions in general?
57-
- The implementation details [can be found](./extension/background.js) [in the files](./extension/contentScript.ts) themselves.
58-
- We also encourage you to dive into [the official Chrome Developer Docs](https://developer.chrome.com/home). Some relevant sections are reproduced below:
59+
## Data Flow Architecture
60+
61+
The general flow of data is described in the following steps:
62+
63+
![demo](../assets/AppStructureDiagram.png)
64+
65+
1. When the background bundle is loaded by the browser, it executes a script injection into the dom. (see section on *backend*). This script uses a technique called [throttle](https://medium.com/@bitupon.211/debounce-and-throttle-160affa5457b) to send state data from the app to the content script every specified milliseconds (in our case, this interval is 70ms).
66+
67+
2. The content script always listens for messages being passed from the extension's target application. Upon receiving data from the target app, the content script will immediately forward this data to the background script which then updates an object called `tabsObj`. Each time `tabsObj` is updated, its latest version will be passed to Reactime, where it is processed for displaying to the user by the *app* folder scripts.
68+
69+
3. Likewise, when Reactime emits an action due to user interaction -- a "jump" request for example -- a message will be passed from Reactime via the background script to the content script. Then, the content script will pass a message to the target application containing a payload that represents the state the user wants the DOM to reflect or "jump" to.
70+
- One important thing to note here is that this jump action must be dispatched in the target application (i.e. *backend* land), because only there do we have direct access to the DOM.
71+
72+
73+
## Chrome Developer Resources
74+
Still unsure about what content scripts and background scripts do for Reactime, or for a chrome extensions in general?
75+
- The implementation details [can be found](./extension/background.js) [in the source files](./extension/contentScript.ts) themselves.
76+
- We also encourage you to dive into [the official Chrome Developer Docs](https://developer.chrome.com/home).
77+
78+
Some relevant sections are reproduced below:
5979

6080
> Content scripts are files that run in the context of web pages.
6181
>
@@ -79,17 +99,3 @@ Still unsure about what contents scripts and background scripts do for Reactime,
7999
1. The content script
80100
2. The chrome extension "front-end" **(*NOT* the interface of the browser, this is an important distinction.)**
81101
- In other words, a background script works as a sort of middleman, directly maintaining connection with its parent extension, and acting as a proxy enabling communication between it and the content script.
82-
83-
84-
## Data Flow
85-
86-
The general flow of data is described in the following steps:
87-
88-
![demo](../assets/AppStructureDiagram.png)
89-
90-
1. When the background bundle is loaded by the browser, it executes a script injection into the dom. (see section on *backend*). This script uses a technique called [throttle](https://medium.com/@bitupon.211/debounce-and-throttle-160affa5457b) to send state data from the app to the content script every specified milliseconds (in our case, this interval is 70ms).
91-
92-
2. The content script always listens for messages being passed from the extension's target application. Upon receiving data from the target app, the content script will immediately forward this data to the background script which then updates an object called `tabsObj`. Each time `tabsObj` is updated, its latest version will be passed to Reactime, where it is processed for displaying to the user by the *app* folder scripts.
93-
94-
3. Likewise, when Reactime emits an action due to user interaction -- a "jump" request for example -- a message will be passed from Reactime via the background script to the content script. Then, the content script will pass a message to the target application containing a payload that represents the state the user wants the DOM to reflect or "jump" to.
95-
- One important thing to note here is that this jump action must be dispatched in the target application (i.e. *backend* land), because only there do we have direct access to the DOM.

0 commit comments

Comments
 (0)