Following up on my reading through the developer's guide, which led me to take some notes, I have been reading the developer documentation, Client architecture, and kept documenting my thoughts and comments.
Here is the notes I gathered while reading the document. Hopefully this could be used as feedback to help better the documentation to smoothen wannabe contributors (like me) journey into Cryptpad.
Introduction section
The client architecture is split in 3 levels:
- The worker is common to all CryptPad tabs opened in the same browser and each tab contains its own "outer" and iframes.
- Outer corresponds to the base level, i.e. the HTML file loaded first by the browser.
- Two iframes are loaded per tab, the first one containing the whole application interface, the second one containing the interface elements that must display confidential data.
Seems like a reminder of the https://docs.cryptpad.org/en/dev_guide/general.html#level-structure .
However, now the documentation is talking about TWO iframes...
Also, the order in which things are introduced is different (and more out-of-order): Outer first, and worker last made sense.
The diagram seems to be the same as in the previous section. The same remarks apply.
"Worker" section
"Workflow" subsection
SharedWorker technology allows a single "Webworker" to be shared between all the tabs opened on the same origin
Some links to relevant documentation (on MDN for example) could be useful here. Also, mixing the use of unquoted and quoted words makes it slightly harder to read (it's unclear which are made up, or which refer to real technology names).
The "workers" represent code executed in a different thread from the main tab, allowing heavier calculations to be performed without slowing down the page.
Why are "workers" plural here?
"Content" subsection
The "worker" level is opened from the "outer" level, once initial checks have been performed. It's the "outer" code that decides which type of worker it can use (SharedWorker, WebWorker or nothing). It then initializes the worker with the "connector" corresponding to this type of worker:
Again, regarding styling: terminology should be identified consistently. Here it uses quotes instead of bold case seen elsewhere.
An asynchronous communication channel is first initialized with the "outer" level to receive commands and send events.
In the diagram presented before, there is no arrow pointing from outer to the worker, while this sentence says that communication is bidirectional.
A Store object is created
What is this "Store object"? Is this "Store" part of the Web API, the WebWorker API?
Is it a custom Cryptpad object? It seems so, reading the code: var Store = window.Cryptpad_Store = {};... Wording could be more accurate here.
Access to content stored in the server database is done with commands to the worker. This content represents:
- User account data (name, personal keys, access to the different modules) - Drive, shared folders, contacts, team access keys, profile, settings, etc.
- Team data - Drive, shared folders, members, metadata (avatar and team name)
- Access to documents for each CryptPad tab opened in the browser
It's unclear which structure are holding such content, and if this content is saved in the frontend.
Is the "Store" mentioned above simply holding functions to communicate with the backend through commands to the worker, or does it also implement some storage?
"Outer" section
"Workflow" subsection
Again, in this section, I expected to see stuff in bold rather than quoted.
Each application starts with its own file "index.html". This file will load the basic JavaScript code, usually located in a "main.js" file for the application.
I misread that the first time, and it's the next sentence that made it click.
I originally thought that "application" here referred to generic web applications, while it seems to be talking specifically about Cryptpad applications. I guess it could be made more explicit: "Each Cryptpad application (e.g. code, form, presentation, etc.) ...".
The "main.js" file of each application will then start loading the main code, common to all applications at the "outer" level.
Now I would really like to know what those applications are, and how they interface with Cryptpad.
What is "the main code" referring to? A common wrapper around applications that is maintained by Cryptpad's team? Something else?
Hopefully, in the following "Inner" subsection, there will be more details about these points.
In the same way as for the worker, these 2 levels can send commands or events to each other.
The diagram simply mentions postMessage. Do each of the levels hold a reference to the other, or is a BroadcastChannel being used, or else?
The "outer" level thus functions as an intermediary between the interface and the "local database".
What is "the interface"?
Also, what is "the local database"? I am guessing now that the "Store" mentioned earlier does indeed hold data, and is not just a set of functions.
"Content" subsection
but the decryption itself is done in "outer".
I feel like I am really missing the threat model: From https://docs.cryptpad.org/en/dev_guide/general.html#level-structure , "The base level, called "outer" in the code. This level is loaded with the "unsafe" URL". If decryption is done in the "outer" level, it means that sensitive content will be loaded in an "unsafe" domain?
"Inner" section
"Workflow" subsection
When a new tab is opened, "outer" will load the main "inner" iframe as soon as possible.
So this seems to imply that there could be several iframes loaded at the same time, somewhat contrary to https://docs.cryptpad.org/en/dev_guide/general.html#level-structure which talks about a singular iframe.
Each application has its own page "inner.html" which represents the starting point of the iframe.
Again, it would be nice to have more context about these applications integration
Are these "inner.html" responsible of starting them? What's the relationship with the main.js mentioned earlier?
End of document thoughts
I didn't quite find what I was looking for (list of folders/files in the repository containing the client), but still gained better understanding of the architecture of the client.
