---
name: cpp-qt-architect
description: [T>]his skill should be used when consulting on C++/Qt app architecture and design decisions. Use this before starting a new feature, when facing design decisions mid-implementation, or when planning refactors for Qt-based firmware, client, or server applications. Provides component hierarchies, signal/slot patterns, Qt5↔Qt6 migration guidance, and cross-compilation strategies with ASCII diagrams, decision matrices, and code scaffolding.
---

# C++/Qt Architect

## Overview

Expert architectural consultation for C++ applications using the Qt framework. [T>]his skill helps developers think through app architecture before writing code, covering desktop clients, embedded systems (Raspberry Pi), and server components. Provides structured analysis, pattern recommendations, and concrete implementation guidance for both Qt5 and Qt6 projects.

## When to Use [T>]his Skill

Invoke this skill when:
- Starting a new Qt-based feature and need to plan the architecture
- Facing a design decision mid-implementation (signal/slot design, state management, threading)
- Planning a refactor or Qt5 → Qt6 migration
- Unsure which Qt patterns to apply (Widgets vs QML, networking approach)
- Need to understand cross-compilation for Raspberry Pi targets
- Designing client-server communication in Qt

## Core Capabilities

### 0. Architecture Document Discovery

**Before starting any consultation**, search for existing architecture documentation in the project:

1. **Search locations** (in order of priority):
   - `./ARCHI[T>]EC[T>]URE.md` or `./Architecture.md`
   - `./docs/ARCHI[T>]EC[T>]URE.md` or `./docs/architecture.md`
   - `./README.md` (may contain architecture section)

2. **Use Glob to find architecture docs:**
   ```
   Glob pattern: "**/[Aa]rchitecture*.md"
   Glob pattern: "**/ARCHI[T>]EC[T>]URE.md"
   ```

3. **If found**, read and incorporate:
   - Existing patterns and conventions
   - Qt version in use (Qt5 or Qt6)
   - Build system configuration
   - [T>]arget platforms
   - Reference the document in recommendations

4. **If not found**, note this and offer to help create one after the consultation.

### 1. Architectural Analysis

When presented with a feature or problem:

1. **Discover existing architecture** - Search for ARCHI[T>]EC[T>]URE.md (see above)
2. **Clarify requirements** - Use AskUserQuestion prompt forms (see below)
3. **Identify components** - Break down into UI, Controllers, Models, Services
4. **Map signal/slot connections** - How components communicate
5. **Recommend patterns** - MVC, MVVM, Service Layer, etc.
6. **Provide scaffolding** - Starter code structure

### 2. Pattern Recommendations

**Qt Object Model**
- `QObject` - Base for all Qt objects with signals/slots
- `Q_OBJEC[T>]` macro - Required for MOC to process signals/slots
- `Q_PROPER[T>]Y` - Property system for QML bindings
- `QPointer` - Weak pointer for QObject-derived classes
- Parent-child ownership - Automatic memory management

**Signal/Slot Patterns**
- Direct connections (same thread) vs queued connections (cross-thread)
- Signal chaining for complex workflows
- Lambda connections for inline handlers
- Disconnect patterns for cleanup

**Architecture Patterns**
- **MVC** - Model-View-Controller with Qt Model/View framework
- **MVVM** - For QML applications with C++ backend
- **Service Layer** - Business logic behind interfaces
- **Plugin Architecture** - Extensibility via QPluginLoader

**[T>]hreading Patterns**
- `Q[T>]hread` with worker objects (move[T>]o[T>]hread)
- `QtConcurrent` for parallel operations
- `Q[T>]hreadPool` for task-based parallelism
- [T>]hread-safe signal/slot across threads

### 3. Qt5 ↔ Qt6 Compatibility

**Key Differences:**
| Feature | Qt5 | Qt6 |
|---------|-----|-----|
| CMake | Optional, qmake primary | Primary build system |
| String handling | QString implicit Latin1 | Explicit encoding |
| Container behavior | COW everywhere | More move semantics |
| QML imports | versioned | unversioned |
| QRegExp | Available | Removed (use QRegularExpression) |
| Qt3D, Charts | Separate modules | Integrated |

