From 49a3b71919b2944fd05dfdcfc7ffebb3a3923c91 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Tue, 8 Sep 2026 17:25:44 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=B1=20docs:=20Hold=20Module=20Boundari?= =?UTF-8?q?es,=20Configurable=20Levers=20and=20Injected=20Dependencies=20(?= =?UTF-8?q?#15754)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ๐Ÿงถ docs: Keep the Breadcrumb Carve-Out in AGENTS.md The template and CLAUDE.md both say that naming the merged pull request which caused a bug is history the reader needs, not a breadcrumb. The condensed AGENTS.md version dropped that half, leaving a flat rule against referencing earlier work, which is the file most agents actually read. * ๐Ÿงฑ docs: Hold the Database Boundary and Make New Levers Configurable Workspace Boundaries said where database logic lives but not what may cross the line, so Mongoose types travel outward in exported signatures and make the storage engine part of each module's public API. That is the tax a second engine would pay, and it is cheaper to stop widening than to unwind: packages/api already imports mongoose in dozens of non-test files, while client carries none. Nothing in either file mentioned configSchema or librechat.yaml either, so a new limit or toggle lands as a constant by default and an operator cannot reach it. Both rules now sit in Workspace Boundaries, with the configurability half cross-referenced from the definition of done. Condensed into AGENTS.md as Module boundaries and configuration. * ๐Ÿ”Œ docs: Take Dependencies, Do Not Reach for Them Client State Ownership already tells a frontend feature to accept app-global state through props rather than reaching into the store, and gives the reason: it is what lets the feature move to its own workspace later without a rewrite. The backend had no equivalent, and neither file mentioned dependency injection at all. Backend modules now carry the same rule one layer down, with createModels(mongoose) as the shape to copy and the static singletons under packages/api/src/mcp as the shape to stop extending. Integrations get it explicitly: an injected provider SDK, storage backend, vector store or OAuth server makes a second implementation a new argument instead of a new branch, and lets a test substitute at the boundary rather than mocking the module that holds it. --- AGENTS.md | 27 +++++++++++++++++++++++++-- CLAUDE.md | 27 ++++++++++++++++++++++++++- 2 files changed, 51 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3b972e233e..6db760e607 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,8 +13,9 @@ default branch, so close linked issues by hand. Worktrees share one stash stack, Write the description for a reader who has not followed the branch: what breaks, what triggers it, how it behaves after the change, then one or two views of the mechanism โ€” a focused diff, a call tree, a shallow file tree, or a Mermaid sequence. Keep only what the change carries, and describe -the code as it stands rather than narrating earlier commits or review rounds. The formats and -examples live in `.github/pull_request_template.md`. +the code as it stands rather than narrating earlier commits or review rounds. Naming the merged +pull request that caused the bug is not the same thing; that is history the reader needs. The +formats and examples live in `.github/pull_request_template.md`. ## Review and completion @@ -47,6 +48,28 @@ changed. `packages/client` excludes `*.spec.ts(x)` and `*.test.ts(x)` from typec `npm run sort-imports` with no arguments rewrites every source root โ€” pass the paths you touched. See `CLAUDE.md` under "Typechecking" and "Formatting". +## Module boundaries and configuration + +Database contracts belong to `packages/data-schemas`. Keep Mongoose types (`FilterQuery`, +`Types.ObjectId`, `Document`) out of exported signatures in `packages/api`, `packages/data-provider` +and `client`, because they make the storage engine part of that module's public API. Take and return +plain typed objects and express the query behind a data-schemas method. The boundary already leaks +across `packages/api`, so stop widening it rather than rewriting what exists; the client carries none +of it and must stay that way. + +New levers ship configurable: a limit, timeout, toggle or capability introduced in code earns a field +on `configSchema` (`packages/data-provider/src/config.ts`) so it can be set in `librechat.yaml`, with +a default that reproduces today's behavior. Hard-coded constants and env-only switches need a reason. +Modules take their dependencies rather than reaching for them: code in `packages/api` receives its +config, database methods and clients from the caller, the way `createModels(mongoose)` receives the +app's connection, instead of importing app singletons or reading global state. Integrations (provider +SDKs, storage backends, vector stores, OAuth servers) arrive through an interface the caller +supplies, so a second implementation is a new argument instead of a new branch. The static singletons +under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy. This is the +backend half of client state ownership: pass it in, do not reach for it. + +See `CLAUDE.md` under "Workspace Boundaries". + ## Frontend theming and styling For frontend work, compose existing `@librechat/client` primitives and variants before adding diff --git a/CLAUDE.md b/CLAUDE.md index 1667036b2e..b4ff8546d8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,6 +25,29 @@ The source code for `@librechat/agents` (major backend dependency, same team) li - Database-specific shared logic goes in `/packages/data-schemas`. - Frontend/backend shared API logic (endpoints, types, data-service) goes in `/packages/data-provider`. - Build data-provider from project root: `npm run build:data-provider`. +- **Database contracts stay inside `/packages/data-schemas`.** A Mongoose type in an exported + signature โ€” `FilterQuery`, `Types.ObjectId`, `Document`, `HydratedDocument` โ€” makes the storage + engine part of that module's public API, and every consumer then depends on Mongo instead of on + the data it needs. Take and return plain typed objects, and express the query behind a + data-schemas method. The boundary already leaks across dozens of files in `/packages/api`, so the + rule is to stop widening it rather than to rewrite what exists; `/client` carries none of it and + must stay that way. +- **New levers ship configurable.** A limit, timeout, toggle or capability introduced in code earns + a field on `configSchema` (`packages/data-provider/src/config.ts`) so an operator can set it in + `librechat.yaml`, with a default that reproduces today's behavior. Hard-coded constants and + env-only switches need a reason. The schema is also what keeps one definition of the value instead + of a constant, a fallback and a doc line that drift apart. +- **A backend module takes its dependencies, it does not reach for them.** Code in `/packages/api` + should receive its config, database methods and clients from the caller the way + `createModels(mongoose)` receives the app's connection, rather than importing app singletons or + reading global state. A module the caller constructs can be tested without a running app and moved + to another workspace without a rewrite; one that calls `getInstance()` can do neither. This is the + backend half of "Client State Ownership" โ€” pass it in, do not reach for it. The static singletons + under `packages/api/src/mcp` are the shape to stop extending, not a pattern to copy. +- **Integrations arrive through an interface the caller supplies.** A provider SDK, storage backend, + vector store or OAuth server is injected, so a second implementation is a new argument instead of + a new branch in shared code, and a test can exercise the real logic against a substitute at the + boundary rather than mocking the module that holds it. --- @@ -98,7 +121,9 @@ findings that keep arriving mean the subsystem needs a sweep, not another patch. ARIA intact, and compose shared primitives and semantic theme roles before adding local styling (see "Frontend Rules"). Custom styling that proves unavoidable still supports light/dark and reduced motion. -- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior. +- Preserve existing defaults, configuration compatibility, stored data, and mixed-version behavior, + and expose any new lever through `configSchema` rather than a constant (see "Workspace + Boundaries"). - Make the fix the smallest one consistent with the patterns already in the file, and test the behavior that was missed rather than the line a reviewer pointed at. - **Report what you actually ran**: the pushed head, the local checks from "Testing" and