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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧱 docs: Hold Module Boundaries, Configurable Levers and Injected Dependencies (#15754)
Danny Avila49a3b71919b2
diff --git a/AGENTS.md b/AGENTS.mdindex 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 calltree, 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 stylingFor frontend work, compose existing `@librechat/client` primitives and variants before addingdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 andreduced 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 thebehavior 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