System Usage Guide

Welcome to the System Usage Guide. This document provides a complete overview of the Modern Headless Data Transformation SaaS, which offers a "Schema-First" visual experience at design-time (similar to Altova MapForce) and serverless API execution capabilities at runtime.

1. Core Architecture & Workflow

The platform bridges the gap between low-code ease of use and pro-code flexibility. Instead of writing custom scripts, users visually map data structures.

• Frontend (Designer): A React Flow-based visual canvas where you map fields between the source and target schemas.
• Engine (JSONata): Every visual mapping is instantly compiled into a .jsonata expression file. JSONata is a lightweight, declarative query and transformation language for JSON data.
• Backend (Runtime): The transformation executes via a Serverless API (like AWS Lambda).

XML/XSD Support (Adapter Pattern)

While the engine fundamentally operates on JSON, it natively supports XML and XSD schemas via an Adapter Pattern:

1. Design-Time: You can select "XML" as the input format and upload an .xsd file. The system converts the XSD into an internal JSON schema and visualizes it as a tree.
2. Runtime: The system intercepts application/xml payloads, parses the XML into JSON using fast-xml-parser (preserving attributes with an @_ prefix), executes the JSONata logic, and then converts the output back to an XML string if required.

2. Using the Visual Mapper

The core of the platform is the Visual Mapper. It consists of a dual-schema visualizer and a drag-and-drop canvas.

Uploading Schemas

• Import your Source and Target schemas. You can use JSON samples, JSON Schema, or XSD files.
• The interface displays interactive tree topologies. Deeply nested objects and arrays can be expanded or collapsed.
• Field types (String, Number, Boolean, Array, Object) are explicitly marked with distinct icons and colors.

Declarative Mapping

• Drag-and-Drop: Simply drag a field from the source schema to a field on the target schema to establish a mapping.
• Type Checking: The system performs real-time type compatibility checks. For instance, mapping a String to a Number might trigger a coercion warning or auto-inject a conversion function.

3. Advanced Logic & Function Pipelines

Instead of just mapping 1-to-1 fields, you can insert complex logic directly into the mapping lines.

Function Nodes

Drag any built-in function from the palette onto an existing connection line to transform the data in transit.

• String Functions: Uppercase, Lowercase, Trim, Substring, Replace.
• Math Functions: Round, Multiply, Add.
• Conditionals: If/Else, Default Value, Lookup tables.

Function nodes can be chained together (e.g., Source -> Uppercase -> Substring -> Target). Some functions (like Concatenate) support multiple inputs, allowing you to merge several source fields into one target field.

Virtual Nodes

For intermediate calculations or constant values, you can create Virtual Nodes. These act as custom variables that can aggregate data before passing it to the final target field.

Array Context Handling

Arrays are a common pain point in data transformation. When connecting arrays, the system will prompt an Array Context Dialog with options:

1. Iterate: Map element-by-element (e.g., source list of items to target list of products).
2. Aggregate: Map many elements to a single value (e.g., sum up an array of prices into a totalAmount).
3. Index Match: Pick an element at a specific index.
4. Filter: Apply a condition to selectively process array items.

4. Live Preview and Debugging

The platform offers a zero-latency live preview panel directly beneath the canvas.

• Instant Feedback: As you draw connections or insert functions, the resulting JSONata expression is immediately compiled and run against your sample data in the browser.
• Reverse Tracing: By clicking on any value in the transformed output preview, the system will trace back and highlight the specific mapping lines and nodes responsible for generating that value.

5. Deployment and API Usage

Once you are satisfied with your transformation rules:

1. Save and Publish: Save the project. The platform securely stores the compiled JSONata configuration.
2. Execute via API: The system provides a dedicated API endpoint (POST /api/v1/transform).
   • You can authenticate using an API Key.
   • Simply pass your JSON/XML data in the request body along with the project ID.
   • The Serverless backend will execute your transformation instantly and scale automatically.

AI Copilot (Coming Soon)

Future updates will include an AI Copilot that semantic-matches fields (e.g., fname -> firstName) automatically and allows you to generate logic pipelines simply by typing natural language commands ("multiply all prices by 1.2").