# Architecture of the `rhailib_dsl` Crate The `rhailib_dsl` crate serves as the central Domain-Specific Language (DSL) implementation for the Rhai scripting engine within the heromodels ecosystem. It provides a comprehensive set of business domain modules that expose Rust data structures and operations to Rhai scripts through a fluent, chainable API. ## Core Architecture The DSL follows a modular architecture where each business domain is implemented as a separate module with its own Rhai integration: ```mermaid graph TD A[rhailib_dsl] --> B[Business Domains] B --> C[biz - Business Operations] B --> D[finance - Financial Models] B --> E[library - Content Management] B --> F[flow - Workflow Management] B --> G[calendar - Time Management] B --> H[circle - Community Management] B --> I[contact - Contact Management] B --> J[access - Access Control] B --> K[core - Core Utilities] B --> L[object - Generic Objects] C --> C1[company] C --> C2[product] C --> C3[sale] C --> C4[shareholder] D --> D1[account] D --> D2[asset] D --> D3[marketplace] E --> E1[collection] E --> E2[image] E --> E3[pdf] E --> E4[markdown] E --> E5[book] E --> E6[slideshow] F --> F1[flow] F --> F2[flow_step] F --> F3[signature_requirement] ``` ## Design Patterns ### 1. Builder Pattern Integration Each domain model follows a consistent builder pattern that enables fluent, chainable APIs in Rhai scripts: ```rhai let company = new_company() .name("Acme Corp") .email("contact@acme.com") .business_type("global") .status("active"); ``` ### 2. Macro-Driven Code Generation The crate heavily utilizes procedural macros for: - **Authorization**: `register_authorized_*_fn!` macros for CRUD operations - **Type Conversion**: `id_from_i64_to_u32` for safe ID conversions - **Derive Macros**: `FromVec` for array wrapper types ### 3. Type Safety with Rhai Integration Each Rust type is carefully wrapped for Rhai compatibility: - **Custom Types**: Using `#[rhai_type]` for proper Rhai integration - **Array Wrappers**: Specialized array types (e.g., `RhaiCollectionArray`) for collections - **Error Handling**: Comprehensive error propagation with `Result>` ## Module Structure ### Business Domain Modules #### `biz` - Business Operations Handles core business entities: - **Company**: Corporate entity management with registration, status, and business type - **Product**: Product catalog and inventory management - **Sale**: Sales transaction processing - **Shareholder**: Equity and ownership management #### `finance` - Financial Models Manages financial operations: - **Account**: Financial account management - **Asset**: Asset tracking and valuation - **Marketplace**: Trading and marketplace operations #### `library` - Content Management Comprehensive content management system: - **Collection**: Content organization and grouping - **Image**: Image asset management with dimensions - **PDF**: Document management with page tracking - **Markdown**: Text content with formatting - **Book**: Multi-page publications with table of contents - **Slideshow**: Presentation management #### `flow` - Workflow Management Business process automation: - **Flow**: Workflow definition and execution - **FlowStep**: Individual workflow steps - **SignatureRequirement**: Digital signature management ### Core Infrastructure Modules #### `access` - Access Control Security and permission management for resource access. #### `calendar` - Time Management Calendar and scheduling functionality. #### `circle` - Community Management Community and group management with themes and membership. #### `contact` - Contact Management Contact information and relationship management. #### `core` - Core Utilities Fundamental utilities including comment systems. #### `object` - Generic Objects Generic object handling and manipulation. ## Rhai Integration Patterns ### Function Registration Each module follows a consistent pattern for Rhai function registration: ```rust #[export_module] mod rhai_module_name { // Constructor functions #[rhai_fn(name = "new_entity")] pub fn new_entity() -> RhaiEntity { ... } // Setter functions (chainable) #[rhai_fn(name = "field_name", return_raw)] pub fn set_field(entity: &mut RhaiEntity, value: Type) -> Result> { ... } // Getter functions #[rhai_fn(get = "field_name", pure)] pub fn get_field(entity: &mut RhaiEntity) -> Type { ... } } ``` ### CRUD Operations Standardized CRUD operations are generated using macros: ```rust register_authorized_create_by_id_fn!(/* save operations */); register_authorized_get_by_id_fn!(/* retrieve operations */); register_authorized_delete_by_id_fn!(/* delete operations */); register_authorized_list_fn!(/* list operations */); ``` ### JSON Serialization A generic JSON serialization system allows any domain object to be converted to JSON: ```rust fn register_json_method(engine: &mut Engine) where T: CustomType + Clone + Serialize ``` This enables Rhai scripts to call `.json()` on any domain object for debugging or data export. ## Data Flow Architecture ```mermaid sequenceDiagram participant Script as Rhai Script participant DSL as DSL Module participant Model as Domain Model participant DB as Database participant Auth as Authorization Script->>DSL: new_entity() DSL->>Model: Entity::new() Model-->>DSL: Entity instance DSL-->>Script: RhaiEntity Script->>DSL: entity.field(value) DSL->>Model: entity.field(value) Model-->>DSL: Updated entity DSL-->>Script: RhaiEntity Script->>DSL: save_entity(entity) DSL->>Auth: Check permissions Auth-->>DSL: Authorization result DSL->>DB: Store entity DB-->>DSL: Stored entity DSL-->>Script: Result ``` ## Security Architecture ### Authorization Layer All database operations go through an authorization layer: - **Permission Checking**: Each operation validates user permissions - **Resource-Based Access**: Access control based on resource types - **Caller Identification**: Operations are attributed to specific callers ### Type Safety - **ID Conversion**: Safe conversion between Rhai's i64 and Rust's u32 IDs - **Error Propagation**: Comprehensive error handling prevents script crashes - **Input Validation**: Type checking and validation at the Rhai boundary ## Performance Considerations ### Memory Management - **Move Semantics**: Efficient ownership transfer using `std::mem::take` - **Clone Optimization**: Strategic cloning only when necessary - **Reference Counting**: Shared ownership where appropriate ### Compilation Efficiency - **Macro Generation**: Compile-time code generation reduces runtime overhead - **Module Separation**: Modular compilation for faster build times - **Feature Flags**: Conditional compilation based on requirements ## Integration Points ### External Dependencies - **heromodels**: Core domain models and database abstractions - **heromodels_core**: Fundamental data structures - **heromodels-derive**: Procedural macros for model generation - **rhai**: Scripting engine integration - **serde**: Serialization for JSON export ### Internal Dependencies - **macros**: Authorization and utility macros - **derive**: Custom derive macros for Rhai integration ## Usage Patterns ### Script Development Typical Rhai script patterns enabled by this DSL: ```rhai // Create and configure entities let company = new_company() .name("Tech Startup") .business_type("startup") .email("hello@techstartup.com"); // Save to database let saved_company = save_company(company); // Retrieve and modify let existing = get_company(saved_company.id); let updated = existing.status("active"); save_company(updated); // Export data print(company.json()); ``` ### Error Handling Comprehensive error handling throughout: - **Type Validation**: Invalid enum values are caught and reported - **Database Errors**: Database operation failures are propagated - **Authorization Errors**: Permission failures are clearly communicated ## Extensibility The architecture supports easy extension: - **New Domains**: Add new business domains following existing patterns - **Custom Operations**: Extend existing domains with new operations - **Integration**: Easy integration with external systems through Rhai scripts This modular, type-safe architecture provides a powerful foundation for business logic implementation while maintaining security and performance.