From 0e641f2bf2244f2c23f951ca000bddfd96621e1f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Jun 2025 19:28:01 +0000 Subject: [PATCH 1/4] Initial plan for issue From 81784fb9a8c748c4ced91ddc0583dab2f3c38f5b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Jun 2025 19:34:49 +0000 Subject: [PATCH 2/4] Update core architecture documentation for .NET 9 Blazor Web App with CLEAN architecture Co-authored-by: gmcgrady <129766830+gmcgrady@users.noreply.github.com> --- .../architecture/app-architecture.mdx | 79 +++++++++++++------ documentation/architecture/tech-stack.mdx | 4 +- documentation/components/app.mdx | 15 +++- 3 files changed, 68 insertions(+), 30 deletions(-) diff --git a/documentation/architecture/app-architecture.mdx b/documentation/architecture/app-architecture.mdx index 553ccf6..9b5e678 100644 --- a/documentation/architecture/app-architecture.mdx +++ b/documentation/architecture/app-architecture.mdx @@ -1,29 +1,58 @@ --- title: App Architecture -description: "Numa includes fully extensible components, models, services, and interfaces." +description: "Numa follows CLEAN architecture principles with fully extensible components, models, services, and interfaces, using a mixture of WebAssembly & Server rendering modes." --- +## CLEAN Architecture Principles +Numa follows CLEAN architecture principles to ensure maintainability, testability, and separation of concerns: + +- **Presentation Layer**: Razor components and pages handle user interface logic +- **Application Layer**: Services contain business logic and orchestrate data operations +- **Domain Layer**: Models and entities represent core business objects +- **Infrastructure Layer**: External integrations (Azure services, databases, APIs) + +The architecture promotes: +- **Dependency Inversion**: High-level modules don't depend on low-level modules +- **Single Responsibility**: Each component has one reason to change +- **Interface Segregation**: Services implement focused interfaces +- **Separation of Concerns**: Clear boundaries between layers + +## Blazor Web App Rendering Modes +Numa leverages Blazor Web App's flexible rendering capabilities: + +- **Server-side Rendering (SSR)**: Fast initial load for public pages +- **Interactive Server**: Real-time updates via SignalR for admin features +- **Interactive WebAssembly**: Client-side execution for rich user interactions +- **Automatic Rendering**: Optimal rendering mode selection per component + ## Project Structure -`Numa.sln` is organized into `components`, `models`, `services`, and `interfaces`. The project root contains: - - - `Components/` - Contains reusable Razor components - - `Layout/` - Contains layout components for page structures - - `MainLayout.razor` - Defines the main layout of the application - - `Pages/` - Contains Razor pages for routing - - `SermonSearch.razor` - Defines a page or component for SermonSearch - - `SermonSearch.razor.cs` - Code-behind logic for `SermonSearch.razor` - - `Routes.razor` - Configures application routes and navigation - - `App.razor` - The root component of the application - - `Models/` - Contains data models representing entities - - `User.cs` - Represents the `User` data model - - `Services/` - Contains services that handle business logic - - `UserService.cs` - Handles user-related operations and logic - - `Interfaces/` - Defines contracts for services and components - - `IUserService.cs` - Interface for user service functionality - - `wwwroot/` - Contains static files like CSS, JS, and images - - `.env` - Stores environment variables for configuration - - `Program.cs` - Entry point for application initialization - - `Numa.sln` - Solution file that organizes the project +`Numa.sln` follows CLEAN architecture principles with clear separation between presentation, application, domain, and infrastructure layers: + + - **Presentation Layer** + - `Components/` - Contains reusable Razor components + - `Layout/` - Contains layout components for page structures + - `MainLayout.razor` - Defines the main layout of the application + - `Pages/` - Contains Razor pages for routing with mixed rendering modes + - `SermonSearch.razor` - Defines a page or component for SermonSearch + - `SermonSearch.razor.cs` - Code-behind logic for `SermonSearch.razor` + - `Routes.razor` - Configures application routes and navigation + - `App.razor` - The root component of the Blazor Web App + - **Domain Layer** + - `Models/` - Contains data models representing core business entities + - `User.cs` - Represents the `User` domain model + - **Application Layer** + - `Services/` - Contains services that handle business logic and orchestration + - `UserService.cs` - Handles user-related operations and logic + - `Interfaces/` - Defines contracts for services and components + - `IUserService.cs` - Interface for user service functionality + - **Infrastructure Layer** + - External service integrations (Azure services, database access) + - Configuration and dependency injection setup + - **Supporting Files** + - `wwwroot/` - Contains static files like CSS, JS, and images + - `.env` - Stores environment variables for configuration + - `Program.cs` - Entry point for application initialization and DI container setup + - `Numa.sln` - Solution file that organizes the project ## Implementing SDKs @@ -37,10 +66,10 @@ As a best practice, Numa wraps all external SDKs in custom services to ensure sc | Markdig | `MarkdownService.cs` | ## Dependency Injection -Numa's services are registered in `Program.cs`, available to be injected into any component. +Numa's services are registered in `Program.cs` following CLEAN architecture principles, with interfaces abstracting implementation details: ```csharp -// Register the custom Numa services +// Register the custom Numa application services (Application Layer) builder.Services.AddScoped(); builder.Services.AddScoped(); builder.Services.AddScoped(); @@ -48,11 +77,13 @@ builder.Services.AddScoped(); builder.Services.AddSingleton(); builder.Services.AddSingleton(); builder.Services.AddSingleton(); + +// Register infrastructure services with configuration builder.Services.AddSingleton( sp => { return new ChatService( azureOpenAiEndpoint, azureOpenAiKey, azureAiSearchEndpoint, azureAiSearchKey ); }); builder.Services.AddSingleton( sp => { return new DocumentStorageService( azureStorageConnectionString ); } ); builder.Services.AddSingleton(); ``` -Injection occurs in the Razor components' code-behind file (i.e., `SermonSearch.razor.cs`). +Services are injected into Razor components using the `[Inject]` attribute in code-behind files (i.e., `SermonSearch.razor.cs`): ```csharp public partial class SermonSearch : ComponentBase { diff --git a/documentation/architecture/tech-stack.mdx b/documentation/architecture/tech-stack.mdx index 1f2f17a..bac2bf4 100644 --- a/documentation/architecture/tech-stack.mdx +++ b/documentation/architecture/tech-stack.mdx @@ -1,12 +1,12 @@ --- title: Tech Stack -description: "Numa is a .NET 8 Blazor Server application that leverages MudBlazor for a modern UI and Azure cloud services for AI & data storage." +description: "Numa is a .NET 9 Blazor Web App that uses CLEAN architecture principles with a mixture of WebAssembly & Server components, leveraging MudBlazor for a modern UI and Azure cloud services for AI & data storage." --- ## App Stack |Module|Purpose| |:--|:--| -|[Blazor Server App (.NET 8)](https://learn.microsoft.com/en-us/aspnet/core/blazor/?view=aspnetcore-8.0)|C# and Razor components with a persistent SignalR connection to the server| +|[Blazor Web App (.NET 9)](https://learn.microsoft.com/en-us/aspnet/core/blazor/?view=aspnetcore-9.0)|CLEAN architecture with C# and Razor components using a mixture of WebAssembly & Server rendering modes| |[MudBlazor](https://mudblazor.com/)|UI Library for Blazor apps| |[Azure SDK](https://learn.microsoft.com/en-us/dotnet/azure/sdk/azure-sdk-for-dotnet)|C# classes to access key vault secrets| |[Azure OpenAI SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.openai-readme?view=azure-dotnet)|C# classes to stream AI-generated responses| diff --git a/documentation/components/app.mdx b/documentation/components/app.mdx index edc7a9b..b6c03c8 100644 --- a/documentation/components/app.mdx +++ b/documentation/components/app.mdx @@ -1,6 +1,6 @@ --- title: App -description: "`App.razor` is the root component of the Blazor Server application; it loads CSS, JS, and handles cascading authentication to the app." +description: "`App.razor` is the root component of the Blazor Web App; it loads CSS, JS, handles cascading authentication, and configures rendering modes for the application." --- Component Name: `App.razor` @@ -17,14 +17,21 @@ protected override async Task OnInitializedAsync() } ``` -## Cascading Authentication +## Cascading Authentication & Rendering Modes ```csharp //Authentication is provided by the Microsoft Entra Id service registered in Program.cs - //Setting the render mode of the Blazor app + //Setting the render mode of the Blazor Web App to automatically choose between Server and WebAssembly //JS scripts -``` \ No newline at end of file +``` + +## Rendering Mode Configuration +The Blazor Web App supports multiple rendering modes: +- **InteractiveAuto**: Automatically chooses between Server and WebAssembly based on component needs +- **InteractiveServer**: Server-side rendering with SignalR for real-time features +- **InteractiveWebAssembly**: Client-side execution for rich interactions +- **Static SSR**: Server-side rendering for fast initial loads \ No newline at end of file From c8407344694dbccd10f7fc7117120024ef575d84 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Jun 2025 19:36:44 +0000 Subject: [PATCH 3/4] Update models and services documentation to reflect CLEAN architecture principles Co-authored-by: gmcgrady <129766830+gmcgrady@users.noreply.github.com> --- documentation/models/numamodels.mdx | 28 +++++++++++-------- documentation/services/numaservices.mdx | 36 +++++++++++++++---------- 2 files changed, 39 insertions(+), 25 deletions(-) diff --git a/documentation/models/numamodels.mdx b/documentation/models/numamodels.mdx index 16e4439..418bb7d 100644 --- a/documentation/models/numamodels.mdx +++ b/documentation/models/numamodels.mdx @@ -1,16 +1,22 @@ --- title: Numa.Models -description: "Models are C# classes that define Numa's data structure & mirror how the data is stored in Azure Cosmos DB." +description: "Models are C# classes that define Numa's domain entities and represent the core business objects following CLEAN architecture principles." --- -## Models -|Model|Purpose| +## Domain Models +These models represent the core business entities of the Numa domain: + +|Model|Purpose|Domain Concept| +|:--|:--|:--| +|[User](user)|Represents a user object|User identity and profile| +|[Conversation](conversation)|Represents a conversation object|Chat session between user and AI| +|[Message](message)|Represents a message object associated with a conversation|Individual communication unit| +|[Citation](citation)|Represents a citation object associated with a RAG response|Source reference for AI responses| +|[Sermon Collection](sermoncollection)|Represents a curated collection of sermons|Content organization and access| +|[Group](group)|Represents a group of users (for security purposes)|Access control and permissions| +|[Admin Settings](adminsettings)|Represents an object containing admin settings|Application configuration| + +## Data Access +|Component|Purpose| |:--|:--| -|[User](user)|Represents a user object| -|[Conversation](conversation)|Represents a conversation object| -|[Message](message)|Represents a message object associated with a conversation| -|[Citation](citation)|Represents a citation object associated with a RAG response| -|[Sermon Collection](sermoncollection)|Represents a curated collection of sermons| -|[Group](group)|Represents a group of users (for security purposes)| -|[Admin Settings](adminsettings)|Represents an object containing admin settings| -|[Numa Context](numacontext)|Represents Numa's Cosmos DB context| \ No newline at end of file +|[Numa Context](numacontext)|Represents Numa's Cosmos DB context for data persistence| \ No newline at end of file diff --git a/documentation/services/numaservices.mdx b/documentation/services/numaservices.mdx index 98705d2..1207171 100644 --- a/documentation/services/numaservices.mdx +++ b/documentation/services/numaservices.mdx @@ -1,18 +1,26 @@ --- title: Numa.Services -description: "Services encapsulate logic related to data access, external APIs, and app functionality." +description: "Services implement business logic and external integrations following CLEAN architecture principles, with clear separation between application and infrastructure concerns." --- -## Services -|Service|Purpose| -|:--|:--| -|[User Service](userservice)|Handles logic related to the `User` model| -|[Conversation Service](conversationservice)|Handles logic related to the `Conversation` model| -|[Message Service](messageservice)|Handles logic related to the `Message` model| -|[Citation Service](citationservice)|Handles logic related to the `Citation` model| -|[Sermon Collection Service](sermoncollectionservice)|Handles logic related to the `SermonCollection` model| -|[Group Service](groupservice)|Handles logic related to the `Group` model| -|[Admin Settings Service](adminsettingsservice)|Handles logic related to the `AdminSettings` model & the configuration of app-wide settings| -|[Chat Service](chatservice)|Wraps the Azure OpenAI SDK for generative AI responses| -|[Markdown Service](markdownservice)|Wraps the MarkDig SDK for handling markdown| -|[Document Storage Service](documentstorageservice)|Wraps the Azure Storage SDK for storing & managing blobs| \ No newline at end of file +## Application Services +These services contain business logic and orchestrate data operations: + +|Service|Purpose|Layer| +|:--|:--|:--| +|[User Service](userservice)|Handles business logic related to the `User` model|Application| +|[Conversation Service](conversationservice)|Handles business logic related to the `Conversation` model|Application| +|[Message Service](messageservice)|Handles business logic related to the `Message` model|Application| +|[Citation Service](citationservice)|Handles business logic related to the `Citation` model|Application| +|[Sermon Collection Service](sermoncollectionservice)|Handles business logic related to the `SermonCollection` model|Application| +|[Group Service](groupservice)|Handles business logic related to the `Group` model|Application| +|[Admin Settings Service](adminsettingsservice)|Handles business logic related to the `AdminSettings` model & app-wide configuration|Application| + +## Infrastructure Services +These services handle external integrations and wrap third-party SDKs: + +|Service|Purpose|Layer| +|:--|:--|:--| +|[Chat Service](chatservice)|Wraps the Azure OpenAI SDK for generative AI responses|Infrastructure| +|[Markdown Service](markdownservice)|Wraps the MarkDig SDK for handling markdown|Infrastructure| +|[Document Storage Service](documentstorageservice)|Wraps the Azure Storage SDK for storing & managing blobs|Infrastructure| \ No newline at end of file From 6bb0a88811e993e7666f613956e656e13454721e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 13 Jun 2025 19:51:35 +0000 Subject: [PATCH 4/4] Add v1.1.0 release notes for latest develop branch commit Co-authored-by: gmcgrady <129766830+gmcgrady@users.noreply.github.com> --- docs.json | 1 + releasenotes/releases.mdx | 1 + releasenotes/v1.1.0.mdx | 68 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 70 insertions(+) create mode 100644 releasenotes/v1.1.0.mdx diff --git a/docs.json b/docs.json index 6542b98..4857856 100644 --- a/docs.json +++ b/docs.json @@ -70,6 +70,7 @@ "group": "Release Notes", "pages": [ "releasenotes/releases", + "releasenotes/v1.1.0", "releasenotes/v1.1.0-beta", "releasenotes/v1.0.0" ] diff --git a/releasenotes/releases.mdx b/releasenotes/releases.mdx index 1b87dac..c9fa7ac 100644 --- a/releasenotes/releases.mdx +++ b/releasenotes/releases.mdx @@ -5,5 +5,6 @@ description: "" | Version | Status | Release Date | |:---|:---|:---| +| [v1.1.0](v1.1.0) | Stable | Latest (develop branch) | | [v1.1.0-beta](v1.1.0-beta) | Development | Expected May 2025 | | [v1.0.0](v1.0.0) | Stable | 03-10-2025 | \ No newline at end of file diff --git a/releasenotes/v1.1.0.mdx b/releasenotes/v1.1.0.mdx new file mode 100644 index 0000000..974a39f --- /dev/null +++ b/releasenotes/v1.1.0.mdx @@ -0,0 +1,68 @@ +--- +title: v1.1.0 +description: "v1.1.0 introduces .NET 9 Blazor Web App with CLEAN architecture principles, mixed rendering modes, and enhanced UI components." +--- + +## Major Architecture Upgrade + +### .NET 9 Blazor Web App Migration +- **Framework Upgrade**: Migrated from .NET 8 Blazor Server App to .NET 9 Blazor Web App +- **CLEAN Architecture**: Implemented comprehensive CLEAN architecture principles with clear layer separation: + - **Presentation Layer**: Razor components and pages + - **Application Layer**: Business logic services + - **Domain Layer**: Core business entities and models + - **Infrastructure Layer**: External service integrations + +### Enhanced Rendering Capabilities +- **Mixed Rendering Modes**: Added support for multiple rendering modes: + - `InteractiveAuto`: Automatic selection between Server and WebAssembly + - `InteractiveServer`: Real-time updates via SignalR + - `InteractiveWebAssembly`: Client-side execution + - Static SSR: Fast initial page loads +- **Performance Optimization**: Default rendering mode changed from `InteractiveServer` to `InteractiveAuto` for optimal performance + +## Component Enhancements + +### New Features +- 🚀 **Admin Group Management**: Admin users can now manage group members in admin settings +- 🚀 **File Management Interface**: Users with upload permissions can view files in sermon collections +- 🚀 **Creative Mode**: Users can adjust creativity levels of AI-generated responses +- 🚀 **Feedback System**: Message feedback system to monitor user sentiment + +### Improvements +- ⚡ **Configuration Management**: Replaced hard-coded values in `Numa.Services` & `Numa.Components` with configurable admin settings +- ⚡ **Service Architecture**: Enhanced dependency injection with proper interface abstractions +- ⚡ **SDK Wrapping**: All external SDKs now wrapped in custom services for better maintainability + +## Bug Fixes +- 🐛 **Query Type Configuration**: Fixed issue with `DataSourceQueryType.VectorSemanticHybrid` as default `QueryType` in `ChatService.cs` +- 🐛 **WebSocket Latency**: Resolved erratic typing behavior in text boxes due to WebSocket latency +- 🐛 **Input Clearing**: Fixed latency between sending messages and clearing input text box + +## Technical Improvements + +### Architecture & Code Quality +- **Service Layer Separation**: Clear distinction between Application and Infrastructure services +- **Domain Models**: Enhanced business entity representations with proper domain concepts +- **Interface Design**: Improved service interfaces following SOLID principles +- **Project Structure**: Reorganized solution to reflect CLEAN architecture layers + +### Cloud Integration +- **Azure Key Vault**: Enhanced secret management with proper authentication flows +- **Azure Services**: Optimized integrations with OpenAI, Storage, and AI Search services +- **Configuration**: Improved environment-based configuration management + +## Developer Experience +- **Documentation**: Comprehensive architecture documentation with CLEAN principles +- **Code Organization**: Clear separation of concerns across all layers +- **Dependency Injection**: Simplified service registration patterns +- **SDK Management**: Consistent wrapping of external dependencies + +## Breaking Changes +- **Rendering Mode**: Default rendering mode changed from `InteractiveServer` to `InteractiveAuto` +- **Service Registration**: Updated service registration patterns in `Program.cs` +- **Architecture**: Restructured project to follow CLEAN architecture principles + +--- + +**Full Changelog**: [View on GitHub](https://github.com/secc/Numa/compare/v1.0.0...develop) \ No newline at end of file