System Entities represent the actual business objects that the system manages. These entities are created, modified, and referenced by actions and are central to the system’s operational flows. System entities can be domain objects such as orders, invoices, users, or shipments, depending on the nature of the system. They evolve as actions modify their state.
If you’re a Software Architect or Engineer, you might be tempted to quickly identify this as the System’s Database Model. However, System Entities in MoSy are not database entities; they are conceptual. You can use them as inputs to later model the technical representations that will be persisted in databases, exposed through APIs, or processed within system components.
In MoSy, System Entities are aligned vertically with the actions that produce or utilize them. Additionally, entities that conceptually belong to the depicted flow are colored in yellow (e.g., Order belongs to the Customer Purchase Flow). In contrast, entities defined and owned by other flows are colored in grey (e.g., Shopping Cart belongs to the Browse and Select Flow).
System Entities in MoSy
Entity Relationships
When modeling system entities in MoSy, it is often helpful to define the relationships between them, such as one-to-one (1:1), one-to-many (1:N), many-to-one (N:1), or optional relationships (0..1:1, etc.). These relationships clarify how different entities interact in reality and help define boundaries when translating business concepts into technical models.
For example, in an e-commerce system, an order consists of multiple order lines. The question then arises: should order lines reference their parent order (N:1), or should the order contain a list of its order lines (1:N)? While the system can technically support either approach, the decision impacts performance, querying, and system scalability.
Technical representatives should primarily lead these discussions as they determine how relationships are implemented within the system. However, business and product stakeholders can provide critical input when there is uncertainty about how the model should reflect real-world scenarios. A typical example is search behavior—if product managers expect customers to search for orders based on specific order lines, this might influence how the data is structured.
However, to ensure effective collaboration, discussions about entity relationships should remain at a level all roles can understand. Rather than diving into purely technical database structures, teams should use these relationships as a way to clarify business rules, refine search and reporting capabilities, and align on system behavior.
Finally, when relationships between entities are unclear or uncertain, it is perfectly acceptable to leave them undefined. Not every entity needs to be strictly linked from the beginning. Some relationships will become more evident as the system evolves, and forcing unnecessary constraints too early can lead to over-complication. The system modeling team should focus on defining only the relationships critical to initial system behavior, allowing flexibility for later adjustments.
Entities are the glue in MoSy
System Entities are a big part of the magic sauce in MoSy that bridges the gap between business/product and technical system modeling. Software architects and developers model reality by taking inputs like stories, user journeys, if-this-then-that/given-when-then statements, etc. Eventually, they translate these inputs into models created for humans to talk with computers, using different programming paradigms: imperative, object-oriented programming, functional, reactive, actor model, etc. On an architectural level, the reality of the business requirements is translated into models (visual or implicit) consisting of components and interfaces, functions, messaging, database entities, etc. Product and business people are often puzzled by Event-Driven Architecture diagrams, Microservices setups, or even UML. These architectural representations alone don’t help either since they are mostly solution-oriented and have already been translated into computer language (at a higher level than programming). Therefore, these visualizations (or implicit structures when visuals don’t exist) are nearly impossible to relate to the business flow representations. This is also why workflow and process management tools and all their associated consultancy resources have seen relative success despite being despised by many software developers: they communicate in the business language, transforming the big black box that technical systems can imply for non-technical people into a grey box. Try asking any organization using these programming frameworks who decided to use them over modeling processes and workflows with any other programming language: it was the organization’s business side.
The MoSy Flow diagram enables business and technical professionals to engage in meaningful discussions about modeling reality by providing a shared context that outlines the actors and the system’s key objectives (we’ll see later how to incorporate them into these diagrams). Entities and Actions are then used as glue to design or depict the system’s technical plane with its components and APIs.
To build a system entity model, you need some of the talents from software architecture and product design. MoSy diagrams are intended to be built collaboratively, so work together and use the actions to design (or represent) the entities in your system for each particular flow. Using the previous example of an e-commerce system customer purchase flow, these would be helpful questions for the discussion:
- What input does the “Proceeds to Checkout” action require? It needs the Shopping cart lines, which model the items the customer has added for a later purchase. These concepts don’t seem to belong to this flow; they probably come from another one where users browse products and can select what they like.
Would this action produce anything? It depends. Do we want to model the interaction as a pre-filled order that the customer creates and sends to the system? Or do we want the system to keep the state in the shopping cart, and the customer just needs to instruct the system to transform it into an order? It might look like a subtle difference, but they’re very different technical implementations and have pros and cons. The second option allows the user to resume shopping from a different device. The first one allows external platforms (e.g., key partners) to redirect users to the checkout page directly without them needing to create a shopping cart in our system. Are these technical implementation details? Not really; they impact the user and partner experience of the product or service you’re building, and a short Q&A session about the flow can save the organization a lot of time in later modifications.