# simulton/qschematic architecture

> Architecture diagram of the GitHub repository simulton/qschematic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simulton/qschematic
- Repository: https://github.com/simulton/qschematic

## Overview

##### Project Type and Purpose
- This is an open-source C++23 library (QSchematic) built on Qt6’s Graphics View Framework.
- A demo application lives in the `demo/` folder to showcase usage.

##### File-Structure Analysis
- Top-level modules:
- `qschematic/` – core library (commands, items, wire_system, scene, netlist generation, settings, utils)
- `demo/` – demo client application using the library (custom items, UI, netlist viewer)
- `CMakeLists.txt` and related build files – configure library and demo targets
- Key patterns:
- Command pattern (`qschematic/commands`) for undo/redo
- Factory pattern (`itemfactory`) for item creation
- Separation of rendering (scene/view) and data (netlist generator, model classes)
- External integration:
- Qt6 (GraphicsView, Widgets)
- GPDS for serialization (XML/YAML)

##### README Insights
- Confirms core components: Item base class, specialized Nodes/Wires, WireSystem, CommandStack, NetlistGenerator, Serialization modules.

##### Main Components
a. Components:
1. Client Application (e.g., `demo` executable)
2. QSchematic Library Modules:
– Scene & View (QGraphicsScene/QGraphicsView wrappers)
– Items (Item, NodeItem, WireItem, Connector, WidgetItem)
– Command Stack & Commands (add/move/remove/resize/rotate)
– WireSystem (connectable, net, manager, line/wire)
– Netlist Generator & Writers (in-memory, JSON, custom)
– Serialization (GPDS integration)
– Utilities & Settings
3. External Dependencies:
– Qt6 Framework
– GPDS (serialization)

b. Relationships & Interactions:
– Client calls Library API → creates Items via ItemFactory → adds to Scene
– User operations → Commands pushed to Command Stack → mutate Items in Scene → update WireSystem
– WireSystem Manager tracks nets and maintains connectivity
– NetlistGenerator traverses WireSystem & Items → produces netlist → hands off to JSONWriter or custom writer
– Serialization module uses GPDS to load/save scene + netlist templates

c. Architectural Patterns & Principles:
– Command Pattern for undo/redo
– Factory Pattern for extensibility of new Item types
– MVC-like separation: Scene/View (visual) vs. Model (netlist, items data)
– Plugin-style extensibility: subclass Item and Writer interfaces

d. Technologies & Frameworks:
– C++23, Qt6 Graphics View, Qt Widgets
– CMake build system with FetchContent / find_package integration
– GPDS for serialization; JSON writers

