# harshil17704/langchain-learnings architecture

> Architecture diagram of the GitHub repository harshil17704/langchain-learnings, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshil17704/langchain-learnings
- Repository: https://github.com/harshil17704/langchain-learnings

## Overview

1. **Repository role**
   - This is not a single application; it is a **structured course repository** of standalone Python examples.
   - Each file demonstrates one LangChain/LangGraph concept, with the repo organized as a learning progression from primitives to full application patterns.

2. **Core architectural boundary**
   - The repository centers on the boundary between:
     - **LLM-facing logic**: prompts, models, chains, tools, agents, graphs
     - **application data**: documents, chat history, vector stores, checkpoints, evaluation data
   - Most examples are “read-and-run” patterns rather than a shared runtime service.

3. **Foundation layer: setup and prompt design**
   - `00_setup` establishes environment and conceptual grounding.
   - `01_prompts` covers prompt templates, chat prompts, few-shot prompting, output parsers, and structured outputs with Pydantic.
   - This layer defines how input is shaped before any model call, and how model output is constrained after generation.

4. **Model and embedding layer**
   - `02_models_embeddings` introduces chat models, embeddings, model alternatives, streaming, and usage tracking.
   - This is the main inference boundary: prompts go in, model text or embeddings come out.
   - Streaming and usage tracking are treated as operational concerns tied to model invocation.

5. **Document ingestion pipeline**
   - `03_document_processing` handles loaders, text splitters, metadata enrichment, and web/PDF ingestion.
   - The data flow here is: raw content → normalized documents → chunked segments → metadata-enriched units.
   - This pipeline feeds retrieval systems and RAG workflows later in the repo.

6. **Composable workflow layer**
   - `04_chains` demonstrates LCEL-based composition: sequential, router, parallel, and branching chains.
   - This is the “workflow orchestration without agents” layer, where multiple model calls or transformations are connected explicitly.
   - It forms the structural bridge between simple prompt calls and more dynamic agent/graph systems.

7. **Conversation state and memory**
   - `05_memory` covers chat history, summary memory, and persistent memory.
   - Memory is treated as application state that augments model context over time.
   - This boundary matters because memory can be in-process, summarized, or persisted externally depending on the pattern.

8. **Retrieval-Augmented Generation subsystem**
   - `06_retrieval_rag` is a full RAG stack: vector stores, retrievers, retrieval pipelines, hybrid search, conversational RAG, query rewriting, multi-query retrieval, reranking, and context compression.
   - Data flow: ingested documents → embeddings/vector index → retriever → context assembly → LLM answer generation.
   - This is the main information-retrieval architecture in the repo and the clearest place to draw a “knowledge store + retrieval + generation” diagram.

9. **Tool-use and agent subsystem**
   - `07_tools` defines custom tools, tool calling, and tool error handling.
   - `08_agents` builds on that with agent executors, ReAct patterns, memory integration, and planning/reflection.
   - The architectural shift here is from fixed workflows to **model-directed control flow**, where the LLM decides when to call tools and how to iterate.

10. **LangGraph orchestration layer**
   - `09_langgraph` introduces state graphs, conditional edges, human-in-the-loop approval, multi-agent supervision, checkpoints, interrupts, and resume.
   - This is the strongest orchestration boundary in the repo: state becomes explicit, transitions are controlled, and execution can pause/restart.
   - It extends the agent idea into a durable workflow engine with branching and persistence.

11. **Production hardening layer**
   - `10_production_patterns` covers callbacks/observability, guardrails/validation, retries/caching, evaluation, and prompt versioning.
   - These examples show the operational controls around LLM systems: tracing, safety checks, reliability, quality measurement, and prompt lifecycle management.
   - This layer sits orthogonally across prompts, chains, RAG, agents, and graphs.

12. **Integrated solutions and reference architectures**
   - `11_projects` contains an end-to-end support bot example that likely combines retrieval, tools, memory, and orchestration patterns.
   - `14_capstone` provides a full-stack RAG-agent blueprint, which acts as the repo’s highest-level system design reference.
   - These sections are where the course’s building blocks converge into realistic application architecture.

