CLI Options & Application Startup

Relevant source files

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

• src/platform/StartupOptions.cpp
• src/platform/StartupOptions.h
• app/desktop/main.cpp
• src/platform/AppPaths.cpp
• src/platform/AppPaths.h
• src/presentation/MainViewModel.cpp

Introduction

The SSA Consulta Rapida application utilizes a structured startup sequence to initialize its environment, parse command-line interface (CLI) options, and wire together its modular architecture. The startup process is designed to be flexible, supporting standard desktop execution alongside automated "smoke" testing modes that involve timed exits and screenshot capture.

Sources: app/desktop/main.cpp:25-50, AGENTS.md:15-23

At high level, the entry point in main.cpp orchestrates the creation of the QGuiApplication, resolves system paths, initializes infrastructure components (SQLite repository and JSON preferences), and sets up the QML engine for the presentation layer.

Sources: app/desktop/main.cpp:25-70

CLI Options Architecture

The application uses the QCommandLineParser to define and process arguments passed during execution. These arguments allow users to override default file paths and control automated behaviors.

Command-Line Arguments

The following table summarizes the available CLI options defined in the application entry point:

Option	Argument	Description	Default Value
project-root	path	Root directory used for relative default paths.	Current working directory
db	path	Path to the SQLite database file.	data/ssas.db under project root
config-dir	path	Directory for configuration and preference files.	config under project root
smoke-exit-ms	ms	Automatically exits the application after N milliseconds.	N/A
screenshot	path	Captures a screenshot of the startup window and exits.	N/A
open-preferences	N/A	Opens the preferences dialog before a smoke screenshot.	N/A

Sources: app/desktop/main.cpp:38-51, src/platform/StartupOptions.cpp:11-25

Startup Options Logic

The ssa::platform::StartupOptions class acts as a data transfer object (DTO) that extracts values from the parser and applies default fallback logic if paths are missing.

Application Startup Sequence

The startup sequence follows a dependency injection pattern where infrastructure and query services are instantiated before the UI presentation layer.

Component Initialization

The initialization flow follows these steps:

1. Application Setup: Sets the application name, organization, and global UI font (Arial/Helvetica).
2. Infrastructure: Initializes the SqliteSsaRepository using the path resolved from CLI options.
3. Business Logic: Creates the SsaQueryService which consumes the repository.
4. Presentation: Instantiates the MainViewModel, which acts as the central coordinator for the UI.
5. QML Engine: Loads the QML modules and sets the MainViewModel as an initial property.

Sources: app/desktop/main.cpp:26-68, src/presentation/MainViewModel.cpp:17-30

Dependency Flow

The following class diagram illustrates the relationships between the components initialized during startup:

Automated "Smoke" Features

The application includes specialized logic for automated testing and documentation generation via the CLI.

Screenshot and Timed Exit

If the --screenshot or --smoke-exit-ms flags are detected, the application initiates a QTimer::singleShot to perform actions after the UI has settled (1200ms delay for screenshots).

• Screenshot Logic: Grabs the root window content, optionally invokes the openPreferencesForSmoke QML method, and saves the image to the specified path.
• Timed Exit: Parses the millisecond value and schedules a QCoreApplication::quit.

Sources: app/desktop/main.cpp:71-105

Error Handling

The startup process includes several critical failure points:

• Object Creation: If the QML engine fails to create objects, the application exits with code 1.
• Screenshot Failure: If the window cannot be grabbed or the file cannot be saved, the application exits with code 2.

Sources: app/desktop/main.cpp:69-70, app/desktop/main.cpp:80-92

Summary

The startup and CLI system in SSA Consulta Rapida C++ provides a robust bridge between environment configuration and the application's modular core. By utilizing StartupOptions and AppPaths, the system ensures that data paths (SQLite) and configuration paths (JSON preferences) are resolved consistently across different operating systems and execution contexts.