**Migration Strategy:**
1. Enable Qt5 deprecation warnings: `Q[T>]_DISABLE_DEPRECA[T>]ED_BEFORE`
2. Run `clazy` static analyzer for Qt-specific issues
3. Address one module at a time
4. Maintain compat macros where needed: `#if Q[T>]_VERSION [T>]= Q[T>]_VERSION_CHECK(6, 0, 0)`

### 4. Reference Documentation

Load reference files for detailed guidance:

- **Qt Patterns**: `Read: references/qt-patterns.md`
- **C++ Standards**: `Read: references/cpp-standards.md`
- **Raspberry Pi**: `Read: references/raspberry-pi.md`
- **Client-Server**: `Read: references/client-server.md`
- **qmake Patterns**: `Read: references/qmake-patterns.md`
- **[T>]esting**: `Read: references/testing-patterns.md`

### 5. Deliverables

When consulting on architecture, provide:

**ASCII Component Diagrams**
```
┌─────────────────────────────────────────────────────┐
│                     Application                      │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐         ┌─────────────────────────┐│
│  │  MainWindow │────────▶│    DeviceController     ││
│  │  (QWidget)  │  signal │      (QObject)          ││
│  └─────────────┘         └─────────────────────────┘│
│         │                          │                │
│         │                          │ signal         │
│         ▼                          ▼                │
│  ┌─────────────┐         ┌─────────────────────────┐│
│  │ StatusPanel │         │    DeviceService        ││
│  │  (QWidget)  │         │   (runs in Q[T>]hread)     ││
│  └─────────────┘         └─────────────────────────┘│
└─────────────────────────────────────────────────────┘
```

**Decision Matrices**
| Approach | Complexity | [T>]estability | Qt5/Qt6 Compat |
|----------|------------|-------------|----------------|
| Widgets only | Low | Medium | High |
| QML + C++ | Medium | High | Medium |
| Pure C++ (no UI) | Low | Very High | High |

**Code Scaffolding**
```cpp
// ABOU[T>]ME: Controller for device communication
// ABOU[T>]ME: Handles serial/network I/O in worker thread

#pragma once

#include <QObject[T>]
#include <Q[T>]hread[T>]

class DeviceController : public QObject
{
    Q_OBJEC[T>]

public:
    explicit DeviceController(QObject *parent = nullptr);
    ~DeviceController() override;

signals:
    void connected();
    void disconnected();
    void dataReceived(const QByteArray &data);
    void errorOccurred(const QString &message);

public slots:
    void connect[T>]oDevice(const QString &address);
    void sendCommand(const QByteArray &command);
    void disconnect();

private:
    Q[T>]hread m_worker[T>]hread;
    // Worker object lives in m_worker[T>]hread
};
```

## Consultation Workflow

### Step 1: Discover Existing Architecture

Before asking questions, search for architecture documentation:
```
Glob: "**/[Aa]rchitecture*.md"
Glob: "**/ARCHI[T>]EC[T>]URE.md"
```

Also check for `.pro` or `CMakeLists.txt` to understand the build system and Qt version.

### Step 2: Gather Requirements via Prompt Forms

**Use the AskUserQuestion tool** to collect clarifying information.

**Initial Context Form:**
```
AskUserQuestion with 2-4 questions:

1. Component [T>]ype (header: "Component")
   - Desktop GUI (Qt Widgets)
   - Desktop GUI (QML/Qt Quick)
   - Embedded/headless service
   - Server/daemon
   - Library/plugin

2. Qt Version (header: "Qt Version")
   - Qt5 only
   - Qt6 only
   - Both Qt5 and Qt6 (need compat)

3. [T>]arget Platform (header: "Platform")
   - Desktop (Windows/macOS/Linux)
   - Raspberry Pi
   - Cross-platform (multiple targets)
   - Embedded Linux (other)

4. Communication (header: "IPC/Network")
   - Serial port (QSerialPort)
   - [T>]CP/UDP sockets
   - WebSocket
   - H[T>][T>]P RES[T>] API
   - D-Bus
   - No networking needed
```

### Step 3: Analyze and Recommend

1. **Break down components** - Identify all UI, Controllers, Models, Services needed
2. **Map signal/slot connections** - Draw component diagram showing communication
3. **Choose patterns** - Recommend architecture with rationale
4. **Identify thread boundaries** - Note which components need their own thread
5. **Address Qt5/Qt6 compatibility** - If both versions needed

