Merge pull request #17 from Azure-Samples/copilot/add-documentation-for-deployment

Add comprehensive documentation for deployment and architecture

Author: diberry

README.md

@@ -24,6 +24,20 @@ The repository is organized as a monorepo with the following packages:
 - **langgraph-agent**: Core agent implementation using LangGraph
 - **server-api**: FastAPI server exposing the agent functionality
 
+## Documentation
+
+New to Azure, LangChain, monorepos, or cloud deployment? Check out our comprehensive documentation in the [**docs**](./docs) directory:
+
+- 📚 [Getting Started](./docs/01-getting-started.md) - Quick setup and deployment guide
+- 💻 [Local Development](./docs/02-local-development.md) - Monorepo structure and npm workspaces
+- 🏗️ [Infrastructure & Deployment](./docs/03-infrastructure-deployment.md) - Azure Developer CLI and Bicep
+- 🧪 [Testing with HTTP Files](./docs/04-testing-with-http-files.md) - API testing in VS Code
+- 🔐 [Azure Identity Authentication](./docs/05-azure-identity-authentication.md) - Passwordless auth
+- 🚀 [Azure Container Apps](./docs/06-azure-container-apps.md) - Container deployment and ingress
+- 🔍 [Azure AI Search Vector Store](./docs/07-azure-ai-search-vector-store.md) - Vector database and indexing
+
+See the [documentation index](./docs/README.md) for the complete guide.
+
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) (v18 or later)

docs/01-getting-started.md

