Add Architecture document

README.md

@@ -29,7 +29,8 @@ For a real world example, check the open source [Chie](https://chie.app) app.
 
 ## Docs
 
-* [Sign mac app](https://github.com/yue/boilerplate-nodejs/blob/main/docs/sign-mac-app.md)
+* [Architecture](https://github.com/yue/boilerplate-nodejs/blob/main/docs/architecture.md)
+* [How to sign macOS app in CI](https://github.com/yue/boilerplate-nodejs/blob/main/docs/sign-mac-app.md)
 * [Yue documents (external link)](http://libyue.com/docs/latest/js/)
 
 ## License

docs/architecture.md

@@ -0,0 +1,33 @@
+# Architecture of boilerplate-nodejs
+
+This project consists of 2 parts: the pure-js part which is responsible for
+controlling native UI (similar to the main process in Electron apps), and the
+web part that gets loaded in the browser (i.e. renderer process).
+
+Note that while this project uses browser to show UI, it is also possible to
+get rid of the browser part and use pure native UI.
+
+## Source code structure
+
+* `app/` - The web app.
+* `src/` - The TypeScript code for creating window and loading the web app.
+* `node_modules/` - Third party Node.js modules.
+* `out/` - Executables generated by `npm run build` are put here.
+
+## Testing and packaging
+
+A custom Node.js runtime [Yode](https://github.com/yue/yode) is used for running
+the app, due to [the lack of ability to run GUI message loop](https://libyue.com/docs/latest/js/guides/getting_started.html)
+in upstream Node.js runtime.
+
+When you run `npm start`, it uses Yode to invoke `ts-node` to compile and
+execute the project on the fly. This is usually how you do app development.
+
+There is also `npm run build`, which generates an executable (or app bundle on
+macOS) in the `out/` directory that can be shipped to users. The js code are
+packaged into ASAR archive and appended to the executable under this mode, so
+the environment is slightly different from `npm start` and sometimes errors
+may happen, you should test your app with this command before publishing it.
+
+Finally there is `npm run dist`, which just runs `npm run build` and then create
+a ZIP archive.

docs/sign-mac-app.md

@@ -1,4 +1,4 @@
-# Sign mac app
+# How to sign macOS app in CI
 
 This template has a GitHub workflow that signs and the notorizes the app bundle,
 and you need to set following secrects in repo/orgnaization to make it work.