2. Architecture & Data Flow

The Screen Generation Package consists of six interconnected data flows that work together to analyze data models and generate complete screen definitions. The architecture follows a modular design where a main orchestration flow coordinates specialized sub-flows, each responsible for generating specific screen components.

Package Components

Processing Workflow

The screen generation process follows this execution sequence:

1. Input Reception: Developer provides data model name(s) via the source input node in the Screen Generator flow
2. Model Discovery: The Get Model By Name transform retrieves complete model metadata including fields, types, relationships, and validation rules
3. Field Analysis: Each field is analyzed to determine appropriate UI component type based on data type (String → text input, Boolean → checkbox, ID → combobox selector, etc.)
4. Relationship Resolution: For ID fields referencing other models, the system identifies related models and configures combobox controls with proper label fields
5. Component Generation: Specialized sub-flows execute in parallel to create actions, columns, filters, and sections
6. Screen Assembly: All generated components are combined into a complete screen definition ready for deployment
7. Output Delivery: The final screen configuration is returned, which can be saved as a new screen or used to update existing screens

Field Type Mapping

The Screen Generation Package intelligently maps data model field types to appropriate UI components:

3. Core Concepts

AI-Powered Analysis

The Screen Generation Package leverages Fuuz's native AI capabilities to perform intelligent analysis of data model structures. Rather than applying rigid templates, the system examines field names, data types, metadata annotations, and relationship patterns to make contextual decisions about UI component selection and screen organization.

For example, when the AI encounters a field named "description" or "note" with String type, it recognizes this as a likely candidate for a markdown editor rather than a simple text input. Similarly, ID fields ending in "Id" trigger relationship analysis to automatically configure combobox selectors with appropriate label fields from the related model.

Metadata-Driven Generation

Screen generation relies heavily on data model metadata stored in the Fuuz platform. Critical metadata elements include:

• Label Fields: Defines which field should display in dropdown selectors (e.g., "name" instead of "id")
• Default Values: Automatically populates form fields with configured defaults
• Sequence Configuration: Identifies auto-incrementing fields to exclude from required validation
• Module Information: Determines proper navigation paths and screen organization
• Validation Rules: Applies required field indicators based on schema definitions

This metadata-driven approach ensures that generated screens automatically inherit the business logic and constraints defined in the data model layer, maintaining data integrity without additional configuration.

Modular Component Architecture

The package architecture separates screen generation into specialized concerns, each handled by a dedicated data flow. This modular design provides several advantages:

• Maintainability: Individual component flows can be updated independently without affecting other generation logic
• Customization: Developers can modify specific flows (e.g., column generation) to change only that aspect of screen output
• Reusability: Component flows can be called independently for partial screen updates or specialized use cases
• Parallel Processing: Multiple component flows can execute simultaneously, improving generation performance
• Debugging: Issues can be isolated to specific component flows rather than debugging monolithic generation logic

Source Node Triggering

Screen generation is initiated through the source input node pattern within the Screen Generator data flow. This approach allows developers to:

1. Open the Screen Generator flow in the Data Flow Designer
2. Locate the source input node at the flow's entry point
3. Replace placeholder data model names with actual model names from their application
4. Execute the flow to generate screens for the specified models
5. Review and save the generated screen definitions

This direct execution model eliminates the need for external triggers, configuration files, or API calls, providing immediate feedback and rapid iteration during development.

Validation and Required Fields

The Screen Generation Package implements intelligent validation logic based on data model schema analysis:

• Required Indicator: Fields marked as non-nullable in the schema automatically receive required validation
• Default Value Exemption: Fields with configured default values are excluded from required validation since values are auto-populated
• Sequence Field Handling: Auto-incrementing fields with sequence configuration bypass required validation (v0.0.3 enhancement)
• ID Field Exception: Primary key ID fields are excluded from required validation as they are system-generated
• Type-Specific Validation: Email fields receive format validation, numeric fields receive type validation, etc.

4. Usage & Implementation

Prerequisites

Before using the Screen Generation Package, ensure the following requirements are met:

Basic Usage Pattern

To generate screens using the Screen Generation Package:

