App and service conceptual overview (#114)

Pulled a brief description of each from meeting transcript discussion
from earlier this week

workbench-app/README.md

@@ -1,4 +1,37 @@
-# Semantic Workbench App Setup Guide
+# 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.
+
+**Client-Server Interaction**: The app communicates with the Workbench backend service via RESTful APIs, performing AJAX requests to handle user input and display responses.
+
+**Single Page Application (SPA)**: Ensures smooth and seamless transitions between different parts of the app without requiring full page reloads.
+
+### Initialization and Authentication
+
+The application requires user authentication, typically via Microsoft AAD or MSA accounts. Instructions for setting up the development environment are in the repo readme. To deploy in your own environment see [app registration documentation](../docs/CUSTOM_APP_REGISTRATION.md).
+
+### 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 may prompt for admin credentials when installed during local 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**: The app makes AJAX requests to the backend service, fetching data such as message history, user sessions, and conversation context.
+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. **State Management**: The backend service keeps track of the conversation state and other relevant information, enabling the app to provide a consistent user experience.
+
+#### 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](../workbench-service/README.md) backend service.
 

workbench-service/README.md

@@ -1,4 +1,32 @@
-# Semantic Workbench Service Setup Guide
+# Semantic Workbench Service
+
+## Architecture
+
+The Semantic Workbench service consists of several key components that interact to provide a seamless user experience:
+
+**Workbench Service**: A backend Python service that handles state management, user interactions, and assists in broker functionalities.
+
+[**Workbench App**](../workbench-app): A single-page web application written in TypeScript and React, compiled into static HTML that runs in the user’s browser.
+
+**FastAPI Framework**: Utilized for the HTTP API, providing endpoints and continuous communication between the Workbench and assistants.
+
+**Assistants**: Independently developed units that connect to the Workbench Service through a RESTful API. Assistants can manage their own state and handle connections to various language models.
+
+![Architecture Diagram](../docs/images/architecture-animation.gif)
+
+### Communication
+
+The communication between the Workbench and Assistants is managed through HTTP requests:
+
+1. **Initialization**: Assistants notify the Workbench about their presence and provide a callback URL.
+2. **Message Handling**: Both the Workbench and Assistants can send HTTP requests to each other as needed.
+3. **Events**: There are several types of events (e.g., `message created`) that are handled through designated HTTP endpoints.
+
+### Agents
+
+Each assistant (or agent) is registered and maintains its connection through continuous ping requests to the Workbench. This ensures that the state information and response handling remain synchronized.
+
+## Setup Guide
 
 The Semantic Workbench service is a Python service that provides the backend functionality of the Semantic Workbench.