# bhancockio/langchain-crash-course architecture

> Architecture diagram of the GitHub repository bhancockio/langchain-crash-course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhancockio/langchain-crash-course
- Repository: https://github.com/bhancockio/langchain-crash-course

## Overview

##### Project type and purpose
- This is not a deployed product but a hands-on code-example repository for the “LangChain Crash Course.”
- Purpose: teach core LangChain concepts via runnable Python scripts covering Chat Models, Prompt Templates, Chains, RAG, and Agents & Tools.

##### File structure
- Top-level files
- .env.example / .gitignore / pyproject.toml – environment and dependency config
- README.md – project overview and usage
- Five main folders (modules) numbered 1–5:
1) 1_chat_models
2) 2_prompt_templates
3) 3_chains
4) 4_rag (incl. local books and utils)
5) 5_agents_and_tools (with deep-dive subfolders)
- Pattern: each folder contains sequential Python scripts illustrating incremental features

##### README for additional insights
- Outlines six course sections matching the five folders (+ setup)
- Mentions technologies: Python 3.10/3.11, Poetry, LangChain, Firestore, vector stores, web scraping

##### Main components
a. Configuration & Environment
- .env (API keys), Poetry virtualenv, dependency resolution (pyproject.toml)
b. Core LangChain Modules (as code packages)
1) Chat Models – interfaces to LLM providers (OpenAI, Claude, Gemini)
2) Prompt Templates – reusable prompt patterns
3) Chains – small workflows combining prompts and models
4) RAG – document ingestion, embedding, vector store retrieval, conversational interface
– Local “books” folder as document corpus
– embedding utility for cost calculation
5) Agents & Tools – agent orchestrator + custom tools (constructor, decorator, base)
c. External Services & Data Stores
- LLM Providers via API
- Vector store (e.g., FAISS, Pinecone)
- Firestore for message history
- Web-scraping service (e.g., Firecrawl)
d. User / Developer interaction
- CLI / script execution via Python
- Input: developer-provided prompt or code parameters
- Output: printed responses, saved records in Firestore

##### Relationships and interactions
- Configuration initializes environment → imports LangChain
- Chat Models & Prompt Templates feed into Chains
- Chains can call Chat Models, use Prompt Templates, and direct text to RAG or Agents
- RAG module: Documents → Text Splitting → Embeddings → Vector Store → Retriever → LLM via Chain
- Agents: orchestrate Chains + Tools for decision-making, dynamic tool invocation
- Tools can call external APIs or internal utilities (e.g., embedding cost calculator)

##### Architectural patterns and design principles
- Modular separation by concept (single responsibility per folder)
- Pipeline pattern (Chains) for data flow
- Adapter pattern for external LLM providers (Chat Models)
- Strategy pattern for different prompt templates and tool implementations
- Layered architecture: Config → Core Modules → External Services

##### Technology and framework call-outs
- Python + Poetry
- LangChain SDK
- Firestore integration
- Vector store of choice (FAISS/Pinecone)
- Web-scraping via Firecrawl

- Clear labels on every component (e.g., “3_chains” as “Chains Module”)
- Example data flow: “User prompt → Prompt Template → Chat Model → Chain → Output”
- Call out optional branches: “Agent invokes Tool A or Tool B based on condition”

