Skip to content

Commit

Permalink
docs(ledger-browser): add initial GUI documentation and fix some bugs
Browse files Browse the repository at this point in the history
- Add new documentation section to project docs. New pages can be found under
    `Cactus` -> `Ledger Browser` category. Documentation include GUI setup
    instructions, application overviews, developer guide and tutorial
    on developing new app plugin for the GUI.
- Do some minor quality of life improvements and bug fixes.
- Add missing GUI database schema file.
- Remove dead code from GUI that still used `getAppList`.
- Add documentation links to the GUI. For now, most links are empty and they
    will be set once this PR is merged and the docs URLs are confirmed.
- Add sample tutorial application (the same that is created step-by-step in
    the tutorial in the documentation)
- Improve plugin app URL regex to allow more valid paths.
- Expose ethereum and fabric schemas in supabase-all-in-one
- Extend persistence plugin init SQL with code for exposing custom schemas.
- Improve supabase-all-in-one readme documentation.
- Fix persistence sample setup scripts ports so that both scripts can be run
    at the same time.

Depends on hyperledger-cacti#3448
Depends on hyperledger-cacti#3449

Signed-off-by: Michal Bajer <michal.bajer@fujitsu.com>
  • Loading branch information
outSH committed Aug 13, 2024
1 parent 63fc3f1 commit 90ad2db
Show file tree
Hide file tree
Showing 39 changed files with 1,310 additions and 62 deletions.
143 changes: 143 additions & 0 deletions docs/docs/cactus/ledger-browser/developer-guide/architecture.md
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)
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 18 additions & 0 deletions docs/docs/cactus/ledger-browser/developer-guide/overview.md
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](https://github.com/hyperledger/cacti/blob/main/.eslintrc.js).
- Whenever possible, utilize [MaterialUI](https://mui.com/) and [common UI components](https://github.com/hyperledger/cacti/tree/main/packages/cacti-ledger-browser/src/main/typescript/components/ui).
- Use [PageTitle](https://github.com/hyperledger/cacti/tree/main/packages/cacti-ledger-browser/src/main/typescript/components/ui/PageTitle.tsx) as main page title.
- Use [PageTitleWithGoBack](https://github.com/hyperledger/cacti/tree/main/packages/cacti-ledger-browser/src/main/typescript/components/ui/PageTitleWithGoBack.tsx) as subpage title (it has arrow attached for going back).
- Use [NotificationContext](https://github.com/hyperledger/cacti/blob/main/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.
Loading

0 comments on commit 90ad2db

Please sign in to comment.