Luana Quinaglia Maistro; Vinicius Santos Andrade

DOI: 10.22167/2675-6528-202601105

Article prepared by the ResumeAI tool, an artificial intelligence solution developed by the Pecege Institute focused on synthesis and writing.

Summary

The efficient management of sales and inventory has proven crucial for business competitiveness in dynamic and data-driven markets. Nexsell was developed, an Intelligent Sales Management System with personalized recommendation functionalities, aiming to integrate operational control and data intelligence into an accessible solution for small and medium-sized enterprises. The system was architected based on the principles of Clean Architecture and Domain-Driven Design, utilizing .NET 8, PostgreSQL, and Entity Framework Core on the backend, and React 19 with TypeScript on the frontend. Six comprehensive functional modules were implemented, including product registration, customer management, sales recording, inventory control, intelligent recommendations, and interactive management reports. Personalized recommendations were provided via Recombee, an external platform, based on purchase history and customer profiles. The system was validated through 212 unit tests in xUnit and automated integration tests, which evaluated the quality of suggestions generated by the algorithm with Precision@K and Recall@K metrics in 55 simulated scenarios. The results demonstrated the successful integration of traditional operational functionalities with an intelligent recommendation module, presenting an average Precision@5 of 19.3% and an average Recall@5 of 48.2%, consistent with expectations for small catalogs. The adopted architecture ensured maintainability, testability, and resilience to external failures, contributing to a robust and adaptable solution for market needs.

Keywords: Software architecture; Automation; Clean Architecture; Domain-Driven Design; Collaborative filtering.

1. Introduction

Digital transformation has profoundly redefined the business landscape, demanding continuous adaptation and the adoption of innovative strategies for organizations to maintain competitiveness. In this scenario, efficient sales and inventory management has emerged as a fundamental pillar for success, especially in dynamic and increasingly data-driven markets. The ability to process and analyze large volumes of information to optimize operations and predict consumer trends has become a strategic differentiator. Laudon and Laudon (2023) emphasize that well-structured information systems are no longer a luxury but an imperative necessity, as companies that cannot control their operations and base decisions on data risk losing relevance. However, small and medium-sized enterprises (SMEs) often face significant challenges in implementing integrated solutions, frequently relying on disconnected tools or manual processes that severely limit their analytical and growth capabilities.

In parallel with this evolution, artificial intelligence (AI) has been revolutionizing the shopping experience and commercial management. Among its various applications, recommender systems stand out as one of the most successful branches of machine learning, as pointed out by Ricci, Rokach, and Shapira (2015). These systems are capable of analyzing consumer behavior, such as purchase history and preferences, to suggest relevant products in a personalized way. The effectiveness of this approach is widely proven by market giants like Amazon and Netflix, which use sophisticated collaborative filtering and content-based algorithms to significantly increase conversion rates, boost average sales value, and enhance customer satisfaction. The personalization of the shopping experience, once restricted to large corporations with vast technological resources, has become a decisive factor in engaging customers and driving business growth at any scale.

Despite the transformative potential of artificial intelligence, the implementation of intelligent and integrated systems remains a considerable challenge for small and medium-sized enterprises. The high development costs, the complexity of integration with existing infrastructures, and the scarcity of specialized technical knowledge often make the adoption of these advanced technologies unfeasible. In this context, modern software engineering seeks solutions that balance functionality, ease of use, and economic viability, as advocated by Sommerville (2011), especially when developing systems for organizations with limited resources. The need for systems that are not only functional but also adaptable and scalable highlights the importance of well-founded architectural decisions. Richards and Ford (2020) argue that software architecture transcends the mere choice of technologies, involving strategic decisions about how to structure systems to meet business requirements, ensuring adaptability to future changes and resilience to failures. Principles such as Clean Architecture and Domain-Driven Design (DDD) are crucial for building robust and maintainable systems. DDD, as proposed by Evans (2003), focuses on modeling the business domain, using concepts like entities and value objects to encapsulate business rules and ensure data integrity, an approach that Vernon (2013) details as essential for validation logic. Clean Architecture, in turn, promotes the separation of concerns into layers, isolating business rules from infrastructure and user interface, which facilitates the testability, maintainability, and scalability of the system over time, essential characteristics for systems that need to evolve and integrate reliably with external services.

Given the gap between the need of small and medium-sized enterprises for efficient sales and inventory management and the complexity of implementing advanced technological solutions, this work is justified by the growing demand for the democratization of intelligent tools and the opportunity to apply cutting-edge software engineering concepts, systems architecture, and artificial intelligence in a practical and market-relevant context. Thus, the objective of this article is to present the development of an intelligent sales management system that integrates traditional operational functionalities with personalized recommendation features, offering an accessible and robust solution for small and medium-sized enterprises to optimize their operations and enhance customer experience through suggestions based on their purchase history.

2. Material and Methods

The research was characterized as applied, aiming to solve a practical market problem, according to Gil’s (2002) classification. Its objectives were exploratory and descriptive, seeking to understand the commercial management challenges in small businesses and develop a functional technological solution. The methodological approach adopted was applied research with proof-of-concept development, focusing on the construction and technical validation of an intelligent sales management system. This process occurred in iterative cycles, with continuous evaluation of results, following Agile methodologies principles, without involving direct participation of end-users in a real operational environment.

