Technical Documentation
This Wiki page provides an overview of the different forms of documentation that exist for the Open FinAL project.
The core of the software follows the Clean Architecture designed by Robert C. Martin. The Clean Architecture is a variant of the Onion Architecture, in which dependencies between software layers point inward as depicted in the layered circle in the figure below. The inner Entity layer represents the core entities and associated business rules that govern the entities. The Entity layer has no other dependencies. The Interactor layer contains application-specific business rules and depends on entities to complete the logic. The Technology Adapter layer represents interfaces and adapters that allow for highly adaptable software. The Technology Implementation layer represents actual frameworks (e.g., React) and drivers (e.g., MySQL database driver) that allow interactors and entities concrete implementation through the adapters.
Within this architecture, creating a new feature often requires the following work:
- Creating a New UI Page and/or New UI Component
- Creating a New Interactor file
- Creating a New Gateway
If you are only adding a new data provider then you may only need to create a new Gateway file.
In the software, the user interface (UI) is primarily contained in the View folder. The software relies on the Electron framework to allow software to run cross-platform. Electron utilizes a Chromium browser to run HTML, Javascript (nodeJS), and CSS on multiple OS platforms. In addition to the Electron framework, the software uses React to create an interactive user experience. The jsx files in the View folder contain React logic that users engage with. These interactive elements trigger calls to Interactors.
The other files that run the UI include the index.html that contains the base HTML logic. The index.html file calls the React App. The styling for the user interface is contained primarily in the index.css file. The core Electron logic that runs the Chromium browser is included in the main.js file for the core Electron app logic, the preload.js file that contains bridging logic to connect the main Electron app to the React logic in the View folder. The renderer.js file instantiates the React App.
To create a new page in the software, you will need to create a new .jsx file in the View folder. You may also need to add a React Route to the new page in the App/Loaded.jsx file.
If you need to create a new reusable UI component that can be used on multiple pages, or to separate UI logic on complex pages, you will also create a new .jsx file in the View folder. These UI components can be embedded into pages or even into other UI components.
The Interactors are contained in the Interactor folder. The .ts files in this folder are written in TypeScript, which is simply type safe Javascript (nodeJS). The interactors contain logic that connects the UI architecture to the data architecture. Interactors in this folder implement the IInputBoundary interface. The input boundary interface and the interactors use methods that mimic RESTful web calls (i.e., get, post, put, delete). A UI Page or UI component may use one or more interactors to retrieve or manipulate data using the get, post, put, and delete methods. The get method is used to retrieve data. The post method is used to retrieve data. The put method is used to edit data. And the delete method is used to remove data.
When you need to make connections to new data sources, you will need to create a new Interactor .ts file in the Interactor folder. Be sure that the new Interactor implements the IInputBoundary interface. You can then write case-specific get, post, put, and delete logic for the new data source.
The Gateway architecture relies on the adapter pattern to connect Interactors to technological implementations of data sources, such as databases and data APIs. While the interactor contains general get, post, put, and delete logic, the gateway .ts files in the Gateway folder contain connection details to specific APIs. For example, there are multiple data sources for stock price and volume data, such as Yahoo Finance and AlphaVantage. The StockInteractor.ts file in the Interactor folder contains general logic to manipulate stock data. However, the specific implementations for interacting with Yahoo Finance and AlphaVantage are contained in the Gateway folder. The interactors use the gateways to provide a highly configurable system.
If you needed to create a new Interactor, chances are, you will need to create a Gateway as well. You should not put specific data access implementation logic into Interactors. That logic belongs in a Gateway file. The data gateways contain logic to create, read, update, and delete data from different sources. To create a consistent feel across all gateways, the gateways implement one of the variants of the IDataGateway interface. For example, if the API requires the use of an API key, you would implement the IKeyedDataGateway.ts in your new gateway file. Not every gateway needs a concrete implementation of all of the methods (i.e., create, read, update, and delete). Some gateways are read only, so only the create method is required.
In addition to the core architecture of Electron, React, and the Clean Architecture; the software utilizes certain technology supports to make the system easier to manage. The software utilizes webpack to manage the packaging of the HTML, CSS, Javascript/Typescript, and other system files. The webpack files, such as webpack.main.config.js and webpack.renderer.config.js contain the logic for how the different system files should be packaged.
The system also uses nodeJS, which requires configuration of the different nodeJS modules in the package.json file. If you need to add a new nodeJS package to the system, you will need to add it to the package.json file.
The complementary systems architecture files, namely the webpack and package.json files, should not be altered without permission from the repository owner. These configuration files can be complicated for individuals with little experience to update correctly. Bad configurations in these files can cause the entire system to fail.
The core logic of the monolithic desktop application relies on nodeJS. No other programming language should be added to the software architecture without permission of the repository owner. There are few features that can't be built in nodeJS for the core, free parts of the system. Opportunities will exist to add other cloud-based features to the software using other programming languages. However, these paid, cloud features are not apart of the initial roadmap for the product. The software is eing developed primarily as a free, open-source tool to democratize access to financial investing knowledge and skills. Find nodeJS packages to implement your ideas rather than creating complexity to the architecture with additional programming languages.
The following pages outline core and peripheral features of Open FinAL:
TODO: Create documentation
The following are technology guides and reports examined by contributors:
- Style Guide - style guidelines for the UI and branding of Open FinAL