markitect-main/EPIC_64_TEMPLATE_ENGINE.md

# Epic #64: Template & Calculation Engine

**Priority**: Critical - Foundation for all business applications
**Phase**: 1 (Core Business Engine)
**Epic Owner**: Requirements Engineering Agent
**Created**: 2025-10-02

## Epic Overview

Transform MarkiTect from static document analysis into dynamic document generation by implementing a comprehensive template rendering and calculation engine. This enables real-world business applications like invoice generation, automated reports, and dynamic document creation.

## Business Value

- **Invoice Generation**: Create professional invoices from templates + customer data
- **Report Automation**: Generate periodic reports with calculated metrics
- **Dynamic Documents**: Support conditional content and data-driven generation
- **Business Logic**: Enable mathematical calculations and formula evaluation

## Epic Acceptance Criteria

- [ ] Render invoice template with customer data producing professional document
- [ ] Calculate totals, taxes, and derived values automatically
- [ ] Support conditional content rendering based on data
- [ ] Integrate seamlessly with existing frontmatter/contentmatter/tailmatter
- [ ] Maintain backward compatibility with current CLI commands
- [ ] Performance: Render 100+ documents in under 10 seconds

## Architecture Integration

### **Existing Integration Points**
- **Frontmatter**: Use as template metadata and configuration
- **Contentmatter**: Support MMD key-value pairs in rendered content
- **Tailmatter**: Template validation and QA workflows
- **CLI Commands**: Extend with new `generate` and `render` commands
- **Database**: Store templates and generation history

### **New Domain Models Required**
- `Template`: Template definition with metadata
- `TemplateEngine`: Core rendering engine
- `ExpressionEvaluator`: Mathematical calculation engine
- `RenderContext`: Data context for template rendering
- `TemplateValidation`: Template syntax and structure validation

## Decomposed Issues

### **Issue #64.1: Template Engine Foundation**
**Priority**: Critical | **Effort**: Large | **Dependencies**: None

**Description**: Implement core template rendering engine with variable substitution

**Acceptance Criteria**:
- [ ] Parse template syntax `{{variable}}` and `{{object.property}}`
- [ ] Substitute variables with data from JSON/YAML context
- [ ] Handle missing variables gracefully with configurable behavior
- [ ] Support nested object access with dot notation
- [ ] Preserve markdown formatting during substitution
- [ ] CLI command: `markitect render --template file.md --data data.json`

**Technical Requirements**:
- Template parser with AST for variable extraction
- Context resolver for nested data access
- Configurable error handling (strict/lenient modes)
- Integration with existing document structure preservation

---

### **Issue #64.2: Mathematical Expression Evaluator**
**Priority**: Critical | **Effort**: Large | **Dependencies**: #64.1

**Description**: Implement calculation engine for business logic and mathematical operations

**Acceptance Criteria**:
- [ ] Evaluate expressions: `{{add field1 field2}}`, `{{multiply quantity price}}`
- [ ] Support mathematical functions: add, subtract, multiply, divide, sum, avg
- [ ] Handle currency formatting and decimal precision
- [ ] Array operations: sum, count, filter, map
- [ ] Date/time calculations and formatting
- [ ] Error handling for invalid calculations

**Technical Requirements**:
- Expression parser with mathematical operation support
- Type system for numbers, currencies, dates
- Formatter system for output presentation
- Integration with template variable substitution

---

### **Issue #64.3: Conditional Content & Control Flow**
**Priority**: High | **Effort**: Medium | **Dependencies**: #64.1

**Description**: Support conditional rendering and iterative content generation

**Acceptance Criteria**:
- [ ] Conditional blocks: `{{#if condition}}...{{/if}}`
- [ ] Loops over arrays: `{{#each items}}...{{/each}}`
- [ ] Conditional operators: equals, not equals, greater than, less than
- [ ] Nested conditions and loops
- [ ] Template inclusion and composition
- [ ] Performance optimization for large datasets

**Technical Requirements**:
- Control flow parser for conditional syntax
- Loop execution engine with context management
- Template composition system for reusability
- Performance monitoring for complex templates

---