The study’s context encompassed the scenario of small and medium-sized enterprises seeking to optimize sales and inventory management through advanced technologies. The development location was the research and development environment, without a specific physical field application site. The research execution period was not explicitly delimited, but the system development occurred in iterative cycles, reflecting a continuous approach. The main unit of analysis was the Nexsell system, a sales management software with recommendation functionalities, evaluated for its architecture, implementation, and technical performance.

For the system validation, a population or sample of real users was not used, but rather a case study with simulation of commercial operations. The data employed were synthetic, elaborated based on real business patterns to ensure relevance. Specific scenarios were created that contemplated five distinct customer profiles and their respective purchasing patterns. This approach allowed for the evaluation of the quality of the recommendations generated by the system under controlled conditions, without the need for interaction with a real production environment or sensitive customer data.

The unit of analysis for the validation of the recommendations consisted of 50 synthetic products, equally distributed into five categories: IT, Electronics, Books, Sports, and Home. For each of the five modeled consumption profiles (Programmer, Gamer, Reader, Athlete, and HomeOffice), eleven simulated customers were instantiated, totaling 55 evaluation scenarios. These scenarios were crucial for testing the recommendation algorithm’s capability in different contexts of preference and purchase history, ensuring a comprehensive analysis of the recommender system’s behavior.

The Nexsell system was developed following the principles of Domain-Driven Design (DDD) and Clean Architecture (Richards; Ford, 2020), which guided architectural and tactical modeling decisions. The backend was implemented in .NET 8, using PostgreSQL as the database and Entity Framework Core for data access. The business logic was exposed through a REST API, organized into four layers (Domain, Application, Infrastructure, and API) and documented with Swagger/OpenAPI, facilitating the integration and consumption of services by other applications.

The system’s frontend was built as a web application in React 19 with TypeScript, using Ant Design for interface components, Zustand for state management, and Axios for HTTP requests. The Vite tool was employed for building and development, optimizing speed. The system comprised six main modules: product registration and control, customer management, sales registration, inventory control, intelligent recommendations, and managerial reports. A shared TypeScript library, containing Value Objects and use cases, was published via GitHub Packages for reuse.

The customer management functionality was integrated with the ViaCEP API for automatic address filling, enhancing the user experience and data accuracy. The intelligent recommendation module was enabled by integration with Recombee, a platform specialized in recommender systems. This choice allowed us to focus on the practical application of artificial intelligence, delegating the complexity of developing machine learning algorithms to the external service. Interaction data, such as purchase history, was sent to Recombee via API to generate personalized suggestions.

The system development followed a pipeline of four main stages. Initially, analysis and modeling were performed, with requirements gathering and architecture definition. Next, implementation occurred, with the creation of functionalities and the application of automated tests for each new functionality. The third stage involved integration with the Recombee service, configuring the sending of purchase events and the consumption of recommendations. Finally, final validation was carried out, with scenario simulations and collection of quality metrics to evaluate system performance.

The testing strategy was structured in three complementary levels, as recommended by Sommerville (2011), to ensure software quality. Domain unit tests were performed, covering entities and value objects, totaling 154 tests. Additionally, 58 application unit tests were executed to validate the application layer services, using the xUnit framework and the Moq library for creating stubs. These tests verified behaviors, state transitions, business rules, and expected failure cases, ensuring the internal robustness of the system.

Automated integration tests were developed and executed in the Teste.Integration project, using the xUnit framework, directly against the Recombee API. The quality of the recommendations was measured using the Precision@K and Recall@K metrics, widely recognized in the recommender system literature (Ricci, Rokach, and Shapira, 2015). For each of the 55 evaluation scenarios, the *train/test split* technique was applied, where four purchases were used for training and two were retained as *ground truth* for evaluation, with K=5 for the metrics.

Communication with Recombee occurred at three key moments in the business flow. When a product was registered or updated, the RecomendacaoService service automatically synchronized the item, sending properties such as name, category, and price, which make up Recombee’s data schema. Upon confirming a sale, the system automatically registered an AddPurchase event for each item sold, providing the main input for the collaborative filtering algorithm. The customer’s viewing of an item also generated interactions, contributing to the algorithm’s learning.

Formal ethical procedures were not applied, as the research involved the development of a system and its validation with synthetic data, without direct human participation or the collection of personal data. The main methodological limitation identified was the use of synthetic data for the evaluation of recommendations. Although this approach was sufficient to validate the technical integration and functioning of the algorithm, it does not replace an evaluation with real operational data in a production environment, which could offer additional *insights* into performance under real-world usage conditions.

3. Results and Discussion

The development of the Nexsell system, the central object of this work, was guided by a robust architecture and modern software engineering principles, aiming not only for functionality but also for maintainability, scalability, and extensibility. The choice of Domain-Driven Design (DDD) and Clean Architecture, as advocated by Evans (2003) and Richards and Ford (2020), respectively, proved fundamental for organizing the code into four distinct layers: Domain, Application, Infrastructure, and API. This separation of responsibilities is a pillar for complex systems, ensuring that business rules remain isolated from technological details, which facilitates evolution and adaptation to new market demands.

The Domain layer, for example, concentrated the essential business entities, such as Customer, Product, Stock, Sale, SaleItem, and User. Each of these entities was modeled with rigorous encapsulation, using private *setters* and domain methods that ensure data integrity and compliance with business invariants. This approach is in line with the DDD philosophy, which emphasizes the modeling of a rich and expressive domain. Furthermore, value objects like CPF, CNPJ, Document, Contact, and Address were implemented as immutable types with built-in validation. This practice, advocated by Vernon (2013), ensures that validation logic resides within the type itself, preventing the dispersion of validation rules throughout the application and promoting data consistency from its creation. The immutability of these value objects contributes to the system’s robustness, preventing unwanted changes after their initialization.

