doc: document backend key locations

Author: KernelDeimos

doc/contributors/structure.md

@@ -29,6 +29,7 @@ Every directory under `/tools` is [an npm "workspaces" module](https://docs.npmj
 
 Some of these modules are core pieces of Puter:
 - **Puter's backend** is [`/src/backend`](/src/backend)
+  - See [key locations in backend documentation](/src/backend/doc/contributors/structure.md)
 - **Puter's GUI** is [`/src/gui`](/src/gui)
 
 Some of these modules are apps:

src/backend/doc/contributors/structure.md

@@ -0,0 +1,84 @@
+# Puter Backend - Directory Structure
+
+## MFU - Most Frequently Used
+
+These locations under `/src/backend/src` are the most important
+to know about. Whether you're contributing a feature or fixing a bug,
+you might only need to look at code in these locations.
+
+### `modules` directory
+
+The `modules` directory contains Puter backend kernel modules only.
+Everything in here has a `<name of>Module.js` file and one or more
+`<name of>Service.js` files.
+
+> **Note:** A "backend kernel module" is simply a class understood by
+  [`src/backend/src/Kernel.js`](../../src/Kernel.js)
+  that registers a number of "Service" classes.
+  You can look at [Puter's init file](../../../../tools/run-selfhosted.js)
+  to see how modules are added to Puter.
+
+The `README.md` file inside any module directory is generated with
+the `module-docgen` script in the Puter repo's `/tools` directory.
+The actual documentation for the module exists in jsdoc comments
+in the source files.
+
+Each module might contain these directories:
+- `doc/` - additional module documentation, like sample requests
+- `lib/` - utility code that isn't a Module or Service class.
+  This utility code may be exposed by a service in the module
+  to Puter's runtime import mechanism for extension support.
+
+### `services` directory
+
+This directory existed before the `modules` directory. Most of
+the services here go on a module called **CoreModule**
+(CoreModule.js is directly in `/src/backend/src`), but this
+directory can be thought of as "services that are not yet
+organized in a distinct module".
+
+### `routers` directory
+
+While routes are typically registered by Services, the implementation
+of a route might be placed under `src/backend/src/routers` to keep the
+service's code tidy or for legacy reasons.
+
+These are some services that reference files under `src/backend/src/routers`:
+- [PermissionAPIService](../../src/services/PermissionAPIService.js) - 
+  This service registers routes that allow a user to configure permissions they
+  grant to apps and groups. This is a relatively recent case of using files under the
+  `routers` directory to clean up the service.
+- [UserProtectedEndpointsService](../../src/services/web/UserProtectedEndpointsService.js) -
+  This service follows a slightly different approach where files under
+  `routers/user-protected` contain an "endpoint specification" instead of an express
+  handler function. This might be good inspiration for future routes.
+- [PuterAPIService](../../src/services/PuterAPIService.js) -
+  This service is a catch-all for routes that existed before separation of concerns
+  into backend kernel modules.
+  
+### `filesystem` directory
+
+The filesystem is likely the most complex portion of Puter's source code. This code
+is in its own directory as a matter of circumstance more than intention. Ideally the
+filesystem's concerns will be split across a few modules as we prepare to add
+support for mounting different file systems and improved cache behavior.
+For example, Puter's native filesystem implementation should be mostly moved to
+`src/backend/src/modules/puterfs` as we continue this development.
+
+Since this directory is in flux, don't trust this documentation completely.
+If you're contributing to filesystem,
+[tag @KernelDeimos on the community Discord](https://discord.gg/PQcx7Teh8u)
+if you have questions.
+
+These are the key locations in the `filesystem` directory:
+- `FSNodeContext.js` - When you have a reference to a file or directory in backend code,
+  it is an instance of the FSNodeContext class.
+- `ll_operations` - Runnables that implement the behavior of a filesystem operation.
+  These used to include the behavior of Puter's filesystem, but they now delegate
+  the actual behavior to the implementation in the `.provider` member of a
+  FSNodeContext (filesystem node / a file or directory) so that we can eventually
+  support "mountpoints" (multiple filesystem implementations).
+- `hl_operations` - Runnables that implement the behavior of higher-level versions
+  of filesystem operations. For example, the high-level mkdir operation might create
+  multiple directories in chain; the high-level write might change the name of the
+  file to avoid conflicts if you specify the `dedupe_name` flag.