13. **Ecosystem and deployment**
   - `13_ecosystem` adds LangSmith tracing and LangServe deployment.
   - LangSmith is the observability/evaluation boundary for tracing runs and inspecting behavior.
   - LangServe represents the deployment boundary where a chain or app can be exposed as a service.

14. **Overall architectural shape**
   - The repo progresses from **single-call LLM interactions** to **stateful workflows**, then to **retrieval systems**, **tool-using agents**, and finally **graph-orchestrated, production-aware applications**.
   - For a diagram, the most important flows are:
     - prompt → model → parser
     - documents → split/chunk → embed → retrieve → generate
     - user input → memory/context/tool calls → agent decisions
     - state graph → conditional transitions → checkpoints/human approval → resume
     - application runs → tracing/evaluation/guardrails/retries/versioning

Main entry points: [`06_retrieval_rag/03_rag_pipeline.py`](https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/03_rag_pipeline.py) (RAG Pipeline), [`08_agents/01_agent_executor_basics.py`](https://github.com/harshil17704/langchain-learnings/blob/main/08_agents/01_agent_executor_basics.py) (Agents), [`09_langgraph/01_stategraph_basics.py`](https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/01_stategraph_basics.py) (State Graph), [`14_capstone/01_full_stack_rag_agent_blueprint.py`](https://github.com/harshil17704/langchain-learnings/blob/main/14_capstone/01_full_stack_rag_agent_blueprint.py) (Capstone)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_foundation["Foundations"]
  node_setup["Setup"]
  node_prompts["Prompts<br/>prompting"]
  node_parsers["Parsers<br/>output parsing"]
  node_models["Models<br/>inference<br/>[01_chat_models.py]"]
  node_embeddings["Embeddings<br/>vectorization<br/>[02_embeddings.py]"]
end

subgraph group_workflow["Workflow"]
  node_lcel["LCEL<br/>composition<br/>[01_lcel_basics.py]"]
  node_chains["Chain Patterns<br/>workflow"]
  node_memory["Memory<br/>conversation state"]
end

subgraph group_retrieval["Retrieval"]
  node_ingestion["Ingestion<br/>document pipeline"]
  node_vectorstore[("Vector Store<br/>index")]
  node_retriever["Retriever<br/>search<br/>[02_retrievers.py]"]
  node_rag["RAG Pipeline<br/>generation pipeline<br/>[03_rag_pipeline.py]"]
  node_rag_improve["RAG Tuning<br/>retrieval optimization"]
end

subgraph group_agents["Agents"]
  node_tools["Tools<br/>tooling<br/>[01_custom_tools.py]"]
  node_agent["Agents<br/>agent loop"]
  node_agent_reflect["Planning<br/>reasoning loop"]
end

subgraph group_graph["Graph Orchestration"]
  node_stategraph["State Graph<br/>graph workflow"]
  node_hitl["Human Loop<br/>approval flow"]
  node_persistence["Persistence<br/>durable state"]
end

subgraph group_ops["Ops"]
  node_production["Production<br/>ops layer"]
  node_ecosystem["Ecosystem<br/>platform integration"]
end

subgraph group_apps["Applications"]
  node_support_bot["Support Bot<br/>solution example"]
  node_capstone["Capstone<br/>reference blueprint"]
end

node_setup -->|"introduces"| node_prompts
node_prompts -->|"constrains output"| node_parsers
node_prompts -->|"calls"| node_models
node_models -->|"produces"| node_embeddings
node_ingestion -->|"chunks for"| node_embeddings
node_embeddings -->|"indexes"| node_vectorstore
node_vectorstore -->|"serves"| node_retriever
node_retriever -->|"feeds context"| node_rag
node_ingestion -->|"supplies docs"| node_rag
node_rag -->|"extends to"| node_rag_improve
node_lcel -->|"composes"| node_chains
node_chains -->|"augments with"| node_memory
node_models -->|"drives"| node_lcel
node_tools -->|"enables"| node_agent
node_agent -->|"iterates"| node_agent_reflect
node_agent -->|"uses state"| node_memory
node_agent_reflect -->|"maps to"| node_stategraph
node_stategraph -->|"branches to"| node_hitl
node_stategraph -->|"persists"| node_persistence
node_rag -.->|"toolifies"| node_agent
node_rag -.->|"orchestrated by"| node_stategraph
node_production -->|"observes"| node_models
node_production -->|"hardens"| node_rag
node_ecosystem -->|"supports"| node_production
node_support_bot -->|"integrates"| node_rag
node_support_bot -->|"integrates"| node_agent
node_support_bot -->|"retains context"| node_memory
node_capstone -->|"combines"| node_rag_improve
node_capstone -->|"orchestrates"| node_stategraph
node_capstone -->|"hardened by"| node_production
node_ecosystem -.->|"deploys and traces"| node_capstone

click node_setup "https://github.com/harshil17704/langchain-learnings/blob/main/00_setup/01_environment_and_concepts.py"
click node_prompts "https://github.com/harshil17704/langchain-learnings/blob/main/01_prompts/01_prompt_templates.py"
click node_parsers "https://github.com/harshil17704/langchain-learnings/blob/main/01_prompts/03_output_parsers.py"
click node_models "https://github.com/harshil17704/langchain-learnings/blob/main/02_models_embeddings/01_chat_models.py"
click node_embeddings "https://github.com/harshil17704/langchain-learnings/blob/main/02_models_embeddings/02_embeddings.py"
click node_ingestion "https://github.com/harshil17704/langchain-learnings/blob/main/03_document_processing/01_document_loaders.py"
click node_lcel "https://github.com/harshil17704/langchain-learnings/blob/main/04_chains/01_lcel_basics.py"
click node_chains "https://github.com/harshil17704/langchain-learnings/blob/main/04_chains/02_sequential_chain_lcel.py"
click node_memory "https://github.com/harshil17704/langchain-learnings/blob/main/05_memory/01_chat_history_basics.py"
click node_vectorstore "https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/01_vectorstores_basics.py"
click node_retriever "https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/02_retrievers.py"
click node_rag "https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/03_rag_pipeline.py"
click node_rag_improve "https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/04_rag_improvements.py"
click node_tools "https://github.com/harshil17704/langchain-learnings/blob/main/07_tools/01_custom_tools.py"
click node_agent "https://github.com/harshil17704/langchain-learnings/blob/main/08_agents/01_agent_executor_basics.py"
click node_agent_reflect "https://github.com/harshil17704/langchain-learnings/blob/main/08_agents/04_planning_and_reflection.py"
click node_stategraph "https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/01_stategraph_basics.py"
click node_hitl "https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/03_human_in_the_loop.py"
click node_persistence "https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/05_checkpoints_and_persistence.py"
click node_production "https://github.com/harshil17704/langchain-learnings/blob/main/10_production_patterns/01_callbacks_observability.py"
click node_ecosystem "https://github.com/harshil17704/langchain-learnings/blob/main/13_ecosystem/01_langsmith_tracing.py"
click node_support_bot "https://github.com/harshil17704/langchain-learnings/blob/main/11_projects/01_end_to_end_support_bot.py"
click node_capstone "https://github.com/harshil17704/langchain-learnings/blob/main/14_capstone/01_full_stack_rag_agent_blueprint.py"

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_setup,node_prompts,node_parsers,node_models,node_embeddings,node_support_bot,node_capstone toneBlue
class node_lcel,node_chains,node_memory toneAmber
class node_ingestion,node_vectorstore,node_retriever,node_rag,node_rag_improve toneMint
class node_tools,node_agent,node_agent_reflect toneRose
class node_stategraph,node_hitl,node_persistence toneIndigo
class node_production,node_ecosystem toneTeal
```

## Components

### Foundations

Prompting, model calls, and document prep basics.

- [Setup](https://github.com/harshil17704/langchain-learnings/blob/main/00_setup/01_environment_and_concepts.py): course setup · Environment setup and conceptual grounding for the repo. · `00_setup/01_environment_and_concepts.py`
- [Prompts](https://github.com/harshil17704/langchain-learnings/blob/main/01_prompts/01_prompt_templates.py): prompting · Prompt templates, chat prompts, few-shot examples, and structured output design. · `01_prompts/01_prompt_templates.py`
- [Parsers](https://github.com/harshil17704/langchain-learnings/blob/main/01_prompts/03_output_parsers.py): output parsing · Output parsers and structured output constraints for model responses. · `01_prompts/03_output_parsers.py`
- [Models](https://github.com/harshil17704/langchain-learnings/blob/main/02_models_embeddings/01_chat_models.py): inference · Chat models, embeddings, alternatives, streaming, and usage tracking. · `02_models_embeddings/01_chat_models.py`
- [Embeddings](https://github.com/harshil17704/langchain-learnings/blob/main/02_models_embeddings/02_embeddings.py): vectorization · Embedding generation used to support retrieval and similarity search. · `02_models_embeddings/02_embeddings.py`

### Workflow

LCEL composition, memory, and classic chain patterns.

- [LCEL](https://github.com/harshil17704/langchain-learnings/blob/main/04_chains/01_lcel_basics.py): composition · Core LCEL composition patterns for chaining transformations and model calls. · `04_chains/01_lcel_basics.py`
- [Chain Patterns](https://github.com/harshil17704/langchain-learnings/blob/main/04_chains/02_sequential_chain_lcel.py): workflow · Sequential, router, parallel, and branching chain patterns. · `04_chains/02_sequential_chain_lcel.py`
- [Memory](https://github.com/harshil17704/langchain-learnings/blob/main/05_memory/01_chat_history_basics.py): conversation state · Chat history, summary memory, and persistent memory patterns. · `05_memory/01_chat_history_basics.py`

### Retrieval

Vector search and RAG pipelines over processed documents.

- [Ingestion](https://github.com/harshil17704/langchain-learnings/blob/main/03_document_processing/01_document_loaders.py): document pipeline · Loaders, splitters, metadata enrichment, and web/PDF ingestion. · `03_document_processing/01_document_loaders.py`
- [Vector Store](https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/01_vectorstores_basics.py): index · Vector store basics as the storage layer for embedded documents. · `06_retrieval_rag/01_vectorstores_basics.py`
- [Retriever](https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/02_retrievers.py): search · Retriever abstractions that query the vector index for relevant context. · `06_retrieval_rag/02_retrievers.py`
- [RAG Pipeline](https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/03_rag_pipeline.py): generation pipeline · End-to-end retrieval-augmented generation flow from query to answer. · `06_retrieval_rag/03_rag_pipeline.py`
- [RAG Tuning](https://github.com/harshil17704/langchain-learnings/blob/main/06_retrieval_rag/04_rag_improvements.py): retrieval optimization · Hybrid search, conversational RAG, query rewriting, reranking, and context compression. · `06_retrieval_rag/04_rag_improvements.py`

### Agents

Tool use and model-directed control flow.

- [Tools](https://github.com/harshil17704/langchain-learnings/blob/main/07_tools/01_custom_tools.py): tooling · Custom tools, tool calling, and tool error handling. · `07_tools/01_custom_tools.py`
- [Agents](https://github.com/harshil17704/langchain-learnings/blob/main/08_agents/01_agent_executor_basics.py): agent loop · Agent executor basics and ReAct-style tool-using loops. · `08_agents/01_agent_executor_basics.py`
- [Planning](https://github.com/harshil17704/langchain-learnings/blob/main/08_agents/04_planning_and_reflection.py): reasoning loop · Planning, reflection, and agent memory integration. · `08_agents/04_planning_and_reflection.py`

### Graph Orchestration

Stateful LangGraph execution, branching, and persistence.

- [State Graph](https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/01_stategraph_basics.py): graph workflow · LangGraph state graph basics and conditional transitions. · `09_langgraph/01_stategraph_basics.py`
- [Human Loop](https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/03_human_in_the_loop.py): approval flow · Human-in-the-loop approval, interrupts, and resume behavior. · `09_langgraph/03_human_in_the_loop.py`
- [Persistence](https://github.com/harshil17704/langchain-learnings/blob/main/09_langgraph/05_checkpoints_and_persistence.py): durable state · Checkpoints, persistence, interrupts, and restartable execution. · `09_langgraph/05_checkpoints_and_persistence.py`

### Ops

Production controls, tracing, deployment, and evaluation.

- [Production](https://github.com/harshil17704/langchain-learnings/blob/main/10_production_patterns/01_callbacks_observability.py): ops layer · Callbacks, guardrails, retries, caching, evaluation, and prompt versioning. · `10_production_patterns/01_callbacks_observability.py`
- [Ecosystem](https://github.com/harshil17704/langchain-learnings/blob/main/13_ecosystem/01_langsmith_tracing.py): platform integration · LangSmith tracing and LangServe deployment integration. · `13_ecosystem/01_langsmith_tracing.py`

### Applications

Integrated examples and reference blueprints.

- [Support Bot](https://github.com/harshil17704/langchain-learnings/blob/main/11_projects/01_end_to_end_support_bot.py): solution example · End-to-end support bot that combines retrieval, memory, and orchestration. · `11_projects/01_end_to_end_support_bot.py`
- [Capstone](https://github.com/harshil17704/langchain-learnings/blob/main/14_capstone/01_full_stack_rag_agent_blueprint.py): reference blueprint · Full-stack RAG-agent blueprint tying together the repo's major patterns. · `14_capstone/01_full_stack_rag_agent_blueprint.py`

## Connections

- Setup → Prompts: introduces · Conceptual setup leads into prompt shaping and output control.
- Prompts → Parsers: constrains output · Prompts are paired with parsers and structured output rules.
- Prompts → Models: calls · Prompted input is sent to chat models for inference.
- Models → Embeddings: produces · The model layer includes embeddings as the representation boundary.
- Ingestion → Embeddings: chunks for · Loaded and split documents become embedding-ready units.
- Embeddings → Vector Store: indexes · Embeddings are stored in a vector index for retrieval.
- Vector Store → Retriever: serves · The vector store is queried through retriever abstractions.
- Retriever → RAG Pipeline: feeds context · Retriever output becomes context for answer generation.
- Ingestion → RAG Pipeline: supplies docs · Ingested documents flow into the RAG pipeline.
- RAG Pipeline → RAG Tuning: extends to · The basic RAG pipeline is refined with better retrieval strategies.
- LCEL → Chain Patterns: composes · LCEL basics expand into explicit chain patterns.
- Chain Patterns → Memory: augments with · Workflow examples are combined with conversational state.
- Models → LCEL: drives · Model calls are the core execution unit inside LCEL flows.
- Tools → Agents: enables · Tools are orchestrated by agent execution loops.
- Agents → Planning: iterates · Agents are extended with planning, reflection, and memory.
- Agents → Memory: uses state · Agents can carry chat history and persistent context.
- Planning → State Graph: maps to · Planning and reflection can be expressed as graph state transitions.
- State Graph → Human Loop: branches to · Graph execution can pause for human approval.
- State Graph → Persistence: persists · State graphs support checkpoints and resumable execution.
- RAG Pipeline → Agents: toolifies · Retrieval workflows can be embedded in agentic control flow.
- RAG Pipeline → State Graph: orchestrated by · RAG can be wrapped in explicit graph state and routing.
- Production → Models: observes · Operational controls wrap model invocations.
- Production → RAG Pipeline: hardens · Guardrails and retries apply across RAG workflows.
- Ecosystem → Production: supports · Tracing and deployment sit alongside production patterns.
- Support Bot → RAG Pipeline: integrates · The support bot likely uses retrieval as a core capability.
- Support Bot → Agents: integrates · The support bot also incorporates tool-using behavior.
- Support Bot → Memory: retains context · Conversation state supports the application example.
- Capstone → RAG Tuning: combines · The capstone blueprint incorporates advanced retrieval patterns.
- Capstone → State Graph: orchestrates · The capstone reference architecture uses graph-based control flow.
- Capstone → Production: hardened by · The blueprint is framed with production concerns.
- Ecosystem → Capstone: deploys and traces · Platform integrations support the top-level reference architecture.