##### Essential Details to Capture
- The Command stack’s central role for undo/redo.
- The two‐way interaction between Items and WireSystem (items report connector changes).
- How netlist generation is decoupled via writer interfaces.
- Serialization plug-in capability via GPDS.
- CMake targets: static/shared library, demo executable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User Actions"]:::external

    %% Demo Application
    subgraph "Demo Application" 
        direction TB
        DemoApp["Client Application (demo.exe)"]:::demo
        CustomFactory["CustomItemFactory"]:::demo
        DemoCommands["Demo Commands"]:::demo
        NetlistViewer["Netlist Viewer"]:::demo
        DemoCommon["Demo Common Utils"]:::demo
    end

    %% QSchematic Library
    subgraph "QSchematic Library"
        direction TB

        subgraph "Scene & View"
            Scene["Scene"]:::library
            View["View"]:::library
        end

        subgraph "Items Module"
            ItemBase["Item Base & Hierarchy"]:::library
            NodeItem["NodeItem"]:::library
            WireItem["WireItem"]:::library
            Connector["Connector"]:::library
            WidgetItem["WidgetItem"]:::library
            ItemFactory["ItemFactory"]:::library
        end

        subgraph "Command Stack & Commands"
            CommandStack["CommandStack"]:::library
            SpecificCommands["Specific Commands"]:::library
        end

        subgraph "WireSystem"
            Connectable["Connectable"]:::library
            WireClass["Wire"]:::library
            Line["Line"]:::library
            Manager["Manager"]:::library
            Net["Net"]:::library
        end

        subgraph "Netlist Generation"
            NetlistGenerator["NetlistGenerator"]:::library
            JSONWriter["JSONWriter"]:::library
            NetlistDS["Netlist Data Structure"]:::library
        end

        subgraph "Serialization (GPDS)"
            Serialization["Serialization Module"]:::library
        end

        subgraph "Utilities & Settings"
            Settings["Settings"]:::library
            Utilities["Utilities"]:::library
        end
    end

    %% External Dependencies
    Qt6["Qt6 Framework"]:::external
    GPDS["GPDS (Serialization)"]:::external

    %% Connections
    DemoApp -->|"uses API"| ItemFactory
    DemoApp -->|"instantiates"| Scene
    DemoApp -->|"uses"| View
    User -->|"triggers"| CommandStack
    CommandStack -->|"executes"| SpecificCommands
    SpecificCommands -->|"mutates"| ItemBase
    ItemFactory -->|"creates"| ItemBase
    ItemBase -->|"includes"| NodeItem
    ItemBase -->|"includes"| WireItem
    ItemBase -->|"includes"| Connector
    ItemBase -->|"includes"| WidgetItem
    ItemBase -->|"reports to"| Connectable
    Connectable -->|manages| WireClass
    WireClass -->|uses| Line
    WireClass -->|tracked by| Manager
    Manager -->|groups| Net
    Manager -->|"provides"| NetlistGenerator
    ItemBase -->|provides data to| NetlistGenerator
    NetlistGenerator -->|"outputs"| JSONWriter
    NetlistGenerator -->|"populates"| NetlistDS
    Serialization -->|"loads/saves"| Scene
    Serialization -->|"integrates with"| GPDS
    Qt6 -->|"provides"| Scene
    Qt6 -->|"provides"| View
    Qt6 -->|"provides"| Widgets
    GPDS -->|"used by"| Serialization

    %% Demo internal connections
    CustomFactory -->|"extends"| ItemFactory
    DemoCommands -->|"examples of"| SpecificCommands
    NetlistViewer -->|"consumes"| NetlistDS
    DemoCommon -->|"helpers for"| DemoApp

    %% Click Events for QSchematic Library
    click Scene "https://github.com/simulton/qschematic/blob/main/qschematic/scene.hpp"
    click View "https://github.com/simulton/qschematic/blob/main/qschematic/view.hpp"
    click ItemBase "https://github.com/simulton/qschematic/blob/main/qschematic/items/item.hpp"
    click NodeItem "https://github.com/simulton/qschematic/blob/main/qschematic/items/node.hpp"
    click WireItem "https://github.com/simulton/qschematic/blob/main/qschematic/items/wire.hpp"
    click Connector "https://github.com/simulton/qschematic/blob/main/qschematic/items/connector.hpp"
    click WidgetItem "https://github.com/simulton/qschematic/blob/main/qschematic/items/widget.hpp"
    click ItemFactory "https://github.com/simulton/qschematic/blob/main/qschematic/items/itemfactory.hpp"
    click CommandStack "https://github.com/simulton/qschematic/blob/main/qschematic/commands/base.hpp"
    click SpecificCommands "https://github.com/simulton/qschematic/tree/main/qschematic/commands/"
    click Connectable "https://github.com/simulton/qschematic/blob/main/qschematic/wire_system/connectable.hpp"
    click WireClass "https://github.com/simulton/qschematic/blob/main/qschematic/wire_system/wire.hpp"
    click Line "https://github.com/simulton/qschematic/blob/main/qschematic/wire_system/line.hpp"
    click Manager "https://github.com/simulton/qschematic/blob/main/qschematic/wire_system/manager.hpp"
    click Net "https://github.com/simulton/qschematic/blob/main/qschematic/wire_system/net.hpp"
    click NetlistGenerator "https://github.com/simulton/qschematic/blob/main/qschematic/netlistgenerator.hpp"
    click JSONWriter "https://github.com/simulton/qschematic/blob/main/qschematic/netlist_writer_json.hpp"
    click NetlistDS "https://github.com/simulton/qschematic/blob/main/qschematic/netlist.hpp"
    click Settings "https://github.com/simulton/qschematic/blob/main/qschematic/settings.hpp"
    click Utilities "https://github.com/simulton/qschematic/blob/main/qschematic/utils.hpp"

    %% Click Events for Demo
    click DemoApp "https://github.com/simulton/qschematic/blob/main/demo/main.cpp"
    click CustomFactory "https://github.com/simulton/qschematic/blob/main/demo/items/customitemfactory.hpp"
    click DemoCommands "https://github.com/simulton/qschematic/blob/main/demo/commands/commands.hpp"
    click NetlistViewer "https://github.com/simulton/qschematic/blob/main/demo/netlist/viewer.hpp"
    click DemoCommon "https://github.com/simulton/qschematic/blob/main/demo/common/treemodel.hpp"

    %% Styles
    classDef library fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef demo fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000;
```
