Front-End Composition Architecture Plan

[MSzalowski]

Front-End Composition Architecture Plan

This document’s sole purpose is to capture the discussions happening during architecture strategy planning. It describes the problem, proposed solution and the direction in which a well-governed architecture and technical designs should move forward. Credits for all of them goes to Intesect's Solutions Architect - Igor Velickovic @kickloop 🎉

This is an initial capture that stays open to refinement and further discussion.

Background for the recomposition

Current architecture of the application characterized by its monolithic nature, confronts several critical problems that impede our ability to deliver governance community tools in separation and by different teams.

Lack of modularity and scalability

The monolithic architecture of our application inherently lacks modularity, leading to tightly coupled components and dependencies. This intertwined nature inhibits scalability, as any changes or updates necessitate modifications to the entire application which enforces different teams to contribute inside the existing monolithic codebase with the increasing risk of desynchronization of the dependencies and overflowing requirements.
As application grows in complexity and scope becomes increasingly cumbersome to manage, scale and adapt new functionalities.

Limited team autonomy and collaboration

With the current structure, different teams are constrained by shared codebases and dependencies, resulting in limited autonomy and collaboration. Teams face challenges in independently developing and deploying features, as changes to shared components may inadvertently impact other parts of the application. This lack of autonomy stifles innovation and slows down the development process, as teams must coordinate closely to avoid conflicts and regressions. It is still recommended that government tools share style guides and the contributing approach, but it should not be restricted by the way system is designed, but enforced by the community standards.

Deployment complexity and risk

The monolithic nature of our application introduces deployment complexities and risks, as changes to any part of the codebase necessitate deploying the entire application. This monolithic deployment approach increases the likelihood of introducing bugs or issues, as changes to unrelated components may inadvertently affect the application's behavior. Moreover, the lengthy deployment process further exacerbates downtime and disrupts user experience, undermining our ability to deliver timely updates and enhancements.

Hindered Technology Adoption and Innovation

In a monolithic architecture, adopting new technologies or frameworks becomes inherently challenging, as any changes impact the entire application. This reluctance to embrace emerging technologies stifles innovation and impedes our ability to stay competitive in a rapidly evolving landscape. Furthermore, the monolithic architecture may lock us into outdated technologies, limiting our agility and adaptability to market trends and customer needs.

Cumbersome Testing and Maintenance

Testing and maintaining a monolithic application pose significant challenges due to its interconnected nature. Comprehensive testing becomes laborious and time-consuming, as changes to one component may necessitate retesting the entire application. Moreover, maintaining code quality and addressing technical debt become increasingly challenging as the codebase grows in size and complexity, leading to decreased developer productivity and increased risk of software defects.

---

In light of these challenges it is imperative to reevalute our application architecture and transition towards a more modular and scalable approach.

Focus Areas

1. Repository Structure

• Establish a clear and scalable repository structure to facilitate collaboration among multiple teams.
• Utilize a modular approach where UI and business logic are encapsulated within sub-packages.
• Enable seamless sharing of components and functionality across different sub-packages.

2. GovTool (Frontend Root Package) Responsibility

• The root package orchestrates sub-packages.
• Manages wallet connections and decentralized logic.
• Exposes wallet connection (including CSL integration) API via service or event-driven architecture for communication.

3. Tool (Frontend Sub-package) Application Composition

• Implement appropriate design patterns for decentralization.
• Each sub-package represents pillar of the GovTool which is supposed to be a tool of a GovTool tools.
• Each sub-package ensures compatibility with decentralized technologies via exposed by the Root Package API.

4. Independend Deployment

• Enable independent deployment of sub-packages.
• Implement CI/CD pipelines and automation.
• Utilize containerization and microfrontends (composition) architecture.

5. Separation of Concerns

• Enforce clear separation of concerns.
• Adopt architectural patterns for delineating responsibilities.
• Encourage modular design principles.

6. Open Source Considerations

• Provide comprehensive documentation and guidelines.
• Embrace open-source GovTool philosophy.
• Utilize version control systems and platforms.

Current architecture overview

(As of 29th march 2024)

On the diagram above it is visible that GovTool Frontend is a monolithic application that shares its components directly from each other which indicates that changing anything in the UI component would have a direct impact on all the application modules.

Current repository structure

src
    ├── components
    │   ├── atoms
    │   ├── molecules
    │   └── organisms
    ├── consts
    ├── context
    ├── hooks
    ├── i18n
    ├── mock
    ├── models
    ├── pages
    ├── services
    ├── stories
    ├── types
    └── utils

Where src includes the code of the single monolithic app.

