# Caltrans Payment Tracking API - Lambda Deployment This folder contains everything needed to deploy the Caltrans Payment Tracking API to AWS Lambda using AWS SAM (Serverless Application Model). ## Files Overview - `main.py` - The FastAPI application (copied from parent directory) - `lambda_function.py` - Lambda handler that wraps the FastAPI app using Mangum - `requirements.txt` - Python dependencies for Lambda - `template.yaml` - SAM template defining AWS resources - `samconfig.toml` - SAM configuration file - `deploy.sh` - Deployment script - `README.md` - This documentation ## Prerequisites 1. **AWS CLI** - Install and configure with your AWS credentials ```bash aws configure ``` 2. **SAM CLI** - Install the Serverless Application Model CLI ```bash # macOS with Homebrew brew install aws-sam-cli # Or download from AWS documentation: # https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html ``` 3. **AWS Account** - Ensure you have appropriate permissions to create: - Lambda functions - API Gateway - IAM roles - CloudFormation stacks ## Deployment Steps ### Option 1: Quick Deployment (Recommended) 1. Make the deployment script executable: ```bash chmod +x deploy.sh ``` 2. Run the deployment script: ```bash ./deploy.sh ``` 3. Follow the guided deployment prompts to configure: - Stack name (default: `caltrans-payment-tracking-api`) - AWS region (default: `us-west-1`) - Other deployment parameters ### Option 2: Manual Deployment 1. Build the SAM application: ```bash sam build ``` 2. Deploy with guided setup: ```bash sam deploy --guided ``` 3. For subsequent deployments (after initial setup): ```bash sam deploy ``` ## API Endpoints Once deployed, your API will be available at the provided API Gateway URL with these endpoints: ### Core Endpoints - `GET /` - API information and available endpoints - `GET /health` - Health check endpoint ### Contract Payment Endpoints - `GET /contracts/{contract_number}/payments` - Complete payment history for a contract - `GET /contracts/{contract_number}/payments/monthly/{month}` - Detailed monthly payments with CAS145 estimates ### Example Usage ```bash # Get API information curl https://your-api-url.execute-api.us-west-1.amazonaws.com/prod/ # Get contract payment history curl https://your-api-url.execute-api.us-west-1.amazonaws.com/prod/contracts/033F0704/payments # Get detailed monthly payments for December 2024 curl https://your-api-url.execute-api.us-west-1.amazonaws.com/prod/contracts/033F0704/payments/monthly/2024-12 ``` ## Configuration ### Lambda Function Settings - **Runtime**: Python 3.10 - **Memory**: 512 MB - **Timeout**: 30 seconds - **Architecture**: x86_64 ### API Gateway Settings - **CORS**: Enabled for all origins - **Binary Media Types**: Supported - **Stage**: prod ## Monitoring and Logs - **CloudWatch Logs**: Lambda function logs are automatically sent to CloudWatch - **CloudWatch Metrics**: Standard Lambda and API Gateway metrics are available - **X-Ray Tracing**: Can be enabled for detailed performance monitoring ## Cost Considerations - **Lambda**: Pay per request and compute time - **API Gateway**: Pay per API call - **CloudWatch**: Standard logging and monitoring costs Estimated cost for moderate usage (1000 requests/month): ~$1-2/month ## Troubleshooting ### Common Issues 1. **Import Errors**: Ensure all dependencies are in `requirements.txt` 2. **Timeout Issues**: Increase Lambda timeout in `template.yaml` if needed 3. **Memory Issues**: Increase Lambda memory allocation for large responses 4. **CORS Issues**: API Gateway CORS is pre-configured ### Debugging 1. Check CloudWatch Logs: ```bash sam logs -n CaltransPaymentTrackingAPI --stack-name caltrans-payment-tracking-api --tail ``` 2. Local testing: ```bash sam local start-api ``` 3. Invoke function locally: ```bash sam local invoke CaltransPaymentTrackingAPI ``` ## Updating the Application 1. Make changes to `main.py` or other files 2. Run deployment again: ```bash ./deploy.sh ``` Or: ```bash sam build && sam deploy ``` ## Cleanup To remove all AWS resources: ```bash sam delete --stack-name caltrans-payment-tracking-api ``` ## Security Notes - API is publicly accessible by default - Consider adding API key authentication for production use - All external HTTP requests are made from Lambda (ensure appropriate security groups if using VPC) - No sensitive data is stored in the Lambda function ## Support For issues or questions about the API functionality, refer to the main application documentation or contact the development team.