Morphir Application Architect Skill

Designs and reviews morphir-dotnet architecture: AST/IR type structures, functional programming patterns, visitor implementations, and code generation backends. References project knowledge bases for pattern details and implements solutions using the Dual IR (F# Classic + C# Modern) design.

Primary Responsibilities

1. Language Design Guidance - AST/CST patterns, visitor implementations, type system design
2. Functional Programming Expertise - Monads, functors, lenses, railway-oriented programming
3. IR Modeling & Transformation - Morphir IR design, validation, optimization pipelines
4. Code Generation Architecture - Template design, backend implementations, multi-target generation
5. F#/C# Interop Strategy - Bridging patterns, dual IR design, conversion strategies
6. Pattern Recognition & Application - Identify applicable patterns, recommend implementations

Core Competencies

Language Design Patterns

When asked about AST/CST design, type systems, or tree structures:

1. Reference Language Design Patterns KB
2. Identify 22+ documented patterns including:
   • Algebraic Data Types (F# discriminated unions, C# sealed records)
   • Generic Attributes Pattern for extensible ASTs
   • Wrapper Types (AccessControlled, Documented)
   • Immutable Trees with Structural Sharing
   • Smart Constructors for invariant enforcement
3. Provide F# and C# implementations as appropriate
4. Show morphir-dotnet usage examples from actual codebase
5. Explain trade-offs (performance vs type safety vs complexity)

Example:

// F# Classic IR: Generic Attributes Pattern
type Type<'attributes> =
    | Variable of 'attributes * Name
    | Reference of 'attributes * FQName * Type<'attributes> list
    | Function of 'attributes * Type<'attributes> * Type<'attributes>

// Allows flexible attribute annotation:
type Type<unit> = ...        // Untyped AST
type Type<SourceSpan> = ...  // With source locations
type Type<TypeInfo> = ...    // Fully typed AST

Key Principles:

• Make illegal states unrepresentable (ADTs)
• Immutability first, effects at edges
• Structural sharing for performance
• Value semantics for tree comparison

Visitor Pattern Implementations

When designing AST traversals or transformations:

1. Reference Visitor Pattern Implementations KB
2. Choose from 8 documented variants:
   • Classic OO Visitor (C# Modern IR)
   • Functional Pattern Matching (F# Classic IR)
   • Type-Safe Record Visitor (F# composable)
   • Transforming Visitor (structural preservation)
   • Accumulating Visitor (fold/reduce)
   • Context-Passing Visitor (scoped information)
3. Provide selection criteria based on use case
4. Show implementation with morphir-dotnet IR types

Checklist:

• Identified visitor use case (traversal, transformation, validation)
• Selected appropriate variant (OO vs functional)
• Implemented visitor interface/record
• Handled all AST node types exhaustively
• Provided usage examples

Functional Programming Patterns

When implementing FP patterns or error handling:

1. Reference Functional Programming Patterns KB
2. Apply 18+ documented patterns:
   • Monads: Option, Result, List, State, Reader, IO/Async
   • Functors: map operations preserving structure
   • Applicatives: validation with error accumulation
   • Railway-Oriented Programming: Result pipelines
   • Lenses: composable getters/setters
3. Choose F# or C# implementation based on context
4. Integrate with existing morphir-dotnet patterns

Process:

Identify Pattern Need
    ↓
Select Appropriate Pattern (monad, functor, etc.)
    ↓
Choose Language (F# native vs C# encoding)
    ↓
Implement Using KB Examples
    ↓
Validate Against Laws (if applicable)
    ↓
Test with Morphir IR Types

Common Patterns:

• Option for Nullable Safety: F# option, C# nullable reference types → Avoid nulls
• Result for Error Handling: Railway-oriented programming → Explicit error propagation
• Lenses for Nested Updates: Composable updates → addressLens >>> cityLens

Computation Expressions for AST Modeling

When building DSLs or simplifying tree construction:

1. Reference Computation Expressions for AST KB
2. Understand builder pattern (Yield, Bind, For, Combine, CustomOperation)
3. Study real-world examples:
   • Fabulous.AST: 93% boilerplate reduction for F# code generation
   • Fun.Blazor: Used in Morphir.Live for component trees
4. Design computation expression builders for Morphir IR construction
5. Balance readability vs complexity

Example (Proposed Morphir Type Builder):

type TypeBuilder() =
    member _.Yield(()) = Type.Unit(())

    [<CustomOperation("variable")>]
    member _.Variable(_, name) = Type.Variable((), Name.fromString name)

    [<CustomOperation("func")>]
    member _.Function(_, param, ret) = Type.Function((), param, ret)

let typeExpr = typeBuilder {
    func (variable "a") (variable "b")
}
// Produces: Function((), Variable("a"), Variable("b"))

Compiler Services & Metaprogramming

When implementing code generation or analysis:

1. Reference Compiler Services & Metaprogramming KB
2. Choose appropriate technology:
   • F# Compiler Service: Parse/analyze F# code (Morphir SDK docs)
   • Roslyn: Parse/analyze C# code (user validation)
   • C# Source Generators: Generate C# visitors for Modern IR
   • Myriad: Generate F# visitors for Classic IR (planned)
3. Follow decision matrix for technology selection
4. Implement with AOT compatibility in mind

Decision Tree:

Need to generate code?
  YES → What language?
    ├─ F# → Use Myriad (MSBuild-integrated)
    ├─ C# → Use Source Generators (incremental pipeline)
    └─ Both → Separate generators for each

  NO → Need to analyze code?
    ├─ F# code → Use F# Compiler Service
    ├─ C# code → Use Roslyn
    └─ Morphir IR → Direct pattern matching (fastest)

Project-Specific Context

morphir-dotnet Architecture Specifics

Dual IR Design:

• Classic IR (F#): src/Morphir.Models/IR/Classic/ - Discriminated unions, functional operations
• Modern IR (C#): src/Morphir.Core/IR/ - Sealed records, C# consumption
• Conversion Functions: Bidirectional translation between representations

Key Areas:

1. IR Structure - Distribution → Package → Module → Types/Values hierarchy
2. FQName System - Name → Path → QName → FQName for qualified naming
3. Generic Attributes - Type<'attributes> for extensible AST annotation
4. Immutable Collections - F# Map, C# ImmutableDictionary for persistence
5. Wrapper Types - AccessControlled, Documented for metadata

Important Files and Directories

src/
├── Morphir.Core/IR/               # C# Modern IR (sealed records)
│   ├── Type.cs                    # Type expressions
│   ├── Value.cs                   # Value expressions
│   └── Module.cs                  # Module definitions
├── Morphir.Models/IR/Classic/     # F# Classic IR (discriminated unions)
│   ├── Type.fs                    # Type<'attributes>
│   ├── Value.fs                   # Value definitions
│   └── Distribution.fs            # Top-level IR
├── Morphir.SDK/                   # F# standard library
│   ├── List.fs                    # List operations
│   ├── Maybe.fs                   # Option type
│   └── Result.fs                  # Result type (planned)
├── Morphir.Live/                  # Interactive documentation
│   └── TryMorphir.fs             # Fun.Blazor usage example
└── Morphir.Internal.CodeGeneration/ # Code generators
    └── Generators/
        ├── VisitorGenerator.fs    # Myriad visitor (stub)
        └── LensGenerator.fs       # Myriad lens (stub)

.agents/
├── kbs/                           # Knowledge bases
│   ├── ecosystem-knowledge-base.md
│   ├── language-design-patterns.md
│   ├── visitor-pattern-implementations.md
│   ├── computation-expressions-for-ast.md
│   ├── functional-programming-patterns.md
│   └── compiler-services-metaprogramming.md
└── decisionlogs/
    └── architectural-decisions.md # 25 ADRs

Commands and Tools

# Build and test
./build.sh                         # Default build
./build.sh --target Test           # Run tests
dotnet format                      # Format code (required pre-commit)

# Code generation (planned)
# Generate visitors for Classic IR
dotnet build -t:MyriadGenerate src/Morphir.Models/Morphir.Models.fsproj

# Generate visitors for Modern IR (future)
# Automatically generated via C# Source Generators during build

Decision Trees

Decision Tree 1: "Choosing IR Representation"

Need to work with Morphir IR?
  YES → What language is the consumer?
    ├─ F# → Use Classic IR (src/Morphir.Models/IR/Classic/)
    │  └─ Why: Native discriminated unions, pattern matching
    │
    ├─ C# → Use Modern IR (src/Morphir.Core/IR/)
    │  └─ Why: Sealed records, better IDE support
    │
    └─ Both → Use conversion functions
       ├─ classicToCSharp: Classic IR → Modern IR
       └─ csharpToClassic: Modern IR → Classic IR

  NO → Working with different AST?
    └─ Apply same patterns (ADTs, immutability, etc.)

Decision Tree 2: "Selecting Visitor Pattern"

Need to traverse/transform AST?
  ├─ Language: F# + Discriminated Unions
  │  ├─ Simple traversal → Functional Pattern Matching
  │  ├─ Composable operations → Record Visitor
  │  └─ Complex transformation → Catamorphism (fold)
  │
  ├─ Language: C# + Sealed Records
  │  ├─ Multiple operations → Classic OO Visitor (ITypeVisitor<TResult>)
  │  ├─ Single transformation → Pattern Matching (switch expressions)
  │  └─ Accumulation → Accumulating Visitor
  │
  └─ Special Requirements
      ├─ Deep recursion → Trampolined Visitor (stack safety)
      ├─ Async operations → Async Visitor
      └─ Scoped context → Context-Passing Visitor

Decision Tree 3: "Error Handling Strategy"

Need to handle errors?
  ├─ User-facing validation (collect all errors)
  │  └─ Use Applicative Validation
  │      → Accumulate errors: map2, map3, apply
  │      → Better UX (show all errors at once)
  │
  ├─ Internal pipeline (stop on first error)
  │  └─ Use Railway-Oriented Programming
  │      → Result monad with bind (>>=)
  │      → Short-circuit on failure
  │      → Explicit error propagation
  │
  └─ Optional values (no error information)
      └─ Use Option/Maybe
          → Some/None (F#)
          → Nullable reference types (C#)

Playbooks

Playbook 1: Design New AST/IR Type

When to use: Creating new AST node types or extending Morphir IR

Prerequisites:

• Understand the domain concept being modeled
• Reviewed similar types in Morphir IR
• Decided on F# (Classic IR) vs C# (Modern IR)

Steps:

Phase 1: Design ADT Structure

1. Define Type Variants

   • List all possible cases/shapes
   • Ensure variants are mutually exclusive
   • Make illegal states unrepresentable

2. Add Generic Attributes (if F#)

   type MyType<'attributes> =
       | Case1 of 'attributes * Field1 * Field2
       | Case2 of 'attributes * OtherFields

   • Enables extensible annotation
   • Allows untyped, typed, or custom attributes

3. Apply Immutability

   • F#: Records/DUs are immutable by default
   • C#: Use record with init-only properties
   • Use immutable collections (Map, ImmutableDictionary)

Phase 2: Implement Functor (if needed) 4. Add Map Function

let rec mapMyType (f: 'a -> 'b) (typ: MyType<'a>) : MyType<'b> =
    match typ with
    | Case1 (attrs, field1, field2) -> Case1 (f attrs, field1, field2)
    | Case2 (attrs, others) -> Case2 (f attrs, others)

• Transforms attributes without changing structure
• Essential for attribute pipelines

Phase 3: Create Visitor Support (optional) 5. Design Visitor Interface/Record

• F#: Record with function fields OR direct pattern matching
• C#: ITypeVisitor interface

6. Implement Common Operations
   • Size calculation (count nodes)
   • Pretty-printing (toString)
   • Validation (check invariants)

Post-Workflow:

• Add unit tests for all variants
• Document in knowledge base
• Update visitor generators (if applicable)

Duration: ~2-3 hours

Playbook 2: Implement Railway-Oriented Programming Pipeline

When to use: Building validation or transformation pipelines with error handling

Prerequisites:

• Understand Result type (Ok/Error)
• Know the transformation steps
• Have error types defined

Steps:

Phase 1: Define Error Type

1. Create Error ADT

   type ValidationError =
       | EmptyName
       | InvalidFormat of field: string * pattern: string
       | OutOfRange of field: string * min: int * max: int

2. Define Result Type Alias

   type ValidationResult<'T> = Result<'T, ValidationError>

Phase 2: Build Railway Functions 3. Create Validation Functions

let validateNotEmpty fieldName value =
    if String.IsNullOrWhiteSpace(value) then
        Error (EmptyName)
    else
        Ok value

let validateRange fieldName min max value =
    if value >= min && value <= max then
        Ok value
    else
        Error (OutOfRange (fieldName, min, max))

4. Compose with Bind

   let (>>=) = Result.bind
   
   let validatePerson name age email =
       Ok (fun n a e -> { Name = n; Age = a; Email = e })
       <!> validateNotEmpty "name" name
       >>= fun f -> validateAge age >>= fun a -> Ok (f a)
       >>= fun f -> validateEmail email >>= fun e -> Ok (f e)

Phase 3: Handle Errors 5. Map Errors (if needed)

let result =
    validatePerson name age email
    |> Result.mapError (fun err ->
        match err with
        | EmptyName -> "Name cannot be empty"
        | InvalidFormat (field, pattern) -> $"{field} format invalid"
        | OutOfRange (field, min, max) -> $"{field} out of range [{min}-{max}]"
    )

6. Recover from Errors (optional)

   let orElse alternative result =
       match result with
       | Ok _ -> result
       | Error _ -> alternative
   
   let getUser userId =
       fetchFromCache userId
       |> orElse (fetchFromDatabase userId)

Post-Workflow:

• Test happy path
• Test all error cases
• Document error types
• Update error handling guide

Duration: ~1-2 hours

Playbook 3: Implement Lens for Nested Updates

When to use: Need to update deeply nested immutable structures

Prerequisites:

• Understand lens laws (get-put, put-get, put-put)
• Know the data structure hierarchy
• F# or C# implementation chosen

Steps:

Phase 1: Define Lenses

1. Create Lens Type (F#)

   type Lens<'S, 'A> = {
       Get: 'S -> 'A
       Set: 'A -> 'S -> 'S
   }

2. Define Field Lenses

   let addressLens = {
       Get = fun p -> p.Address
       Set = fun a p -> { p with Address = a }
   }
   
   let cityLens = {
       Get = fun a -> a.City
       Set = fun c a -> { a with City = c }
   }

Phase 2: Compose Lenses 3. Create Lens Composition

let compose (outer: Lens<'A, 'B>) (inner: Lens<'B, 'C>) : Lens<'A, 'C> =
    {
        Get = fun a -> inner.Get (outer.Get a)
        Set = fun c a -> outer.Set (inner.Set c (outer.Get a)) a
    }

let (>>>) = compose

4. Compose Deep Lenses

   let personCityLens = addressLens >>> cityLens

Phase 3: Use Lenses 5. Perform Updates

let updatedPerson = Lens.set personCityLens "Shelbyville" person

6. Generate Lenses (future - Myriad)

   [<GenerateLenses>]
   type Config = { Port: int; Host: string; Timeout: int }
   
   // Myriad generates:
   // module Config.Lenses =
   //     let port = { Get = fun c -> c.Port; Set = fun v c -> { c with Port = v } }
   //     let host = { Get = fun c -> c.Host; Set = fun v c -> { c with Host = v } }
   //     let timeout = { Get = fun c -> c.Timeout; Set = fun v c -> { c with Timeout = v } }

Post-Workflow:

• Validate lens laws
• Test composition
• Document lens usage
• Plan Myriad generator implementation

Duration: ~30 minutes - 1 hour

Review Capability

Review Scope

This skill proactively reviews morphir-dotnet architecture for:

1. ADT Design Anti-patterns - Non-exhaustive pattern matching, mutable state

   • Example: Missing case in visitor, mutable fields in IR types
   • Detection: Grep for var , search for _ in pattern matches
   • Impact: Runtime errors, broken invariants

2. FP Pattern Violations - Improper monad usage, nullable instead of Option

   • Example: null instead of None, exceptions instead of Result
   • Detection: Grep for null, throw, check Result usage
   • Impact: Hidden errors, unclear error handling

3. Immutability Violations - Mutable collections, mutable fields

   • Example: List<T> instead of ImmutableList<T>, mutable properties
   • Detection: Grep for List<, set; in properties
   • Impact: Thread unsafety, unexpected mutations

4. IR Consistency Issues - Classic/Modern IR sync, missing conversions

   • Example: Type exists in Classic IR but not Modern IR
   • Detection: Compare type counts, check conversion functions
   • Impact: Incomplete interop, broken conversions

Review Triggers

Scheduled Review:

• Frequency: Quarterly (Q1, Q2, Q3, Q4)
• Trigger: Manual request or end of quarter
• Scope: Full codebase architectural scan
• Output: Comprehensive review report

Session-Based Review:

• Trigger: After major IR changes, new AST types
• Scope: Changed files and related code
• Output: Integrated into workflow results

On-Demand Review:

• Trigger: @skill morphir-architect review
• Scope: User-specified or full domain scan
• Output: Detailed report with recommendations

Review Output Format

Findings Structure:

# Morphir Architect Review Report
**Date:** 2025-12-24
**Scope:** Full codebase architectural scan
**Duration:** ~10 minutes

## Summary
- ADT Types Reviewed: 42
- FP Pattern Usage: 95% compliant
- Immutability: 100% (all IR types immutable)
- IR Consistency: Classic/Modern in sync

## Findings

### Category: ADT Design
- **Finding 1:** Non-exhaustive pattern match in src/Morphir.Tooling/Transform.fs:145
  - **Location:** src/Morphir.Tooling/Transform.fs:145
  - **Severity:** High
  - **Recommendation:** Add `_ -> failwith "Unreachable"` or handle all cases

### Category: FP Patterns
- **Finding 1:** Using `null` instead of Option in src/Morphir.Backends/Utils.cs:67
  - **Location:** src/Morphir.Backends/Utils.cs:67
  - **Severity:** Medium
  - **Recommendation:** Replace with `Option<T>` or nullable reference type

## Trends
- Railway-Oriented Programming adoption increasing (5 new uses this quarter)
- Lens usage still manual (pending Myriad generator)

## Recommendations
1. **Immediate:** Fix non-exhaustive pattern matches
2. **Short-term:** Implement Myriad lens generator
3. **Long-term:** Standardize Result type across CLI tools

## Automation Opportunities
- Lens generation: Manual lenses in 12 files → Myriad generator
- Visitor generation: Manual visitors in 8 files → Source generator/Myriad

Review Automation Scripts

Location: .claude/skills/morphir-architect/scripts/

architecture-review.fsx

• Purpose: Scan codebase for architectural anti-patterns
• Triggers: Quarterly or on-demand
• Output: Review report (markdown)
• Token Savings: ~5000 tokens (vs manual review)

ir-consistency-check.fsx (future)

• Purpose: Verify Classic IR and Modern IR are in sync
• Triggers: After IR changes
• Output: Consistency report
• Token Savings: ~2000 tokens

Usage:

# Run architectural review
dotnet fsi .claude/skills/morphir-architect/scripts/architecture-review.fsx

# Check IR consistency
dotnet fsi .claude/skills/morphir-architect/scripts/ir-consistency-check.fsx

Review Checklist

Before completing a review:

• All IR types reviewed for immutability
• Pattern matching exhaustiveness checked
• FP pattern usage validated
• Classic/Modern IR consistency verified
• Findings categorized by severity
• Recommendations provided
• Trends analyzed
• Automation opportunities identified
• Report generated and saved

Pattern Catalog

See the knowledge bases for comprehensive pattern documentation:

• Language Design Patterns — 22+ AST/type system patterns (ADTs, Generic Attributes, Wrapper Types)
• Functional Programming Patterns — 18 FP patterns including monads, lenses, Railway-Oriented Programming
• Visitor Pattern Implementations — 8 visitor variants with selection criteria
• Computation Expressions for AST — CE builders for IR construction
• Compiler Services & Metaprogramming — Source generators, Myriad, Roslyn

Integration Points

Coordination with Other Skills

Technical Writer:

• Direction: to/from this skill
• Interaction: Architecture diagrams, pattern documentation
• Trigger: New patterns discovered, ADR updates
• Protocol: Architect defines structure, writer creates diagrams and docs

QA Tester:

• Direction: from this skill
• Interaction: Test strategies for FP code, property-based testing
• Trigger: New IR types, transformation pipelines
• Protocol: Architect provides invariants, QA creates tests

AOT Guru:

• Direction: to/from this skill
• Interaction: Pattern selection for AOT compatibility
• Trigger: Reflection-heavy patterns proposed
• Protocol: Architect consults on pattern trade-offs, AOT guru validates

Elm-to-F# Guru:

• Direction: to this skill
• Interaction: Elm pattern translation to F# idioms
• Trigger: New Elm patterns from morphir-elm
• Protocol: Elm guru identifies patterns, Architect adapts for F#/C#

Escalation Paths

When to Escalate:

1. Fundamental IR design changes (breaking changes)
2. New language features requiring core architecture updates
3. Conflicting pattern recommendations (trade-off decisions)

How to Escalate:

1. Document the architectural decision point
2. Provide options with trade-off analysis
3. Tag maintainer: @DamianReeves
4. Label issue: architecture, maintainer-attention
5. Wait for guidance before proceeding

What NOT to Decide:

• Breaking changes to public IR API
• Major paradigm shifts (e.g., mutable IR)
• Removing core patterns without migration path

Templates

Location: .claude/skills/morphir-architect/templates/

Template 1: new-ast-type.md

Purpose: Template for designing new AST/IR types When to Use: Creating new node types for Morphir IR or custom ASTs

Usage:

1. Copy template: cp .claude/skills/morphir-architect/templates/new-ast-type.md .
2. Fill in type variants, attributes, operations
3. Implement in F# or C# following template guidance

Template 2: transformation-pipeline.md

Purpose: Template for Railway-Oriented Programming pipelines When to Use: Building validation or transformation chains

Usage:

1. Copy template: cp .claude/skills/morphir-architect/templates/transformation-pipeline.md .
2. Define error types and validation steps
3. Implement using Result monad

Template 3: visitor-implementation.md

Purpose: Template for implementing visitor patterns When to Use: Need systematic AST traversal or transformation

Usage:

1. Copy template: cp .claude/skills/morphir-architect/templates/visitor-implementation.md .
2. Choose variant (OO, functional, record-based)
3. Implement for target AST types

Related Resources

Within This Project:

• README.md - Quick reference guide
• MAINTENANCE.md - Maintenance and evolution guide
• metadata.yaml - Skill metadata and configuration

Knowledge Bases:

• Ecosystem Knowledge Base - 50+ ecosystem entries
• Language Design Patterns - 22+ AST/type system patterns
• Visitor Pattern Implementations - 8 visitor variants
• Computation Expressions for AST - CE patterns
• Functional Programming Patterns - 18 FP patterns
• Compiler Services & Metaprogramming - Code generation

Project Guidance:

• AGENTS.md - Primary agent guidance
• CLAUDE.md - Claude Code-specific instructions
• Architectural Decisions - 25 ADRs
• Skills Reference - All available skills

External Resources:

• Morphir Homepage - Official Morphir documentation
• morphir-elm - Reference implementation
• F# for Fun and Profit - FP patterns and ROP
• Category Theory for Programmers - Theoretical foundations

Last Updated: 2025-12-24 Version: 1.0.0-alpha Status: alpha Maintainer: Damian Reeves (@DamianReeves)