Ports & Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
The Ports & Interfaces layer serves as the architectural boundary of the SSA Consulta Rapida C++ application. It defines the abstract contracts through which the core logic interacts with external systems, such as the operating system, persistent storage, and external web services. By adhering to a hexagonal architecture approach, this project ensures that the domain and query logic remain decoupled from specific implementation details like Qt, SQLite, or the filesystem.
Sources: AGENTS.md:12-19, src/ports/IExternalCommandPort.h:11-23
Architectural Overview
The project enforces a strict separation of concerns where the src/ports directory contains interfaces for communication between layers. These interfaces are prohibited from depending on Qt, ensuring that the core logic is portable and testable. Implementations of these ports are located in the src/infra or src/platform directories.
The diagram above illustrates how the src/ports layer acts as an abstraction between the business logic and the concrete infrastructure.
Sources: AGENTS.md:14-19, AGENTS.md:27-28
External Command Port
The IExternalCommandPort defines how the application triggers external actions. This is primarily used for deep-linking into the SAM (Sistema de Apoio à Manutenção) web interface and handling file exports.
Key Operations
The interface mandates the following capabilities:
- SAM Integration: Opening the home page or a specific SSA record by ID.
- System Commands: Opening filesystem paths or executing arbitrary commands with parameters.
- Data Export: Exporting a selection of records formatted as a list of key-value maps.
| Method | Purpose | Implementation Location |
|---|---|---|
openSamHome() | Opens the SAM portal root URL | DesktopExternalCommandPort.cpp |
openSsa(string) | Navigates to a specific SSA record | DesktopExternalCommandPort.cpp |
exportSelection(vector) | Processes selected rows for external output | DesktopExternalCommandPort.cpp |
Sources: src/ports/IExternalCommandPort.h:11-21, src/platform/DesktopExternalCommandPort.h:11-18
User Preferences Store
The IUserPreferencesStore interface manages the persistence of application state and user configuration. It utilizes a Snapshot pattern to pass data between the store and the application.
Data Structure: UserPreferencesSnapshot
The snapshot captures the entire state of the user's interface configuration.
| Field | Type | Description |
|---|---|---|
visibleColumns | std::vector<std::string> | Keys of columns currently visible in the table |
columnWidths | std::map<std::string, int> | Width in pixels for specific columns |
pageSize | int | Number of rows per page (default: 100) |
theme | std::string | UI theme identifier (e.g., "dark", "system") |
detailsVisible | bool | Visibility state of the side details panel |
excludeScaSesSte | bool | Toggle for default filtering of specific status codes |
Sources: src/ports/IUserPreferencesStore.h:11-25, src/domain/SsaTypes.h:15-18
Lifecycle and Flow
The MainViewModel coordinates the loading and saving of preferences through the port. To optimize performance, saving is often debounced using a timer.
The sequence shows the asynchronous, debounced saving mechanism used to persist state.
Sources: src/presentation/MainViewModel.cpp:244-290, src/ports/IUserPreferencesStore.h:27-32
Data Transfer and Domain Types
Interfaces in the Ports layer rely on types defined in src/domain/SsaTypes.h. These types ensure that data is passed across boundaries in a structured manner without leaking implementation details.
Pagination and Search Contracts
The application uses specific structures to request and receive data across the repository port (implied by ISsaRepository used in smoke tests):
- SsaPageRequest: Contains
pageIndex,pageSize,searchText, and sorting specifications (SortSpec). - SsaPageResult: Returns a
vector<SsaRecord>, the total row count, and pagination metadata.
struct SortSpec {
std::string columnKey{"numero_ssa"};
bool ascending{false};
bool statusLast{true};
};
struct SsaPageRequest {
std::size_t pageIndex{0};
std::size_t pageSize{100};
std::string searchText;
std::map<std::string, std::string> columnFilters;
bool excludeScaSesSte{true};
SortSpec sort;
};
Sources: src/domain/SsaTypes.h:103-134, tests/smoke/PresentationSmokeTest.cpp:18-35
Conclusion
The Ports & Interfaces in SSA Consulta Rapida C++ provide a robust abstraction layer that facilitates the project's goal of modularity. By isolating side effects—such as OS commands and disk I/O—behind these interfaces, the system allows for easier unit testing (via fakes and mocks) and ensures that the core domain remains independent of the Qt framework and external infrastructure changes.