The Infrastructure layer was responsible for data persistence, employing Entity Framework Core 8 and applying the Repository and Unit of Work patterns. These patterns are crucial for abstracting data access operations, allowing the business logic in the Domain layer to not need to know the specific database details. During development, SQLite was used for its configuration simplicity, ideal for prototyping and testing environments. However, the migration to PostgreSQL in a production environment, facilitated by Entity Framework Core itself, demonstrated the architecture’s flexibility. The ability to apply migrations automatically upon application startup eliminated the need for manual *scripts*, reducing the chance of errors and speeding up *deploy*. This adaptability to different database systems, without impacting business rules, is a testament to the effectiveness of Clean Architecture in decoupling technical concerns from business rules. The resulting data model, divided into client and commercial domains, is illustrated by entity diagrams detailing the relationships and attributes.

Figure 1. Customer domain entity diagram

Source: Original research results

Figure 1, which presents the customer domain entity diagram, details the data structure for managing crucial consumer information. The `Clientes` (Customers) entity is observed as the core, containing attributes such as `Id`, `Nome` (Name), `DocumentoNumero` (Document Number), `DocumentoTipo` (Document Type), and `Ativo` (Active), in addition to `DataCadastro` (Registration Date). This entity relates to `ClienteEnderecos` (Customer Addresses) and `ClienteContatos` (Customer Contacts), allowing the registration of multiple addresses and contacts for the same customer. The modeling of `ClienteEnderecos` with fields such as `CEP` (Postal Code), `Logradouro` (Street), `Numero` (Number), `Complemento` (Complement), `Bairro` (Neighborhood), `Cidade` (City), and `UF` (State) reflects the need for detailed geographical data for commercial and logistical operations. The integration with the ViaCEP API, mentioned in the methodology, optimizes the filling of these fields, reducing errors and improving the user experience, which is a practical differentiator for small businesses seeking efficiency. The `ClienteContatos` entity, in turn, allows storing `Telefone` (Phone), `Celular` (Mobile), and `Email`, offering multiple communication channels with the customer. This granularity in customer data modeling is essential for a sales management system that aims for personalization and lasting relationships, as advocated by Laudon and Laudon (2023), who emphasize the importance of well-structured information systems for business competitiveness.

Figure 2. Commercial domain entity diagram

Source: Original research results

Figure 2, which illustrates the business domain, complements the system’s vision by presenting the entities `Products`, `Stock`, `Sales`, `SaleItems`, and `Users`. The `Products` entity includes `Id`, `Code`, `Name`, `Description`, `UnitPrice`, `Category`, `Active`, and `RegistrationDate`, providing a solid foundation for the product catalog. Automatic integration with Recombee for product synchronization, as detailed below, ensures that recommendations are always based on updated data. The `Stock` entity manages the `Quantity`, `MinimumQuantity`, and `Location` of each product, allowing for precise inventory control and the generation of alerts for low stock levels, a critical functionality for preventing sales losses and optimizing working capital management in small businesses. `Sales` are recorded with `Id`, `CustomerId`, `SaleDate`, `Status`, `PaymentMethod`, and `Observation`, while `SaleItems` details each product included in a sale, with `ProductId`, `ProductName`, `Quantity`, and `UnitPrice`. This structure allows for complete tracking of the sales cycle, from creation to confirmation and cancellation, with automatic stock deduction and the sending of purchase events to Recombee, demonstrating the interconnection and automation of business processes. The `Users` entity manages system access with `Id`, `Name`, `Email`, `PasswordHash`, and `Role`, implementing profile-based access control, essential for system security and governance.

The API layer, implemented in ASP.NET Core 8, exposes the business logic through a RESTful interface. This approach is widely recognized for its flexibility and compatibility with various client applications. The *endpoints* were distributed among modules for Authentication, Clients, Products, Inventory, Sales, Recommendations, and Reports. The interactive API documentation, automatically generated with Swagger/OpenAPI, facilitated the consumption and testing of the *endpoints*. The OpenAPI Specification (OPENAPI INITIATIVE, 2015) is a standard that allows for the automated creation of SDKs, speeding up integration between *frontend* and *backend* and reducing development workload. This compliance with open standards is an indicator of the project’s maturity and its ability to integrate with external ecosystems.

Layering, as per Clean Architecture, is an architectural outcome of great value. Richards and Ford (2020) describe maintainability, extensibility, and testability as essential architectural characteristics. Nexsell, by isolating responsibilities, ensures that modifications in one layer do not affect others, facilitating maintenance. Extensibility is favored by the use of interfaces and dependency injection, allowing for easy component replacement. Testability is enabled by the decoupling between layers, making it possible to write effective unit and integration tests.

