# itemka/nodejs-backend-mastery architecture

> Architecture diagram of the GitHub repository itemka/nodejs-backend-mastery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itemka/nodejs-backend-mastery
- Repository: https://github.com/itemka/nodejs-backend-mastery

## Overview

This is a Node.js learning monorepo: runnable applications and AI-engineering examples demonstrate backend patterns, alongside shared libraries. Users interact through web apps or CLIs; the examples then invoke their domain services and produce pages, streamed answers, search results, or evaluation reports. The graph emphasizes active apps and documented examples, with an internal implementation layer where source evidence supports it. Several README-listed capabilities have no sampled implementation excerpts, so their nodes are linked only where documentation or the source index supports the relationship.

Main entry points: [`workspaces/ai-engineering/llm-chat/src/main.ts`](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/main.ts) (LLM Chat CLI), [`workspaces/apps/local-llm-playground/backend/src/app.ts`](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/app.ts) (Playground API), [`workspaces/ai-engineering/rag-pipeline/src/retrieval/retriever.ts`](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/retrieval/retriever.ts) (Hybrid Retriever), [`workspaces/packages/llm-client/src/provider-factory.ts`](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/packages/llm-client/src/provider-factory.ts) (Provider-Neutral LLM Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Runnable Apps"]
  node_shop_app["Shop MVC<br/>[app.ts]"]
  node_shop_routes["Shop Routes<br/>[index.ts]"]
  node_shop_product_routes["Product Routes<br/>[products.routes.ts]"]
  node_shop_controller["Product Controller"]
  node_shop_views["Product Views<br/>[productsPage.ts]"]
  node_play_client["Playground UI<br/>[App.tsx]"]
  node_play_api["Playground API<br/>[app.ts]"]
  node_play_chat["Chat Endpoint<br/>[chat-router.ts]"]
  node_play_compare["Compare Endpoint<br/>[compare-router.ts]"]
  node_checker_endpoint["Checker Endpoint"]
end

subgraph group_ai["AI Examples"]
  node_llm_chat_cli["LLM Chat CLI<br/>[main.ts]"]
  node_chat_service["Chat Service<br/>[service.ts]"]
  node_docs_client["RAG Search Client"]
  node_rag_service["RAG Service<br/>[app.ts]"]
  node_rag_ingest["Document Ingest<br/>[ingest-router.ts]"]
  node_rag_search["Search Endpoint<br/>[search-router.ts]"]
  node_embedding["Embedding Provider"]
  node_mcp_cli["MCP Chat CLI<br/>[main.ts]"]
  node_mcp_tools["MCP Tool Manager"]
  node_mcp_client["MCP Client<br/>[mcp-client.ts]"]
  node_mcp_server["Document MCP Server"]
  node_claude_cli["Claude Scenarios<br/>[main.ts]"]
  node_scenario_args["Scenario Arguments<br/>[args.ts]"]
  node_eval_cli["Prompt Evaluation CLI<br/>[run-eval.ts]"]
end

subgraph group_shared["Shared Libraries"]
  node_llm_client["Provider-Neutral LLM Client"]
  node_terminal_theme["CLI Output Theme<br/>[index.js]"]
end

subgraph group_internal["Domain Internals"]
  node_shop_store[("In-Memory Products")]
  node_play_models["Model Service<br/>[model-service.ts]"]
  node_checker_service["Checker Service"]
  node_retriever["Hybrid Retriever<br/>[retriever.ts]"]
  node_indexes[("Search Indexes")]
end

node_browser(("Browser User"))
node_ollama["Ollama Runtime"]

node_browser -->|"submits requests"| node_shop_app
node_shop_app -->|"mounts routes"| node_shop_routes
node_shop_routes -->|"routes products"| node_shop_product_routes
node_shop_product_routes -->|"calls handlers"| node_shop_controller
node_shop_controller -->|"reads and writes"| node_shop_store
node_shop_controller -->|"renders pages"| node_shop_views
node_browser -->|"uses playground"| node_play_client
node_play_client -->|"calls API"| node_play_api
node_play_api -->|"mounts endpoints"| node_play_chat
node_play_api -->|"mounts endpoints"| node_play_compare
node_play_api -->|"mounts endpoints"| node_checker_endpoint
node_play_api -->|"configures service"| node_play_models
node_checker_endpoint -->|"runs checks"| node_checker_service
node_checker_service -.->|"checks runtime"| node_ollama
node_llm_chat_cli -->|"creates service"| node_chat_service
node_llm_chat_cli -->|"configures search"| node_docs_client
node_llm_chat_cli -->|"creates provider"| node_llm_client
node_llm_chat_cli -.->|"searches remotely"| node_rag_search
node_rag_service -->|"mounts endpoint"| node_rag_ingest
node_rag_service -->|"mounts endpoint"| node_rag_search
node_rag_service -->|"configures indexes"| node_retriever
node_rag_ingest -->|"ingests chunks"| node_retriever
node_rag_search -.->|"retrieves matches"| node_retriever
node_retriever -.->|"queries indexes"| node_indexes
node_retriever -.->|"creates embeddings"| node_embedding
node_mcp_cli -->|"connects server"| node_mcp_client
node_mcp_cli -->|"registers tools"| node_mcp_tools
node_mcp_cli -->|"creates provider"| node_llm_client
node_mcp_tools -->|"calls tools"| node_mcp_client
node_mcp_client -.->|"connects over stdio"| node_mcp_server
node_claude_cli -->|"parses flags"| node_scenario_args
node_claude_cli -.->|"uses provider"| node_llm_client
node_eval_cli -.->|"evaluates prompts"| node_llm_client
node_llm_chat_cli -.->|"formats output"| node_terminal_theme
node_claude_cli -.->|"formats output"| node_terminal_theme

click node_shop_app "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/app.ts"
click node_shop_routes "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/routes/index.ts"
click node_shop_product_routes "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/routes/shop/products.routes.ts"
click node_shop_controller "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts"
click node_shop_store "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts"
click node_shop_views "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/views/products/productsPage.ts"
click node_play_client "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/client/src/App.tsx"
click node_play_api "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/app.ts"
click node_play_chat "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/routes/chat-router.ts"
click node_play_compare "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/routes/compare-router.ts"
click node_play_models "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/services/model-service.ts"
click node_checker_endpoint "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/routes/llm-checker-router.ts"
click node_checker_service "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/services/llm-checker-service.ts"
click node_llm_chat_cli "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/main.ts"
click node_chat_service "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/chat/service.ts"
click node_docs_client "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/tools/search-docs-client.ts"
click node_rag_service "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/app.ts"
click node_rag_ingest "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/routes/ingest-router.ts"
click node_rag_search "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/routes/search-router.ts"
click node_retriever "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/retrieval/retriever.ts"
click node_indexes "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/indexes/in-memory-vector-index.ts"
click node_embedding "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/embeddings/embedding-provider.ts"
click node_mcp_cli "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/cli/main.ts"
click node_mcp_tools "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/chat/mcp-tool-manager.ts"
click node_mcp_client "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/client/mcp-client.ts"
click node_mcp_server "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/server/document-mcp-server.ts"
click node_claude_cli "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/claude-capabilities-lab/src/main.ts"
click node_scenario_args "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/claude-capabilities-lab/src/cli/args.ts"
click node_eval_cli "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/prompt-eval-lab/src/cli/run-eval.ts"
click node_llm_client "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/packages/llm-client/src/provider-factory.ts"
click node_terminal_theme "https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/packages/cli-output/index.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shop_app,node_shop_routes,node_shop_product_routes,node_shop_controller,node_shop_views,node_play_client,node_play_api,node_play_chat,node_play_compare,node_checker_endpoint,node_browser toneBlue
class node_llm_chat_cli,node_chat_service,node_docs_client,node_rag_service,node_rag_ingest,node_rag_search,node_embedding,node_mcp_cli,node_mcp_tools,node_mcp_client,node_mcp_server,node_claude_cli,node_scenario_args,node_eval_cli toneAmber
class node_llm_client,node_terminal_theme toneMint
class node_shop_store,node_play_models,node_checker_service,node_retriever,node_indexes toneRose
class node_ollama toneIndigo
```

## Components

### Runnable Apps

- [Shop MVC](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/app.ts): `workspaces/apps/shop-mvc-express/src/app.ts`
- [Shop Routes](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/routes/index.ts): `workspaces/apps/shop-mvc-express/src/routes/index.ts`
- [Product Routes](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/routes/shop/products.routes.ts): `workspaces/apps/shop-mvc-express/src/routes/shop/products.routes.ts`
- [Product Controller](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts): `workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts`
- [Product Views](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/views/products/productsPage.ts): `workspaces/apps/shop-mvc-express/src/views/products/productsPage.ts`
- [Playground UI](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/client/src/App.tsx): `workspaces/apps/local-llm-playground/client/src/App.tsx`
- [Playground API](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/app.ts): `workspaces/apps/local-llm-playground/backend/src/app.ts`
- [Chat Endpoint](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/routes/chat-router.ts): `workspaces/apps/local-llm-playground/backend/src/routes/chat-router.ts`
- [Compare Endpoint](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/routes/compare-router.ts): `workspaces/apps/local-llm-playground/backend/src/routes/compare-router.ts`
- [Checker Endpoint](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/routes/llm-checker-router.ts): `workspaces/apps/local-llm-playground/backend/src/routes/llm-checker-router.ts`

### AI Examples

- [LLM Chat CLI](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/main.ts): `workspaces/ai-engineering/llm-chat/src/main.ts`
- [Chat Service](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/chat/service.ts): `workspaces/ai-engineering/llm-chat/src/chat/service.ts`
- [RAG Search Client](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/llm-chat/src/tools/search-docs-client.ts): `workspaces/ai-engineering/llm-chat/src/tools/search-docs-client.ts`
- [RAG Service](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/app.ts): `workspaces/ai-engineering/rag-pipeline/src/app.ts`
- [Document Ingest](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/routes/ingest-router.ts): `workspaces/ai-engineering/rag-pipeline/src/routes/ingest-router.ts`
- [Search Endpoint](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/routes/search-router.ts): `workspaces/ai-engineering/rag-pipeline/src/routes/search-router.ts`
- [Embedding Provider](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/embeddings/embedding-provider.ts): `workspaces/ai-engineering/rag-pipeline/src/embeddings/embedding-provider.ts`
- [MCP Chat CLI](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/cli/main.ts): `workspaces/ai-engineering/mcp-chat/src/cli/main.ts`
- [MCP Tool Manager](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/chat/mcp-tool-manager.ts): `workspaces/ai-engineering/mcp-chat/src/chat/mcp-tool-manager.ts`
- [MCP Client](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/client/mcp-client.ts): `workspaces/ai-engineering/mcp-chat/src/client/mcp-client.ts`
- [Document MCP Server](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/mcp-chat/src/server/document-mcp-server.ts): `workspaces/ai-engineering/mcp-chat/src/server/document-mcp-server.ts`
- [Claude Scenarios](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/claude-capabilities-lab/src/main.ts): `workspaces/ai-engineering/claude-capabilities-lab/src/main.ts`
- [Scenario Arguments](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/claude-capabilities-lab/src/cli/args.ts): `workspaces/ai-engineering/claude-capabilities-lab/src/cli/args.ts`
- [Prompt Evaluation CLI](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/prompt-eval-lab/src/cli/run-eval.ts): `workspaces/ai-engineering/prompt-eval-lab/src/cli/run-eval.ts`

### Shared Libraries

- [Provider-Neutral LLM Client](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/packages/llm-client/src/provider-factory.ts): `workspaces/packages/llm-client/src/provider-factory.ts`
- [CLI Output Theme](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/packages/cli-output/index.js): `workspaces/packages/cli-output/index.js`

### Domain Internals

- [In-Memory Products](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts): `workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts`
- [Model Service](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/services/model-service.ts): `workspaces/apps/local-llm-playground/backend/src/services/model-service.ts`
- [Checker Service](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/apps/local-llm-playground/backend/src/services/llm-checker-service.ts): `workspaces/apps/local-llm-playground/backend/src/services/llm-checker-service.ts`
- [Hybrid Retriever](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/retrieval/retriever.ts): `workspaces/ai-engineering/rag-pipeline/src/retrieval/retriever.ts`
- [Search Indexes](https://github.com/itemka/nodejs-backend-mastery/blob/main/workspaces/ai-engineering/rag-pipeline/src/indexes/in-memory-vector-index.ts): `workspaces/ai-engineering/rag-pipeline/src/indexes/in-memory-vector-index.ts`

### Other components

- **Browser User**
- **Ollama Runtime**

## Connections

- Browser User → Shop MVC: submits requests (evidence: `README.md`)
- Shop MVC → Shop Routes: mounts routes (evidence: `workspaces/apps/shop-mvc-express/src/app.ts`)
- Shop Routes → Product Routes: routes products (evidence: `workspaces/apps/shop-mvc-express/src/routes/shop/products.routes.ts`)
- Product Routes → Product Controller: calls handlers (evidence: `workspaces/apps/shop-mvc-express/src/routes/shop/products.routes.ts`)
- Product Controller → In-Memory Products: reads and writes (evidence: `workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts`)
- Product Controller → Product Views: renders pages (evidence: `workspaces/apps/shop-mvc-express/src/controllers/products.controller.ts`)
- Browser User → Playground UI: uses playground (evidence: `README.md`)
- Playground UI → Playground API: calls API (evidence: `workspaces/apps/local-llm-playground/client/src/App.tsx`)
- Playground API → Chat Endpoint: mounts endpoints (evidence: `workspaces/apps/local-llm-playground/backend/src/app.ts`)
- Playground API → Compare Endpoint: mounts endpoints (evidence: `workspaces/apps/local-llm-playground/backend/src/app.ts`)
- Playground API → Checker Endpoint: mounts endpoints (evidence: `workspaces/apps/local-llm-playground/backend/src/app.ts`)
- Playground API → Model Service: configures service (evidence: `workspaces/apps/local-llm-playground/backend/src/app.ts`)
- Checker Endpoint → Checker Service: runs checks (evidence: `workspaces/apps/local-llm-playground/backend/src/routes/llm-checker-router.ts`)
- Checker Service → Ollama Runtime: checks runtime
- LLM Chat CLI → Chat Service: creates service (evidence: `workspaces/ai-engineering/llm-chat/src/main.ts`)
- LLM Chat CLI → RAG Search Client: configures search (evidence: `workspaces/ai-engineering/llm-chat/src/main.ts`)
- LLM Chat CLI → Provider-Neutral LLM Client: creates provider (evidence: `workspaces/ai-engineering/llm-chat/src/main.ts`)
- LLM Chat CLI → Search Endpoint: searches remotely
- RAG Service → Document Ingest: mounts endpoint (evidence: `workspaces/ai-engineering/rag-pipeline/src/app.ts`)
- RAG Service → Search Endpoint: mounts endpoint (evidence: `workspaces/ai-engineering/rag-pipeline/src/app.ts`)
- RAG Service → Hybrid Retriever: configures indexes (evidence: `workspaces/ai-engineering/rag-pipeline/src/app.ts`)
- Document Ingest → Hybrid Retriever: ingests chunks (evidence: `workspaces/ai-engineering/rag-pipeline/src/routes/ingest-router.ts`)
- Search Endpoint → Hybrid Retriever: retrieves matches
- Hybrid Retriever → Search Indexes: queries indexes
- Hybrid Retriever → Embedding Provider: creates embeddings
- MCP Chat CLI → MCP Client: connects server (evidence: `workspaces/ai-engineering/mcp-chat/src/cli/main.ts`)
- MCP Chat CLI → MCP Tool Manager: registers tools (evidence: `workspaces/ai-engineering/mcp-chat/src/cli/main.ts`)
- MCP Chat CLI → Provider-Neutral LLM Client: creates provider (evidence: `workspaces/ai-engineering/mcp-chat/src/cli/main.ts`)
- MCP Tool Manager → MCP Client: calls tools (evidence: `workspaces/ai-engineering/mcp-chat/src/chat/mcp-tool-manager.ts`)
- MCP Client → Document MCP Server: connects over stdio
- Claude Scenarios → Scenario Arguments: parses flags (evidence: `workspaces/ai-engineering/claude-capabilities-lab/src/main.ts`)
- Claude Scenarios → Provider-Neutral LLM Client: uses provider
- Prompt Evaluation CLI → Provider-Neutral LLM Client: evaluates prompts
- LLM Chat CLI → CLI Output Theme: formats output
- Claude Scenarios → CLI Output Theme: formats output