1. Navigate to Data Flow Designer: Access the Data Flow module within your Fuuz application
2. Open Screen Generator Flow: Locate and open the "Screen Generator" data flow from the installed package
3. Locate Source Input Node: Find the source input node at the beginning of the flow (typically labeled "Request" or "Input")
4. Configure Model Names: Edit the source node payload to specify your data model name(s) - replace any placeholder values with actual model names from your application
5. Execute Flow: Run the data flow using the execution controls in the Data Flow Designer
6. Review Output: Examine the generated screen definition in the flow response
7. Save Screen: If satisfied with the generated output, save it as a new screen in the Screen Designer or use it to update existing screens

Customization Options

While the Screen Generation Package produces high-quality screens out-of-the-box, developers can customize the output flows to meet specific project requirements:

• Field Order Modification: Adjust transform nodes to reorder form fields according to UX requirements
• Component Type Override: Modify field type mapping logic to use different UI components for specific field types
• Section Organization: Customize the Screen Generation Section Create flow to alter how fields are grouped into sections
• Validation Rules: Enhance or relax validation logic in the Screen Generation Actions Create flow
• Column Configuration: Adjust table column generation in the Screen Generation Column Create flow to change default sorting, filtering, or display options
• Label Formatting: Modify label generation logic to apply custom formatting rules (e.g., all caps, specific prefixes)

All customizations should be made to copies of the package flows to preserve the original package functionality. This allows developers to maintain both standard and customized screen generation workflows within the same application.

Integration with Screen Designer

Generated screen definitions are fully compatible with the Fuuz Screen Designer. Developers can:

• Import generated screen JSON into Screen Designer for visual editing
• Use generated screens as starting points, then add custom visualizations, charts, or advanced components
• Combine AI-generated sections with manually designed sections within the same screen
• Apply screen templates and themes to generated screens
• Deploy generated screens to any environment (Build, QA, Production) using standard screen deployment workflows

5. Best Practices

Data Model Design

To maximize screen generation quality, follow these data model design practices:

• Descriptive Field Names: Use clear, descriptive field names that convey purpose (e.g., "customerEmail" instead of "email1")
• Proper Label Field Configuration: Ensure all models have appropriate label fields defined in metadata for optimal combobox display
• Consistent Naming Conventions: Follow standard naming patterns for ID fields (e.g., "customerId", "orderId") to enable automatic relationship detection
• Complete Field Descriptions: Populate field description metadata to provide context in generated form labels and tooltips
• Appropriate Default Values: Configure default values where applicable to improve user experience in generated forms
• Logical Module Organization: Assign models to appropriate modules to ensure generated navigation paths are correct

Generation Workflow

• Start with Simple Models: Test screen generation with simple models before attempting complex multi-relationship models
• Iterative Refinement: Generate initial screens, review output, adjust data model metadata if needed, and regenerate
• Version Control: Save generated screen versions before making manual modifications to enable rollback if needed
• Generate in Development Environment: Always generate and test screens in Build or QA environments before promoting to Production
• Batch Processing: Generate screens for multiple related models in a single session to maintain consistency

Customization Strategy

• Copy Before Modifying: Always create copies of package data flows before making project-specific customizations
• Document Customizations: Add detailed descriptions to modified flows explaining what was changed and why
• Minimal Modifications: Make the smallest number of changes necessary to achieve desired results - extensive modifications may complicate package updates
• Test Thoroughly: Test customized flows with various model types to ensure changes don't break generation for edge cases
• Share Customizations: If multiple developers are generating screens, ensure customized flows are accessible to the entire team

Performance Optimization

• Generate During Low-Usage Periods: For complex models with many relationships, run screen generation during off-peak hours
• Limit Concurrent Generations: Avoid running multiple screen generation flows simultaneously to prevent resource contention
• Clean Up Test Screens: Remove generated test screens that won't be used to keep the application organized
• Monitor Execution Logs: Review data flow execution logs to identify any performance bottlenecks in the generation process

Screen Quality Assurance

• Review All Generated Screens: Manually review generated screens before deployment to verify they meet UX requirements
• Test All Form Actions: Verify that Create, Update, and Delete operations function correctly on generated forms
• Validate Relationships: Test all combobox selectors to ensure they populate with correct related records
• Check Validation Rules: Confirm that required field validation and format validation work as expected
• Mobile Responsiveness: Test generated screens on mobile devices to ensure responsive layout works properly
• Cross-Browser Testing: Verify screen functionality across different browsers if application supports multiple browsers

