While the ideal structure can vary based on application complexity and team preferences, a common and effective layout for production-grade LangChain applications, incorporating modern tools like LangGraph and LangServe, often resembles the following:

A typical directory structure for a deployable LangChain application, emphasizing separation of concerns and modern components.

Let's examine the purpose of each main directory:

src/ (or app/): This is the core of your application. It contains the Python modules and packages that define your LangChain logic.
- Modularity: Inside src/, organize your code into subdirectories based on functionality. Common folders include graphs/ (for LangGraph stateful workflows), chains/ (for LCEL runnables), tools/, prompts/, and utils/. This structure helps isolate logic for reuse and testing.
- API Entry Point: For production deployment, you often need an API server. A file like server.py typically lives here to define the FastAPI app and LangServe routes.
- Use an __init__.py file within src/ and subdirectories to mark them as Python packages.
config/: Store configuration files here, separated by environment (e.g., default.yaml, production.yaml). This is useful for complex, non-sensitive settings like model parameters or prompt templates. However, modern applications increasingly rely on Pydantic Settings classes defined in the code that read directly from environment variables, reducing reliance on external YAML files.
tests/: Contains all automated tests.
- unit/: Tests for individual functions, tools, or graph nodes in isolation.
- integration/: Tests that verify interactions between components, such as a full chain execution or an agent loop.
scripts/: Holds utility scripts for tasks not part of the main application flow, such as data ingestion, vector store indexing, or evaluation runs.
notebooks/: Jupyter notebooks used for exploration and prototyping. Keeping them separate ensures experimental code does not mix with production logic.
deploy/ (or infra/): Contains files related to deployment infrastructure, such as Kubernetes manifests (kubernetes/), Terraform configurations (terraform/), or Helm charts.
Dockerfile: Defines how to build the container image for your application. It usually resides in the root directory to allow the build context to include all project files.
Dependency Management Files:
- requirements.txt or pyproject.toml: Defines runtime dependencies. Using pyproject.toml is standard for modern tools like Poetry or PDM, allowing for strict version locking and easier management of dev-dependencies.
Environment Variables:
- .env: Should be listed in .gitignore. Contains secrets (API keys) and local settings.
- .env.example: A template file showing required variables without values.
.gitignore: Specifies files that Git should ignore (e.g., .env, __pycache__/, local data).
README.md: Provides essential documentation on setup, testing, and deployment procedures.

Build LLM apps faster with Kerb

Cleaner syntax. Built-in debugging. Production-ready from day one.

Built for the AI systems behind ApX Machine Learning

Was this section helpful?

References

Packaging Python Projects, Python Packaging Authority, 2024 - Official guide for structuring, packaging, and distributing Python applications and libraries, covering layout and dependency files.
The Twelve-Factor App, Adam Wiggins, 2011 - A foundational methodology for building robust and scalable software-as-a-service applications, including principles for configuration management and deployment.
Poetry Documentation, Sébastien Eustace and Contributors, 2024 - Official documentation for Poetry, a Python dependency management and packaging tool that helps ensure reproducible builds through clear dependency definitions.