Note: This is the first article in a series of technical write-ups from internal Chromia engineers aimed at sharing insights and best practices for building mid-size projects in the blockchain space.
Navigating the Complexities of Blockchain Module File Structure
Hello, fellow developers! As we venture into the dynamic world of Chromia's blockchain, understanding the nuances of their approach to organizing project files becomes crucial. This methodology is more than just about maintaining order; it's a strategic way to structure our code for efficiency and scalability. Currently, we're employing this approach in our products, but it's designed to be adaptable, continually evolving to meet new challenges and improvements.
A Deeper Dive into Chromia's File Setup
Chromia offers an innovative setup akin to an intricately organized workspace for code. It includes various components, such as entities, queries, operations, and more. Each component plays a specific role, collectively contributing to a streamlined development process.
Detailed Breakdown of the File Structure
Understanding the structure in depth, file by file reveals the organization and purpose behind each component:
- module_name/: The heart of each module, serving as a centralized directory for all related files. This main directory is the foundation of the module, where all its functionalities and features are defined and interconnected.
- module_name/external/: A dedicated space for files accessible externally. This is where the module interacts with the outside world, and it’s crucial for defining the module's public interface.
- external/operations.rell: A comprehensive list of all operations that the module can perform. These operations are the actionable components, allowing the module to execute its primary functions.
- external/queries.rell: This file is a repository of all the queries within the module. Queries are pivotal for data retrieval, dictating how the module communicates with the database to fetch and present data.
- external/module.rell: Critical for initial module setup, this file includes import statements and custom mount names. It serves as a blueprint, outlining how the module integrates with the broader application architecture.
- functions.rell: This file encapsulates the core of the module's business logic. It contains a variety of functions essential for the module's operational logic, defining how the module processes data and responds to different inputs.
- mappers.rell: Specializing in data serialization, this file defines how database query results are transformed and formatted. Functions like `map_comment` are examples of how raw data from the database is converted into user-friendly formats.
- entities.rell: This file contains the structural backbone, housing entities, enums, and structures (for modules with up to 3 structs). It also includes functions for retrieving entities by ID, providing a quick reference to the module's fundamental data structures.
- structs.rell: If a module contains more than three structs, this file becomes a dedicated space for them. Its existence helps to maintain clarity and organization within the module, especially for modules with complex or numerous structs
- utils.rell: Here lies a collection of utility functions that have module applications. These functions enhance the reusability and efficiency of the code, providing common tools that can be utilized by different parts of the application. (could be the same file on the modules level for cross-module utils)
- require.rell: A specialized file for functions that validate data using the `require` construct. This is particularly important for authentication or verification functions, ensuring that the module operates within the defined parameters and conditions.
The Philosophy Behind the Structure
The structure is deeply rooted in key software development principles:
- Modularity: We promote flexibility and scalability by breaking down the project into distinct modules. Each module functions as an independent unit, making the codebase easier to manage and update.
- Encapsulation: This principle involves keeping related functionalities bundled together. By doing so, we minimize interdependencies between different parts of the code, enhancing the application's robustness and reliability.
- Maintainability: A well-organized file structure significantly aids in maintaining the code. It makes it easier for current and future developers to understand, debug, and enhance the application.
- Scalability: As the project grows and evolves, a structured approach to file organization ensures that the codebase can adapt and expand without becoming unwieldy or complex.
Real-World Applications and Continuous Evolution
This structure has been applied to our real-world projects, proving its effectiveness in various scenarios. What's compelling about this structure is its inherent flexibility and adaptability. It's designed to evolve with our projects, accommodating new requirements and challenges as they arise.
About Chromia
Chromia is a Layer-1 relational blockchain platform that uses a modular framework to empower users and developers with dedicated dapp chains, customizable fee structures, and enhanced digital assets. By fundamentally changing how information is structured on the blockchain, Chromia provides natively queryable data indexed in real-time, challenging the status quo to deliver innovations that will streamline the end-user experience and facilitate new Web3 business models.
Website | Twitter | Telegram | Facebook | Instagram | Youtube | Discord