6. Technical Considerations

Package Dependencies

The Screen Generation Package (v1.5.1) has no external package dependencies. All required functionality is included within the package itself. The package specification version is 2.0.0, compatible with Fuuz Platform version 2023.11.2 and later.

GraphQL API Integration

The Get Model By Name transform uses the Fuuz GraphQL API to retrieve data model metadata. The query executed is:

query GetModelByName($name: String!) {
  modelMap(where: { name: { _eq: $name } })
}

This query retrieves the complete model definition including all fields, types, relationships, and metadata necessary for screen generation. The query is executed against the application API, automatically respecting the current user's access permissions.

JSONata Transform Language

Screen generation logic is implemented using JSONata, Fuuz's primary transformation language. The package makes extensive use of JSONata's advanced features including:

• Regular Expressions: For parsing field types and extracting base types from GraphQL type notation
• Conditional Logic: For intelligent component selection based on field characteristics
• Object Merging: For combining default component properties with field-specific overrides
• Array Processing: For iterating over model fields and relationships
• Custom Function Calls: Including $executeTransform() for calling saved transforms like Get Model By Name
• String Manipulation: Using functions like $startCase(), $pluralize(), and $lowerFirst()

Developers familiar with JSONata can easily understand and modify the screen generation logic by examining the transform nodes within the package data flows.

Data Flow Execution Context

Screen generation flows utilize the Fuuz data flow context mechanism extensively. The $state.context object is used to pass information between flow nodes, including:

• Component Configuration: Screen component definitions being built
• Model Metadata: Retrieved data model information
• Processing Parameters: API names, module IDs, and other configuration values
• Intermediate Results: Partially generated components passed between sub-flows

Understanding the context structure is essential for developers who want to customize generation logic or debug flow execution.

Node Type Usage

The Screen Generator flow (70 total nodes) utilizes a diverse set of data flow node types to orchestrate screen generation:

Error Handling

The Screen Generation Package includes error handling at multiple levels:

• Model Validation: Checks for existence of specified data models before attempting generation
• Field Type Validation: Handles unknown or unsupported field types gracefully with fallback to text input
• Relationship Validation: Verifies that related models exist before configuring combobox selectors
• Null Safety: Uses JSONata's $coalesce() and $isNilOrEmpty() functions to handle missing metadata
• Execution Logging: Log nodes capture errors for troubleshooting failed generation attempts

Limitations and Known Issues

While the Screen Generation Package is highly capable, users should be aware of the following:

• Custom Component Types: The package generates standard Fuuz UI components - custom or third-party components must be added manually
• Complex Layouts: Generated screens use standard layouts - complex custom layouts require manual design in Screen Designer
• Advanced Visualizations: Charts, dashboards, and data visualizations are not automatically generated
• Business Logic: While validation rules are applied, complex business logic and custom event handlers must be added manually
• Styling Customization: Generated screens use default Fuuz styling - custom CSS or theming requires post-generation modification
• Multi-Model Forms: The package focuses on single-model CRUD operations - forms that combine multiple unrelated models may require customization

7. Related Resources

Fuuz Platform Documentation

• Data Model Designer: Learn how to create and configure data models that will be used for screen generation
• Screen Designer: Understand the screen components and layouts that the Screen Generation Package produces
• Data Flow Designer: Reference for understanding the data flow nodes used in screen generation logic
• JSONata Reference: Complete guide to JSONata transformation language used extensively in the package
• GraphQL API Documentation: Details on the Fuuz GraphQL API used to query data model metadata
• Package Manager: Instructions for installing, updating, and managing Fuuz packages

Related Packages

The following Fuuz packages may complement screen generation workflows:

• Data Model Templates: Pre-built data model packages that work well with screen generation
• UI Component Libraries: Additional UI components that can be added to generated screens
• Validation Rule Packages: Advanced validation logic that can enhance generated forms
• Navigation Templates: Pre-configured navigation structures that integrate with generated screens

Support Resources

Version History