Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

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

Danny Avila49a3b71919b2
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