AI Assistant Integration
Use an AI coding assistant to help generate and maintain your serverless configuration. Add the steering file below to give your assistant full context about the plugin.
Quick Reference: See AI Quick Reference for a condensed reference guide with all component types, link types, and validation rules.
Plugin Integration
Step 1: Install the Plugin
Build and install the plugin to your local Maven repository:
cd serverless-maven-plugin
mvn clean install
Step 2: Add to Your Project
Add the plugin to your project's pom.xml:
<build>
<plugins>
<plugin>
<groupId>uk.co.taylor-made-software</groupId>
<artifactId>plugin-maven</artifactId>
<version>1.0.1-SNAPSHOT</version>
<configuration>
<configFile>${project.basedir}/src/main/serverless/config.json</configFile>
</configuration>
</plugin>
</plugins>
</build>
Step 3: Create Configuration
Create src/main/serverless/config.json with your serverless configuration.
Step 4: Run Maven Goals
mvn serverless:validate # Validate configuration
mvn serverless:plan # Preview changes
mvn serverless:deploy # Deploy infrastructure
Kiro Steering File
Save this as .kiro/steering/serverless-plugin.md in your project:
---
inclusion: auto
---
# Serverless Maven Plugin
This project uses the Serverless Maven Plugin to deploy serverless infrastructure.
## Plugin Integration
- GroupId: `uk.co.taylor-made-software`
- ArtifactId: `plugin-maven`
- Version: `1.0.1-SNAPSHOT`
- Config file: `src/main/serverless/config.json`
- Provider: aws | azure | gcp (set in config)
## Maven Plugin Configuration
```xml
<plugin>
<groupId>uk.co.taylor-made-software</groupId>
<artifactId>plugin-maven</artifactId>
<version>1.0.1-SNAPSHOT</version>
<configuration>
<configFile>${project.basedir}/src/main/serverless/config.json</configFile>
</configuration>
</plugin>
```
## Maven Goals
- `mvn serverless:validate` - Validate configuration
- `mvn serverless:plan` - Generate deployment plan
- `mvn serverless:deploy` - Deploy infrastructure
- `mvn serverless:verify` - Health check deployed resources
- `mvn serverless:undeploy` - Tear down infrastructure
## Maven Goals
```bash
mvn serverless:validate # Validate configuration
mvn serverless:plan # Preview changes
mvn serverless:deploy # Deploy infrastructure
mvn serverless:verify # Health check deployed resources
mvn serverless:undeploy # Tear down infrastructure
```
## Plugin POM Configuration
```xml
<plugin>
<groupId>uk.co.taylor-made-software</groupId>
<artifactId>plugin-maven</artifactId>
<version>1.0.1-SNAPSHOT</version>
<configuration>
<configFile>${project.basedir}/src/main/serverless/config.json</configFile>
</configuration>
</plugin>
```
## Root Configuration Structure
```json
{
"name": "string (human-readable app name)",
"description": "string (optional description)",
"application": "string (reverse-domain notation, e.g. com.example.myapp)",
"provider": "aws | azure | gcp",
"profile": "string (optional, AWS profile name for credentials)",
"variables": {
"variableName": "value"
},
"regions": [
{
"region": "string (e.g. eu-west-2, global)",
"items": [
// component objects or file paths (e.g. "components/my-component.json")
]
}
]
}
```
### Variable Substitution
Use `${variableName}` in any string field to reference variables defined in the root `variables` object.
## Component Base Structure
Every component has this base structure:
```json
{
"type": "component-type",
"name": "unique-component-name",
"providerSettings": {
// component-specific configuration
},
"links": [
{
"sourceComponent": "this-component",
"targetComponent": "target-component",
"linkType": "LINK_TYPE"
}
]
}
```
## Component Types
| Type | Region | Description |
|------|--------|-------------|
| `website` | specific | Static website with CDN |
| `storage` | specific | Object storage bucket |
| `api-gateway` | specific | REST API with routes |
| `functions` | specific | Serverless function group |
| `database` | specific | NoSQL database |
| `event-bus` | specific | Pub/sub event bus |
| `authentication` | **global** | User identity provider |
| `email` | **global** | Transactional email |
| `sms` | **global** | SMS messaging |
## Website Component
Static website with CDN distribution. Always provisions its own storage bucket automatically — do NOT create a separate storage component for website assets.
```json
{
"type": "website",
"name": "frontend",
"providerSettings": {
"domain": "www.example.com"
},
"links": [
{
"sourceComponent": "frontend",
"targetComponent": "main-api",
"linkType": "WEBSITE_TO_API_GATEWAY"
}
]
}
```
**Required:** `domain` (full hostname)
**Valid Links:** WEBSITE_TO_API_GATEWAY, WEBSITE_TO_STORAGE
## Storage Component
Object storage bucket with optional Maven artifact uploads.
```json
{
"type": "storage",
"name": "deploy-artifacts",
"providerSettings": {
"uploads": [
{
"artifact": "com.example:myapp:1.0.0",
"destination": "releases/myapp/",
"unpack": true,
"classifier": "dist",
"extension": "jar"
}
]
},
"links": []
}
```
**Upload fields:**
- `artifact` (required): Maven coordinate `groupId:artifactId:version`
- `destination` (required): Target path in bucket (must end with `/`)
- `unpack` (optional): Extract archive contents instead of uploading file
- `classifier` (optional): Maven classifier (e.g. `dist`, `sources`)
- `extension` (optional): Override file extension
## API Gateway Component
REST API with routes, authentication, and pre/post processing.
```json
{
"type": "api-gateway",
"name": "main-api",
"providerSettings": {
"domain": "api.example.com",
"preProcessFunction": "request-validator",
"postProcessFunction": "response-logger",
"routes": [
{
"path": "/users",
"method": "GET",
"function": "user-handler",
"auth": "user-auth"
},
{
"path": "/public",
"method": "GET",
"function": "public-handler",
"preProcessFunction": "",
"postProcessFunction": ""
}
]
},
"links": []
}
```
**Required:** `domain`, `routes` (at least one)
**Route fields:**
- `path` (required): URL path (must start with `/`)
- `method` (required): HTTP method (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD)
- `function` (required): Function name to invoke
- `auth` (optional): Authentication component name for JWT validation
- `preProcessFunction` (optional): Override component-level pre-processor (use `""` to disable)
- `postProcessFunction` (optional): Override component-level post-processor (use `""` to disable)
**Optional component-level fields:**
- `preProcessFunction`: Function to run before every request
- `postProcessFunction`: Function to run after every response
**Important:** Function names in routes, `preProcessFunction`, and `postProcessFunction` are implicit references — do NOT add them to `links`.
## Functions Component
Groups one or more serverless functions sharing the same deployment artifact.
```json
{
"type": "functions",
"name": "app-functions",
"providerSettings": {
"codeStorage": "deploy-artifacts",
"codePath": "releases/app-functions/app-functions-1.0.0.jar",
"functions": [
{
"name": "api-handler",
"handler": "com.example.ApiHandler::handleRequest",
"runtime": "java21",
"memory": 512,
"timeout": 30,
"environment": {
"STAGE": "dev"
}
}
]
},
"links": [
{
"sourceComponent": "app-functions",
"targetComponent": "app-db",
"linkType": "FUNCTION_TO_DATABASE"
}
]
}
```
**Component-level fields (required):**
- `codeStorage` (string): Storage component name containing the deployment artifact
- `codePath` (string): Path to the JAR/ZIP file within the storage bucket
- `functions` (array): List of function definitions (at least one)
**Function item fields:**
- `name` (required): Unique function name (referenced in api-gateway routes and event-bus subscriptions)
- `handler` (required): Fully-qualified handler method (e.g. `com.example.Handler::handleRequest`)
- `runtime` (required): Runtime identifier (e.g. `java21`, `java17`, `python3.11`, `nodejs20`, `nodejs22.x`)
- `memory` (optional, default 256): Memory allocation in MB (range: 128-10240)
- `timeout` (optional, default 30): Timeout in seconds (range: 1-900)
- `environment` (optional): Environment variables as key-value object
**Valid Links:** FUNCTION_TO_DATABASE, FUNCTION_TO_STORAGE, FUNCTION_TO_EMAIL, FUNCTION_TO_SMS, FUNCTION_TO_EVENT_BUS
**Important:**
- `codeStorage` and `codePath` are shared by all functions in the component
- Links at component level apply to all functions
- Function names are implicit references when used in routes/subscriptions — do NOT add to `links`
## Database Component
NoSQL database (DynamoDB on AWS, CosmosDB on Azure, Firestore on GCP).
```json
{
"type": "database",
"name": "app-db",
"providerSettings": {
"billingMode": "PAY_PER_REQUEST"
},
"links": []
}
```
**Optional:** `billingMode` — `PAY_PER_REQUEST` (default, on-demand) or `PROVISIONED` (fixed capacity)
## Authentication Component
User identity provider with groups and pre-invited users. Must deploy in `"global"` region.
```json
{
"type": "authentication",
"name": "user-auth",
"providerSettings": {
"loginProviders": ["email", "google"],
"registration": "open",
"mfa": "optional",
"passwordPolicy": {
"minLength": 10,
"requireUppercase": true,
"requireNumbers": true,
"requireSymbols": true
},
"groups": [
{ "name": "admin", "description": "Administrator users" },
{ "name": "member", "description": "Standard members" }
],
"users": [
{ "email": "alice@example.com", "groups": ["admin", "member"] },
{ "email": "bob@example.com", "groups": ["member"] }
]
},
"links": [
{
"sourceComponent": "user-auth",
"targetComponent": "transactional-email",
"linkType": "AUTHENTICATION_TO_EMAIL"
}
]
}
```
**Fields:**
- `loginProviders` (array): `"email"`, `"phone"`, `"google"`, `"facebook"`, `"apple"` (default: `["email"]`)
- `registration` (string): `"open"` or `"admin-only"` (default: `"open"`)
- `mfa` (string): `"off"`, `"optional"`, or `"required"` (default: `"off"`)
- `passwordPolicy` (object):
- `minLength` (integer, >= 6, default 8)
- `requireUppercase` (boolean, default true)
- `requireNumbers` (boolean, default true)
- `requireSymbols` (boolean, default false)
- `groups` (array): Each requires `name` (string, non-blank) and `description` (string, non-blank)
- `users` (array): Each requires `email` (string, non-blank); optional `groups` (array of strings referencing defined group names)
**Valid Links:** AUTHENTICATION_TO_EMAIL, AUTHENTICATION_TO_SMS, AUTHENTICATION_TO_FUNCTION (implicit, from `triggers`)
**Cognito Lambda Triggers (AWS):** optional `providerSettings.triggers` maps a trigger point to a function name, e.g. `{ "preTokenGeneration": "mfa-enforcer" }`. The function is an implicit reference (not in `links`). Supported trigger points: preSignUp, postConfirmation, preAuthentication, postAuthentication, preTokenGeneration, customMessage, defineAuthChallenge, createAuthChallenge, verifyAuthChallengeResponse, userMigration. Deploy sets the pool LambdaConfig and grants cognito-idp invoke permission; redeploy updates/removes wiring.
**Validation:** Groups are provisioned before users. User group references must match defined group names. `triggers` keys must be known trigger points and values must name functions that exist. All validation errors are accumulated (no early exit).
## Email Component
Transactional email service. Must deploy in `"global"` region.
```json
{
"type": "email",
"name": "transactional-email",
"providerSettings": {
"fromAddress": "noreply@example.com"
},
"links": []
}
```
**Required:** `fromAddress`
## SMS Component
SMS messaging service. Must deploy in `"global"` region.
```json
{
"type": "sms",
"name": "notification-sms",
"providerSettings": {},
"links": []
}
```
## Event Bus Component
Pub/sub event bus with subscriptions.
```json
{
"type": "event-bus",
"name": "order-events",
"providerSettings": {
"subscriptions": [
{
"eventPattern": "order.placed",
"function": "order-processor"
}
]
},
"links": []
}
```
**Subscription fields:**
- `eventPattern` (required): Event type to match
- `function` (required): Function name to invoke
**Important:** Function names in subscriptions are implicit references — do NOT add them to `links`.
## Link Types
| Link Type | Source → Target |
|-----------|-----------------|
| `WEBSITE_TO_STORAGE` | website → storage |
| `WEBSITE_TO_API_GATEWAY` | website → api-gateway |
| `FUNCTION_TO_DATABASE` | functions → database |
| `FUNCTION_TO_STORAGE` | functions → storage |
| `FUNCTION_TO_EMAIL` | functions → email |
| `FUNCTION_TO_SMS` | functions → sms |
| `FUNCTION_TO_EVENT_BUS` | functions → event-bus |
| `AUTHENTICATION_TO_FUNCTION` | authentication → functions (implicit, Cognito Lambda trigger) |
| `AUTHENTICATION_TO_EMAIL` | authentication → email |
| `AUTHENTICATION_TO_SMS` | authentication → sms |
## Implicit vs Explicit References
**Implicit (do NOT add to `links`):**
- Function names in `api-gateway` routes (`routes[].function`)
- Auth component names in `api-gateway` routes (`routes[].auth`)
- `preProcessFunction` and `postProcessFunction` in `api-gateway`
- Function names in `event-bus` subscriptions (`subscriptions[].function`)
- Storage component name in `functions` `codeStorage`
**Explicit (add to `links`):**
- All other component relationships (FUNCTION_TO_*, AUTHENTICATION_TO_*, WEBSITE_TO_*)
## Domain Configuration
Both `website` and `api-gateway` require a `domain` field — the full hostname to serve from. The base domain is derived automatically (e.g. `api.example.com` → base `example.com`). The base domain must already be registered and have a hosted zone in the cloud provider (Route 53, Azure DNS, or Cloud DNS). The plugin provisions the DNS record and HTTPS certificate automatically.
## Multiple Instances
Any component type can appear multiple times — two websites, two api-gateways, two function groups, etc. Every component must have a unique `name`.
## Validation Rules
1. All component names must be unique
2. All link targets must reference existing components
3. Authentication groups: name and description required, non-blank
4. Authentication users: email required, non-blank; groups must reference defined groups
5. Functions: codeStorage must reference existing storage component
6. API Gateway: domain required; function/auth names must reference existing components
7. Storage uploads: destination must end with `/`
8. Event bus subscriptions: function names must reference existing functions
9. Global components (authentication, email, sms) must be in `"global"` region
## Best Practices
1. Use descriptive kebab-case names (e.g. "user-auth", "order-api", "product-db")
2. Deploy auth, email, sms in global region
3. Use variables for environment-specific values
4. Group related functions in one component
5. Run `mvn serverless:validate` before deploy
6. Run `mvn serverless:plan` to preview changes
7. Use preProcessFunction for request validation/rate limiting
8. Use postProcessFunction for audit logging/security headers
9. Define groups before users in authentication
10. Use PAY_PER_REQUEST billing for databases (default)
## Known Limitations
```json
{
"type": "website",
"name": "frontend",
"providerSettings": {
"domain": "www.example.com"
},
"links": []
}
```
```json
{
"type": "api-gateway",
"name": "main-api",
"providerSettings": {
"domain": "api.example.com",
"routes": [ ... ]
},
"links": []
}
```
The base domain is derived automatically from the last two labels:
- `www.example.com` → base `example.com`
- `app.prod.example.com` → base `example.com`
The base domain must already be registered and have a hosted zone in the cloud provider
(Route 53, Azure DNS, or Cloud DNS). The plugin provisions the DNS record and HTTPS
certificate for the full domain as part of the deploy — no manual certificate or DNS setup required.
## API Gateway Pre/Post Processing
`preProcessFunction` and `postProcessFunction` are optional fields on the api-gateway component.
- `preProcessFunction` — runs before every request is routed (request transformation, IP filtering, etc.)
- `postProcessFunction` — runs after every response is produced (audit logging, security headers, etc.)
Both can be overridden per-route. Set to `""` on a route to disable for that route only.
Because these are named in dedicated fields, they are implicit references — do NOT add them to `references`.
The `website` component always provisions its own CDN-backed storage bucket automatically.
Do NOT add a separate `storage` component for website static assets.
## Storage Uploads
The `storage` component supports an optional `uploads` array in `providerSettings` to push Maven artifacts into the bucket at deploy time.
```json
{
"type": "storage",
"name": "deploy-artifacts",
"providerSettings": {
"uploads": [
{
"artifact": "com.example:myapp:1.0.0",
"destination": "releases/myapp/",
"unpack": true
}
]
},
"links": []
}
```
Each entry requires:
- `artifact` — Maven coordinate `groupId:artifactId:version`
- `destination` — target path prefix in the bucket (must end with `/`)
Optional per entry:
- `unpack: true` — extract the archive contents to `destination` instead of uploading the file itself
- `classifier` — Maven classifier (e.g. `dist`, `sources`)
- `extension` — override the file extension
## Goals
- `mvn serverless:validate` — validate config
- `mvn serverless:plan` — preview changes
- `mvn serverless:deploy` — deploy
- `mvn serverless:verify` — health check
- `mvn serverless:undeploy` — tear down
## Global Region
Use `"region": "global"` for: authentication, email, sms
## Common Patterns and Best Practices
### Pattern 1: Multi-tier Web Application
```json
{
"regions": [
{
"region": "global",
"items": [
{
"type": "authentication",
"name": "user-auth",
"providerSettings": {
"loginProviders": ["email"],
"groups": [
{ "name": "admin", "description": "Administrators" },
{ "name": "user", "description": "Regular users" }
]
},
"links": []
},
{
"type": "email",
"name": "app-email",
"providerSettings": { "fromAddress": "noreply@example.com" },
"links": []
}
]
},
{
"region": "eu-west-2",
"items": [
{
"type": "storage",
"name": "artifacts",
"providerSettings": {
"uploads": [
{
"artifact": "com.example:backend:1.0.0",
"destination": "releases/backend/",
"unpack": true
}
]
},
"links": []
},
{
"type": "database",
"name": "app-db",
"providerSettings": { "billingMode": "PAY_PER_REQUEST" },
"links": []
},
{
"type": "functions",
"name": "backend",
"providerSettings": {
"codeStorage": "artifacts",
"codePath": "releases/backend/backend-1.0.0.jar",
"functions": [
{
"name": "api-handler",
"handler": "com.example.ApiHandler::handleRequest",
"runtime": "java21",
"memory": 512
}
]
},
"links": [
{
"sourceComponent": "backend",
"targetComponent": "app-db",
"linkType": "FUNCTION_TO_DATABASE"
},
{
"sourceComponent": "backend",
"targetComponent": "app-email",
"linkType": "FUNCTION_TO_EMAIL"
}
]
},
{
"type": "api-gateway",
"name": "api",
"providerSettings": {
"domain": "api.example.com",
"routes": [
{
"path": "/users",
"method": "GET",
"function": "api-handler",
"auth": "user-auth"
}
]
},
"links": []
},
{
"type": "website",
"name": "frontend",
"providerSettings": { "domain": "www.example.com" },
"links": [
{
"sourceComponent": "frontend",
"targetComponent": "api",
"linkType": "WEBSITE_TO_API_GATEWAY"
}
]
}
]
}
]
}
```
### Pattern 2: Event-Driven Architecture
```json
{
"regions": [
{
"region": "us-east-1",
"items": [
{
"type": "event-bus",
"name": "events",
"providerSettings": {
"subscriptions": [
{ "eventPattern": "order.created", "function": "order-processor" },
{ "eventPattern": "order.shipped", "function": "notification-sender" }
]
},
"links": []
},
{
"type": "functions",
"name": "processors",
"providerSettings": {
"codeStorage": "artifacts",
"codePath": "releases/processors/processors-1.0.0.jar",
"functions": [
{
"name": "order-processor",
"handler": "com.example.OrderProcessor::handleRequest",
"runtime": "java21"
},
{
"name": "notification-sender",
"handler": "com.example.NotificationSender::handleRequest",
"runtime": "java21"
}
]
},
"links": [
{
"sourceComponent": "processors",
"targetComponent": "events",
"linkType": "FUNCTION_TO_EVENT_BUS"
}
]
}
]
}
]
}
```
### Pattern 3: Multi-Region Deployment
Deploy the same components to multiple regions:
```json
{
"regions": [
{
"region": "global",
"items": [
{ "type": "authentication", "name": "auth", "providerSettings": {} }
]
},
{
"region": "us-east-1",
"items": [
{ "type": "database", "name": "db-us", "providerSettings": {} },
{ "type": "functions", "name": "api-us", "providerSettings": {} }
]
},
{
"region": "eu-west-1",
"items": [
{ "type": "database", "name": "db-eu", "providerSettings": {} },
{ "type": "functions", "name": "api-eu", "providerSettings": {} }
]
}
]
}
```
### Best Practices
1. **Component Naming:** Use descriptive, kebab-case names (e.g., "user-auth", "order-api", "product-db")
2. **Region Selection:**
- Use "global" for: authentication, email, sms
- Use specific regions for: website, storage, api-gateway, functions, database, event-bus
- Consider latency and data residency requirements
3. **Links vs Implicit References:**
- Use `links` array for: FUNCTION_TO_DATABASE, FUNCTION_TO_STORAGE, FUNCTION_TO_EMAIL, FUNCTION_TO_SMS, FUNCTION_TO_EVENT_BUS, AUTHENTICATION_TO_EMAIL, AUTHENTICATION_TO_SMS, WEBSITE_TO_API_GATEWAY, WEBSITE_TO_STORAGE
- Do NOT use `links` for: function names in api-gateway routes, function names in event-bus subscriptions, auth component names in routes, preProcessFunction, postProcessFunction, authentication `triggers` function names (AUTHENTICATION_TO_FUNCTION is implicit)
4. **Authentication Groups:**
- Define groups before users
- Use clear, descriptive group names and descriptions
- Validate that user group references match defined groups
5. **Functions Component:**
- Group related functions together in one component
- Share codeStorage and codePath across all functions in a component
- Use component-level links for shared dependencies
- Set appropriate memory and timeout for each function
6. **Storage Uploads:**
- Use unpack: true for JAR/ZIP files that need extraction
- Ensure destination paths end with "/"
- Reference the correct Maven coordinates
7. **API Gateway:**
- Use preProcessFunction for request validation, IP filtering, rate limiting
- Use postProcessFunction for audit logging, response transformation, security headers
- Override per-route with "" to disable for specific routes
- Always specify auth component for protected routes
8. **Variables:**
- Use variables for environment-specific values (stage, domain suffixes, etc.)
- Reference with ${variableName} syntax in any string field
9. **Validation:**
- Run `mvn serverless:validate` before deploy
- Check for missing required fields, invalid references, blank values
- Verify all component names are unique
10. **Deployment:**
- Use `mvn serverless:plan` to preview changes before deploy
- Deploy to dev/staging environments first
- Use `mvn serverless:verify` after deploy to check health
Prompt Library
Generate a complete application
Generate a serverless config for a web app with:
- A React SPA (website) at www.example.com
- A REST API (api-gateway) at api.example.com backed by Java functions
- A DynamoDB database
- Cognito authentication with admin and member groups
- Email service for transactional emails
- Deploy to AWS eu-west-2
Include:
- Storage component for deployment artifacts
- Functions component with api-handler and event-processor functions
- Authentication with groups: admin, member
- Pre-invite users: admin@example.com (admin group), user@example.com (member group)
- Wire all components together with appropriate links
Add authentication with groups and users
Add an authentication component called "user-auth" with:
- Email login provider
- Open registration
- Optional MFA
- Password policy: min 10 chars, require uppercase, numbers, and symbols
- Groups: "admin" (Administrator users), "editor" (Content editors), "viewer" (Read-only users)
- Pre-invite users:
- admin@example.com in admin and editor groups
- editor@example.com in editor group
- viewer@example.com in viewer group
- Link to "transactional-email" component for verification emails
Deploy in global region
Add a functions component with database access
Add a functions component called "api-functions" with:
- codeStorage: "deploy-artifacts"
- codePath: "releases/api-functions/api-functions-1.0.0.jar"
- Three functions:
1. "user-handler" with handler "com.example.UserHandler::handleRequest", runtime java21, 512MB memory
2. "order-handler" with handler "com.example.OrderHandler::handleRequest", runtime java21, 1024MB memory, 60s timeout
3. "notification-handler" with handler "com.example.NotificationHandler::handleRequest", runtime java21
- Add links to "app-db" database, "transactional-email" email, and "order-events" event-bus
Add an API gateway with routes
Add an api-gateway component called "main-api" with:
- domain: api.example.com
- preProcessFunction: "request-validator" (runs before all routes)
- postProcessFunction: "response-logger" (runs after all routes)
- Routes:
1. GET /users - function: "user-handler", auth: "user-auth"
2. POST /users - function: "user-handler", auth: "user-auth"
3. GET /orders - function: "order-handler", auth: "user-auth"
4. GET /public/health - function: "health-check", no auth, disable pre/post processing
5. POST /webhooks/stripe - function: "webhook-handler", no auth, preProcessFunction: "webhook-validator"
Add an event bus with subscriptions
Add an event-bus component called "order-events" with subscriptions:
- "order.placed" → "order-processor" function
- "order.shipped" → "notification-handler" function
- "order.cancelled" → "refund-processor" function
Add storage with Maven artifact uploads
Add a storage component called "deploy-artifacts" with uploads:
1. artifact: "com.example:api-functions:1.0.0", destination: "releases/api-functions/", unpack: true
2. artifact: "com.example:event-processors:1.0.0", destination: "releases/event-processors/", unpack: true
3. artifact: "com.example:frontend:1.0.0", classifier: "dist", destination: "releases/frontend/", unpack: true
Add component links
My "api-handler" function needs to:
- Read/write to the "app-db" database
- Send emails via the "transactional-email" component
- Publish events to the "order-events" event-bus
- Access files in the "asset-store" storage bucket
Add the appropriate links to the api-handler component's links array.
Update authentication groups and users
Update the "user-auth" authentication component:
- Add a new group: "moderator" with description "Content moderators"
- Add new users:
- moderator@example.com in moderator and viewer groups
- support@example.com in viewer group
- Update alice@example.com to be in admin, editor, and moderator groups
Validate and deploy
Run serverless:validate and explain any errors in my config.
If validation passes, show me the mvn command to deploy.
Explain configuration
Explain my current serverless configuration:
- What components are defined?
- How are they connected (links)?
- What regions are they deployed to?
- Are there any implicit references (routes, subscriptions)?
Troubleshoot validation errors
I'm getting validation errors. Check my config for:
- Missing required fields
- Invalid link types
- Undefined component references
- Blank group/user fields in authentication
- Users referencing non-existent groups
- Functions referencing non-existent storage components
Explain each error and how to fix it.
Explain component fields
What does the "billingMode" field on a database component do?
What are the valid values and when should I use each?
Generate complete example
Generate a complete serverless config for an e-commerce platform with:
**Infrastructure:**
- Website at www.shop.example.com
- API at api.shop.example.com
- Deploy to AWS us-east-1
**Components:**
1. Storage for deployment artifacts with uploads:
- com.shop:api-functions:2.0.0 → releases/api/
- com.shop:event-processors:2.0.0 → releases/events/
2. Database for product catalog and orders
3. Authentication with:
- Email and Google login
- Open registration with optional MFA
- Groups: admin, seller, customer
- Pre-invite: admin@shop.example.com (admin), seller@shop.example.com (seller)
4. Functions component "api-functions" with:
- product-handler (java21, 512MB)
- order-handler (java21, 1024MB, 60s timeout)
- payment-handler (java21, 512MB)
- All linked to database and email
5. Functions component "event-processors" with:
- order-processor (java21, 256MB)
- notification-processor (java21, 256MB)
- Both linked to database and email
6. API Gateway with routes:
- GET/POST /products → product-handler (auth required)
- GET/POST /orders → order-handler (auth required)
- POST /payments → payment-handler (auth required)
- GET /health → product-handler (no auth)
- preProcessFunction: "request-validator"
- postProcessFunction: "audit-logger"
7. Event bus "order-events" with subscriptions:
- order.created → order-processor
- order.completed → notification-processor
8. Email component for transactional emails (from: noreply@shop.example.com)
9. SMS component for order notifications
Wire everything together with appropriate links.
Complete Example Configuration
See example-complete-config.json for a complete, production-ready configuration demonstrating:
- Authentication with groups (admin, seller, customer) and pre-invited users
- Multiple functions components (api-functions, event-processors)
- API Gateway with 10 routes, pre/post processing, and authentication
- Event-driven architecture with order events and subscriptions
- Storage with Maven artifact uploads
- Database, email, and SMS components
- Website with CDN distribution
- Variable substitution for stage and version
- Comprehensive component linking
Known Limitations
- The base domain for website and api-gateway must already be registered and have a hosted zone in the cloud provider (Route 53, Azure DNS, or Cloud DNS). The plugin derives the base domain from the last two labels of the domain field and provisions the DNS record and HTTPS certificate automatically.
- Social login providers (Google, Facebook, Apple) require OAuth app credentials configured outside the plugin.
- Azure AD B2C tenant creation requires manual setup.
- GCP Firestore is project-scoped — all database components in a GCP project share one Firestore instance.
- AWS SES starts in sandbox mode — request production access separately.
- GCP SMS and Email use third-party services (Twilio, SendGrid) via Secret Manager.