The system’s *frontend* was built as a web application in React 19 with TypeScript, using Ant Design for interface components, Zustand for state management, and Axios for HTTP requests. The choice of React (REACT, 2013) is due to its maturity and vast community, which ensure a robust and constantly evolving ecosystem. Ant Design (DEVOGRAPHICS, 2024), in turn, is a widely used component library in corporate applications, offering over 50 responsive components and facilitating the maintenance of visual consistency. Zustand was selected for its simplicity in global state management, abstracting implementation details and offering organizational flexibility. The Axios library, although native alternatives like Fetch API exist, was preferred for its facilitators, such as automatic *status code* handling, the ability to treat HTTP errors as exceptions, and the ease of use of *interceptors*, which reduce repetitive code and standardize request behavior. The Vite tool optimized the *build* and development process, contributing to agility in delivery. A shared TypeScript library, containing *Value Objects* and use cases, was published via GitHub Packages, promoting code reuse and reinforcing the application’s adaptability, allowing the *frontend* to evolve independently of invariant domain logic.

The Nexsell system comprised six main modules, each with a set of functionalities designed to optimize the commercial management of small businesses. Table 1 details these modules and their main functionalities.

Table 1. Implemented modules and their main functionalities

Module	Features
Clients	Registration with CPF/CNPJ, multiple contacts and addresses, activation and deactivation
Products	Registration by code, category, and price, automatic synchronization with Recombee
Stock	Quantity control, low stock alerts, inputs and outputs (In the frontend, integrated with the products screen)
Sales	Creation, addition, and removal of items, confirmation with automatic stock reduction, cancellation
Recommendations	Integration with Recombee, personalized suggestions per client (Integrated in the frontend along with the client screen)
Reports	Sales summary by period, best-selling products, top purchasing customers, and stock position

Source: Original research results

Table 1 presents a concise summary of the implemented modules and their functionalities, demonstrating the comprehensiveness of the Nexsell system. The `Clients` module offers complete registration with CPF/CNPJ, multiple contacts and addresses, as well as activation and deactivation, which is crucial for maintaining an updated and accurate client database, supporting segmentation and relationship strategies. The `Products` module allows registration by code, category, and price, and stands out for its automatic synchronization with Recombee, ensuring that the recommendation system operates with always up-to-date product information. The `Inventory` provides quantity control, alerts for stock below minimum, and registration of entries and exits, a vital functionality for inventory management and to avoid stockouts or excesses. The `Sales` module covers the creation, addition, and removal of items, confirmation with automatic stock deduction, and cancellation, automating operational processes and reducing manual intervention. `Intelligent Recommendations` integrate with Recombee to provide personalized suggestions per client, an artificial intelligence feature that can boost sales and customer satisfaction. Finally, `Management Reports` offer a summary of sales by period, best-selling products, top purchasing clients, and stock position, providing strategic *insights* for decision-making. The implementation of these modules demonstrates success in integrating traditional operational functionalities with advanced artificial intelligence features, addressing the challenge of sales and inventory management in small businesses.

The REST interface exposes the *endpoints* distributed across the modules, as detailed in Table 2. The implementation of these *endpoints* follows best practices in API design, ensuring efficient and secure communication between the *frontend* and the *backend*.

Table 2. Endpoints implemented by module

Method	Route	Description
POST	/api/auth/login	Authenticates the user and returns a JWT token
POST	/api/auth/users	Create a new system user (Admin only)
GET	/api/clients	List all clients
GET	/api/clients/{id}	Returns a client by ID
GET	/api/clients/document/{documento}	Search for a client by CPF or CNPJ
GET	/api/clients/active	List only active clients
GET	/api/clients/search?name={nome}	Search customers by name
POST	/api/clients	Register a new client
PUT	/api/clients/{id}	Updates a client’s data
PATCH	/api/clients/{id}/activate	Reactivate an inactive customer
PATCH	/api/clients/{id}/deactivate	Deactivates an active client
POST	/api/clients/{id}/contacts	Add a secondary contact to the client
POST	/api/clients/{id}/addresses	Add a secondary address to the customer
GET	/api/products	List all products
GET	/api/products/{id}	Return a product by ID
GET	/api/products/code/{codigo}	Search for a product by internal code
GET	/api/products/active	List only active products
GET	/api/products/category/{categoria}	List products by category
GET	/api/products/search?name={nome}	Search products by name
POST	/api/products	Register a new product
PUT	/api/products/{id}	Updates product data
PATCH	/api/products/{id}/activate	Reactivate an inactive product
PATCH	/api/products/{id}/deactivate	Deactivates an active product
PATCH	/api/products/{id}/stock/add	Add quantity to product stock
PATCH	/api/products/{id}/stock/remove	Remove product stock quantity
GET	/api/inventory	List the stock of all products
GET	/api/inventory/{id}	Return an inventory record by ID
GET	/api/inventory/product/{produtold}	Returns the stock of a specific product
GET	/api/inventory/low	List products with stock below minimum
GET	/api/inventory/available/{produtold}/{quantidade}	Check stock availability
POST	/api/inventory	Creates the stock record for a product
PUT	/api/inventory/{id}	Update minimum quantity and location
POST	/api/inventory/input	Record merchandise entry
POST	/api/inventory/output	Record merchandise output
GET	/api/sales	List all sales
GET	/api/sales/{id}	Returns a sale by ID
GET	/api/sales/client/{clienteld}	List all sales for a client
GET	/api/sales/status/{status}	Filter sales by status
GET	/api/sales/period?startDate={data}&endDate={data}	List sales by period
GET	/api/sales/total?startDate={data}&endDate={data}	Returns the total sales value in the period
POST	/api/sales	Create a new sale
POST	/api/sales/{id}/items	Add an item for sale
Remove	/api/sales/{id}/items/{itemId}	Remove an item from the sale
PATCH	/api/sales/{id}/items/{itemId}/quantity	Update the quantity of an item
POST	/api/sales/{id}/confirm	Confirms the sale and reduces stock
POST	/api/vendas/{id}/cancel	Cancel the sale
GET	/api/recommendations/client/{clienteld}	Return recommended products for a client
GET	/api/recommendations/client/{clienteId}/full	Returns the customer with their recommendations
GET	/api/recommendations/all	Return all customers with their recommendations
GET	/api/reports/sales/total-orders?startDate={data}&endDate={data}	Total orders in the period
GET	/api/reports/sales/total-value?startDate={data}&endDate={data}	Total value sold in the period
GET	/api/reports/sales/average-ticket?startDate={data}&endDate={data}	Average ticket in the period
GET	/api/reports/sales/by-product?startDate={data}&endDate={data}	Best-selling products in the period
GET	/api/reports/sales/by-client?startDate={data}&endDate={data}	Top customers by purchases in the period
GET	/api/reports/sales/by-category?startDate={data}&endDate={data}	Best-selling categories in the period
GET	/api/reports/stock	Current stock position