Proposed architecture overview

On the diagram above:

• GovTool wrapper application connects with CSL and GovTool backend to provide wallet connection logic and Cardano DB-Sync Data.
• Every application inside the GovTool wrapper is separate frontend application that handles the:
  • Language/Framework
  • Testing
  • CI/CD
  • Folder structure
    on its own.
• govtool-design-system is the public components library with its own components documentation (on storybook).
• Every shared business logic module can be either separate application or set of utility methods working as a service and deployed separately (with its own versioning & CI/CD pipelines) and can be used across the applications (eg.: metadata validation service)

Proposed repository structure

As the migration from a current monolithic architecture to a composite one might be time-consuming, not only because of the implementation but also because of the synchronization with all the GovTool builders and the selection of appropriate tools to wrap up the micro frontends composition my proposition for the repository structure is:

.
├── govtool-be
├── govtool-wrapper
│   ├── anyTool
│   ├── dRep
│   ├── delegation
│   ├── gaDisplay
│   └── gaSubmission
└── metadata-validation

Notice that in above structure we do not have any globally shared package as govtool-design-system as it can easily be handled using the public npm package which would be used across the apps.

where any directory inside govtool-wrapper is separate frontend application (later on, they should be able to be exposed to any repository in the world and placed anywhere in the repository - that is 1st stage for the easiest migration)
govtool-wrapper is the application on its own that wraps the sub-packages as components and eg.: the routing of the react based wrapper would be:

// App.tsx
import { useCallback, useEffect } from "react";
import { Route, Routes, useNavigate } from "react-router-dom";

// Separate @govtool packages
import { useWalletConnectionListener } from "@govtool/hooks";
import { SetupInterceptors } from "@govtool/services";
import {
  getItemFromLocalStorage,
  WALLET_LS_KEY,
  removeItemFromLocalStorage,
} from "@govtool/utils";
import { Delegation } from '@govtool/delegation'
import { GovernanceActionDisplay } from '@govtool/governanceActionDisplay'
import { DRep } from '@govtool/drep'
import { GovernanceActionSubmission } from '@govtool/governanceActionSubmission'

import { Home } from '@pages'
import { PATHS } from "@consts";

import { useCardano } from "@context";

export default () => {
  const { enable } = useCardano();
  const navigate = useNavigate();

  useWalletConnectionListener();

  useEffect(() => {
    SetupInterceptors(navigate);
  }, []);

  const checkTheWalletIsActive = useCallback(() => {
    const hrefCondition =
      window.location.pathname === PATHS.home ||
      window.location.pathname === PATHS.governanceActions ||
      window.location.pathname === PATHS.governanceActionsAction;

    const walletName = getItemFromLocalStorage(`${WALLET_LS_KEY}_name`);
    if (window.cardano) {
      const walletExtensions = Object.keys(window.cardano);
      if (walletName && walletExtensions.includes(walletName)) {
        enable(walletName);
        return;
      }
    }
    if (
      (!window.cardano && walletName) ||
      (walletName && !Object.keys(window.cardano).includes(walletName))
    ) {
      if (!hrefCondition) {
        navigate(PATHS.home);
      }
      removeItemFromLocalStorage(`${WALLET_LS_KEY}_name`);
      removeItemFromLocalStorage(`${WALLET_LS_KEY}_stake_key`);
    }
  }, []);

  useEffect(() => {
    checkTheWalletIsActive();
  }, [checkTheWalletIsActive]);

  return (
      <Routes>
        <Route path={PATHS.home} element={<Home />} />
        <Route path={PATHS.delegation} element={<Delegation />} />
        <Route path={PATHS.gaDisplay} element={<GovernanceActionDisplay />} />
        <Route path={PATHS.drep} element={<DRep />} />
        <Route path={PATHS.gaSubmission} element={<GovernanceActionSubmission />} />
      </Routes>
  );
};

Important - focus on the imports declaration as it shows how the separation of concerns might look like (all the @govtool/* libraries)

Some of the possible toolings (random order)

1. single-spa - Open source, framework independent, allows to separate UI, logic, and whole apps to be wrapped into one entry point.
2. webpack Module Federation - allows to wrap up frontends treating them as building blocks. Complex setup but with more freedom.
3. bit.dev - Open source, build system for anything (not only frontend) - the most advanced and actively maintained build system for the composable software.

---

Your feedback shapes the future of our project! Share your insights and suggestions to help us create a better experience for everyone. Together, we can drive innovation and build a community-driven platform that meets the needs of all users.

[Ryun1]

First step, draft PR #887