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