##### Detail
- Don’t just lump everything into “Backend.” Break into the five course modules.
- Both high-level flow (e.g., User → Agent → LLM) and internal steps for complex parts (e.g., RAG ingestion).
- External dependencies and where API keys from .env are used.
- Deep-dive submodules under Agents & Tools to show extensibility points.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration
    subgraph "Configuration & Environment"
        direction TB
        Env[".env (API Keys)"]:::config
        PyProj["pyproject.toml"]:::config
    end

    %% Core Modules
    subgraph "Core Modules" 
        direction TB
        subgraph "1_chat_models" 
            direction TB
            CM1["1_chat_model_basic.py"]:::core
            CM2["2_chat_model_basic_conversation.py"]:::core
            CM3["3_chat_model_alternatives.py"]:::core
            CM4["4_chat_model_conversation_with_user.py"]:::core
            CM5["5_chat_model_save_message_history_firebase.py"]:::core
        end
        subgraph "2_prompt_templates"
            direction TB
            PT1["1_prompt_template_basic.py"]:::core
            PT2["2_prompt_template_with_chat_model.py"]:::core
        end
        subgraph "3_chains"
            direction TB
            CH1["1_chains_basics.py"]:::core
            CH2["2_chains_under_the_hood.py"]:::core
            CH3["3_chains_extended.py"]:::core
            CH4["4_chains_parallel.py"]:::core
            CH5["5_chains_branching.py"]:::core
        end
        subgraph "4_rag"
            direction TB
            subgraph "Scripts"
                direction TB
                R1a["1a_rag_basics.py"]:::core
                R1b["1b_rag_basics.py"]:::core
                R2a["2a_rag_basics_metadata.py"]:::core
                R2b["2b_rag_basics_metadata.py"]:::core
                R3["3_rag_text_splitting_deep_dive.py"]:::core
                R4["4_rag_embedding_deep_dive.py"]:::core
                R5["5_rag_retriever_deep_dive.py"]:::core
                R6["6_rag_one_off_question.py"]:::core
                R7["7_rag_conversational.py"]:::core
                R8a["8_rag_web_scrape_basic.py"]:::core
                R8b["8_rag_web_scrape_firecrawl.py"]:::core
            end
            subgraph "Corpus & Utils"
                direction TB
                Books["books (Document Corpus)"]:::datastore
                EmbedUtil["utils/embedding_cost_calculator.py"]:::core
            end
        end
        subgraph "5_agents_and_tools"
            direction TB
            AT1["1_agent_and_tools_basics.py"]:::core
            subgraph "agent_deep_dive"
                direction TB
                AD1["1_agent_react_chat.py"]:::core
                AD2["2_agent_react_docstore.py"]:::core
            end
            subgraph "tools_deep_dive"
                direction TB
                TD1["1_tool_constructor.py"]:::core
                TD2["2_tool_decorator.py"]:::core
                TD3["3_tool_base_tool.py"]:::core
            end
        end
    end

    %% External Services & Data Stores
    subgraph "External Services"
        direction TB
        LLM["LLM Providers (OpenAI, Claude, Gemini API)"]:::external
        WS["Web-scraping Service (Firecrawl)"]:::external
    end
    subgraph "Data Stores"
        direction TB
        FS["Firestore (Message History)"]:::datastore
        VS["Vector Store (FAISS/Pinecone)"]:::datastore
    end

    %% Relationships
    Env -->|provides keys| CM1
    Env -->|provides keys| PT1
    Env -->|provides keys| CH1
    Env -->|provides keys| R1a
    Env -->|provides keys| AT1

    CM1 -->|uses| LLM
    CM2 -->|uses| LLM
    CM3 -->|uses| LLM
    CM4 -->|uses| LLM
    CM5 -->|logs→| FS

    CM1 -->|feeds prompts| PT2
    PT1 -->|templates| CH1
    PT2 -->|templates| CH1

    CH1 -->|calls| CM1
    CH1 -->|uses| PT1
    CH1 -->|branches to| R1a
    CH1 -->|branches to| AT1

    %% RAG internal
    R1a -->|ingests docs| Books
    Books -->|split text| R3
    R3 -->|create embeddings| R4
    R4 -->|store vectors| VS
    VS -->|retrieve| R5
    R5 -->|query→| CM1

    R8b -->|scrapes data| WS

    %% Agents & Tools
    AT1 -->|invokes| AD1
    AT1 -->|invokes| AD2
    AD1 -->|uses| TD1
    AD1 -->|uses| TD2
    AD2 -->|uses| TD3
    AD1 -->|calls→| CM1

    %% Styling
    classDef config fill:#d0d0d0,stroke:#333
    classDef core fill:#a0f0a0,stroke:#333
    classDef external fill:#a0c0ff,stroke:#333
    classDef datastore fill:#f0f0a0,stroke:#333

    %% Click Events
    click Env "https://github.com/bhancockio/langchain-crash-course/blob/main/.env.example"
    click PyProj "https://github.com/bhancockio/langchain-crash-course/blob/main/pyproject.toml"
    click CM1 "https://github.com/bhancockio/langchain-crash-course/blob/main/1_chat_models/1_chat_model_basic.py"
    click CM2 "https://github.com/bhancockio/langchain-crash-course/blob/main/1_chat_models/2_chat_model_basic_conversation.py"
    click CM3 "https://github.com/bhancockio/langchain-crash-course/blob/main/1_chat_models/3_chat_model_alternatives.py"
    click CM4 "https://github.com/bhancockio/langchain-crash-course/blob/main/1_chat_models/4_chat_model_conversation_with_user.py"
    click CM5 "https://github.com/bhancockio/langchain-crash-course/blob/main/1_chat_models/5_chat_model_save_message_history_firebase.py"
    click PT1 "https://github.com/bhancockio/langchain-crash-course/blob/main/2_prompt_templates/1_prompt_template_basic.py"
    click PT2 "https://github.com/bhancockio/langchain-crash-course/blob/main/2_prompt_templates/2_prompt_template_with_chat_model.py"
    click CH1 "https://github.com/bhancockio/langchain-crash-course/blob/main/3_chains/1_chains_basics.py"
    click CH2 "https://github.com/bhancockio/langchain-crash-course/blob/main/3_chains/2_chains_under_the_hood.py"
    click CH3 "https://github.com/bhancockio/langchain-crash-course/blob/main/3_chains/3_chains_extended.py"
    click CH4 "https://github.com/bhancockio/langchain-crash-course/blob/main/3_chains/4_chains_parallel.py"
    click CH5 "https://github.com/bhancockio/langchain-crash-course/blob/main/3_chains/5_chains_branching.py"
    click R1a "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/1a_rag_basics.py"
    click R1b "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/1b_rag_basics.py"
    click R2a "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/2a_rag_basics_metadata.py"
    click R2b "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/2b_rag_basics_metadata.py"
    click R3 "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/3_rag_text_splitting_deep_dive.py"
    click R4 "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/4_rag_embedding_deep_dive.py"
    click R5 "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/5_rag_retriever_deep_dive.py"
    click R6 "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/6_rag_one_off_question.py"
    click R7 "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/7_rag_conversational.py"
    click R8a "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/8_rag_web_scrape_basic.py"
    click R8b "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/8_rag_web_scrape_firecrawl.py"
    click Books "https://github.com/bhancockio/langchain-crash-course/tree/main/4_rag/books/"
    click EmbedUtil "https://github.com/bhancockio/langchain-crash-course/blob/main/4_rag/utils/embedding_cost_calculator.py"
    click AT1 "https://github.com/bhancockio/langchain-crash-course/blob/main/5_agents_and_tools/1_agent_and_tools_basics.py"
    click AD1 "https://github.com/bhancockio/langchain-crash-course/blob/main/5_agents_and_tools/agent_deep_dive/1_agent_react_chat.py"
    click AD2 "https://github.com/bhancockio/langchain-crash-course/blob/main/5_agents_and_tools/agent_deep_dive/2_agent_react_docstore.py"
    click TD1 "https://github.com/bhancockio/langchain-crash-course/blob/main/5_agents_and_tools/tools_deep_dive/1_tool_constructor.py"
    click TD2 "https://github.com/bhancockio/langchain-crash-course/blob/main/5_agents_and_tools/tools_deep_dive/2_tool_decorator.py"
    click TD3 "https://github.com/bhancockio/langchain-crash-course/blob/main/5_agents_and_tools/tools_deep_dive/3_tool_base_tool.py"
```
