|
1 | | -This documentation explains the architecture of Reactime v4. |
| 1 | +# Reactime v4 Architecture |
2 | 2 |
|
| 3 | +## Brief |
| 4 | +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. 🏃🏾💨 |
3 | 5 |
|
4 | | - |
| 6 | +### Main Structure |
| 7 | + |
| 8 | +In the *src* folder, there are three directories we care about: *app*, *backend*, and *extension*. |
| 9 | +``` |
| 10 | +src/ |
| 11 | +├── app/ # Frontend code |
| 12 | +│ │ # |
| 13 | +│ ├── __tests__/ # |
| 14 | +│ ├── actions/ # Redux action creators |
| 15 | +│ ├── components/ # React components |
| 16 | +│ ├── constants/ # |
| 17 | +│ ├── containers/ # More React components |
| 18 | +│ ├── reducers/ # Redux mechanism for updating state |
| 19 | +│ ├── styles/ # |
| 20 | +│ ├── index.tsx # App component |
| 21 | +│ ├── module.d.ts # |
| 22 | +│ └── store.tsx # |
| 23 | +│ |
| 24 | +├── backend/ # "Backend" code |
| 25 | +│ │ # |
| 26 | +│ ├── __tests__/ # |
| 27 | +│ ├── types/ # Typescript interfaces |
| 28 | +│ ├── helpers.js # |
| 29 | +│ ├── index.ts # Starting point for backend functionality |
| 30 | +│ ├── index.d.ts # |
| 31 | +│ ├── linkFiber.ts # |
| 32 | +│ ├── masterState.js # Component action record interface |
| 33 | +│ ├── module.d.ts # |
| 34 | +│ ├── package.json # |
| 35 | +│ ├── puppeteerServer.js # |
| 36 | +│ ├── readme.md # |
| 37 | +│ ├── timeJump.ts # Rerenders DOM based on snapshot from background |
| 38 | +│ └── tree.ts # Custom structure to send to background |
| 39 | +│ |
| 40 | +├── extension/ # Chrome Extension code |
| 41 | +│ │ # |
| 42 | +│ ├── build/ # Destination for bundles |
| 43 | +│ │ # and manifest.json (Chrome config file) |
| 44 | +│ │ # |
| 45 | +│ ├── background.js # |
| 46 | +│ └── contentScript.ts # |
| 47 | +└── |
| 48 | +``` |
5 | 49 |
|
6 | | -In the src folder, there are three directories: app, backend, and extension. |
| 50 | +1. The *app* folder is responsible for the Single Page Application that you see when you open the chrome dev tools under the Reactime tab. |
7 | 51 |
|
| 52 | +2. The *backend* folder contains the set of all scripts that we inject into our "target" application via `background.js` |
| 53 | + - In Reactime, its main role is to generate data and handle time-jump requests from the background script in our *extension* folder. |
8 | 54 |
|
9 | | -The app folder is responsible a SPA that you see when you open the chrome dev tools under the Reactime tab. |
| 55 | +3. The *extension* folder is where the `contentScript.js` and `background.js` are located. |
| 56 | + - 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. |
| 57 | + - These two files help us handle requests both from the web browser and from the Reactime extension itself |
10 | 58 |
|
11 | | -The backend folder is responsible for generating data and handle time-jump request from the background.js scripts in extension. |
| 59 | +Still unsure about what contents scripts and background scripts do for Reactime, or for a chrome extensions in general? |
| 60 | + - The implementation details [can be found](./src/extension/background.js) [in the files](./src/extension/contentScript.ts) themselves. |
| 61 | + - We also encourage you to dive into [the official Chrome Developer Docs](https://developer.chrome.com/home). Some relevant sections are reproduced below: |
12 | 62 |
|
13 | | -The extension folder is where the contentscript.js and background.js located. These two files belongs to Chrome internal to help us handle requests both from the web browser and from the chrome dev tools. Unsure what contentscripts and backgroundscripts are? The details implementation are documented in the files themselves. |
| 63 | +> Content scripts are files that run in the context of web pages. |
| 64 | +> |
| 65 | +> By using the standard Document Object Model (DOM), they are able to **read** details of the web pages the browser visits, **make changes** to them and **pass information back** to their parent extension. ([Source](https://developer.chrome.com/extensions/content_scripts)) |
14 | 66 |
|
15 | | -> Content scripts are files that run in the context of web pages. By using the standard Document Object Model (DOM), they are able to read details of the web pages the browser visits, make changes to them and pass information to their parent extension. Source: https://developer.chrome.com/extensions/content_scripts |
| 67 | +- One helpful way to remember a content script's role in the Chrome ecosystem is to think: a *content* script is used to read and modify a target web page's rendered *content*. |
16 | 68 |
|
17 | | ->A background page is loaded when it is needed, and unloaded when it goes idle. Some examples of events include: |
| 69 | +>A background page is loaded when it is needed, and unloaded when it goes idle. |
| 70 | +> |
| 71 | +> Some examples of events include: |
18 | 72 | >The extension is first installed or updated to a new version. |
19 | 73 | >The background page was listening for an event, and the event is dispatched. |
20 | 74 | >A content script or other extension sends a message. |
21 | | ->Another view in the extension, such as a popup, calls runtime.getBackgroundPage. |
22 | | ->Once it has been loaded, a background page will stay running as long as it is performing an action, such as calling a Chrome API or issuing a network request. Additionally, the background page will not unload until all visible views and all message ports are closed. Note that opening a view does not cause the event page to load, but only prevents it from closing once loaded. Source: https://developer.chrome.com/extensions/background_pages |
| 75 | +>Another view in the extension, such as a popup, calls `runtime.getBackgroundPage`. |
| 76 | +> |
| 77 | +>Once it has been loaded, a background page will stay running as long as it is performing an action, such as calling a Chrome API or issuing a network request. |
| 78 | +> |
| 79 | +> Additionally, the background page will not unload until all visible views and all message ports are closed. Note that opening a view does not cause the event page to load, but only prevents it from closing once loaded. ([Source](https://developer.chrome.com/extensions/background_pages)) |
| 80 | +
|
| 81 | +- You can think of background scripts serving a purpose analogous to that of a **server** in the client/server paradigm. Much like a server, our `background.js` listens constantly for messages (i.e. requests) from two main places: |
| 82 | + 1. The content script |
| 83 | + 2. The chrome extension "front-end" **(*NOT* the interface of the browser, this is an important distinction.)** |
| 84 | +- 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. |
23 | 85 |
|
24 | | -Just to reiterate, contentscript is use to read and modify information that is rendered on the webpage, and a host of other objects. Background is very similar to client/server concept in which background is behaving like a server, listening to request from the contentscipt and **the request from the "front-end" of the chrome dev tools in the reactime tab (not the interface of the browser, this is an important distinction.)** In other words, background script works directly with the React Dev Tools, whereas contentscript works with the interface of the browser. |
| 86 | + |
| 87 | +### Data Flow |
25 | 88 |
|
26 | 89 | The general flow of data is described in the following steps: |
27 | 90 |
|
28 | | -1. When the background bundle is loaded from the browser, it injects a script into the dom. This script uses a technique called [throttle](https://medium.com/@bitupon.211/debounce-and-throttle-160affa5457b) to get the data of the state of the app to send to the contentscript every specified miliseconds (in our case, it's 70ms). |
| 91 | + |
29 | 92 |
|
| 93 | +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). |
30 | 94 |
|
31 | | -2. This contentscript always listens to the messages being sent from the interface of the browser. The recieved data will immediately be sent to the background script which then update an object that persist in background script called **tabsObj**. Each time tabsObj is updated, the most recent version will be sent to the interface of reactime dev tools written the app folder. |
| 95 | +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. |
32 | 96 |
|
33 | | -3. Likewise, when there is an action from Reactime dev tools - a jump request for example, a request will be made to the background script which is proxied to the content script. This content script will talk to the browser interface to request the *state* that the user wants to jump to. One important thing to note here is that the jump action will be excecuted in the backend script because it has direct access to the DOM. |
| 97 | +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. |
| 98 | + - 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