### **Issue #64.4: Template Management CLI Commands**
**Priority**: High | **Effort**: Medium | **Dependencies**: #64.1, #64.2

**Description**: Extend CLI with comprehensive template management capabilities

**Acceptance Criteria**:
- [ ] `markitect template create` - Create new template from document
- [ ] `markitect template validate` - Validate template syntax and structure
- [ ] `markitect template list` - List available templates with metadata
- [ ] `markitect template render` - Render template with data
- [ ] `markitect generate` - Generate multiple documents from data source
- [ ] Help documentation and examples for all commands

**Technical Requirements**:
- CLI command integration with existing architecture
- Template storage and retrieval system
- Batch generation capabilities
- Comprehensive error reporting and validation

---

### **Issue #64.5: Template Validation & Quality Assurance**
**Priority**: Medium | **Effort**: Medium | **Dependencies**: #64.1, #64.2, #64.3

**Description**: Implement template validation and QA workflows

**Acceptance Criteria**:
- [ ] Syntax validation for template expressions
- [ ] Data schema validation against template requirements
- [ ] Missing variable detection and reporting
- [ ] Template performance analysis and optimization suggestions
- [ ] Integration with existing tailmatter QA workflows
- [ ] Template testing framework for validation

**Technical Requirements**:
- Template syntax validator with detailed error reporting
- Data schema inference and validation
- Performance profiler for template rendering
- Integration with existing QA checklist system

---

### **Issue #64.6: Business Document Templates Library**
**Priority**: Medium | **Effort**: Small | **Dependencies**: #64.1, #64.2, #64.4

**Description**: Create library of common business document templates

**Acceptance Criteria**:
- [ ] Invoice template with line items and calculations
- [ ] Letter template with recipient and sender information
- [ ] Report template with charts and data tables
- [ ] Contract template with conditional clauses
- [ ] Documentation for template customization
- [ ] Example data files for testing and demonstration

**Technical Requirements**:
- Template library organization and categorization
- Documentation system for template usage
- Example data generation for testing
- Template versioning and update system

---

### **Issue #64.7: Integration & Backward Compatibility**
**Priority**: High | **Effort**: Small | **Dependencies**: All above

**Description**: Ensure seamless integration with existing MarkiTect functionality

**Acceptance Criteria**:
- [ ] All existing CLI commands continue to work unchanged
- [ ] Template metadata integrates with frontmatter system
- [ ] Rendered documents validate against existing schemas
- [ ] Performance impact minimal on existing operations
- [ ] Comprehensive integration tests with existing test suite
- [ ] Migration guide for existing users

**Technical Requirements**:
- Backward compatibility testing framework
- Integration test suite covering all existing functionality
- Performance benchmarking against current baseline
- Documentation for migration and new features

## Epic Dependencies

### **External Dependencies**
- None (self-contained within MarkiTect architecture)

### **Internal Dependencies**
- Existing CLI command architecture
- Current frontmatter/contentmatter/tailmatter parsers
- Database and storage systems
- Test infrastructure and validation frameworks

## Success Metrics

### **Technical Metrics**
- Template rendering speed: <100ms for typical business documents
- Memory usage: <50MB additional for template engine
- Test coverage: >95% for all template engine components
- Error handling: Graceful degradation for all failure scenarios

### **Business Metrics**
- Invoice generation: Complete workflow from template to PDF-ready document
- Template library: 5+ professional business document templates
- User adoption: CLI commands discoverable and well-documented
- Performance: 100+ document batch generation in <10 seconds

## Implementation Timeline

**Phase 1** (Issues #64.1, #64.2): Core engine foundation (2-3 weeks)
**Phase 2** (Issues #64.3, #64.4): Advanced features and CLI (2 weeks)
**Phase 3** (Issues #64.5, #64.6, #64.7): Quality assurance and templates (1-2 weeks)

**Total Epic Duration**: 5-7 weeks

## Risk Mitigation

- **Performance Risk**: Implement caching and optimization from start
- **Complexity Risk**: Start with simple use cases, iterate to advanced features
- **Integration Risk**: Continuous testing against existing functionality
- **User Adoption Risk**: Comprehensive documentation and examples