Source: Original research results

Table 2 details the implemented *endpoints*, revealing the granularity and organization of the REST API. Each *endpoint* is described by the HTTP method (POST, GET, PUT, PATCH, DELETE), its route, and a brief description of its functionality. For example, `/api/auth/login` and `/api/auth/usuarios` manage authentication and user registration, respectively, with the former returning a JWT token for secure sessions. The `/api/clientes` *endpoints* allow for complete CRUD operations, including search by ID, document, name, status (active), and the addition of secondary contacts and addresses, demonstrating the robustness of customer management. Similarly, `/api/produtos` offers functionalities to list, search, register, update, and deactivate products, as well as manage stock directly (`/api/produtos/{id}/estoque/adicionar`, `/api/produtos/{id}/estoque/remover`). The `/api/estoque` *endpoints* provide visibility into inventory, including products with low stock and availability checks. The sales module, accessible via `/api/vendas`, allows for the creation, item management, confirmation, and cancellation of sales, with automatic stock deduction. The `/api/recomendacoes` *endpoints* are crucial for the artificial intelligence module, enabling the retrieval of personalized suggestions for specific or all customers. Finally, `/api/relatorios` offers *endpoints* to obtain aggregated sales data (total orders, total value, average ticket, best-selling products, top purchasing customers, sales by category) and the current stock position, providing the basis for management dashboards. This *endpoint* structure demonstrates the system’s ability to support all business operations programmatically and efficiently, facilitating integration with the *frontend* and future extensions.

The Sales module deserves special mention for its integration between layers and services. Upon confirming a sale, the system automatically checks stock availability for each item, performs the quantity reduction, and then sends the purchase events to Recombee to feed the recommendation model. This integration occurs resiliently, where a potential communication failure with Recombee does not prevent the sale confirmation, ensuring that the central business system is not affected by external dependencies. This approach aligns with the principles of fault tolerance discussed by Richards and Ford (2020), who emphasize the importance of designing systems that can continue operating even in the presence of partial failures. The automation of stock reduction and the real-time sending of purchase events are crucial for operational efficiency and recommendation accuracy, respectively.

Similarly, the Products module automatically synchronizes data with Recombee when creating or updating a product. This synchronization ensures that the recommender system’s catalog is always up-to-date, without requiring manual action from the operator. Data consistency between the management system and the recommendation service is vital for the relevance and quality of suggestions offered to customers, directly impacting the shopping experience and conversion rates.

Information security was addressed with the implementation of authentication based on JSON Web Tokens (JWT), a widely adopted standard in modern REST APIs for its *stateless* nature and compatibility with distributed applications. Communication between the *frontend* and the API occurs exclusively via HTTPS, with JWT tokens transmitted in the Authorization header of each authenticated request. The system uses the Microsoft.AspNetCore.Authentication.JwtBearer package for token validation and the IPasswordHasher from the ASP.NET Core ecosystem itself for password *hashing*, using the PBKDF2 algorithm, ensuring adequate security without reliance on external libraries. All *endpoints*, except for login, require a valid JWT token, and the user creation *endpoint* is restricted to the Admin *role*, preventing ordinary users from creating new accounts. A default administrator user is automatically created on the system’s first startup, enabling initial access without the need for manual *scripts*. Generated tokens are valid for 8 hours and include the user’s identification, email, name, and *role* *claims*. This security implementation is robust and follows industry best practices, protecting system data and access.

The testing strategy was structured in three complementary levels, as recommended by Sommerville (2011), to ensure software quality. Domain unit tests were performed, covering entities and value objects, totaling 154 tests. These tests validated behaviors such as the creation and immutability of value objects (CPF, CNPJ, Document, Contact, Address), the state transitions of entities (activation, deactivation, confirmation, and cancellation of sales), the business rules that protect domain invariants, and expected failure cases. All 154 tests were passed, confirming the robustness of the business logic.

Additionally, 58 application unit tests were executed to validate the application layer services, using the xUnit *framework* and the Moq library for creating stubs. The services tested were ClienteService, ProdutoService, EstoqueService, VendaService, and RecomendacaoService. These tests verified scenarios such as the rejection of duplicate documents in customer registration, the correct propagation of domain errors (like insufficient stock when confirming a sale), the behavior in case of integration failures with Recombee, and the correct return of quantities to stock upon cancellation of a previously confirmed sale. All 58 tests were approved, ensuring the integrity and expected behavior of the application services. The distribution of these tests by service is presented in Table 3.

