Development Guidelines & Rules
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The SSA Consulta Rapida Cpp project is a modular C++/Qt/QML implementation of the SSA search interface. The primary objective is to maintain a high-performance, maintainable codebase that preserves the functional contracts of its predecessor while enforcing a strict separation of concerns. These guidelines ensure that the core business logic remains independent of the graphical user interface and infrastructure details.
Sources: AGENTS.md:3-7, README.md:5-7
The project follows a specific architectural philosophy that prioritizes concrete implementations over excessive design or defensive coding. It mandates the use of C++20 standards, RAII, and value semantics to ensure memory safety and predictable behavior.
Sources: AGENTS.md:10-15, AGENTS.md:32-35
Architectural Constraints
Mandatory Layer Separation
The project enforces a strict directory structure to isolate responsibilities. This prevents "leaking" UI dependencies into the business logic or database logic.
| Layer | Responsibility | Constraints |
|---|---|---|
src/domain | Types and business rules | No Qt, No SQLite, No Filesystem |
src/query | Parser and SQL compilation | No Qt, No direct DB access |
src/ports | Communication interfaces | No Qt |
src/infra | SQLite, Persistence, Preferences | Specific to implementation details |
src/platform | OS-dependent commands | Handles external calls |
src/presentation | Qt ViewModels | Mediates between Core and QML |
app/desktop/qml | Visual interaction | No SQL, No business rules |
Sources: AGENTS.md:18-24, README.md:118-124
Data Flow Architecture
The data flow is designed to be unidirectional from the UI through ViewModels to the Query Service. Results are paged at the database level to prevent excessive memory usage.
The diagram above illustrates how user requests are transformed into SQL queries and returned as paged data.
Sources: src/presentation/MainViewModel.cpp:211-230, src/query/SqlQueryBuilder.cpp:168-185
Coding Standards
Core Requirements
- Language: C++20 is required.
- Character Set: All code, comments, and technical documentation must use ASCII.
- Semantics: Use RAII and value semantics. Variables and parameters should be
constby default. - Error Handling: Errors should be treated at functional boundaries rather than every few lines. Empty catch blocks or silent fallbacks are strictly prohibited.
Sources: AGENTS.md:32-36, AGENTS.md:28-29
Prohibited Practices
- God Classes: Avoid massive classes with multiple responsibilities.
- Generics: Avoid "helper" or "utility" classes without clear ownership.
- Memory Filtering: Filtering must happen in the database; do not load entire tables into memory.
- Qt Dependency: Layers like
domain,query, andportsmust remain free of Qt includes.
Sources: AGENTS.md:26-31
Query and Persistence Logic
SQL Query Construction
Queries are built using the SqlQueryBuilder. It enforces paged results using LIMIT and OFFSET and supports complex filtering including REGEXP and LIKE patterns.
Configuration Defaults
Key domain constants are defined to ensure consistency across the application.
| Constant | Value | Description |
|---|---|---|
kDefaultPageSize | 100 | Default number of records per page |
kMinPageSize | 10 | Minimum allowed page size |
kMaxPageSize | 500 | Maximum allowed page size |
kDefaultExcludeScaSesSte | true | Default filter for specific situations |
kDefaultDetailsPanelWidth | 360 | Default UI width for details |
Sources: src/domain/SsaTypes.h:15-23
Build and Validation Rules
The project uses CMake presets for standardized builds. Continuous Integration and local development must adhere to the following validation steps:
- Configuration:
cmake --preset dev - Build:
cmake --build --preset dev - Tests:
ctest --preset dev - Formatting:
clang-format --dry-run(when available) - Linting:
qmllintfor QML files
Sources: AGENTS.md:46-51, CMakeLists.txt:1-10
Testing Strategy
Testing is divided by layer and responsibility:
- Core/Query/Infra: Tested using Catch2.
- Presentation: Tested using QtTest.
- Startup: Validated via Smoke QML tests.
- Contract Validation: Tests must validate the actual functional contract, not just verify that the application doesn't crash.
Sources: AGENTS.md:40-44, CMakeLists.txt:103-125
Conclusion
The development guidelines for SSA Consulta Rapida Cpp are centered on strict modularity and high-standard C++20 practices. By isolating the domain logic from the Qt-based presentation layer and enforcing paged database interactions, the system maintains high performance and testability. Developers must ensure all new features respect the established boundaries and pass the mandatory validation presets.