Architecture Overview

Relevant source files

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

• AGENTS.md
• app/desktop/main.cpp
• CMakeLists.txt
• src/domain/SsaTypes.h
• src/presentation/MainViewModel.h
• src/presentation/MainViewModel.cpp
• src/query/SqlQueryBuilder.cpp

The SSA Consulta Rapida Cpp project is a modular C++20 application utilizing Qt 6 and QML. It is designed to replace a Python-based GUI while maintaining functional contracts. The system is built on a strict separation of concerns, ensuring that the core domain and query logic remain independent of the Qt framework and infrastructure details.

Sources: AGENTS.md:3-8, README.md:3-5

Layered Architecture

The project enforces a strict directory structure to decouple business logic from presentation and infrastructure:

Layer	Responsibility	Constraints
src/domain	Core types and business rules.	No Qt, No SQLite, No Filesystem.
src/query	Parser and SQL query compilation.	No Qt, No direct DB access.
src/ports	Communication interfaces between layers.	No Qt.
src/infra	SQLite persistence and preference storage.	Specific to storage implementation.
src/presentation	Qt ViewModels and Models.	Coordinates state for QML.
app/desktop	QML UI and application entry point.	No SQL or business logic.

Sources: AGENTS.md:13-20

Dependency Flow

The following diagram illustrates the dependency relationships between the various libraries defined in the system. Presentation depends on core and infra, while core remains isolated.

Data Flow and Query Execution

The application uses an asynchronous data flow to keep the UI responsive. When a user triggers a search, the MainViewModel builds a request object which is then processed by the SsaQueryService (within ssa_core) using QtConcurrent.

Persistence and Configuration

The application manages two primary types of data: the SSA records stored in a SQLite database and user preferences stored in a JSON file.

User Preferences

Preferences include UI state such as themes, column visibility, and window sizing. These are managed by the IUserPreferencesStore interface.

Preference	Type	Default / Constraints
pageSize	Integer	Min: 10, Max: 500, Default: 100
detailsPanelWidth	Integer	Min: 280, Max: 680, Default: 360
theme	String	e.g., "dark", "system"
excludeScaSesSte	Boolean	Default: true

Sources: src/domain/SsaTypes.h:13-18, src/presentation/MainViewModel.cpp:234-255

SQLite Integration

The system uses a SqlQueryBuilder to generate paged SQL queries. It handles filtering, negation (using ! or -), and special exclusion rules like the excludeScaSesSte flag, which filters out specific situations (SCA, SES, STE) by default.

Sources: src/query/SqlQueryBuilder.cpp:125-135, src/query/SearchParser.cpp:25-30

Main Entry and Initialization

The application initialization occurs in app/desktop/main.cpp. It parses command-line arguments to locate the database and config directories, sets up the DI (Dependency Injection) container by instantiating shared pointers for services, and loads the QML engine.

// app/desktop/main.cpp:55-61
const auto repository = std::make_shared<ssa::infra::sqlite::SqliteSsaRepository>(
    std::filesystem::path{options.databasePath.toStdString()});
const auto service = std::make_shared<ssa::query::SsaQueryService>(repository);
const auto commands = std::make_shared<ssa::platform::DesktopExternalCommandPort>();
const auto preferences = std::make_shared<ssa::infra::preferences::JsonUserPreferencesStore>(
    std::filesystem::path{paths.preferencesFile().toStdString()});
ssa::presentation::MainViewModel mainViewModel(service, commands, preferences);

Sources: app/desktop/main.cpp:55-61

Conclusion

The architecture emphasizes modularity and technical constraints, such as the prohibition of Qt dependencies in the domain and query layers. By utilizing asynchronous execution and a clear separation between presentation and infrastructure, the system provides a robust framework for high-performance data consultation.

Sources: AGENTS.md:22-30, README.md:88-94