langchainjs: Architecture

Architecture health: 36/100 (F)

Overview

langchainjs is a JavaScript/TypeScript pnpm monorepo, built with React, Next.js, Vite, and Express. It runs as 2 frontends (test-exports-vercel, test-exports-vite) and a CLI (create-langchain-integration), backed by 2 shared packages. It stores data in SQLite, PostgreSQL, MongoDB, Prisma, TypeORM, Redis, and Redis (Upstash), calls Claude, OpenAI, Google Gemini, Groq, Together, Cohere, Ollama, and Mistral across an explicit AI provider boundary, and integrates with Supabase and Firebase. The main structural risks to watch: 15 oversized "god" files and 4 circular import chains. The file with the widest blast radius is libs/langchain-core/src/messages/ai.ts: 114 files depend on it at runtime; types used by 13 modules; part of an import cycle.

_This entire analysis runs on your machine with no AI required. Connect a model provider to also narrate the reasoning and recover decisions._

Where to start

1. libs/create-langchain-integration/index.ts Start here: how the system boots and wires its subsystems together.
2. libs/langchain-core/src/messages/ai.ts Core module: 324 other modules depend on it, so it shapes much of the system.
3. libs/langchain-core/src/messages/human.ts Core module: 241 other modules depend on it, so it shapes much of the system.
4. libs/langchain-core/src/tools/index.ts Core module: 211 other modules depend on it, so it shapes much of the system.
5. libs/langchain-core/src/messages/base.ts Core module: 182 other modules depend on it, so it shapes much of the system.
6. examples/src/multi-agent/router-knowledge-base.ts Key flow: Authentication, a high-risk path that enters at invoke router-knowledge-base.ts (examples/src/multi-agent/router-knowledge-base.ts).
7. environment_tests/scripts/test-runner.ts Key flow: Mission execution, a high-risk path that enters at invoke test-runner.ts (environment_tests/scripts/test-runner.ts).
8. environment_tests/test-exports-cf/src/index.ts Key flow: AI provider call, a high-risk path that enters at invoke index.ts (environment_tests/test-exports-cf/src/index.ts).
9. libs/langchain-core/src/callbacks/manager.ts Change with care: 106 files depend on it at runtime; types used by 21 modules; oversized and doing too much.
10. libs/langchain-core/src/prompts/prompt.ts Change with care: 118 files depend on it at runtime.

System map

flowchart TD
  subgraph sys_boundary["langchainjs"]
    test_exports_vercel["test-exports-vercel"]
    collapsed_units["11 more units, no cross-unit imports: test-exports-cf, test-exports-vite, examples +8"]
  end
  subgraph ai_boundary["AI Provider Boundary"]
    ai_claude{{"Claude"}}
    ai_openai{{"OpenAI"}}
    ai_google_gemini{{"Google Gemini"}}
    ai_groq{{"Groq"}}
    ai_together{{"Together"}}
    ai_cohere{{"Cohere"}}
    ai_ollama{{"Ollama"}}
    ai_mistral{{"Mistral"}}
  end
  ext_supabase{{"Supabase"}}
  ext_firebase{{"Firebase"}}
  test_exports_vercel -->|LLM calls| ai_openai
  class test_exports_vercel frontend
  class ai_claude aiprovider
  class ai_openai aiprovider
  class ai_google_gemini aiprovider
  class ai_groq aiprovider
  class ai_together aiprovider
  class ai_cohere aiprovider
  class ai_ollama aiprovider
  class ai_mistral aiprovider
  class ext_supabase external
  class ext_firebase external
  class collapsed_units muted
  %% collapsed (no cross-unit imports): test-exports-cf, test-exports-vite, examples, create-langchain-integration, SQLite, PostgreSQL, MongoDB, Prisma, TypeORM, Redis, Redis Upstash
  classDef frontend fill:#2563eb,stroke:#93c5fd,color:#fff,stroke-width:2px;
  classDef service fill:#059669,stroke:#6ee7b7,color:#fff,stroke-width:2px;
  classDef store fill:#d97706,stroke:#fcd34d,color:#fff,stroke-width:2px;
  classDef queue fill:#9333ea,stroke:#d8b4fe,color:#fff,stroke-width:2px;
  classDef job fill:#4f46e5,stroke:#a5b4fc,color:#fff,stroke-width:2px;
  classDef external fill:#475569,stroke:#cbd5e1,color:#fff,stroke-width:2px;
  classDef aiprovider fill:#e11d48,stroke:#fda4af,color:#fff,stroke-width:2px;
  classDef library fill:#0891b2,stroke:#67e8f9,color:#fff,stroke-width:2px;
  classDef cli fill:#0d9488,stroke:#5eead4,color:#fff,stroke-width:2px;
  classDef user fill:#64748b,stroke:#e2e8f0,color:#fff,stroke-width:2px;
  classDef muted fill:#334155,stroke:#64748b,color:#cbd5e1,stroke-width:1px;

Critical flows

Application startup medium risk

Entry: process start (libs/create-langchain-integration/index.ts)

Boot wires every subsystem together; a fault here stops the whole process from starting.

sequenceDiagram
  actor C0 as Process
  participant F0 as index.ts
  participant F1 as create-app.ts
  participant F2 as is-folder-empty.ts
  participant F3 as validate-pkg.ts
  C0->>F0: process start
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls

Authentication high risk

Entry: invoke router-knowledge-base.ts (examples/src/multi-agent/router-knowledge-base.ts)

sends a prompt and receives a completion (AI provider)

Authentication guards every protected resource; a regression here can expose data or grant unauthorized access.

sequenceDiagram
  actor C0 as Caller
  participant F0 as router-knowledge-base.ts
  participant F1 as openai_functions_openapi_customization.ts
  participant F2 as token_text_splitter.ts
  participant F3 as token_buffer.ts
  participant F4 as integration_openai_stream_tokens.ts
  participant F5 as token_usage_tracking.ts
  participant AI as AI provider
  C0->>F0: invoke router-knowledge-base.ts
  F3->>AI: sends a prompt and receives a completion

Mission execution high risk

Entry: invoke test-runner.ts (environment_tests/scripts/test-runner.ts)

writes files to the working tree (disk)

Mission execution drives autonomous code changes; errors here corrupt runs or the target repository.

sequenceDiagram
  actor C0 as Caller
  participant F0 as test-runner.ts
  participant F1 as prompts/pipeline.ts
  participant F2 as runner_utils.ts
  participant F3 as prompts/pipeline.ts
  participant F4 as fake_model_builder.ts
  participant F5 as parsers/pipeline.ts
  participant Disk as disk
  C0->>F0: invoke test-runner.ts
  F0->>Disk: writes files to the working tree

AI provider call high risk

Entry: invoke index.ts (environment_tests/test-exports-cf/src/index.ts)

sends a prompt and receives a completion (AI provider); calls an external service (external API)

Provider calls cost money and shape model output; mistakes leak prompts, burn budget, or route to the wrong model. Note: chat.ts is a fragile zone on this path.

sequenceDiagram
  actor C0 as Caller
  participant F0 as src/index.ts
  participant F1 as prompts/index.ts
  participant F2 as base.ts
  participant F3 as chat.ts
  participant F4 as few_shot.ts
  participant F5 as pipeline.ts
  participant AI as AI provider
  participant External as external API
  C0->>F0: invoke index.ts
  F0->>AI: sends a prompt and receives a completion
  F0->>External: calls an external service
  F0->>F1: calls
  F1->>F2: calls
  F1->>F3: calls
  F1->>F4: calls
  F1->>F5: calls

File changes / writes high risk

Entry: invoke test-runner.ts (environment_tests/scripts/test-runner.ts)

writes files to the working tree (disk)

Direct writes to the working tree are hard to reverse; an unguarded write can clobber user code.

sequenceDiagram
  actor C0 as Caller
  participant F0 as test-runner.ts
  participant F1 as node/update_resolutions_latest.js
  participant F2 as node/update_resolutions_lowest.js
  participant F3 as node/update_resolutions_latest.js
  participant F4 as node/update_resolutions_lowest.js
  participant F5 as update_workspace_deps.js
  participant Disk as disk
  C0->>F0: invoke test-runner.ts
  F0->>Disk: writes files to the working tree
  F1->>Disk: writes files to the working tree
  F2->>Disk: writes files to the working tree
  F3->>Disk: writes files to the working tree
  F4->>Disk: writes files to the working tree
  F5->>Disk: writes files to the working tree

Background jobs medium risk

Entry: scheduled trigger (environment_tests/test-exports-cf/src/index.ts)

sends a prompt and receives a completion (AI provider); calls an external service (external API)

Background jobs run unattended; failures are silent and can pile up unnoticed.

sequenceDiagram
  actor C0 as Scheduler
  participant F0 as index.ts
  participant AI as AI provider
  participant External as external API
  C0->>F0: scheduled trigger
  F0->>AI: sends a prompt and receives a completion
  F0->>External: calls an external service

Fragile zones

• libs/langchain-core/src/messages/ai.ts (score 247.5): 114 files depend on it at runtime; types used by 13 modules; part of an import cycle
• libs/langchain-core/src/callbacks/manager.ts (score 239.5): 106 files depend on it at runtime; types used by 21 modules; oversized and doing too much
• libs/langchain-core/src/prompts/prompt.ts (score 237.8): 118 files depend on it at runtime
• libs/langchain-core/src/tools/index.ts (score 230.8): 91 files depend on it at runtime; types used by 45 modules
• libs/langchain-core/src/messages/base.ts (score 225): 85 files depend on it at runtime; types used by 52 modules
• libs/langchain-core/src/runnables/base.ts (score 197.5): 91 files depend on it at runtime; oversized and doing too much
• libs/langchain-core/src/messages/human.ts (score 194.3): 97 files depend on it at runtime
• libs/langchain-core/src/prompts/chat.ts (score 191): 93 files depend on it at runtime
• libs/langchain-core/src/utils/types/index.ts (score 186.3): 57 files depend on it at runtime; types used by 72 modules
• libs/langchain-core/src/documents/document.ts (score 164): 72 files depend on it at runtime; types used by 20 modules
• libs/langchain-core/src/language_models/base.ts (score 161): 26 files depend on it at runtime; types used by 106 modules
• libs/langchain-classic/src/chains/llm_chain.ts (score 138.8): 66 files depend on it at runtime; part of an import cycle

Architecture rules