Application Paths Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Application Paths Integration system in the SSA Consulta Rapida Cpp project is responsible for managing and resolving filesystem locations for critical application resources, including the SQLite database and user preference files. It ensures that the application behaves predictably across different operating systems (Windows, macOS, and Linux) by centralizing path logic and allowing overrides via command-line arguments.
This system acts as a foundational layer, providing the necessary filesystem context for the infrastructure components such as the SqliteSsaRepository and the JsonUserPreferencesStore. By decoupling path resolution from business logic, the project maintains high modularity as defined in the project's architectural rules.
Sources: src/platform/AppPaths.h, app/desktop/main.cpp:51-65, AGENTS.md:16-24
Core Components and Architecture
The path management logic is primarily encapsulated in the AppPaths class, which stores the project root and configuration directory. This data is typically populated during application startup within the main entry point.
Path Resolution Logic
The application uses a combination of hardcoded defaults and dynamic overrides. During startup, the QCommandLineParser processes arguments that define where the application should look for its data.
The diagram above shows how command-line options flow into the AppPaths utility to initialize backend storage.
Sources: app/desktop/main.cpp:51-60, src/platform/AppPaths.cpp:18-20
Key Classes and Methods
| Class | Method | Description |
|---|---|---|
AppPaths | projectRoot() | Returns the base directory for the project, often used for default data relative paths. |
AppPaths | configDir() | Returns the directory where configuration and state files are stored. |
AppPaths | preferencesFile() | Returns the full path to ssa_cpp_preferences.json within the config directory. |
StartupOptions | fromParser() | Static factory that extracts path-related strings from command-line arguments. |
Sources: src/platform/AppPaths.h:9-14, src/platform/AppPaths.cpp:18-20, app/desktop/main.cpp:51-52
Filesystem Interaction and Configuration
The application interacts with specific files located in the paths resolved by the AppPaths class. The most significant file is the JSON preferences store, which persists the UI state.
Configuration Files
| File Name | Purpose | Default Location |
|---|---|---|
ssas.db | Main SQLite database containing SSA records. | data/ relative to project root or --db path. |
ssa_cpp_preferences.json | Stores theme, density, column widths, and visible columns. | Inside --config-dir. |
Sources: README.md:88-91, src/platform/AppPaths.cpp:19, src/presentation/MainViewModel.cpp:249-265
Implementation Detail: Path Construction
The AppPaths implementation uses Qt's QDir::filePath to ensure platform-independent path joining.
// src/platform/AppPaths.cpp:18-20
QString AppPaths::preferencesFile() const {
return QDir(configDir_).filePath("ssa_cpp_preferences.json");
}
Sources: src/platform/AppPaths.cpp:18-20
Integration with Infrastructure
The resolved paths are injected into infrastructure services during the dependency injection phase in main.cpp.
The sequence diagram illustrates the lifecycle of path information from startup to service instantiation.
Sources: app/desktop/main.cpp:51-62
Default Path Behaviors by Platform
According to the project documentation, if paths are not explicitly provided via command-line arguments, the application defaults to specific directories:
- macOS: Uses the application bundle path or specific homebrew paths for development.
- Linux: Often defaults to
$HOME/.config/ssa-consulta-rapida-cpp. - Windows: Often uses
$LOCALAPPDATA\SSA_Consulta_Rapida_Cpp.
Sources: README.md:73-86, packaging/macos/README.md
Summary
The Application Paths Integration ensures that SSA Consulta Rapida Cpp can locate its SQLite data and user preferences across diverse environments. By utilizing the AppPaths class and StartupOptions, the system provides a clean interface for the rest of the application to access the filesystem, facilitating both production deployment and testing scenarios (such as smoke tests with fixture databases).
Sources: app/desktop/main.cpp:51-65, tests/integration/SqliteRepositoryTests.cpp:21-40