Module Builder Agent

Overview

What it is

The Facets Module Development AI Agent is a built-in assistant that helps you create, modify, and validate production-ready Terraform modules for the Facets platform. It provides a natural language interface to generate module scaffolding, manage configurations, validate schemas, and publish modules to your Control Plane—without needing to manually write boilerplate code or edit complex YAML files.

Praxis (Our Agent) helps you query existing intents, create new intents with proper categorisation, register custom output types with JSON Schema validation, and choose appropriate flavors for your infrastructure.

Key Benefits

Accelerated Module Creation: Generate complete Terraform modules in minutes with proper structure, type-safe configurations, and best practices built-in.

Zero Boilerplate: Automatically scaffold facets.yaml, main.tf, variables.tf, and outputs.tf with validated schemas.

Type-Safe Integration: Enforce output type schemas and input dependencies, ensuring modules connect safely across your infrastructure.

Preview and Test: Push preview versions to test environments before marking modules as production-ready.

Capabilities

The agent can handle the complete module development lifecycle, from creation to deployment:

Module Scaffolding: Generate new modules or fork existing ones from the Facets registry with customized intents and flavors.

Configuration Management: Create and edit facets.yaml definitions, Terraform files (main.tf, variables.tf), and type-safe outputs.tf with validated fields.

Type System: Query, create, and register module intents and custom output types with JSON Schema validation.

Validation: Check module structure, Terraform syntax, format compliance, and output type registration before deployment.

Repository Integration: Attach git repositories, commit changes, and push to remote using secure Personal Access Token (PAT) authentication.

Preview Deployments: Publish test versions to the Control Plane, deploy to test environments, monitor logs, and debug failures.

How to Use It

Access Praxis: From the Intelligence landing page, click the "Build Terraform Modules" card
Describe Your Module: Tell Praxis what infrastructure you want to provision (e.g., "Create a PostgreSQL RDS module with Multi-AZ support")
Review the Plan: Praxis shows you all files and configurations before making changes
Approve and Generate: Confirm to create the module structure with all necessary files
Validate: Praxis automatically validates structure, format, and Terraform syntax
Preview: Push a test version to Control Plane for environment testing
Deploy and Test: Test in a live environment and review deployment logs

How It Works

Praxis orchestrates module creation through integration with the Facets Control Plane and your git repositories.

Module Generation: When you request a module, Praxis queries the Control Plane for existing intents and output types, generates Terraform files following Facets conventions, creates type-safe facets.yaml configurations, and registers custom output types if needed.

Type System Enforcement: All module outputs must conform to registered output type schemas. Praxis validates output definitions against JSON Schema, ensures required fields are present, checks that output types exist in Control Plane, and enforces provider compatibility for dependencies.

Validation Pipeline: Before preview or publishing, modules pass through structure validation (required files), format validation (YAML/Terraform syntax), Terraform syntax check, output type validation, and schema compliance verification.

Repository Integration: Praxis securely manages git operations using your Personal Access Tokens (never exposed), clones repositories into dedicated working directories, tracks changes across multiple repositories, and supports standard git workflows (commit, push, branch management).

Safety Mechanisms: All destructive operations default to dry-run mode, showing diffs before applying changes and requiring explicit user approval for modifications.

Example Prompts

Module Creation:

"Create a new Kubernetes cluster module for GKE with flavor 'standard'"
"Generate an S3 bucket module with versioning and encryption enabled"
"Fork the existing 'rds-postgres' module and customize it for Aurora"

Configuration Management:

"Add a variable for backup retention days to the RDS module"
"Update the outputs to include the database endpoint and port"
"Register a new output type for Redis connection strings"

Validation and Testing:

"Validate the PostgreSQL module structure"
"Push a preview version of this module to test it"
"Deploy the preview module to my staging environment"
"Check the deployment logs for the last test run"

Repository Management

Praxis provides seamless git integration for professional module development workflows.

Attaching Repositories: Use Personal Access Tokens (PATs) configured in Facets for authentication. PAT credentials are never exposed. Multiple repositories can be attached to the same session.

Git Operations: Praxis performs standard git operations including status checks, commits with descriptive messages, and push to remote branches.

Best Practices: Always work in repositories for production modules, use clear commit messages, test with preview deployments before merging to main branches.

Security and Access Control

PAT Security: Personal Access Tokens are stored encrypted in Facets and never exposed or displayed in conversations.

Sensitive Outputs: Praxis enforces sensitivity flags for outputs containing secrets (database passwords, API keys) which are excluded from logs and UI display.

Module Validation: All modules are validated against Facets platform schemas before deployment, ensuring no malicious code can be published and output types match registered schemas.

RBAC: Module operations respect Facets platform permissions for repository access, preview deployments, and module publishing.

Troubleshooting & FAQ

Q: Validation fails with "Provider configuration not present" A: The agent can skip provider validation with skip_terraform_validation_if_provider_not_found=true. Structure and format validation will still occur.

Q: Preview push fails with "Output type not found" A: Your module references an output type that doesn't exist in the Control Plane. Ask Praxis to register the output type for you.

Q: Module generation creates files but they're not in git A: Ensure you have a repository attached before generating modules. Use: "Attach my modules repository"

Q: Can I modify modules outside Praxis? A: Yes! Praxis uses standard Terraform files. You can edit files manually. However, for outputs.tf, use Praxis to maintain type safety.

Q: What happens if deployment testing fails? A: Praxis provides deployment logs and error analysis to help you identify and fix issues (e.g., IAM permissions, resource conflicts).