Developer Guide

Relevant source files

The following files were used as context for generating this wiki page:

• MercaditoMovil.Infrastructure/Tools/Scripts/create_csvs.py
• MercaditoMovil.Infrastructure/Repositories/CsvUserRepository.cs
• Mercadito.Domain/Entities/User/User.cs
• MercaditoMovil.Application/Service/AuthService.cs
• Mercadito.Domain/Interfaces/Interface1.cs
• MercaditoMovil.Application/Features/UserManagement/IAuthService.cs
• MercaditoMovil.Application/Validators/UserValidator.cs
• MercaditoMovil/Controllers/LoginController.cs
• MercaditoMovil/Program.cs
• MercaditoMovil/Views/Form1.cs
• MercaditoMovil/Views/Form1.Designer.cs

This guide provides a technical overview of the MercaditoMovil project, detailing its architecture, data management strategy, and core functionalities. The application is a Windows Forms desktop client built with .NET, following a layered architecture. Its primary data persistence mechanism is a set of CSV files, which are initially generated by a Python script.

The core of the application is divided into Domain, Application, Infrastructure, and Presentation (WinForms) layers. This separation of concerns allows for modularity and maintainability. The guide will cover the data seeding process, the structure of the data files, the domain model, and the application services responsible for business logic like user authentication.

Project Architecture

The project is structured into distinct layers, each with a specific responsibility. This design promotes loose coupling and separation of concerns. The main layers are Presentation (WinForms UI), Application (Business Logic), Domain (Entities & Interfaces), and Infrastructure (Data Access & Tools).

The diagram below illustrates the dependency flow between the major components of the application.

Component Interfaces

The architecture heavily relies on interfaces to decouple the application logic from the infrastructure details.

The diagram below shows the key service and repository interfaces and their concrete implementations.

Data Management

Data persistence is handled via CSV files located in the MercaditoMovil.Infrastructure/DataFiles/ directory. A Python script is provided to generate the initial dataset.

Data Seeding

The create_csvs.py script is responsible for creating and populating the CSV files used by the application. It generates data for users, markets, producers, and products. This script has no external dependencies and resolves paths relative to its own location, ensuring it can be run from anywhere.

The script creates the following directory structure and files:

• DataFiles/
  • GeoLocations/locations.csv (optional input)
  • Markets/markets.csv
  • People/users.csv
  • Producers/producers.csv
  • Catalogs/product_catalog.csv
  • Commerce/producer_products.csv

Sources: MercaditoMovil.Infrastructure/Tools/Scripts/create_csvs.py:16-30

Data Schemas

The following ER diagram shows the relationships between the main data entities as defined by the CSV generation script.

users.csv

This file stores user account information.

Column	Description
UserId	Unique user identifier (e.g., USR-XXXXXXXX)
Username	Login username
Password	User's password (stored as plain text)
FirstName	User's first name
FirstLastName	User's first last name
SecondLastName	User's second last name
NationalId	National identification number
Email	User's email address
Phone	User's phone number
Address	User's physical address
Province	Province of residence
Canton	Canton of residence
District	District of residence
MarketId	Foreign key to markets.csv

Sources: MercaditoMovil.Infrastructure/Tools/Scripts/create_csvs.py:162-164

Data Access Layer

The CsvUserRepository class is the concrete implementation of IUserRepository. It handles all read/write operations for the users.csv file.

• Reading: The GetByUsername method performs a sequential scan of the CSV file. It uses Microsoft.VisualBasic.FileIO.TextFieldParser to correctly handle comma-delimited fields that may be enclosed in quotes. It skips the header row and iterates through each record to find a matching username (case-insensitive).
• Writing: The Add method appends a new user record to the file. It ensures the directory and file exist, creating them and writing the header if necessary. It manually quotes and escapes each field to maintain CSV integrity.

Sources: MercaditoMovil.Infrastructure/Repositories/CsvUserRepository.cs:34-62, 70-107

Domain Model

The core business entities and their contracts are defined in the Mercadito.Domain project.

User Entity

The User class represents an application user. It is a sealed class with read-only properties, ensuring immutability after creation. The constructor handles null inputs by defaulting them to empty strings, except for MarketId which defaults to "MKT-000".

Property	Type	Description
UserId	string	Unique identifier
Username	string	Login username
Password	string	User's password
FirstName	string	User's first name
LastName1	string	User's first last name
LastName2	string	User's second last name
NationalId	string	National ID
Email	string	Email address
Phone	string	Phone number
ExactAddress	string	Full street address
Province	string	Province
Canton	string	Canton
District	string	District
MarketId	string	Associated market ID

Sources: Mercadito.Domain/Entities/User/User.cs:8-49

Application Logic

The MercaditoMovil.Application project contains the business logic, services, and validators.

Authentication Service (AuthService)

AuthService implements the IAuthService interface and orchestrates the login and registration processes. It depends on IUserRepository to interact with the data store and uses UserValidator to check inputs.

Login Flow

The login process validates inputs, retrieves the user by username, and compares the password.

Registration Flow

The registration process validates the new user's data, checks for duplicate usernames, and then persists the new user.

Input Validation (UserValidator)

The static class UserValidator centralizes validation logic for user-related operations.

• ValidateLogin(username, password, out message): Checks that the username and password are not null or whitespace.
• ValidateRegister(user, out message): Checks that the user object is not null and that required fields (Username, Password, FirstName, NationalId, Email) are not empty.

Sources: MercaditoMovil.Application/Validators/UserValidator.cs:11-44

Presentation Layer

The user interface is a Windows Forms application.

• Entry Point: The application starts execution in Program.cs, which initializes and runs Form1.
• Main Form: Form1 is the main window of the application. Its designer file is Form1.Designer.cs.
• Controller: The LoginController acts as a bridge between the view (Form1) and the AuthService. It decouples the UI from the application's business logic, making the system more modular.

Sources: MercaditoMovil/Program.cs:11-13, MercaditoMovil/Views/Form1.cs, MercaditoMovil/Controllers/LoginController.cs:12

Summary

The MercaditoMovil project is a well-structured desktop application that demonstrates a clean, layered architecture. It uses CSV files for data storage, with a dedicated Python script for data seeding. The separation of concerns via Domain, Application, and Infrastructure layers, combined with the use of interfaces, makes the codebase modular and testable. The core functionality currently exposed revolves around user authentication, with clear flows for login and registration managed by the AuthService.