@@ -0,0 +1,100 @@
+# Getting Started
+
+This guide will help you get started with the Azure TypeScript LangChain sample, whether you're new to Azure, LangChain, monorepos, or cloud deployment.
+
+## Overview
+
+This repository demonstrates how to build an intelligent agent using TypeScript, LangChain.js, LangGraph, Azure OpenAI, and Azure AI Search to create a Retrieval Augmented Generation (RAG) application. The sample includes an HR document query system that allows users to ask questions about employee benefits and company policies.
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+- **[Node.js](https://nodejs.org/)** (v18 or later)
+- **[npm](https://www.npmjs.com/)** (comes with Node.js)
+- **[Azure subscription](https://azure.microsoft.com/free/)** - Get a free account if you don't have one
+- **[Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)** - For authentication and resource management
+- **[Azure Developer CLI (azd)](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd)** - For deployment
+
+## Quick Start
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/Azure-Samples/azure-typescript-langchainjs.git
+cd azure-typescript-langchainjs
+```
+
+### 2. Authenticate with Azure
+
+```bash
+# Login to Azure CLI
+az login
+
+# Configure Azure Developer CLI to use Azure CLI authentication
+azd config set auth.useAzCliAuth true
+```
+
+### 3. Deploy to Azure
+
+```bash
+# Deploy all resources and the application
+azd up
+```
+
+**Important Notes:**
+- Choose a short environment name (7-10 lowercase letters recommended, e.g., `lang-exam`)
+- The deployment process takes approximately 15 minutes
+- This will:
+  - Build the Docker container
+  - Create all necessary Azure resources (OpenAI, AI Search, Container Apps, etc.)
+  - Load the Azure AI Search index with embeddings from PDF documents
+  - Deploy the application
+
+### 4. Wait for Document Indexing
+
+After deployment completes, the system will automatically index PDF documents into Azure AI Search. The sample includes **263 documents** that need to be indexed before you can use the `/answer` endpoint effectively.
+
+You can check the indexing status in the deployment output, or use the Azure Portal to view your Azure AI Search service.
+
+### 5. Test the API
+
+Once indexing is complete, you can test the API using the URL displayed at the end of the `azd up` command:
+
+```bash
+# Test the API (use the URL from azd up output)
+curl -X POST <YOUR_API_URL>/answer \
+  -H "Content-Type: application/json" \
+  -d '{"question": "What are the standard benefit options?"}'
+```
+
+## Next Steps
+
+- [Learn about local development](./02-local-development.md)
+- [Understand the CI/CD infrastructure](./03-infrastructure-deployment.md)
+- [Learn how to test APIs locally](./04-testing-with-http-files.md)
+- [Understand Azure Identity authentication](./05-azure-identity-authentication.md)
+
+## Common Issues
+
+### Deployment Fails
+
+If deployment fails, check:
+- Your Azure subscription has sufficient quota for the required resources
+- You're deploying to a supported region (eastus2 or swedencentral)
+- Your environment name follows naming conventions (3-64 chars, lowercase letters, numbers, hyphens)
+
+### Can't Query Documents
+
+If queries return empty results:
+- Ensure all 263 documents are indexed (check `INDEX_DOCUMENT_COUNT` in environment variables)
+- Wait a few minutes after deployment for indexing to complete
+- Check the Azure AI Search service in the Azure Portal
+
+## Additional Resources
+
+- [LangChain.js Documentation](https://js.langchain.com/)
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraphjs/)
+- [Azure OpenAI Service Documentation](https://learn.microsoft.com/azure/ai-services/openai/)
+- [Azure AI Search Documentation](https://learn.microsoft.com/azure/search/)
+- [Azure Container Apps Documentation](https://learn.microsoft.com/azure/container-apps/)

docs/02-local-development.md

@@ -0,0 +1,243 @@
+# Local Development
+
+This guide explains how to set up and develop this application locally using the monorepo structure with npm workspaces.
+
+## Monorepo Structure
+
+This repository is organized as a **monorepo** using [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces). A monorepo allows multiple related packages to be managed in a single repository, making it easier to share code and maintain consistency.
+
+### Package Structure
+
+The repository contains two main workspaces in the `packages-v1` directory:
+
+```
+azure-typescript-langchainjs/
+├── packages-v1/
+│   ├── langgraph-agent/     # Core agent implementation
+│   └── server-api/           # Fastify API server
+├── package.json              # Root package with workspace config
+└── azure.yaml                # Azure deployment configuration
+```
+
+#### langgraph-agent
+
+The core agent implementation package containing:
+- **LangGraph agent architecture** for orchestrating AI components
+- **Azure OpenAI integration** for embeddings and completions
+- **Azure AI Search vector store** integration
+- **PDF document processing** and loading scripts
+- **Reusable utilities** for Azure credential management
+
+#### server-api
+
+The API server package that:
+- Exposes the agent functionality via REST API
+- Uses [Fastify](https://www.fastify.io/) web framework
+- Depends on the `langgraph-agent` package
+- Handles HTTP requests to the `/answer` endpoint
+
+### Separation of Concerns
+
+Each workspace has a clear responsibility:
+- **langgraph-agent**: Business logic, AI orchestration, data processing
+- **server-api**: HTTP layer, request/response handling, API contracts
+
+This separation makes it easy to:
+- Test agent logic independently
+- Reuse the agent in different contexts (CLI, API, batch processing)
+- Scale different components independently
+
+## Setting Up Local Development
+
+### 1. Install Dependencies
+
+From the repository root:
+
+```bash
+# Install all dependencies for all workspaces
+npm install
+```
+
+This will install dependencies for both the root project and all workspace packages.
+
+### 2. Configure Environment Variables
+
+**Prerequisites**: Complete the `azd up` deployment first (see [Getting Started](./01-getting-started.md)), which automatically creates the `.env` file with all necessary Azure resource information.
+
+If you need to manually update environment variables, edit the `.env` file in the repository root:
+
+```bash
+# Azure OpenAI
+AZURE_OPENAI_EMBEDDING_INSTANCE="your-openai-instance"
+AZURE_OPENAI_EMBEDDING_MODEL="text-embedding-3-small"
+AZURE_OPENAI_EMBEDDING_API_VERSION="2023-05-15"
+
+AZURE_OPENAI_COMPLETE_INSTANCE="your-openai-instance"
+AZURE_OPENAI_COMPLETE_MODEL="gpt-4.1-mini"
+AZURE_OPENAI_COMPLETE_API_VERSION="2025-01-01-preview"
+AZURE_OPENAI_COMPLETE_MAX_TOKENS=1000
+
+# Azure AI Search
+AZURE_AISEARCH_ENDPOINT="https://your-search-service.search.windows.net"
+AZURE_AISEARCH_INDEX_NAME="northwind"
+
+# Authentication (use passwordless for local dev)
+SET_PASSWORDLESS=true
+```
+
+**Note**: For local development, use passwordless authentication (`SET_PASSWORDLESS=true`) with Azure CLI login. See [Azure Identity Authentication](./05-azure-identity-authentication.md) for details.
+
+### 3. Build All Packages
+
+```bash
+# Build all workspaces
+npm run build
+```
+
+This command:
+1. Builds all workspace packages using their individual `build` scripts
+2. Links packages together (via `postbuild` script)
+3. Creates compiled JavaScript in each package's `dist/` directory
+
+## Key npm Scripts
+
+The root `package.json` defines several useful scripts that work across all workspaces:
+
+### Building
+
+```bash
+# Build all packages
+npm run build
+
+# Build specific workspace
+npm run build --workspace=packages-v1/langgraph-agent
+```
+
+### Running the Server
+
+```bash
+# Run the server in development mode (builds and runs with hot reload)
+npm run dev
+
+# Or run production mode after building
+npm run build
+npm start
+```
+
+The API server will start on `http://localhost:3000`.
+
+### Working with Vector Data
+
+**Note**: If you deployed with `azd up`, vector data is already loaded. These commands are only needed if you're setting up from scratch without using `azd up`.
+
+```bash
+# Load PDF documents into Azure AI Search index (only needed if not using azd up)
+npm run load_data
+
+# Test embedding generation (useful for verifying Azure OpenAI authentication)
+npm run embed
+
+# Test LLM completion (useful for verifying Azure OpenAI authentication)
+npm run llm
+```
+
+### Docker
+
+```bash
+# Build Docker image
+npm run build:docker
+
+# Build and run in Docker
+npm run start:docker
+```
+
+### Cleanup
+
+```bash
+# Clean build artifacts from all packages
+npm run clean
+```
+
+## Development Workflow
+
+### 1. Make Changes to Agent Logic
+
+Edit files in `packages-v1/langgraph-agent/src/`:
+
+```bash
+# Make changes to agent code
+vim packages-v1/langgraph-agent/src/graph.ts
+
+# Rebuild the package
+npm run build --workspace=packages-v1/langgraph-agent
+```
+
+### 2. Make Changes to API Server
+
+Edit files in `packages-v1/server-api/src/`:
+
+```bash
+# Make changes to server code
+vim packages-v1/server-api/src/server.ts
+
+# Rebuild and run
+npm run dev --workspace=packages-v1/server-api
+```
+
+### 3. Test Your Changes
+
+See [Testing with HTTP Files](./04-testing-with-http-files.md) for details on testing the API.
+
+## Workspace-Specific Commands
+
+You can run commands in specific workspaces:
+
+```bash
+# Run a command in langgraph-agent
+npm run <script> --workspace=packages-v1/langgraph-agent
+
+# Run a command in server-api
+npm run <script> --workspace=packages-v1/server-api
+```
+
+## TypeScript Configuration
+
+Each package has its own `tsconfig.json` for TypeScript compilation:
+
+- **langgraph-agent**: Configured for ES modules with Node18 target
+- **server-api**: Similar configuration, references langgraph-agent types
+
+## Troubleshooting
+
+### Build Errors
+
+If you encounter build errors:
+
+```bash
+# Clean and rebuild everything
+npm run clean
+npm install
+npm run build
+```
+
+### Module Not Found Errors
+
+If the server can't find the agent package:
+
+```bash
+# Re-link packages
+npm run build
+```
+
+The `postbuild` script handles linking, but you may need to run it manually.
+
+### Environment Variable Issues
+
+Ensure you're running commands from the repository root where the `.env` file is located. The npm scripts use `--env-file` to load environment variables.
+
+## Additional Resources
+
+- [npm Workspaces Documentation](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Node.js ES Modules](https://nodejs.org/api/esm.html)
+- [Fastify Documentation](https://www.fastify.io/)