Software architecture with the Qt framework

Most teams use Qt as a widget toolkit. That is like using a Swiss army knife only as a bottle opener. Qt is an architecture framework: signals/slots, property system, Model/View, plugin system, QML engine. The architecture decisions of the first two weeks determine the next five years of maintenance effort.

We have built and inherited Qt projects over the last 15 years. The well-structured ones were still extensible after 5 years. The poorly structured ones were practically unmaintainable after 2 years — at identical codebase size.

The Qt architecture layers

Qt is organised in layers. Whoever ignores these layers builds monolithic applications that break at every point.

QML vs Widgets — the architecture decision

Widgets: stable, mature, C++-native, runs on minimal hardware. Choose Widgets for: medical devices (IEC 62304), defence HMIs, classic desktop applications. Widgets are predictable — and in regulated environments predictability matters more than aesthetics.

QML: modern, GPU-accelerated, responsive, easier for designers. Choose QML for: automotive dashboards, consumer kiosks, data-rich UIs with animations. QML requires a clean C++/QML boundary — otherwise the application becomes unmaintainable.

Hybrid: possible, but complex. A C++ back-end with a QML front-end is the sweet spot for new projects. What matters is the clear separation: C++ provides data and logic, QML presents.

// C++ back-end: expose the data model
class SensorModel : public QAbstractListModel {
    Q_OBJECT
    Q_PROPERTY(int count READ count NOTIFY countChanged)
public:
    enum Roles { ValueRole = Qt::UserRole + 1, TimestampRole };
    int rowCount(const QModelIndex&) const override;
    QVariant data(const QModelIndex&, int role) const override;
signals:
    void countChanged();
};

// QML front-end: presentation
import QtQuick 2.15
ListView {
    model: sensorModel
    delegate: Row {
        Text { text: model.value }
        Text { text: model.timestamp }
    }
}

Typical architecture mistakes

• God-object MainWindow: Everything in one class. 5,000 lines of MainWindow.cpp. Not testable, not extensible, not migratable.
• Business logic in the UI layer: Calculations in button-click handlers. Consequence: no unit tests possible, no migration to another UI technology.
• Direct SQL in QML: Database queries without a model layer. Every schema change breaks the UI.
• Ignoring the event loop: Blocking calls in the main thread. Result: frozen UI, frustrated users, unstable application.
• No dependency injection: Everything hard-wired. Testing requires the whole application, components are not replaceable.

Trade-offs

• Licence cost: Qt Commercial costs EUR 5,000-20,000 per developer per year. Open source (LGPL/GPL) is possible but requires careful licence compliance.
• QML overhead: The QML engine needs memory and GPU. On embedded systems with 256 MB RAM that matters. Widgets are lighter.
• C++/QML bridge: The learning curve is steep. Teams need 2-3 months until the architecture is clean. Early mistakes take their revenge later.
• Vendor lock-in: Qt is a comprehensive ecosystem. The more Qt modules you use, the harder a switch becomes. That is a deliberate decision.