Skip to content

Latest commit

 

History

History
129 lines (85 loc) · 5.34 KB

README.md

File metadata and controls

129 lines (85 loc) · 5.34 KB

Semantic Workbench App

Architecture

The Semantic Workbench app is designed as a client-side, single-page application (SPA) using React and TypeScript. It runs entirely in the user's browser and interacts with the backend Semantic Workbench service for state and conversation management.

Key Components

React/TypeScript: The app is built using the React library and TypeScript for static typing.

Vite: Build system and development server that provides fast HMR (Hot Module Replacement).

Fluent UI & Fluent Copilot: Microsoft design system components that provide a consistent look and feel.

Redux & Redux Toolkit: Centralized state management with middleware for side effects.

React Router: Handles navigation and URL management within the SPA.

Client-Server Interaction: The app communicates with the Workbench backend service via RESTful APIs and SSE (Server-Sent Events) for real-time updates.

Content Rendering: Support for rich content types including Markdown, code syntax highlighting, Mermaid diagrams, ABC notation for music, and more.

Initialization and Authentication

The application requires user authentication, typically via Microsoft AAD or MSA accounts. The app uses Microsoft Authentication Library (MSAL) for authentication flows. Instructions for setting up the development environment are in the repo readme. To deploy in your own environment see app registration documentation.

Connecting to the Backend Service

The Semantic Workbench app connects to the backend service using RESTful API calls. Here's how the interaction works:

  1. Initial Setup: On application startup, the app establishes a connection to the backend service located at a specified endpoint. This connection requires SSL certificates, which are automatically generated by vite-plugin-mkcert during development.
  2. User Authentication: Users must authenticate via Microsoft AAD or MSA accounts. This enables secure access and interaction between the app and the backend.
  3. Data Fetching & State Management: The app uses Redux Toolkit Query to manage API requests and caching of conversation data, messages, and participant information.
  4. Event Handling: User actions within the app (e.g., sending a message) trigger RESTful API calls to the backend, which processes the actions and returns the appropriate responses.
  5. Real-time Updates: The app uses Server-Sent Events (SSE) to receive real-time updates from the backend service, enabling live updates of conversation state.

Error Handling

The app includes error handling mechanisms that notify users of any issues with the backend connection, such as authentication failures or network issues.

Setup Guide

The Semantic Workbench app is a React/TypeScript app integrated with the Semantic Workbench backend service.

Prerequisites

  • Node.js: Version 20.x is required (enforced by the run script)
  • pnpm: Used for package management
  • SSL certificates: Automatically generated during development for HTTPS

Follow the setup guide to install all required development tools.

Installing dependencies

In the workbench-app directory:

make

This command runs pnpm install to install all required dependencies.

Running from VS Code

To run and/or debug in VS Code:

  1. Open the workspace file semantic-workbench.code-workspace
  2. View -> Run
  3. Select "app: semantic-workbench-app"

Running from the command line

In the workbench-app directory:

pnpm dev

or

pnpm start

Then open https://127.0.0.1:4000 in your browser.

Note: The first time you run the app, your browser may warn about the self-signed SSL certificate.

Development Tools

Available Scripts

  • pnpm dev / pnpm start - Start development server
  • pnpm build - Build for production
  • pnpm preview - Locally preview production build
  • pnpm lint - Run ESLint to check code quality
  • pnpm format / pnpm prettify - Format code with Prettier
  • pnpm type-check - Run TypeScript type checking
  • pnpm find-deadcode - Identify unused code
  • pnpm depcheck - Check for dependency issues

Documentation

Application Documentation

Related Documentation

Project Structure

Key directories in the project:

workbench-app/
├── src/
│   ├── components/     # Reusable UI components
│   ├── models/         # TypeScript interfaces and types
│   ├── redux/          # State management
│   ├── routes/         # Application routes
│   ├── services/       # API services
│   └── libs/           # Utility functions and hooks
├── public/             # Static assets
├── docs/               # Documentation
└── certs/              # SSL certificates for development