forked from hyperledger-cacti/cacti
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(wip): add architecture doc page
- Loading branch information
Showing
6 changed files
with
246 additions
and
2 deletions.
There are no files selected for viewing
143 changes: 143 additions & 0 deletions
143
docs/docs/ledger-browser/developer-guide/architecture.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,143 @@ | ||
# Architecture | ||
|
||
## Components | ||
|
||
### AppDefinition | ||
|
||
Each application must define an `AppDefinition`. This includes essential information like the app's name, category, and default settings shown to the user during app creation (such as description, path, and custom options). The most critical part of the `AppDefinition` is the `createAppInstance` factory method. This method accepts a `GuiAppConfig` (which contains dynamic app settings configured by the user and stored in a database) and returns an `AppInstance` object. | ||
|
||
#### Interface | ||
|
||
```typescript | ||
interface AppDefinition { | ||
/** | ||
* Application name as shown to the user | ||
*/ | ||
appName: string; | ||
|
||
/** | ||
* Application category, the user can filter using it. | ||
* If there's no matching category for your app consider adding a new one! | ||
*/ | ||
category: string; | ||
|
||
/** | ||
* Full URL to a setup guide, it will be displayed to the user on app configuration page. | ||
*/ | ||
appSetupGuideURL?: string; | ||
|
||
/** | ||
* Full URL to app documentation page | ||
*/ | ||
appDocumentationURL?: string; | ||
|
||
/** | ||
* Default value for instance name that user can set to uniquely identitify this ap instance. | ||
*/ | ||
defaultInstanceName: string; | ||
|
||
/** | ||
* Default value for app description. | ||
*/ | ||
defaultDescription: string; | ||
|
||
/** | ||
* Default path under which app routes will be mounted (must be path with `/`, like `/eth`) | ||
*/ | ||
defaultPath: string; | ||
|
||
/** | ||
* Default custom, app-specific options in JSON format. This will change between applications. | ||
*/ | ||
defaultOptions: unknown; | ||
|
||
/** | ||
* Factory method for creating application instance object from configuration stored in a database. | ||
*/ | ||
createAppInstance: CreateAppInstanceFactoryType; | ||
} | ||
``` | ||
|
||
### AppInstance | ||
|
||
An `AppInstance` represents the runtime configuration of an app. It holds all the details required by `Ledger Browser` to render the app correctly. Key components include `menuEntries` (links displayed in the top header bar) and `routes` that adhere to [react-router-dom](https://reactrouter.com/en/main) specifications. | ||
|
||
```typescript | ||
interface AppInstance<T = unknown> { | ||
/** | ||
* Unique database ID of this app instance. | ||
*/ | ||
id: string; | ||
|
||
/** | ||
* Name of the application (can be same as appName in app definition) | ||
*/ | ||
appName: string; | ||
|
||
/** | ||
* Instance name (set by the user) | ||
*/ | ||
instanceName: string; | ||
|
||
/** | ||
* Instance description (set by the user) | ||
*/ | ||
description: string | undefined; | ||
|
||
/** | ||
* Path under which app routes will be mounted (must be path with `/`, like `/eth`) | ||
*/ | ||
path: string; | ||
|
||
/** | ||
* Custom, app-specific options in JSON format. This will change between applications. | ||
*/ | ||
options: T; | ||
|
||
/** | ||
* List on titles and URL of menu entries to be added to the top bar (used to navigate within an app) | ||
*/ | ||
menuEntries: AppInstanceMenuEntry[]; | ||
|
||
/** | ||
* `react-router-dom` compatible list of this application routes. | ||
*/ | ||
routes: RouteObject[]; | ||
|
||
/** | ||
* Method for retriving application status details. | ||
*/ | ||
useAppStatus: () => GetStatusResponse; | ||
|
||
/** | ||
* Status component showed when user opens a app status pop up window. | ||
*/ | ||
StatusComponent: React.ReactElement; | ||
|
||
/** | ||
* Full URL to a setup guide, it will be displayed to the user on app configuration page. | ||
*/ | ||
appSetupGuideURL?: string; | ||
|
||
/** | ||
* Full URL to app documentation page | ||
*/ | ||
appDocumentationURL?: string; | ||
} | ||
``` | ||
|
||
### AppConfig | ||
|
||
To make an application available to the `Ledger Browser`, it must be added to the main `AppConfig` mapping (located in `common/config.tsx`). When creating a new app, ensure it is included here, and assign it a unique ID within the map. | ||
|
||
### ConfiguredApps (GuiAppConfig) | ||
|
||
`ConfiguredApps` refers to the dynamic settings for apps as configured by the user and stored in a database. This data is maintained in the `public.gui_app_config` table within the GUI's PostgreSQL instance. | ||
|
||
### AppInstance List | ||
|
||
During startup, the application reads dynamic app configurations from the database (`GuiAppConfig`), retrieves the corresponding `AppDefinition` from the main `AppConfig`, and uses the `createAppInstance` method to generate the final `AppInstance`. This instance is then added to a list, with its routes mounted under the specified path. | ||
|
||
## Diagram | ||
|
||
![Ledger Browser Architecture Diagram](images/architecture_cacti_ledger_browser_architecture.png) |
Binary file added
BIN
+40.9 KB
...owser/developer-guide/images/architecture_cacti_ledger_browser_architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
# Developer Guide Overview | ||
|
||
Ledger Browser is designed with extensibility and customization in mind. You can enhance the GUI functionality by developing custom apps that users can configure and use. | ||
|
||
## Limitations | ||
|
||
Currently, applications must be included in the ledger-browser source code and built together with the main application. As the number of apps grows, we may consider transitioning to a more modular (though also more complex) design, allowing apps to be developed in separate packages. | ||
|
||
## Guidelines | ||
|
||
- Use React functional components. | ||
- Use TypeScript and adhere to the [global Cacti linter requirements](../../../../.eslintrc.js). | ||
- Whenever possible, utilize [MaterialUI](https://mui.com/) and [common UI components](../../../../packages/cacti-ledger-browser/src/main/typescript/components/ui). | ||
- Use [PageTitle](../../../../packages/cacti-ledger-browser/src/main/typescript/components/ui/PageTitle.tsx) as main page title. | ||
- Use [PageTitleWithGoBack](../../../../packages/cacti-ledger-browser/src/main/typescript/components/ui/PageTitleWithGoBack.tsx) as subpage title (it has arrow attached for going back). | ||
- Use [NotificationContext](../../../../packages/cacti-ledger-browser/src/main/typescript/common/context/NotificationContext.tsx) for displaying Pop-Up windows with notifications (info, success, error, etc..). | ||
- App routes are defined using [react-router-dom](https://reactrouter.com/en/main). | ||
- Use [react-query](https://tanstack.com/query/v3) for fetching data, `QueryClientProvider` is already available in the application. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters