initial version of the software documentation

documentation.md

@@ -0,0 +1,116 @@
+# Documenation of our Program
+
+## Table of Contents
+1. [How to run the Software](#how-to-run-the-software)
+2. [How it works](#how-it-works)
+3. [Modules](#modules)
+3. [IPC](#ipc)
+
+## How to run the Software
+If you read the readme file, you will see the basic setup command in order to run the program.  
+You will need nodejs, the newer the better.  
+The software is tested with `nodejs-19`, `nodejs-20`, `nodejs-22` and `nodejs-24`.  
+These versions are confirmed to work with our software, but prior versions may work aswell.  
+To get nodejs, simply go to their [website](https://nodejs.org/en/download) and download whatever version you want and install it.  
+Afterward go into the directory of our program, and run the command `npm i`, this will install all the necessary libraries.  
+Next up you need to set up the .env file.  
+The file must contain your keys for the modules you want to use.  
+The .env file looks like this:
+```
+ASSEMBLYAI_API_KEY=wefhjhjakeghjkahejkghjkaegh
+GOOGLE_API_KEY=wefhjhjakeghjkahejkghjkaegh
+SAIA_API_KEY=wefhjhjakeghjkahejkghjkaegh
+```
+Note that if you write your module in the same format we did, then you will only need to supply the api keys to the individual services you will actually use.  
+If you dont want to use Assembly AI, you can for example just leave this row out of your .env, and the program will just work fine.  
+Only issue will be that it will throw an error if you do run the Assembly AI module anyways.  
+Once that is done, you can run the command `npm start` to actually start the program.  
+Alternatively you can double click the start.bat if you are on Windows for example.  
+
+## How it works
+Our software is fully modular, this means, every part can easily be edited, replaced, removed or added without needing to make many adjustments in the code.  
+The modules can be found under `./services/modules`  
+The Structure is as follows:
+Inside of `modules` are folders named after the general thing the module does.  
+For example, `transcription-remote`, this folder contains all the modules that do transcription on a remote service, such as assembly-ai for example.  
+Inside of these folders we put our modules.  
+The name of the folder and the module dont matter, as long as the structure is kept, and the module filename ends with .js, it will work.  
+The program iterates through all of the folders within `./services/modules`, and then iterates over each `.js` file within each of these folders, and then loads them into a specific map called `mapFunctions`.  
+This map is available ANYWHERE in the backend code, even within a module, which means, you can call a module, from within a module, from within a module, from within yet another module.  
+
+## Modules
+Building a new module is super easy, any idiot can get it done.  
+All you need to do is follow the previously mentioned structure.  
+When you have created your module file, the `.js` file, you simply copy paste this code snippet into it.  
+```js
+module.exports = {
+    name:"example", // Unique name for our function that will later be used to get the function from the map via "mapFunctions.get("example").function()"
+    type:"example-type", // value used to differentiate each module to order them in the UI
+    displayname:"Example", // The displayname used within the UI
+    async function(randomParameter){
+        // Here we put a simple console.log to show how the system works
+        // This function will be called from the @startup.js function in the utility folder
+        console.log(`\n------------\nThis is the example function called by the ${randomParameter} function\n------------\n`);
+    }
+}
+```
+If by this point, you cared enough to actually look at the code and the modules and so on, you might have spotted a file in `./services/modules/utility` called `example.js`.  
+This is a template file that you can just copy paste and use as a base for your new module.  
+It has the same exact code as mentioned right above.  
+Now as for how the code works.  
+Each module is essentially just a JSON object that is being exported, so that the main process can load it into the `mapFunctions` map.  
+the required fields are as follows
+- name: This field contains the internal name through which it will be called. It HAS TO BE unique.
+- type: This field contains the type of the module. Is it an LLM module, transcription module, or whatever.
+- displayname: This field contains the Displayname used in the UI.
+
+And lastly the function call.  
+This function call is what is being called by other functions, it is generally the main entrypoint for a module.  
+Sure, you can always set custom function names, but this is a general solution that works without having to manage function names.  
+You can always define custom functions inside your module that you call from the entrypoint function, but it is highly advised just to call the entrypoint function from outside of the module as it prevents headaches by just working as intended.  
+
+Note, there are also other module fields for specific module types, such as: 
+- description: Used by any module that needs to be shown on the UI, such as Transcription and LLM modules.
+- audioformat: Used by transcription modules to tell the audio extraction module what audio format to use.
+
+## IPC
+Our software is split up into 2 pieces, the main process (Backend) and the frontend.  
+The frontend is written in Electron, so it is essentially just a website.  
+This makes it relatively easy to edit the frontend.  
+But it comes with one downside, which is, the frontend and backend cant just directly communicate, you first need to set up an IPC channel between them.  
+As for the base functionality, all of this is already done.  
+The frontend gets a list of all the available LLM and Transcription modules sent by the backend on startup.  
+The JSON object for this information looks like this:
+```json
+{
+    "ai_modules":[
+        {"name": "Example", "displayname": "Example"}
+    ],
+    "transcription_modules":[
+        {"name": "Example", "displayname": "Example"}
+    ]
+}
+```
+The backend needs a specific set of informations from the frontend in order to start the pipeline.  
+The JSON for that looks like this:  
+```json
+{
+  "video": {
+    "module": "extraction-video-to-audio",
+    "inputVideoPath": "A:\\programing\\@projects\\video2document\\test\\unit\\testvideo.mp4"
+  },
+  "transcription": {
+    "module": "assembly"
+  },
+  "document": {
+    "module": "llm-saia_openai_gpt",
+    "type": "followup-report",
+    "outputType": "pdf"
+  }
+}
+```
+As you can see in this JSON object, each part specifies which module is being used for each step.  
+The module names are each the name field specified in the module itself.  
+As for the rest of the fields, they are pretty self explanatory except `document.type`, that is a predefined report type.  
+This is the minimum required setup for the currently implemented pipeline to work.  
+You can always add fields to it, but dont remove the ones from above.