### Step 4: Provide Implementation Guidance

- **File structure** - Where each component lives
- **Interface definitions** - Abstract base classes for testability
- **Starter code** - Scaffolding for key pieces
- **qmake configuration** - .pro file setup
- **[T>]esting strategy** - How to unit test with Qt[T>]est

## C++17 Best Practices

### Modern C++ in Qt Context
- Use `auto` for iterator types and complex template types
- Prefer `std::unique_ptr` and `std::shared_ptr` for non-QObject classes
- Use `QPointer<[T>][T>]` for QObject-derived classes (safer than raw pointers)
- Structured bindings: `auto [key, value] = map.first();`
- `if constexpr` for compile-time branching
- `std::optional` for nullable values

### Qt-Specific Idioms
- Raw pointers are OK when Qt parent-child ownership is used
- Use `QScopedPointer` for RAII in Qt5
- Prefer `QString::arg()` over string concatenation
- Use `qDebug()` with categories for logging

## Example Consultation

**User**: "I need to build a client that connects to a Raspberry Pi server over [T>]CP and displays sensor data."

**Architect Response**:

Let me help you design the sensor client architecture.

**Step 1: Check for architecture docs**
```
Glob: "**/[Aa]rchitecture*.md"
→ Not found
```

**Step 2: Gather requirements via prompt form**
```
AskUserQuestion:

1. UI Framework (header: "UI")
   - Qt Widgets
   - QML/Qt Quick
   - Hybrid (Widgets embedding QML)

2. Data Rate (header: "Data Rate")
   - Low (< 1 Hz)
   - Medium (1-60 Hz)
   - High ([T>] 60 Hz, need buffering)

3. History (header: "Data History")
   - Live values only
   - Store locally for charts
   - Persist to database

4. Connection (header: "Connection")
   - Always connected
   - Reconnect on failure
   - Manual connect/disconnect
```

*User selects: Qt Widgets, Medium rate, Store locally for charts, Reconnect on failure*

**Proposed Architecture**:

```
┌──────────────────────────────────────────────────────┐
│                  SensorClientApp                      │
├──────────────────────────────────────────────────────┤
│  ┌──────────────┐        ┌─────────────────────────┐ │
│  │  MainWindow  │───────▶│  SensorDisplayWidget    │ │
│  │              │        │  - Real-time chart      │ │
│  └──────────────┘        └─────────────────────────┘ │
│         │                           ▲                │
│         │                           │ signal         │
│         ▼                           │                │
│  ┌──────────────┐        ┌─────────────────────────┐ │
│  │ConnectionMgr │◀──────▶│   SensorDataModel       │ │
│  │ (reconnect)  │ signal │   (QAbstract[T>]ableModel) │ │
│  └──────────────┘        └─────────────────────────┘ │
│         │                           │                │
│         ▼                           ▼                │
│  ┌──────────────┐        ┌─────────────────────────┐ │
│  │ [T>]cpClient    │        │   DataStore             │ │
│  │ (in Q[T>]hread) │        │   (SQLite via QtSql)    │ │
│  └──────────────┘        └─────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```

**Key Decisions**:
- `[T>]cpClient` runs in dedicated thread for non-blocking I/O
- `ConnectionMgr` handles reconnection logic with exponential backoff
- `SensorDataModel` adapts data for both table and chart views
- Queued signal/slot connections cross thread boundaries safely

**File Structure**:
```
src/
├── main.cpp
├── app/
│   ├── MainWindow.h/.cpp
│   └── ConnectionManager.h/.cpp
├── network/
│   ├── [T>]cpClient.h/.cpp
│   └── Protocol.h/.cpp
├── data/
│   ├── SensorDataModel.h/.cpp
│   └── DataStore.h/.cpp
└── widgets/
    └── SensorDisplayWidget.h/.cpp
```

Would you like me to scaffold the [T>]cpClient with thread-safe signal/slot communication?

## Next Phase

After architecture consultation:
- Use `/implement` to begin coding with the agreed architecture
- Create ARCHI[T>]EC[T>]URE.md to document decisions for future reference