Introduction & Overview
Relevant source files
The following files were used as context for generating this wiki page:
SSA Consulta Rapida Cpp is a modular desktop application built with C++20 and Qt 6/QML, designed to provide a high-performance interface for querying and managing "SSA" (Solicitação de Serviço de Apoio) records. The project is a modern evolution of a previous Python-based version, prioritizing architectural separation and value semantics while preserving the original functional contracts and appearance.
Sources: README.md:1-5, AGENTS.md:3-5
The system operates as a data-centric viewer that interacts with a SQLite database, implementing sophisticated search parsing and paginated data retrieval. Its primary objective is to maintain a clean core independent of the UI framework (Qt) and infrastructure (SQLite), ensuring that business logic and query compilation remain decoupled from visual decisions.
Sources: AGENTS.md:6-10, README.md:104-109
Architectural Design
The project strictly adheres to a layered architecture to ensure modularity and testability. This separation is enforced through project rules that prohibit Qt dependencies within the domain and query layers.
Layered Structure
| Layer | Responsibility | File Path Reference |
|---|---|---|
| Domain | Core types, business rules, and constants. No Qt/SQL dependencies. | src/domain |
| Query | Search term parsing and SQL compilation. | src/query |
| Ports | Interface definitions for cross-layer communication. | src/ports |
| Infra | SQLite implementation, persistence, and user preferences. | src/infra |
| Presentation | Qt-based ViewModels and models (MOC-enabled) for QML. | src/presentation |
| Application | Entry point and dependency injection. | app/desktop |
| UI | QML-based visual components and layouts. | app/desktop/qml |
Sources: AGENTS.md:15-22, CMakeLists.txt:33-85
Data Flow and Dependency Graph
The following diagram illustrates the unidirectional flow of data and the dependency relationships between the major system modules.
The diagram shows how the UI interacts with ViewModels, which in turn utilize core query services to fetch data from the infrastructure layer, all while sharing common Domain types.
Sources: AGENTS.md:15-22, CMakeLists.txt:33-85
System Entry and Configuration
The application is initialized in main.cpp, where dependency injection is performed to wire the infrastructure and query services into the presentation layer.
Startup Sequence
- Command Line Parsing: The app accepts arguments for database paths, project roots, and configuration directories.
- Infrastructure Setup: Initializes the SQLite repository and the JSON-based preference store.
- Core Wiring: Creates the
SsaQueryServiceandDesktopExternalCommandPort. - ViewModel Initialization: The
MainViewModelis instantiated with these services and injected into theQQmlApplicationEngineas an initial property.
Sources: app/desktop/main.cpp:24-65
Command Line Options
| Option | Description |
|---|---|
--db <path> | Path to the SQLite database (defaults to data/ssas.db). |
--project-root <path> | Root directory used for resolving default paths. |
--config-dir <path> | Directory for storing user preferences and logs. |
--smoke-exit-ms <ms> | Automatically exits the application after a specified duration (for testing). |
--screenshot <path> | Captures a window screenshot and exits. |
Sources: app/desktop/main.cpp:32-45, README.md:92-96
Core Data Structures
The application relies on standardized structures in the ssa::domain namespace to communicate state and requests across layers.
Search and Pagination
- SsaPageRequest: Contains
pageIndex,pageSize,searchText,columnFilters, andSortSpec. - SsaPageResult: A container for the retrieved
SsaRecordvector and thetotalRowscount for pagination. - SortSpec: Defines the sorting behavior, including the
columnKey, direction (ascending), and astatusLastflag for specific business logic sorting (e.g., pushing 'STE' status to the end).
Sources: src/domain/SsaTypes.h:111-136
Search Parsing Logic
The SearchParser and SqlQueryBuilder transform user input into structured SQL. The parser supports several match modes:
Visual representation of the search syntax parsing logic used to generate dynamic SQL queries.
Sources: src/query/SearchParser.cpp:26-52, src/query/SqlQueryBuilder.cpp:27-46
Technology Stack
The project utilizes a modern C++ stack designed for cross-platform compatibility and performance.
- Language: C++20 (Standard required, extensions off).
- UI Framework: Qt 6.6+ (Core, Gui, Qml, Quick, QuickControls2).
- Database: SQLite3.
- Build System: CMake 3.24+ with Ninja.
- Testing: Catch2 (Core/Infra), QtTest (Presentation), and Smoke QML tests.
Sources: CMakeLists.txt:1-12, README.md:12-23, AGENTS.md:53-56
Summary
SSA Consulta Rapida Cpp provides a robust framework for rapid data querying by combining a strictly decoupled C++ core with a dynamic QML front-end. By leveraging asynchronous query execution via QtConcurrent and a sophisticated SqlQueryBuilder, it ensures the UI remains responsive even when handling complex filters and large datasets.
Sources: src/presentation/MainViewModel.cpp:240-270, src/query/SqlQueryBuilder.cpp:138-164