create-veloflow-service

🚀 CLI tool to create new VeloFlow Lambda services from template

Create production-ready VeloFlow Lambda services in seconds with an interactive CLI.

Features

✅ Interactive Setup - Guided prompts for service configuration ✅ Production-Ready - Complete CI/CD with GitHub Actions ✅ Comprehensive Testing - Unit tests, coverage, linting, security scans ✅ VeloFlow Integration - Full compatibility with VeloFlow workflows ✅ Smart Defaults - Intelligent configuration based on service type ✅ No Dependencies - Works with npx, no installation needed

Quick Start

Create a New Service

npx create-veloflow-service my-pdf-processor

That's it! The CLI will:

1. ✅ Prompt you for service configuration
2. ✅ Download the latest service template
3. ✅ Customize all files with your inputs
4. ✅ Initialize git repository
5. ✅ Install dependencies (npm + pip)
6. ✅ Display next steps

Usage

Interactive Mode

npx create-veloflow-service

Prompts you for:

• Service name
• Description
• Service type (PDF processor, Excel processor, etc.)
• Input/output formats
• AI provider (if applicable)
• Lambda memory and timeout
• CI/CD preferences

With Service Name

npx create-veloflow-service my-service-name

Provide the service name upfront and configure the rest interactively.

With Custom Template

npx create-veloflow-service my-service --template github:myorg/custom-template

Use a custom template repository instead of the default.

Skip Options

# Skip dependency installation
npx create-veloflow-service my-service --skip-install

# Skip git initialization
npx create-veloflow-service my-service --skip-git

# Skip both
npx create-veloflow-service my-service --skip-install --skip-git

What Gets Created

my-service/
├── lambda_handler.py              # Main Lambda handler
├── service_event_emitter.py       # VeloFlow event emitter
├── veloflow.json                  # Service metadata ⭐
├── requirements.txt               # Python dependencies
├── requirements-dev.txt           # Dev/test dependencies
├── serverless.yml                 # Serverless Framework config
├── package.json                   # NPM scripts
├── test-event.json                # Sample test event
│
├── .github/workflows/             # GitHub Actions CI/CD ⭐
│   ├── pr-validation.yml          # PR testing
│   ├── ci-deploy-dev.yml          # Auto deploy to dev
│   ├── promote-qa.yml             # Promote to QA
│   └── promote-prod.yml           # Promote to production
│
├── tests/                         # Unit tests ⭐
│   └── test_lambda_handler.py
│
├── scripts/                       # Utility scripts
│   └── README.md
│
└── README.md                      # Service documentation

Generated Service Features

VeloFlow Integration

• ✅ Complete event format handling
• ✅ Real-time progress updates via EventBridge
• ✅ Multi-stage workflow support
• ✅ S3 input/output handling
• ✅ Service metadata in veloflow.json

CI/CD Pipeline

• ✅ PR Validation: Tests, linting, security scans
• ✅ Auto Deploy to Dev: On merge to main
• ✅ Promote to QA: Manual with smoke tests
• ✅ Promote to Production: Manual with approval
• ✅ Build Artifact Promotion: Build once, deploy many
• ✅ Git Tag Versioning: Track all deployments

Testing Infrastructure

• ✅ pytest with coverage (40% minimum)
• ✅ black for code formatting
• ✅ flake8 for linting
• ✅ isort for import sorting
• ✅ bandit for security scanning
• ✅ safety for dependency vulnerabilities

After Creating Your Service

1. Implement Your Logic

# Edit lambda_handler.py
def process_file(input_path, output_path, config, emitter):
    emitter.emit_progress('Processing started...')

    # Your service logic here

    emitter.emit_progress('Processing complete')
    return {'success': True, 'metadata': {}}

2. Update Service Metadata

# Edit veloflow.json with your service details
vim veloflow.json

3. Test Locally

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/ --cov

# Check formatting
black --check .
flake8 .

4. Deploy to AWS

# Deploy to dev environment
npm run deploy:dev

# View logs
npm run logs:dev

5. Register with VeloFlow

cd ~/git/VeloFlow
python3 scripts/services/register_service.py ~/path/to/my-service --stage dev

6. Set Up CI/CD

1. Push to GitHub
2. Configure secrets: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
3. Create environments: qa, production
4. Enable branch protection on main

See .github/workflows/README.md for detailed CI/CD documentation.

Service Types

The CLI supports these service types out of the box:

• PDF Processor - Extract, parse, or transform PDF documents
• Excel Processor - Process Excel/CSV files
• Financial Analyzer - Analyze financial statements
• Data Formatter - Format and transform data
• Document Analyzer - Analyze various document types
• Custom - Define your own service type

AI Provider Integration

If your service uses AI:

• Anthropic (Claude) - Adds anthropic>=0.18.0
• OpenAI - Adds openai>=1.0.0
• AWS Bedrock - Uses existing boto3

Dependencies are automatically added to requirements.txt.

Requirements

• Node.js >= 14.0.0 (for npx and Serverless Framework)
• Python >= 3.11 (for Lambda runtime)
• Git (for repository initialization)
• Internet connection (to download template)

Options Reference

create-veloflow-service [service-name] [options]

Arguments:
  service-name              Name of the service to create

Options:
  -t, --template <url>      Custom template repository
  --skip-install            Skip dependency installation
  --skip-git                Skip git initialization
  -h, --help                Display help information

Template Repository

This CLI uses VeloQuote/service-template as the default template.

Using a Custom Template

You can use your own template repository:

npx create-veloflow-service my-service --template github:myorg/my-template

Template requirements:

• Must be a public GitHub repository (or use private with token)
• Should follow VeloFlow service structure
• Include veloflow.json for service metadata

Troubleshooting

"Template download failed"

• Check your internet connection
• Verify the template repository is accessible
• Try again with --template VeloQuote/service-template

"Permission denied" on Linux/Mac

# Make sure npm global bin is in PATH
npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"

"Module not found" errors

# Reinstall dependencies
cd my-service
npm install
pip install -r requirements.txt

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT © VeloQuote

Links

• GitHub: https://github.com/VeloQuote/create-veloflow-service
• Template: https://github.com/VeloQuote/service-template
• Issues: https://github.com/VeloQuote/create-veloflow-service/issues
• VeloFlow: https://github.com/VeloQuote/VeloFlow

Made with ❤️ by VeloQuote