From 3b51f1a536def20d3861b750745722bff7b4d81d Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Fri, 23 Oct 2026 18:54:29 +0000
Subject: [PATCH 1/2] docs(hub): define backend code conventions

Co-authored-by: Nishiki Liu <hello@nshki.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 hub/docs/backend-architecture.md | 28 ++++++++++++++++++++++++++++
 hub/docs/coding-conventions.md   |  2 ++
 2 files changed, 30 insertions(+)
 create mode 100644 hub/docs/backend-architecture.md

diff --git a/hub/docs/backend-architecture.md b/hub/docs/backend-architecture.md
new file mode 100644
index 00000000..0fe6a175
--- /dev/null
+++ b/hub/docs/backend-architecture.md
@@ -0,0 +1,28 @@
+# Code architecture conventions
+
+Organize backend functions into repositories, integrations, utilities, and domains. Each layer has a clear job and rules for which other layers it may use.
+
+| Layer | Responsibility | Directory example |
+| --- | --- | --- |
+| Repositories | Functions that interact with the database. Each repository directory represents one RESTful resource. | `repositories/user/get-user/index.ts` |
+| Integrations | Functions that interact with an API or SDK. Each integration directory represents one API or SDK service. | `integrations/github/get-user/index.ts` |
+| Utilities | General functions reusable elsewhere in the codebase. | `utils/format-timestamp/index.ts` |
+| Domains | Business logic functions that may compose repositories, integrations, and utilities. | `domains/user/get-user-profile/index.ts` |
+
+## Import boundaries
+
+```text
+Domains -> Repositories -> Utilities
+        -> Integrations -> Utilities
+        -> Utilities
+```
+
+Repositories and integrations may import only utilities from elsewhere in the backend. Utilities may import only other utilities. Domains may import any of these layers, including other domains. Each layer may also use built-in libraries and npm packages.
+
+These rules apply to imported types as well as functions. A repository must not call another repository or an integration. An integration must not call a repository. Keep business decisions in domains rather than moving them into utilities to get around these rules.
+
+## Directory structure
+
+Put each function in a directory named with lowercase words and hyphens, such as `get-user`. Keep `index.ts`, its tests, and its types together. Group repository functions by resource and integration functions by API or SDK service, as shown above. Import from each function's directory, not from a shared file that re-exports its neighbors.
+
+Add directories when their functions are needed. Do not add empty implementations just to fill out the structure.
diff --git a/hub/docs/coding-conventions.md b/hub/docs/coding-conventions.md
index dfc8e857..9b8d41e1 100644
--- a/hub/docs/coding-conventions.md
+++ b/hub/docs/coding-conventions.md
@@ -2,6 +2,8 @@
 
 Follow the [shared coding conventions](../../docs/coding-conventions.md). This guide adds Hub's Rails, TypeScript, and interface rules.
 
+The rebuild's [code architecture conventions](backend-architecture.md) define repositories, integrations, utilities, and domains and their import boundaries.
+
 ## Rails
 
 - Check Rails, Ruby, and existing repository helpers before adding custom token, validation, serialization, or lifecycle code. Use custom behavior when built-in utilities cannot meet requirements such as one-time use, revocation, digest-only storage, or database constraints.

From db77756bb35c244a2415dfcf93a70b26d8acf57f Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Fri, 23 Oct 2026 19:02:55 +0000
Subject: [PATCH 2/2] docs(hub): show code layers with Mermaid

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 hub/docs/backend-architecture.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/hub/docs/backend-architecture.md b/hub/docs/backend-architecture.md
index 0fe6a175..74e4a5d9 100644
--- a/hub/docs/backend-architecture.md
+++ b/hub/docs/backend-architecture.md
@@ -11,10 +11,13 @@ Organize backend functions into repositories, integrations, utilities, and domai
 
 ## Import boundaries
 
-```text
-Domains -> Repositories -> Utilities
-        -> Integrations -> Utilities
-        -> Utilities
+```mermaid
+flowchart LR
+  Domains --> Repositories
+  Domains --> Integrations
+  Domains --> Utilities
+  Repositories --> Utilities
+  Integrations --> Utilities
 ```
 
 Repositories and integrations may import only utilities from elsewhere in the backend. Utilities may import only other utilities. Domains may import any of these layers, including other domains. Each layer may also use built-in libraries and npm packages.