Skip to content

Contributing New Templates

This document defines how to propose, design, implement, and maintain a new template (or major change). It is written for architects and engineers who want to create or modify templates used by the Factory.

Templates are the foundation of the Factory's code generation capabilities. New templates must follow established patterns, be well-tested, and be properly documented.

Important

Templates must follow Clean Architecture, DDD, event-driven, and cloud-native principles. All templates must include observability, security, and testing by default.

When to Create a New Template

Create a new template when:

  • New Architectural Pattern - A new architectural pattern is needed (e.g., CQRS, event sourcing)
  • Repeated Need - Multiple clients need the same pattern or structure
  • Major Platform Variation - A major variation is needed (e.g., event-heavy services, API gateway)
  • New Technology Stack - A new technology stack needs support (with approval)

Do NOT create a template for: - One-off use cases - Customer-specific requirements - Experimental patterns (use experimental template state instead)

Warning

No One-Off Templates: Do not create templates for one-off use cases. Templates must serve multiple customers and use cases. For one-off needs, generate code manually or extend existing templates.

Design and ADRs

ADR Requirement

All new templates require an ADR (Architecture Decision Record):

  • Purpose - Why this template is needed
  • Scope - What the template covers and doesn't cover
  • Dependencies - Dependencies on other templates, libraries, or platforms
  • Alternatives - Alternatives considered and why they were rejected
  • Consequences - Consequences of this template decision

See: Decision Records Process for ADR process.

Design Principles

  • Follow Clean Architecture - Domain → Application → Infrastructure layers
  • DDD Patterns - Bounded contexts, aggregates, domain events
  • Event-Driven - Important actions expressed as events
  • Cloud-Native - Stateless, scalable, observable
  • Multi-Tenant - Support multi-tenant SaaS by default

See: Clean Architecture & DDD, Event-Driven Mindset, Cloud-Native Mindset

Implementation Steps

Step 1: Clone Base Template (If Exists)

  • Base Template - Start from existing template if applicable
  • Template Structure - Follow established template structure
  • Naming - Use consistent naming conventions

Step 2: Define Configuration Parameters

  • Required Parameters - Bounded context, service name, entities
  • Optional Parameters - Features, integrations, customizations
  • Validation - Validate parameters before generation
  • Defaults - Provide sensible defaults

Step 3: Wire In Standard Cross-Cutting Features

  • Observability - Logging, tracing, metrics (OpenTelemetry)
  • Security - Authentication, authorization, input validation
  • Testing - Unit tests, integration tests, BDD specs
  • CI/CD - Pipeline templates and configurations
  • Documentation - README, API docs, architecture docs

Step 4: Add Sample Usage

  • Example Project - Create example project using template
  • Documentation - Document template usage and examples
  • Quickstart - Provide quickstart guide

Testing and Validation

Minimum Testing Requirements

  • Generate Sample Service - Generate a sample service from template
  • Build Success - Generated code must build successfully
  • Tests Pass - All tests must pass
  • CI/CD Pipeline - Pipeline must run successfully
  • Deploy Success - Deploy to test environment successfully

Validation Checklist

  • Template generates valid project structure
  • Generated code follows Clean Architecture
  • Observability hooks are present
  • Security patterns are implemented
  • Tests are included and passing
  • CI/CD pipeline is configured
  • Documentation is generated

Documentation Requirements

Template Page

Create a template page in the Templates section:

  • Overview - What the template does
  • Structure - Project structure generated
  • Parameters - Configuration parameters
  • Features - Key features and capabilities
  • Examples - Usage examples

See: Microservice Template for example.

Quickstart Snippet

Provide a quickstart snippet showing:

  • How to Use - How to use the template
  • Parameters - Required and optional parameters
  • Example - Example usage

Known Limitations

Document known limitations:

  • What It Doesn't Do - What the template doesn't cover
  • Constraints - Constraints and limitations
  • Future Enhancements - Planned enhancements

Maintenance and Deprecation

Maintenance Responsibilities

  • Owner - Template owner is responsible for maintenance
  • Updates - Regular updates for security, dependencies, patterns
  • Support - Support for template users
  • Documentation - Keep documentation up to date

Deprecation Policy

  • Lifecycle States - Templates follow lifecycle states (Draft → Experimental → Beta → Stable → Deprecated)
  • Deprecation Notice - Provide advance notice before deprecation
  • Migration Path - Provide migration path for deprecated templates

See: Templates Lifecycle for lifecycle details.