🧱 docs: Hold Module Boundaries, Configurable Levers and Injected Dependencies (#15754)

* 🧶 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.
This commit is contained in:
Danny Avila 2026-09-08 17:25:44 -04:00 • committed by GitHub
parent 2dd7ca478a
commit 49a3b71919
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 51 additions and 3 deletions

View file

@ -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

View file

@ -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