Skip to content

Commit 95ecd89

Browse files
sinediedsinedied
committed
docs: add agents.md (closes #3)
1 parent ee21ee8 commit 95ecd89

1 file changed

Lines changed: 122 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Serverless Recipes for JavaScript/TypeScript
2+
3+
A collection of ready-to-use serverless code samples and recipes for building applications with TypeScript, Azure Functions, and Azure services.
4+
5+
## Overview
6+
7+
- **Purpose**: Provide practical, standalone code examples demonstrating serverless development patterns on Azure
8+
- **Audience**: Developers building serverless applications with TypeScript and Azure
9+
- **Architecture**: Serverless-first approach using Azure Functions with various Azure services (OpenAI, Cosmos DB, Blob Storage)
10+
- **Project structure**: Monorepo with multiple independent samples in the `samples/` directory, each deployable as a standalone project
11+
12+
## Key Technologies and Frameworks
13+
14+
- **Runtime**: Node.js (>=20), TypeScript 5.x
15+
- **Serverless compute**: Azure Functions (v4) with HTTP triggers
16+
- **AI/ML**: Azure OpenAI Service, OpenAI extensions for Azure Functions
17+
- **Database**: Azure Cosmos DB for NoSQL
18+
- **Storage**: Azure Blob Storage
19+
- **Protocols**: Model Context Protocol (MCP) for AI tool integration
20+
- **API documentation**: OpenAPI/Swagger specifications
21+
- **Infrastructure**: Azure Developer CLI (azd), Bicep templates
22+
- **Build tools**: Vite 6.x, Azure Functions Core Tools v4
23+
- **Development**: GitHub Codespaces, VS Code Dev Containers
24+
25+
## Constraints and Requirements
26+
27+
- **Node.js version**: Minimum v20 LTS required for all samples
28+
- **Azure account**: Required with specific permissions:
29+
- `Microsoft.Authorization/roleAssignments/write` (RBAC Administrator, User Access Administrator, or Owner role)
30+
- `Microsoft.Resources/deployments/write` at subscription level
31+
- **Regional availability**: Some samples require Azure OpenAI enabled regions
32+
- **Quotas**: Azure OpenAI models have regional quotas and capacity limits
33+
- **Cost management**: All samples use consumption-based pricing; remember to clean up resources with `azd down --purge`
34+
35+
## Development Workflow
36+
37+
### Setup and Installation
38+
```bash
39+
# Clone the repository
40+
git clone <your-fork-url>
41+
42+
# Navigate to a specific sample
43+
cd samples/<sample-name>
44+
45+
# Install dependencies
46+
npm install
47+
```
48+
49+
### Local Development
50+
```bash
51+
# Start local development server
52+
npm start
53+
54+
# Run linting
55+
npm run lint
56+
57+
# Build the project
58+
npm run build
59+
60+
# Test API endpoints (if available)
61+
# Open api.http file in VS Code and use "Send Request"
62+
```
63+
64+
### Deployment
65+
```bash
66+
# Login to Azure
67+
azd auth login
68+
69+
# Deploy to Azure
70+
azd up
71+
72+
# Clean up resources
73+
azd down --purge
74+
```
75+
76+
### Testing
77+
- Use `api.http` files for HTTP endpoint testing in VS Code
78+
- OpenAPI/Swagger specifications available for API exploration
79+
- MCP Inspector for testing Model Context Protocol tools at `http://localhost:7071/runtime/webhooks/mcp/sse`
80+
81+
## Coding Guidelines
82+
83+
- **Language**: TypeScript with strict type checking enabled
84+
- **Code style**: XO linter with Prettier formatting (2 spaces, semicolons, single quotes, 120 char line width)
85+
- **File structure**: Functions in `src/functions/`, shared code in `src/`, infrastructure in `infra/`
86+
- **Configuration**: Environment variables in `local.settings.json` for local development
87+
- **Error handling**: Proper HTTP status codes and error messages in API responses
88+
- **Security**: Use Azure managed identity for resource access, no hardcoded secrets
89+
90+
## Security Considerations
91+
92+
- **Authentication**: Azure managed identity for inter-service communication
93+
- **Secrets management**: Use Azure Key Vault or App Settings, never commit secrets to code
94+
- **API security**: Implement proper input validation and sanitization
95+
- **CORS**: Configure appropriate CORS policies for web clients
96+
- **Resource access**: Use principle of least privilege for Azure role assignments
97+
98+
## Pull Request Guidelines
99+
100+
- **Build status**: All CI/CD checks must pass (build, lint, test across Node.js v20)
101+
- **Sample structure**: Each sample must be self-contained with its own `README.md`, `package.json`, and deployment configuration
102+
- **Documentation**: Update main README.md samples list if adding new samples
103+
- **Testing**: Ensure `npm start` works locally and `azd up` deploys successfully
104+
- **Cleanup**: Verify `azd down --purge` removes all resources
105+
106+
## Debugging and Troubleshooting
107+
108+
### Common Issues
109+
- **Quota exceeded**: Deploy to different regions or request quota increases for Azure OpenAI
110+
- **Resource conflicts**: Use `azd down --purge` to fully clean up soft-deleted resources (48-hour retention)
111+
- **Cold start delays**: First requests may take several seconds due to serverless scale-to-zero
112+
- **Regional availability**: Check [Azure OpenAI model availability matrix](https://aka.ms/oai/models) for supported regions
113+
114+
### Local Development
115+
- **Functions runtime**: Ensure Azure Functions Core Tools v4 is installed
116+
- **Environment variables**: Copy and configure `local.settings.json` from template
117+
- **Port conflicts**: Default local port is 7071 for Azure Functions
118+
119+
### Performance Considerations
120+
- **Serverless cold starts**: Consider Azure Functions Premium plan for production workloads requiring consistent performance
121+
- **Memory optimization**: Configure appropriate memory allocation for Functions
122+
- **Connection pooling**: Implement proper database connection management for Azure Cosmos DB

0 commit comments

Comments
 (0)