Architecture

Technical design and implementation details

← Back to Home

Overview

Arshu Assembler is a polyglot declarative framework implementing a component-oriented architecture for composing markup and data. The framework follows consistent design patterns across all language implementations while respecting idiomatic conventions of each language.

Key Design Principle: Structural consistency across all language implementations is crucial. The same logic and structure is maintained across C#, Rust, Go, Node.js, PHP, and JavaScript, using idiomatic patterns in respective languages.

Two Engine Architecture

The assembler implements two distinct engines for template processing:

Normal Engine

  • Combines parsing and merging in a single pass
  • Processes templates on-the-fly
  • Simpler implementation with less memory overhead
  • Ideal for straightforward template scenarios

PreProcess Engine

  • Separates parsing from merging into distinct phases
  • Parses templates and JSON into intermediate data structures
  • Performs all JSON merging in the engine phase
  • Provides better debugging and template analysis capabilities
  • Outputs structure dumps for validation (Analysis folder)

Role Separation

Component Normal Engine PreProcess Engine
Loader Loads templates Parse templates and structure, Parse JSON (no merging)
Engine Parse and merge together Use parsed data to merge templates, All JSON merging happens here

Core Components

Assembler Library

The core library that implements:

AssemblerTest

Comprehensive test suite that:

AssemblerWeb

Web server implementation that:

AssemblerWebJs (C# only)

Specialized server for client-side JavaScript assembly:

Template Processing Flow

Normal Engine Flow

1. Load Template Files
2. Parse & Merge Simultaneously
   - Identify placeholders
   - Replace with component content or JSON data
   - Process nested components recursively
3. Output Final HTML

PreProcess Engine Flow

1. Load & Parse Templates
   - Build template structure tree
   - Identify all placeholders and slots
   - Parse JSON data into objects
   - Output structure dump (for debugging)
2. Merge Phase
   - Walk the structure tree
   - Resolve all placeholders
   - Apply JSON data bindings
   - Handle array iterations and conditionals
3. Output Final HTML

File Organization

AppSite Structure

Each AppSite (test case) follows a consistent structure:

AppSites/
└── <AppSiteName>/
    ├── index.html # Main entry template
    ├── Index.json # Data file (if needed)
    ├── Component/ # Reusable components
    │ ├── Header.html
    │ └── Footer.html
    ├── Common/ # Shared layouts
    │ └── Layout.html
    └── Views/ # Context-specific views
        ├── ViewA/
        └── ViewB/

Output Structure

Analysis/
└── output/
    ├── <AppSite>_normal.html # Normal engine output
    ├── <AppSite>_preprocess.html # PreProcess engine output
    └── structure/ # Debug dumps (PreProcess only)
        └── <AppSite>_structure.json

Design Patterns

Consistent Naming Conventions

No Regular Expressions

The framework explicitly avoids using regular expressions for parsing, instead using:

Rationale: Avoiding regex ensures predictable behavior, better error messages, and easier debugging across different language implementations.

Language Implementations

Implementation Philosophy

All language implementations follow the same core logic and structure, adapted to each language's idiomatic patterns:

Validation Strategy: Each implementation is validated by comparing outputs across all languages to ensure identical results for the same inputs.

Performance Considerations

Idle Tracking

All web servers implement idle tracking for deployment optimization:

Performance Testing

The test suite includes performance benchmarking:

Future Architecture

Planned Features

Back to Home