Initial commit: NexusArchitect Professional Workstation Overhaul
This commit is contained in:
Debian
@@ -0,0 +1,11 @@
|
||||
# Definition of Done (DoD)
|
||||
|
||||
1. **Architecture Compliance:** Feature follows CQRS flow. Logic is in Handlers. Result is wrapped in `Result<T>` from FluentResult.
|
||||
2. **Modularization:** Code is in `/src`, tests in `/tests`. Module-specific logic is isolated.
|
||||
3. **UI/UX Integrity:** - "Vertical Flow Check" passed (Assistant is part of the document stream, not an absolute pop-up).
|
||||
- No "Layout Shift" during AI content streaming.
|
||||
- Safe-area-insets respected for iOS/Android notches.
|
||||
4. **Code Quality:** C# 14 syntax used (Primary Constructors, etc.). Scoped CSS (.razor.css) implemented.
|
||||
5. **D3.js Performance:** JS Modules correctly disposed using `IAsyncDisposable`.
|
||||
6. **Persistence:** State survives manual page refresh (Local/Session Storage integration).
|
||||
7. **Mapping:** All entity-to-DTO conversions must use Mapster.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Agent Personas
|
||||
|
||||
## NexusArchitect
|
||||
- **Role:** Lead Architect & Creative Technologist (.NET 10 & Blazor)
|
||||
- **Persona:** Professional, precise, Senior Full-Stack Engineer focused on performance and "invisible UI".
|
||||
- **Architecture Role:** Lead Clean Architecture Specialist.
|
||||
- **Skills:** [nexus-clean-architecture, nexus-ui-engine, nexus-graph-d3, blazor-state-performance, blazor-hybrid-bridge, semantic-kernel-orchestrator]
|
||||
- **Technical Constraints:**
|
||||
- **Directory Structure:** Strict separation: `/src` (app code) and `/tests` (testing code) at solution root level.
|
||||
- **Patterns:** Mandatory CQRS via `MediatR` (LuckyPennySoftware implementation). No business logic in UI components.
|
||||
- **Error Handling:** All handlers must return `Result<T>` via `FluentResult`.
|
||||
- **Mapping:** Use `Mapster` exclusively. Zero-tolerance for AutoMapper.
|
||||
- **Platform:** Target .NET 10 with Native AOT compatibility in mind for mobile performance.
|
||||
- **Verification:** Follow "Verification-led development" — the agent must plan the test before writing the feature code.
|
||||
- **UI Framework:** Use Blazor Component Model. NEVER generate raw HTML/CSS; always use isolated Razor Components (.razor + .razor.css).
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: blazor-hybrid-bridge
|
||||
description: Standards for cross-platform compatibility (Web & MAUI Hybrid)
|
||||
---
|
||||
# Cross-Platform Integration
|
||||
|
||||
- **Abstraction Layer:**
|
||||
- Define all platform-specific logic in `NexusReader.Application/Abstractions/Services`.
|
||||
- Use `IPlatformService` for device hardware (Haptics, Orientation).
|
||||
- Use `INativeStorageService` for persistent key-value storage.
|
||||
|
||||
- **Implementation Strategy:**
|
||||
- **MAUI**: Implement in `NexusReader.Infrastructure.Mobile` using `Microsoft.Maui.*` APIs.
|
||||
- **Web**: Implement in `NexusReader.Web.Client` using `IJSRuntime` to access Browser APIs (e.g., `navigator.vibrate`, `localStorage`).
|
||||
|
||||
- **UI Compatibility:**
|
||||
- **Notch Support**: Use `env(safe-area-inset-top)` and other safe-area variables in CSS to prevent content from being hidden by hardware notches or home indicators.
|
||||
- **Touch Optimization**:
|
||||
- Use `user-select: none` for non-text interactive elements.
|
||||
- Ensure touch targets are at least `44x44px`.
|
||||
- Handle `active` states for immediate feedback on mobile.
|
||||
|
||||
- **Platform Detection:**
|
||||
- Use `IPlatformService.GetDeviceContext()` to determine `DeviceType` (Phone, Tablet, Desktop).
|
||||
- Adapt UI layout dynamically based on the context (e.g., sidebars on Tablet/Desktop, bottom navigation on Phone).
|
||||
|
||||
- **Dependency Injection:**
|
||||
- Register implementations in `MauiProgram.cs` for mobile and `Program.cs` for web.
|
||||
- Components in `NexusReader.UI.Shared` must only depend on the interfaces.
|
||||
|
||||
- **JS Interop Standards:**
|
||||
- Keep JS Interop calls isolated within service implementations.
|
||||
- Use `IJSObjectReference` for module-based scripts to avoid global namespace pollution.
|
||||
- Always provide a fallback or graceful failure for browsers that don't support specific APIs.
|
||||
@@ -0,0 +1,9 @@
|
||||
---
|
||||
name: blazor-state-performance
|
||||
description: Performance & State Persistence in Blazor .NET 10
|
||||
---
|
||||
# Performance Rules
|
||||
|
||||
- **State Management:** Use `PersistentComponentState` to sync data between prerendering and client-side.
|
||||
- **Optimization:** Use `@key` directive for list iterations to minimize DOM diffing.
|
||||
- **Memory:** Always implement `IAsyncDisposable` in components using JS Interop to prevent memory leaks.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
name: nexus-clean-architecture
|
||||
description: Clean Architecture & CQRS implementation for .NET 10 with Blazor Hybrid
|
||||
---
|
||||
# Clean Architecture Standards
|
||||
|
||||
- **Project Structure (Layered):**
|
||||
- `NexusReader.Domain`: Enterprise business rules (Entities, Value Objects, Domain Events).
|
||||
- `NexusReader.Application`: Application business rules (Commands, Queries, DTOs, Mappings, Interfaces).
|
||||
- `NexusReader.Infrastructure`: Data access, external services, and platform-specific implementations.
|
||||
- `NexusReader.UI.Shared`: UI logic and Blazor components.
|
||||
- `NexusReader.Maui` / `NexusReader.Web`: Platform host projects.
|
||||
|
||||
- **CQRS & Messaging:**
|
||||
- **MediatR**: Use standard `MediatR` for decoupling.
|
||||
- **Queries**: Read-only operations, return `Task<Result<T>>`.
|
||||
- **Commands**: State-changing operations, return `Task<Result>` or `Task<Result<T>>`.
|
||||
- **Handlers**: Located in `Application` layer, grouped by feature (e.g., `Queries/Reader/...`).
|
||||
|
||||
- **Functional Error Handling:**
|
||||
- Mandatory use of `FluentResults`.
|
||||
- No exceptions for business logic flow. Handlers must return `Result.Ok()` or `Result.Fail()`.
|
||||
|
||||
- **UI Architecture (Atomic Design):**
|
||||
- Components in `NexusReader.UI.Shared` must follow Atomic Design:
|
||||
- `Atoms`: Smallest functional units (Buttons, Inputs).
|
||||
- `Molecules`: Groups of atoms (Search Bar, Form Field).
|
||||
- `Organisms`: Complex UI sections (Navigation, Header).
|
||||
- `Pages`: Composed organisms forming a full view.
|
||||
|
||||
- **Object Mapping:**
|
||||
- Use `Mapster` for all DTO/Entity mappings.
|
||||
- Centralize configuration in `NexusReader.Application/Mappings/MappingConfig.cs`.
|
||||
- No `AutoMapper` allowed.
|
||||
|
||||
- **Cross-Platform Strategy:**
|
||||
- Maximize code sharing in `NexusReader.UI.Shared`.
|
||||
- Use `IPlatformService` (or similar abstractions) for native features, implemented in `Infrastructure.Mobile` or Maui projects.
|
||||
@@ -0,0 +1,11 @@
|
||||
---
|
||||
name: nexus-graph-d3
|
||||
description: D3.js standards for Knowledge Graph
|
||||
---
|
||||
# D3.js Standards
|
||||
|
||||
- **Data Exchange:** Use `System.Text.Json` with CamelCase naming.
|
||||
- **JS Interop:** Use ES6 modules and `IJSObjectReference`.
|
||||
- **Responsiveness:** SVG must use `viewBox` for fluid portrait scaling.
|
||||
- **Visuals:** Use CSS variables (`--nexus-neon`) for node styling.
|
||||
- **Events:** JS emits events (like `nodeClicked`) caught by Blazor via `DotNetObjectReference`.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: nexus-ui-engine
|
||||
description: Design System & Component rules for Blazor
|
||||
---
|
||||
# UI Standards
|
||||
|
||||
- **Atomic Design:**
|
||||
- Build reusable components in `NexusReader.UI.Shared/Components`.
|
||||
- `Atoms`: Base elements (`NexusButton`, `NexusIcon`, `NexusTypography`).
|
||||
- `Molecules`: Small groups (`AiAssistantBubble`, `KnowledgeCheck`).
|
||||
- `Organisms`: High-level sections (`KnowledgeGraph`, `ReaderCanvas`).
|
||||
|
||||
- **Styling & Isolation:**
|
||||
- Mandatory use of scoped CSS (`.razor.css`).
|
||||
- No global CSS except for design tokens in `app.css`.
|
||||
- Use `::deep` only when absolutely necessary to style child components.
|
||||
|
||||
- **Design System (Nexus Neon):**
|
||||
- **Color Palette:**
|
||||
- Primary Accent: `--nexus-neon` (`#00ff99`) - Used for borders, highlights, and icons.
|
||||
- Dark Mode: `--nexus-bg` (`#0a0a0a`), `--nexus-card` (`#141414`).
|
||||
- Light Mode: `--nexus-bg` (`#f8f9fa`), `--nexus-card` (`#ffffff`).
|
||||
- **Typography:**
|
||||
- UI Elements: `Inter` (Sans-Serif) for controls, menus, and labels.
|
||||
- Reading Content: `Merriweather` (Serif) for books and articles to ensure high readability.
|
||||
- **Effects:**
|
||||
- Subtle neon glows (`box-shadow: 0 0 15px rgba(0, 255, 153, 0.3)`).
|
||||
- Glassmorphism for overlays and modals.
|
||||
|
||||
- **Adaptive Layouts:**
|
||||
- Support `.platform-mobile` and `.platform-desktop` context classes.
|
||||
- Handle safe-area insets (`--safe-area-inset-*`) for mobile devices.
|
||||
|
||||
- **Accessibility (A11y):**
|
||||
- Touch Targets: Min `44x44px` on mobile (enforced via CSS variables).
|
||||
- Contrast: Minimum ratio of 4.5:1.
|
||||
- Semantic HTML: Use appropriate tags (`<button>`, `<article>`, `<nav>`).
|
||||
|
||||
- **Interactive Flow:**
|
||||
- AI Assistant interactions must be non-blocking and smoothly transition using CSS animations.
|
||||
- Interactive elements must have clear `:hover`, `:active`, and `:focus` states.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
name: semantic-kernel-orchestrator
|
||||
description: Integrating AI logic with .NET Semantic Kernel
|
||||
---
|
||||
# AI Implementation Rules
|
||||
|
||||
- **Kernel Setup:** Use Microsoft Semantic Kernel with .NET 10.
|
||||
- **Function Calling:** Define C# Plugins for "Graph Update" and "Quiz Generation".
|
||||
- **Streaming:** Implement `IAsyncEnumerable<string>` for real-time assistant responses in the UI.
|
||||
- **Context:** Ensure chapter metadata is passed as Semantic Memory.
|
||||
Reference in New Issue
Block a user