Table 3. Distribution of unit tests by service

Service	Number of Tests
ClientService	11
ProductService	11
StockService	14
SaleService	17
RecomendacaoService	5
Sum	58

Source: Original research results

Table 3, which details the distribution of unit tests by service, offers a quantitative view of test coverage in the application layer. It is observed that `VendaService` has the highest number of tests (17), which is expected, given the complexity and criticality of sales operations, involving multiple business rules and interactions with other layers and services (such as inventory and recommendations). `EstoqueService` also presents a significant number of tests (14), reflecting the importance of inventory control for business operations. `ClienteService` and `ProdutoService` have 11 tests each, covering CRUD functionalities and specific validations for each entity. `RecomendacaoService`, with 5 tests, focuses on validating integration with Recombee and handling failure scenarios, as the complex recommendation logic is delegated to the external service. The total of 58 unit tests in the application layer, added to the 154 domain tests, totaling 212 unit tests, demonstrates a commitment to software quality and the rigorous application of software engineering practices, as advocated by Sommerville (2011). This comprehensive test coverage is a crucial outcome for the reliability and maintainability of the Nexsell system.

Automated integration tests were developed and executed in the Teste.Integration project, using the xUnit *framework*, directly against the Recombee API. The quality of the recommendations was measured using Precision@K and Recall@K metrics, widely recognized in the literature of recommender systems (Ricci, Rokach, and Shapira, 2015). For each of the 55 evaluation scenarios, the *train/test split* technique was applied, where four purchases were used for training and two were retained as *ground truth* for evaluation, with K=5 for the metrics. This methodology allowed simulating the behavior of real customers and evaluating the recommendation algorithm’s capability in different contexts of preference and purchase history.

The results obtained from the integration with Recombee and the evaluation of the recommendations are presented in Table 4.

Table 4. Precision@5 and Recall@5 by customer profile

Profile	N	Precision@5	Recall@5
Sportsman	11	34,50%	86,4%
Video game player	11	12,70%	31,8%
Home Office	11	7,3%	18,2%
Reader	11	34,5%	86,4%
Programmer	11	7,3%	18,2%

Source: Original research results

Table 4 presents the results of the Precision@5 and Recall@5 metrics for each of the five simulated customer profiles, as well as an overall total. This data is fundamental to understanding the performance of the recommender system in different consumption contexts. The `Athlete` and `Reader` profiles demonstrated the best results, with Precision@5 of 34.5% and Recall@5 of 86.4%. These values are notably close to the theoretical ceiling of 40% for Precision@5 and 100% for Recall@5 in the evaluated scenario (with 2 ground truth items and K=5), indicating high assertiveness of the algorithm for profiles with homogeneous purchasing behavior within a single category. This finding corroborates the literature that points to the effectiveness of collaborative filtering in identifying similarity patterns among users with well-defined preferences (Ricci, Rokach, and Shapira, 2015).

In contrast, the `Programmer` and `HomeOffice` profiles registered the lowest performances, with Precision@5 of 7.3% and Recall@5 of 18.2%. This significant difference is explained by the heterogeneous purchasing behavior of these profiles, where the *ground truth* items belonged to distinct categories. Collaborative filtering algorithms, although powerful, tend to have more difficulty in making accurate recommendations when user interests are very diversified or distributed across unrelated categories, as observed by Ricci, Rokach, and Shapira (2015). In these cases, the algorithm may tend to focus on one of the categories, retrieving only one of the relevant items in most scenarios.

The `Gamer` profile showed intermediate performance, with Precision@5 of 12.7% and Recall@5 of 31.8%. This result can be attributed to the overlap of two categories (Computing and Electronics) in the purchase history, which, although less homogeneous than the `Reader` and `Sportsman` profiles, is less dispersed than the `Programmer` and `HomeOffice` profiles. The algorithm demonstrated greater assertiveness in Computing items than in Electronics items for this profile, resulting in partial hits in most scenarios.

The overall average Precision@5 of 19.3% and Recall@5 of 48.2% positions the system within the expected performance range for the data configuration used and for small catalogs. These results demonstrate that the recommender system, even with synthetic data, is capable of generating relevant suggestions, with performance varying according to the complexity of consumption patterns. Figure 3 presents these same results in a graphical format, facilitating visual comparison between profiles.

Figure 3. Precision@5 and Recall@5 comparison by customer profile in the 55 integration test scenarios with Recombee

Source: Original research results

Figure 3 offers a clear and concise visual representation of the results presented in Table 4, allowing for a quick comparison of the performance of the Precision@5 and Recall@5 metrics between different customer profiles. The horizontal bar graph visually highlights the superiority of the `Esportista` (Sports Enthusiast) and `Leitor` (Reader) profiles in both metrics, with the Precision@5 and Recall@5 bars reaching significantly longer lengths compared to other profiles. This visualization reinforces the conclusion that the homogeneity of customer purchasing behavior directly impacts the effectiveness of the recommendation system. The `Gamer` profiles show intermediate performance, with moderately long bars, while `HomeOffice` and `Programador` (Programmer) exhibit the shortest bars, graphically illustrating the algorithm’s difficulty in handling more heterogeneous interests. The graphical representation facilitates the identification of the recommendation system’s strengths and weaknesses in different scenarios, serving as a valuable tool for interpreting results and communicating findings. Visual clarity is essential for managers and developers to quickly understand where the system performs best and where there is room for optimization, for example, through recommendation diversification strategies for profiles with broad interests.

