docs(ui): add developer readme

Author: a-asaad

README.md

@@ -27,32 +27,9 @@ Keip Canvas is hosted at https://octoconsulting.github.io/keip-canvas/
 
 ## Development
 
-To run the Keip Canvas UI locally, first make sure these prerequisites are installed:
+To get started with developing the Canvas UI, see the [dev docs](./ui/DEVELOPER.md).
 
-- Node.js v20
-- npm v10
-
-Clone the repository:
-
-```shell
-git clone https://github.com/OctoConsulting/keip-canvas.git && cd keip-canvas/ui
-```
-
-Install dependencies:
-
-```shell
-npm install
-```
-
-Run the development web server:
-
-```shell
-npm run dev
-```
-
-Check the `ui/package.json` for more useful commands
-
-### Architecture
+## Architecture
 
 For more details on how Keip Canvas is implemented, see the [architecture documentation](docs/ARCHITECTURE.md).
 

docs/ARCHITECTURE.md

@@ -33,7 +33,7 @@ Fetches XML Schema Definitions (XSD) and parses them into a catalog of EIP Compo
 The resulting component definitions are then used by the Canvas UI to populate the draggable node menu and provide the
 user with a specific set of configuration options for each EIP component type.
 
-### [Keip Canvas UI](../README.md)
+### [Keip Canvas UI](../ui/DEVELOPER.md)
 
 A single-page web application that provides drag, drop, and link capabilities for creating integration flow diagrams.
 

ui/DEVELOPER.md

@@ -0,0 +1,105 @@
+# Keip Canvas UI Overview
+
+The UI is built around a canvas that allows you to drag, drop, and
+connect [EIP](https://www.enterpriseintegrationpatterns.com/patterns/messaging/) nodes to create integration flows.
+In addition to being a design and documentation tool, the UI allows you to configure the behavior of the individual EIP
+nodes, thus providing the ability to generate deployable integration flow artifacts (e.g. XML).
+
+## Requirements
+
+For local development, the following must be installed:
+
+- Node.js v20
+- npm v10 (other package managers should work as well)
+
+[Volta](https://volta.sh/) is recommended for setting up your JS environment.
+
+### Run the dev server
+
+Clone the repository:
+
+```shell
+git clone https://github.com/OctoConsulting/keip-canvas.git && cd keip-canvas/ui
+```
+
+Install dependencies:
+
+```shell
+npm install
+```
+
+Run the development web server:
+
+```shell
+npm run dev
+```
+
+## Dependencies
+
+The UI is mostly written in Typescript and relies heavily on the following libraries:
+
+- [React](https://react.dev/): main UI library
+- [React Flow](https://reactflow.dev/): powers the interactive flow canvas
+- [Zustand](https://github.com/pmndrs/zustand): state-management
+- [Carbon Design System](https://carbondesignsystem.com/): React component library
+- [Vite](https://vite.dev/): build tooling
+
+## Structure
+
+The source code is spread across multiple modules, some important ones are highlighted below:
+
+### api
+
+Defines the types and interfaces used across the UI components. Notably, the `api/generated` subdirectory contains
+code generated from the [EIP Json schemas](../schemas/README.md). To use updated source schemas,
+the [code-generation script](./genApiFromSchema.js) must be updated to point to the desired schema versions.
+The API files can then be generated by running `npm run codegen`.
+In this specific case, the generated files should be checked into version control to avoid the need to constantly
+rebuild them.
+
+### assets
+
+Holds static assets such as the EIP icon SVGs.
+
+### components
+
+Contains all the UI's React components. Developers will likely spend the majority of their time working in here.
+
+### json
+
+Stores the [EIP Component Definition](../schemas/model/json/eipComponentDef.schema.json) JSON, which populates the
+catalog of EIP nodes that a user is able to drag and drop onto the canvas.
+
+### singletons
+
+Initializes singleton instances that are required across the application, most notable is the `store` module.
+The `store` module manages the React application's global state, through the use of a Zustand store.
+The module does not provide direct access to the app store, rather several use-case/event specific custom hooks are
+exported for use by components. This helps us keep stateful business logic encapsulated inside the store.
+
+## Formatting and Linting
+
+Formatting and linting is handled by [Prettier](https://prettier.io/) and [ESLint](https://eslint.org/) respectively.
+
+Formatting commands:
+
+```shell
+# check only
+npm run check-format
+
+# apply formatting
+npm run format
+```
+
+Run linter:
+
+```shell
+npm run lint
+```
+
+Rules are configured in:
+
+- Prettier: [.prettierrc.json](./.prettierrc.json)
+- ESLint: [.eslintrc.cjs](./.eslintrc.cjs)
+
+Consult your IDE's documentation on how to integrate these rules.

ui/genApiFromSchema.js

@@ -7,6 +7,8 @@ import path from "node:path"
 // TODO: Look into avoiding duplication of generated types when multiple top-level schemas 
 // reference the same common schemas.
 
+// TODO: Use git tags instead of commit hashes
+// To use an updated source schema, change this to point to the desired version.
 const COMMIT_HASH = "4fe59e1438fad31b79c87568686cf867fd14a41e"
 
 const SCHEMAS = ["eipComponentDef.schema.json", "eipFlow.schema.json"]