Update README and add project/repo overview doc

Signed-off-by: falkTX <falktx@falktx.com>

README.md

@@ -1,10 +1,71 @@
 # DISTRHO Cardinal
 
-*Cardinal, bring forth the Rack!*
+*Cardinal, the Rack!*
 
-WORK IN PROGRESS - nothing to see here
+**! THIS PROJECT IS A WORK IN PROGRESS !**
 
-Just an experiment to see how far we can go about a VCV plugin version that is opensource and uses original VCV source core directly.
-Maybe it will work, maybe not, hard to say at this point.
+This is a [DPF-based](https://github.com/DISTRHO/DPF/) plugin wrapper around [VCV Rack](https://github.com/VCVRack/Rack/),
+using its code directly instead of forking the project.  
+The target is to have a proper, self-contained, fully free and open-source plugin version of Rack.  
+See [project overview](doc/OVERVIEW.md) document for an overview on how the project source code is structured.
 
-This is a DPF'ied build of [VCVRack](https://github.com/VCVRack/Rack), allowing it to be used as an audio plugin.
+Because it is using DPF, Cardinal already supports LV2 and VST2 with an extra JACK standalone mode if self-compiled.  
+A VST3 version is in progress, already part of the build but still experimental.
+
+**The project should be considered in alpha state at the moment.**
+
+## Current status
+
+Most of the features already work, you can assume things work in general except when stated otherwise.  
+Currently the following features are known NOT to work:
+
+- Clipboard (copy&paste)
+- Clock related triggers in built-in MIDI modules
+- Export/import module selection
+- File dialogs triggered by module right-click menus
+
+### Current builds
+
+If you want to try this out early, checkout the GitHub actions tab.  
+There is absolutely no warranty, use at your own risk and all that...
+
+## Why
+
+Cardinal was created first and foremost as a way to have Rack as a **proper open-source audio plugin**.  
+A proper audio plugin should be self-contained as much as possible, as to not interfere with the DAW/Host.
+Loading external modules clearly goes against this idea.  
+Not to mention being **open-source**, otherwise we are at the mercy of the wishes of a company for what we can and cannot do,
+which is not something Cardinal's authors wish to abide by.
+
+A self-contained plugin can't be overstated, as DLL/shared-object symbol conflicts can trigger hard-to-debug crashes.  
+While Rack tries to mitigate this as much as possible, crashes due to conflicting modules have already been seen in v2 builds.  
+On the other side, Cardinal redefines class and function names as needed to avoid as many conflicts as possible.
+
+Support for ARM and non-mainstream platforms (for example BSD) has also always been missing from the official Rack since the start.  
+While we can patch the Rack free version to support these, same can't be done with VCV Rack Pro with it being a closed-source product.  
+The online library/store only supports a very specific set of platforms too,
+so non-supported platforms would need any 3rd-party modules to be manually compiled to make them usable.
+
+Unhappiness with the audio threading behaviour of Rack also plays a role.  
+Both audio and MIDI should be locked to the host audio thread as to minimize (or even altogether remove) latency and jitter.  
+The use of separate threads for MIDI is bad design, one that has been corrected in DAWs and JACK-MIDI for several years...  
+But Rack's use of RtMidi requires separate threading, so Cardinal does not use it.
+
+Other relevant reasons include:
+
+ - LV2 plugin version from the start
+ - Proper dark mode support
+ - Proper optimized build (because all code is compiled to a single file, we can use LTO over the whole thing)
+ - Removing online access from the plugin and included modules (no phone-home here!)
+ - Works as a test case for [DPF](https://github.com/DISTRHO/DPF/) and [Carla](https://github.com/falkTX/Carla/)
+ - It is fun :)
+
+## Vs. Rack Pro
+
+It needs to be said that Cardinal project and its author(s) do not wish anything bad to the original/official Rack project.  
+In fact, Cardinal wouldn't exist if not for Rack v2 release. (which has many needed things to make a plugin version work)
+
+Cardinal and Rack should be able to co-exist friendly and peacefully, as they clearly have different targets.  
+It is likely most people will prefer to use Rack Pro for its official support and its big module collection (including commercial ones).
+
+A feature comparison between Cardinal and Rack Pro can be seen [here](doc/DIFFERENCES.md).

doc/DIFFERENCES.md

@@ -42,4 +42,4 @@ Additionally, Cardinal contains the following built-in modules not present in th
  * Ildaeil Host
  * Host Parameters (24 host-exposed parameters as CV sources)
  * Host Time (play, reset, bar, beat, tick, bar-phase and beat-phase CV sources)
- * Host CV (for the CV IO variant, allows direct CV access to/from the DAW)
+ * Host CV (for the Raw-CV plugin variant, allows direct CV access to/from the DAW)

doc/OVERVIEW.md

@@ -0,0 +1,138 @@
+# PROJECT OVERVIEW
+
+This document describes how the DISTRHO Cardinal project is structured,
+so developers and interested third-parties can have an easier time contributing code and resources.
+
+On the root folder the following directories can be seen;
+
+ * carla
+ * deps
+ * doc
+ * dpf
+ * include
+ * lv2export
+ * patches
+ * plugins
+ * src
+
+Going through one by one in alphebetical order we have...
+
+## CARLA
+
+This directory contains the source code for Carla, a modular plugin host created by falkTX, the same author of Cardinal, DPF and many other projects.  
+Cardinal uses Carla as the base for all internal plugin hosting.  
+Being GPLv2+ the code license is compatible with Cardinal's GPLv3+.
+
+## DEPS
+
+3rd-party libraries build setup.  
+No actual code is hosted here, only a Makefile with steps for fetching source code and build it.  
+It basically overrides Rack's `dep.mk` things for a proper static build, and supporting more platforms.
+
+## DOC
+
+Here you find several files (like this one you are reading now) describing the Cardinal project.  
+It is intentionally not using something like GitHub Wiki so that rehosting does not lose any information.  
+Also allows for offline hosting and reading.
+
+## DPF
+
+This directory contains the source code for DPF, the plugin framework used by Cardinal that handles all the complex parts of plugin format support.  
+Implementing new plugin formats will be done here.
+
+## INCLUDE
+
+This directory contains special header files needed to build the original Rack code as required by Cardinal.  
+These headers are included before the official Rack ones, allowing us to override some implementation details.
+
+Additionally a few compatiblity headers are present, helping compile the code for more targets than officially supported in Rack.
+
+## LV2EXPORT
+
+An experiment for building individual Rack modules directly as LV2 plugins.  
+Only quick&dirty hacks so far, nothing interesting to see here yet.
+
+## PATCHES
+
+Public domain or CC0 licensed Rack patches, suitable for use in Cardinal.  
+Must be stored as plain text files (not zstd compressed) so they play nicely with git.
+
+## PLUGINS
+
+Module/Plugin related code and build setup.  
+Only Cardinal internal modules are hosted here, everything else uses a git submodule reference.
+
+See https://github.com/DISTRHO/Cardinal/discussions/28 for how to add more modules yourself.
+
+## SRC
+
+The main code for Cardinal, where the magic happens.  
+There are quite a few files here, so let's describe them in detail.
+
+### Cardinal / CardinalFX / CardinalSynth
+
+Directories that contain the supported Cardinal plugin variants.  
+Everything is a symlink except `DistrhoPluginInfo.h` (setting plugin info) and `Makefile` (set the unique name).
+
+The source code is the same for all the variants, with compiler macros used to tweak behaviour and IO count.
+
+### extra
+
+A few extra files for having access to a few utilities, code borrowed from Carla, which in turn borrowed it from JUCE.  
+The important one is `SharedResourcePointer`, as a way to easily manage a shared class lifecycle.
+
+### override
+
+Here are files that need to be customized by Cardinal, where it is not possible or wanted to use the originals from Rack.  
+This can be for disabling certain features, or simply tweaking engine/UI behaviour.  
+The filenames should be self-explanatory in what they override from Rack.
+
+### Rack
+
+A git submodule reference to the official Rack source code repository.
+
+### AsyncDialog.{cpp,hpp}
+
+Custom Cardinal code for showing a dialog in async fashion, optionally with a callback for when the user clicks "Ok".
+
+### CardinalPlugin.cpp
+
+The DSP/plugin side of the plugin, and also where the global/shared class lifecycle is managed.  
+This file implements the DPF `Plugin` class.
+
+### CardinalUI.cpp
+
+The UI-specific side of the plugin, dealing with e.g. Window events.  
+This file implements the DPF `UI` class.
+
+### Makefile
+
+The file describing rules for building Rack's code as a rack.a static library.
+
+### Makefile.cardinal.mk
+
+A makefile imported by each of Cardinal's plugin variants, which will build the actual plugin.  
+This same file is used by all variants, changing behaviour based on the plugin variant name.
+
+### PluginContext.hpp
+
+And handy but perhaps somewhat hacky `rack::Context` class extension, so internal modules can have direct access to DAW provided data.  
+This also extends the base `Plugin` and `UI` classes from DPF, to provide methods needed for Rack Audio/MIDI drivers.
+
+### PluginDriver.hpp
+
+Code that glues Rack Audio/MIDI drivers to the DPF side of things.
+
+### ResizeHandle.hpp
+
+A DPF-related Widget that does what you think it does.  
+Handles all the resizing for us.
+
+### template.vcv
+
+The default template patch as used by Cardinal
+
+### WindowParameters.hpp
+
+Defines a few methods for saving and restoring Rack Window state, in order to allow many Cardinal/Rack UIs to be open at once even though Rack `settings` is a global.  
+Used by `CardinalUI.cpp` and `override/Window.cpp`.