From 7fd1f9aa5f2c1f649af02bddb5cf25e616801dbb Mon Sep 17 00:00:00 2001 From: KernelDeimos Date: Mon, 24 Feb 2025 15:56:50 -0500 Subject: [PATCH] doc: document backend key locations --- doc/contributors/structure.md | 1 + src/backend/doc/contributors/structure.md | 84 +++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 src/backend/doc/contributors/structure.md diff --git a/doc/contributors/structure.md b/doc/contributors/structure.md index 6b005c289..c939fdd48 100644 --- a/doc/contributors/structure.md +++ b/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: diff --git a/src/backend/doc/contributors/structure.md b/src/backend/doc/contributors/structure.md new file mode 100644 index 000000000..01bd01051 --- /dev/null +++ b/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 `Module.js` file and one or more +`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.