Hi! If you are reading this, you are probably trying to understand how this software works internally. **Good for you!**
In general, I try to write [DOXYGEN](https://www.doxygen.nl/index.html) comments to explain what each function does. *However*, this does not help newcomers understand how a program's source code is organized (or how it *works*). For this reason, I will try to explain what each folder & class does in this document.
Think of this file as an *introductory document* for colaborators, hackers and geeks.
Of course, if this documentation is not clear enough (or you are a good writer), you are very welcome to fork this project, modify it & create a [pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
### But I'm not a coder!
Don't worry! You can help this project by reporting bugs, providing ideas, creating translations, writing about it in your blog/vlog, etc. You can also [donate](https://www.paypal.com/donate?hosted_button_id=XN68J47QJKYDE) through PayPal!
## Software architecture
Before explaining what each module does, please take a look at the "high-level" architecture of Serial Studio. If you have any doubts, feel free to use any of the support channels provided by the maintainers of the project.
Since there are over 30 source files that compromise this project (not including any libraries or the [UI/QML](https://github.com/Serial-Studio/Serial-Studio/tree/master/assets/qml) part), it is important to keep the files organized in subdirectories corresponding to the their respective high-level functionalities.
- The **CSV** directory contains the `CSV::Export` module and the `CSV::Player` functionality.
- The **IO** folder contains the `IO::Manager`, handlers for device data sources `IO::DataSources::Serial`, `IO::DataSources::Network`&`IO::Console` data handler.
- A `JSON::Frame` object represents the title, groups & datasets of a single frame. The frame object is generated by combining information received from the connected device and the JSON map file.
- The `JSON::Group` class represents a group object. Groups contain a title and an array of datasets.
- The `JSON::Dataset` class represents a dataset object. Datasets contain a title, a value and the units in which the dataset is measured (e.g. volts, meters, seconds, etc).
- The `JSON::Generator` class receives data from the `I/O Manager` and uses the JSON map file to generate a JSON document that is used to create a `Frame` object.
-`JSON::FrameInfo` (JFI) implements a structure that contains a JSON frame, the RX date/time and the frame ID number.
- The `JSON::Editor` provides the necessary logic to allow users to build JSON files directly from the user interface.
- The **Misc** directory contains several utility classes, such as the global `Misc::TimerEvents` class, which is used to update the UI elements at a given frequency. Or the `Misc::ModuleManager`, which is used to initialize the application.
- The **Plugins** folder contains a simple `Plugins::Server` that allows Serial Studio to interact with external applications/plugins.
- The **UI** folder contains the QML data provider, which provides QML-friendly functions so that the QML user interface can represent the lastest `JSON::Frame` object.
- The **Widgets** directory contains several `QWidget` based controls adapted to be used with a QML interface, most of the user interface elements that display data are implemented here. Most of the widgets are implemented with the help of [Qwt](https://qwt.sourceforge.io/).
The user interface is written in [QtQuick/QML](https://doc.qt.io/qt-5/qtquick-index.html). You can find the "source code" of the user interface in the `$PROJ_ROOT/assets/qml` folder.
## Coding styles
If possible, please follow the coding conventions defined in the `.clang-format` file. If you are as lazy as me, you can download and install [clang-format-all](https://github.com/eklitzke/clang-format-all) and run the following command before making a commit:
> `clang-format-all src`
This will apply the style defined in the `.clang-format` file recursively to all C++ headers and sources in the project. No need to worry about writing "ugly" code anymore!
**IMPORTANT! Please write explanatory comments to document your changes!**