The automated execution of the 55 test scenarios with the calculation of metrics per profile can be verified in Figure 4, which shows the output of the integration test.

Figure 4. Output of the integration test showing the Precision@5 and Recall@5 metrics calculated for the 55 scenarios evaluated by customer profile

Source: Original research results

Figure 4 presents the textual output of the integration test, which validates the data synchronization process with Recombee and the evaluation of recommendations. The sequence of messages “[0/4] Ensuring property schema in Recombee… OK Schema verified (name, category, price).”, “[1/4] Registering products in Recombee (sequential)… OK 50 products registered.”, “[2/4] Sending training interactions (sequential)… OK 220 interactions (55 clients × 4 purchases).”, “[3/4] Waiting for Recombee processing (3 s)…”, and “[4/4] Obtaining and evaluating recommendations… OK 55 scenarios evaluated.” demonstrates the complete and successful flow of test execution. This output confirms that the system performed all necessary steps for the validation of the recommendation module, from data schema verification to product registration, sending training interactions, and finally, obtaining and evaluating recommendations for all 55 scenarios. The “METRICS PER PROFILE” section in Figure 4 replicates the data from Table 4, providing direct proof of the computation of these metrics during test execution. The line “TOTAL 55 19.3% 48.2%” summarizes the overall performance, corroborating the aggregated results. This evidence of automated test execution is crucial for the credibility of the results, as it shows that the evaluation process is replicable and consistent, a cornerstone of modern software engineering (Sommerville, 2011).

The validation of the minimum thresholds established (Precision@5 ≥ 5% and Recall@5 ≥ 10%), confirmed by the xUnit *framework*, is presented in Figure 5.

Figure 5. Final result of the integration tests execution, confirming approval at the minimum established thresholds

Source: Original research results

Figure 5 displays the final result of the integration tests execution, providing explicit confirmation that the system met the minimum performance criteria established. The message “Test Execution Successful. Total tests: 1 Passed: 1 Total time: 1.2245 Minutes Test.Integration test net8.0 success (74.4s)” indicates that the main integration test was completed successfully, without failures. The line “Test Summary: total: 1; failed: 0; successful: 1; skipped: 0; duration: 74.3s” reinforces the total approval. This formal validation, performed by a testing *framework*, is a critical outcome that attests to the functionality and quality of the recommendation module. Passing the minimum thresholds of Precision@5 (≥ 5%) and Recall@5 (≥ 10%) demonstrates that the system is capable of generating recommendations with an acceptable level of relevance, even in the most challenging scenarios. Although the thresholds are relatively low, they serve as a basis to ensure that the algorithm is functioning correctly and that the technical integration with Recombee was successful. For small businesses, having a system that generates recommendations, even with variable performance, already represents a significant advancement compared to the absence of such functionality, opening doors for customer experience personalization and potential sales increase.

The results demonstrate a satisfactory performance for recommender systems applied to small catalogs. Ricci, Rokach, and Shapira (2015) highlight that the performance of recommender systems varies significantly with the volume of interactions available per user, which explains the performance difference observed between the evaluated profiles. Profiles with homogeneous behavior (Reader and Sports Enthusiast) achieved Precision@5 of 34.5% and Recall@5 of 86.4%, values close to the theoretical ceiling of 40% for the evaluated scenario. In these cases, the collaborative filtering algorithm accurately identified the similarity between users and concentrated recommendations on the correct items. In most scenarios for these profiles, both ground truth items were recovered among the top five suggestions, achieving Recall@5 = 100% individually. This suggests that for companies with a well-defined market niche or customers with consistent purchasing patterns, the Nexsell system can offer highly effective recommendations, driving cross-selling and customer satisfaction.

The Gamer profile achieved a Recall@5 of 31.8%, an intermediate performance explained by the overlap of two categories in the purchase history. The algorithm demonstrated greater assertiveness in Informatics items than in Electronics items, resulting in partial hits in most scenarios. This indicates that, for customers with interests in adjacent categories, the system can still generate relevant recommendations, but with slightly lower precision. To optimize performance in these cases, future improvements could explore category weighting or the incorporation of more item attributes to refine content-based filtering.

The Programmer and HomeOffice profiles registered the lowest Recall@5 (18.2% each). In these profiles, the two ground truth items belonged to distinct categories, requiring the system to be correct in both simultaneously. Recombee’s recommendations tended to focus on one of the categories, retrieving only one of the two relevant items in most cases. This behavior is consistent with the literature, which indicates greater difficulty for collaborative filtering algorithms when the user has heterogeneous interests between poorly related categories (Ricci, Rokach, and Shapira, 2015). For companies with customers of very diverse interests, the practical implication is that the system may need more interaction data or hybrid recommendation strategies to improve the diversity and relevance of suggestions. The overall average Precision@5 of 19.3% and Recall@5 of 48.2% position the system within the expected performance range for the data configuration used, confirming the viability of the solution for small catalogs.

In addition to automated tests, the recommendation module was functionally validated through the GET `/api/recomendacoes/cliente/{clienteId}/completo` *endpoint* of the REST API. This *endpoint* returns the recommended products enriched with the system’s registration data, including product name, category, and unit price. The *endpoint*’s response for a specific client, as illustrated in Figure 6, confirms that the complete integration flow is operational: purchases registered in the system are automatically sent to Recombee, which processes the history and returns personalized suggestions in real time.

Figure 6. Response of the REST API recommendations endpoint returning personalized products for a customer based on their purchase history.

Source: Original research results.

Figure 6 displays the JSON response of the `/api/recomendacoes/cliente/{clienteId}/completo` *endpoint*, demonstrating the functional validation of the intelligent recommendations module. The response body shows a list of JSON objects under the key “recommendacoes”, where each object represents a suggested product. For each product, the `produtoId`, `produtoNome`, `categoria`, and `precoUnitario` are returned. For example, the first recommendation is a “Logitech MX Master Wireless Mouse” from the “Peripherals” category with a unit price of 599.9. Other recommendations include a “Dell XPS Notebook” from the “Computers” category and a “Logitech Mechanical Keyboard” also from “Peripherals”. This enriched data structure is crucial for the *frontend*, as it allows recommendations to be displayed completely and usefully for the client, without the need for additional calls to the *backend* to obtain product details. The presence of different categories in the recommendations (Peripherals, Computers) suggests that the algorithm is considering a variety of products, although diversification can be a challenge for heterogeneous profiles, as discussed previously. The functional validation of the *endpoint* is a practical result that confirms the system’s ability to deliver personalized suggestions in real-time, an artificial intelligence feature that can transform the shopping experience in small businesses, making them more competitive by offering a service similar to that of large *e-commerces*.

In summary, the Nexsell system represents a technological solution that integrates operational control and data intelligence in an accessible way for small businesses. The adoption of Domain-Driven Design and Clean Architecture principles, along with a comprehensive testing strategy, ensured the construction of a robust, maintainable, and extensible system. The integration with external services such as ViaCEP and Recombee demonstrated the system’s ability to leverage advanced technologies without incurring the complexity of developing them from scratch. The results of the recommendation module evaluation, although with synthetic data, confirmed the algorithm’s effectiveness in identifying consumption patterns and generating relevant suggestions, especially for customer profiles with homogeneous interests. Resilience against external failures, ensured by the isolation of integrations, is a crucial architectural outcome that protects core business operations.

The main methodological limitation identified was the use of synthetic data for the evaluation of recommendations. Although this approach was sufficient to validate the technical integration and functioning of the algorithm, it does not replace an evaluation with real operational data in a production environment. Real data could offer additional *insights* into performance under real-world usage conditions, including user interaction with recommendations and the impact on business metrics. As future work, it is suggested to validate the system with real operational data in a production environment, expand the reporting module with recommendation performance indicators (e.g., click-through rate, recommendation conversion rate), and evaluate the impact of suggestions on customer purchasing behavior over time. These future steps would be crucial to refine the system and maximize its value for small and medium-sized enterprises.

4. Conclusion

It is concluded that the objective was achieved, presenting the development of Nexsell, an intelligent sales management system that integrates traditional operational functionalities with personalized recommendation features. The solution proved to be accessible and robust, optimizing operations and enhancing the customer experience in small and medium-sized enterprises through suggestions based on their purchase history. The adopted architecture, based on Domain-Driven Design and Clean Architecture, ensured the construction of a maintainable, extensible, and resilient system, with successful integrations to external services such as ViaCEP and Recombee. Automated tests confirmed the robustness of the business logic and the effectiveness of the integration. The recommendation module, even with synthetic data, presented an average Precision@5 of 19.3% and Recall@5 of 48.2%, with superior performance for customer profiles with homogeneous purchasing behavior, validating the system’s ability to generate relevant suggestions and boost sales.

The main methodological limitation of this work lies in the use of synthetic data for the evaluation of recommendations. Although this approach was crucial for validating the technical integration and functioning of the algorithm, it does not fully reflect performance in a production environment with real data, which could offer more in-depth *insights* into user interaction and the impact on business metrics. As future studies, we suggest validating the system with real operational data, expanding the reporting module to include recommendation performance indicators, such as click-through and conversion rates, and evaluating the impact of suggestions on customer purchasing behavior over time. These next steps are essential for the continuous improvement of Nexsell and the maximization of its market value.

Bibliographic References

EVANS, E. Domain-Driven Design: Tackling Complexity in the Heart of Software. Boston: Addison-Wesley, 2003.

GIL, A. C. Como elaborar projetos de pesquisa. 4. ed. São Paulo: Atlas, 2002.

LAUDON, K. C.; LAUDON, J. P. Sistemas de Informação Gerenciais: Administrando a Empresa Digital. 17. ed. São Paulo: Pearson; Porto Alegre: Bookman, 2023.

OPENAPI INITIATIVE. A Short History of the OpenAPI Initiative and the OpenAPI Specification. 2015. Disponível em: https://www.openapis

RICCI, F.; ROKACH, L.; SHAPIRA, B. Recommender Systems Handbook. 2. ed. New York: Springer, 2015.

RICHARDS, M.; FORD, N. Fundamentos de Arquitetura de Software: Uma Abordagem de Engenharia. São Paulo: Novatec Editora, 2020.

SOMMERVILLE, I. Engenharia de Software. 9. ed. São Paulo: Pearson Prentice Hall, 2011.

VERNON, V. Implementing Domain-Driven Design. Boston: Addison-Wesley, 2013.

Article originating from the Final Course Work of the Specialization in Software Engineering of the MBA USP/Esalq

To learn more about the course, click here and access the MBX Academy platform