From d576b7cb19becb21296f23e35b3393445e9af6bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Jasi=C5=84ski?= Date: Tue, 5 May 2026 20:05:44 +0200 Subject: [PATCH] refactor: remove legacy backlog files and update gitea MCP server documentation --- BACKLOG.md | 87 ---------------------------- GEMINI.md | 2 +- backlog-ai.md | 87 ---------------------------- backlog-code-review.md | 127 ----------------------------------------- backlog-identity.md | 46 --------------- 5 files changed, 1 insertion(+), 348 deletions(-) delete mode 100644 BACKLOG.md delete mode 100644 backlog-ai.md delete mode 100644 backlog-code-review.md delete mode 100644 backlog-identity.md diff --git a/BACKLOG.md b/BACKLOG.md deleted file mode 100644 index bdc0889..0000000 --- a/BACKLOG.md +++ /dev/null @@ -1,87 +0,0 @@ -# πŸ“‘ Project Backlog: Nexus AI E-Reader (Mockup Implementation) -**Architecture Framework:** .NET 10 | Blazor Component Model | CQRS with MediatR | FluentResult | Mapster - ---- - -## 🟒 PHASE 1: Infrastructure & Design Tokens -*Goal: Prepare the clean architecture foundation and the visual DNA.* - -### [TASK-01] Solution & Directory Structure Setup -- **Action:** Create the folder structure: `/src` for projects, `/tests` for unit/integration tests. -- **Details:** Initialize `NexusReader.Web` (Blazor), `NexusReader.Application`, `NexusReader.Domain`, and `NexusReader.Infrastructure`. -- **DoD:** Solution compiles with strict folder separation. - -### [TASK-02] Core Library Integration -- **Action:** Install and configure LuckyPennySoftware.MediatR, Mapster, and FluentResult. -- **Details:** - Setup `MappingConfig` for Mapster in the Application layer. - - Implement a `BaseHandler` that returns `Result`. -- **DoD:** A sample Query returns a `Success` Result via MediatR. - -### [TASK-03] Nexus Neon Design System -- **Action:** Implement global CSS variables in `app.css` and base Atoms. -- **Details:** - Variables: `--nexus-neon: #00ff99`, `--nexus-bg: #121212`, `--nexus-card: #1e1e1e`. - - Components: `NexusButton.razor`, `NexusTypography.razor` (handling Serif for ebook, Sans for UI). -- **DoD:** Variables are accessible via all scoped CSS files. - ---- - -## πŸ”΅ PHASE 2: Seamless Reader & AI Assistant (Left Side / Inline) -*Goal: Implement the ebook reading logic and the "Vertical Flow" AI injection.* - -### [TASK-04] ReaderCanvas & Dynamic Content Injection -- **Action:** Create `ReaderCanvas.razor` to render ebook text. -- **Details:** - Logic to split text into blocks. - - Implementation of an "Injection Point" system where `AiAssistantBubble.razor` can be rendered inline between paragraphs. -- **Mockup Match:** Text must use the high-contrast Serif font from the mockup. - -### [TASK-05] AiAssistantBubble Component -- **Action:** Implement the AI chat bubble with a robot avatar. -- **Details:** - Scoped CSS for the glowing border and dark glassmorphism background. - - Parameters for `DialogueText` and `ActionButtons` ("PokaΕΌ wiΔ™cej", "RozwiΔ…ΕΌ quiz"). - - Integration with Semantic Kernel for streaming text. -- **DoD:** Bubble appears smoothly in the text flow without absolute positioning. - ---- - -## 🟑 PHASE 3: Knowledge Graph & Brain (Right Side / Flow) -*Goal: Implement the D3.js graph and the "You are here" logic.* - -### [TASK-06] D3.js Knowledge Graph Bridge -- **Action:** Implement `KnowledgeGraph.razor` with JS Interop. -- **Details:** - ES6 Module `knowledgeGraph.js` using D3.js v7. - - SVG ViewBox scaling for portrait orientation. - - Implementation of the "TU JESTEŚ" (You Are Here) pulsing label on the active node. -- **DoD:** Clicking a node in JS triggers a C# EventCallback via `DotNetObjectReference`. - -### [TASK-07] Semantic Mapping Service -- **Action:** Create the `GetKnowledgeGraphQuery` (CQRS). -- **Details:** - Service uses Semantic Kernel to extract nodes from the current chapter. - - Mapster maps the AI raw response to the `GraphViewModel`. -- **DoD:** Graph updates dynamically when the reader moves to a new chapter. - ---- - -## 🟠 PHASE 4: Verification & Mobile Polish -*Goal: Implement the quiz module and cross-platform readiness.* - -### [TASK-08] KnowledgeCheck (Quiz) Module -- **Action:** Implement the `SubmitAnswerCommand` using MediatR. -- **Details:** - UI: `KnowledgeCheck.razor` with radio buttons and a "WyΕ›lij" (Submit) button. - - Logic: Handler returns `Result` (Success/Failure) via FluentResult. - - Mapster: Map `QuizDto` to `QuizViewModel`. -- **Mockup Match:** Neon highlight on the selected/correct answer. - -### [TASK-09] Persistence & Cross-Platform (Hybrid) -- **Action:** Implement `IPlatformService` for Android/iOS support. -- **Details:** - Safe-area-insets implementation for notches. - - `BrowserStorage` implementation of `AppState` to save progress. - - Haptic feedback abstraction (trigger vibration on correct answer). -- **DoD:** App maintains graph state after a manual refresh. - ---- - -## πŸ› οΈ Instructions for NexusArchitect -1. **Vertical Flow Priority:** Ensure that the AI assistant and the Graph never overlay text. Use `Flexbox` or `Grid` for a single, continuous scrollable column in portrait mode. -2. **Result Pattern:** Every single Mediator Handler **must** return `FluentResults.Result`. -3. **Mapster:** Perform all DTO-to-UI mappings in the Query/Command Handlers, not in the Razor components. -4. **Isolated Styles:** All specific CSS for the Neon effect must be in `.razor.css` files. \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md index b470556..1eb465d 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -46,4 +46,4 @@ version: 1.0 > [!IMPORTANT] > **Git Workflow & Integration** -> All tasks originating from the repository must be performed on a separate branch. To connect to the Git repository, use the `gitea-ovh` MCP server. +> All tasks originating from the repository must be performed on a separate branch. To connect to the Git repository, use the `gitea` MCP server. diff --git a/backlog-ai.md b/backlog-ai.md deleted file mode 100644 index 44e13e8..0000000 --- a/backlog-ai.md +++ /dev/null @@ -1,87 +0,0 @@ -# πŸ€– LLM Agent Implementation Backlog: AI Semantic Integration - -**Project Context:** .NET 10, EF Core (SQLite), `Microsoft.Extensions.AI`, [`GeminiDotnet`](https://github.com/rabuckley/GeminiDotnet). -**Core Goal:** Integrate Gemini 1.5 Flash with a persistent Semantic Cache to minimize API costs and latency. - ---- - -## πŸ—οΈ Phase 1: Persistence & Domain Layer -**Objective:** Define the storage schema to prevent redundant AI calls. - -### Task 1.1: Create `SemanticKnowledgeCache` Entity -* **Target Folder:** `Core/Entities` or `Infrastructure/Persistence/Entities`. -* **Requirements:** - * Create a class `SemanticKnowledgeCache`. - * **Properties:** - * `string ContentHash` (Key, Fixed length 64). - * `string JsonData` (Required, stores the serialized AI output). - * `string ModelId` (Default: "gemini-1.5-flash"). - * `string PromptVersion` (Default: "1.0"). - * `DateTime CreatedAt` (UTC). -* **LLM Instructions:** "Generate an EF Core entity for SemanticKnowledgeCache. Ensure `ContentHash` has a Unique Index for O(1) lookups." - -### Task 1.2: Implement Hashing Utility -* **Target Folder:** `Core/Helpers` or `Infrastructure/Security`. -* **Requirements:** - * Create `ContentHasher` class. - * Method `string ComputeHash(string input)`. - * **Logic:** Normalize input (Trim, lower-case) -> Compute SHA-256 -> Return Hex string. -* **LLM Instructions:** "Create a thread-safe utility to generate SHA-256 hashes from strings. Ensure it handles nulls and whitespace consistently." - ---- - -## 🧠 Phase 2: AI Client & Contract Definition -**Objective:** Set up the communication bridge with Google Gemini API using [`GeminiDotnet`](https://github.com/rabuckley/GeminiDotnet). - -### Task 2.1: Define Data Transfer Objects (DTOs) -* **Target Folder:** `NexusReader.Application/DTOs/AI`. -* **Requirements:** - * Define `KnowledgePacket` record containing `List` and `List`. - * Use `[JsonPropertyName]` attributes for strict JSON mapping. -* **LLM Instructions:** "Define immutable records for the AI response schema. Ensure they match the expected JSON structure from the system prompt." - -### Task 2.2: Infrastructure AI Client Setup -* **Target:** `NexusReader.Infrastructure/DependencyInjection.cs`. -* **Requirements:** - * Install `Microsoft.Extensions.AI` and `GeminiDotnet.Extensions.AI`. - * Register `IChatClient` using `GeminiChatClient`. - * Inject `ApiKey` from `IConfiguration`. -* **LLM Instructions:** "Register the `GeminiChatClient` in the DI container. Use the .NET 10 `AddChatClient` extension pattern." - ---- - -## βš™οΈ Phase 3: Service Orchestration (The "Smart" Logic) -**Objective:** Implement the caching proxy logic. - -### Task 3.1: Create `KnowledgeService` Implementation -* **Target Folder:** `Application/Services`. -* **Logic Flow:** - 1. `hash = ContentHasher.ComputeHash(inputText)`. - 2. `cached = await dbContext.Cache.FirstOrDefaultAsync(h => h.ContentHash == hash)`. - 3. If `cached` exists AND `PromptVersion` matches -> Deserialize and return. - 4. Else -> Call `IChatClient.CompleteAsync(...)`. - 5. Save result to DB with the hash -> Return. -* **LLM Instructions:** "Implement a service that acts as a proxy between the UI and the Gemini API. It must prioritize SQLite cache hits over API calls." - -### Task 3.2: System Prompt Engineering -* **Requirements:** - * Create a `PromptRegistry` class. - * **System Message:** "You are an educational assistant. Analyze the text and output ONLY valid minified JSON. Schema: { 'concepts': [], 'quizzes': [] }. Do not include markdown formatting like \` \` \` json." -* **LLM Instructions:** "Craft a high-precision system prompt for Gemini 1.5 Flash to ensure it returns parseable JSON without unnecessary tokens." - ---- - -## πŸ›‘οΈ Phase 4: Resilience & Optimization -**Objective:** Handle API limits and monitor performance. - -### Task 4.1: Resilience Pipeline (Polly) -* **Requirements:** - * Implement an `HttpRetry` policy specifically for `429 Too Many Requests`. - * Use Exponential Backoff with Jitter. -* **LLM Instructions:** "Add a resilience pipeline to the AI client using Polly. Handle rate-limiting gracefully to stay within the Gemini Free Tier limits." - -### Task 4.2: Request Pre-processing (Token Saving) -* **Logic:** - * Check input string length. - * If `length > threshold`, truncate or throw an error to prevent massive token spend. -* **LLM Instructions:** "Add a guard clause to the KnowledgeService to validate input size before calling the API. Log the estimated token count." diff --git a/backlog-code-review.md b/backlog-code-review.md deleted file mode 100644 index a316407..0000000 --- a/backlog-code-review.md +++ /dev/null @@ -1,127 +0,0 @@ -# πŸ” NexusReader Code Review Backlog - -## πŸ”΄ CRITICAL β€” Fix Before Next Release - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Removed `AddMediatR` from `AddApplication()` and `AddInfrastructure()`. Unified registration in Host (`Program.cs`, `MauiProgram.cs`). Added `IInfrastructureMarker` and a startup validation check in `Web.New` that throws `InvalidOperationException` if `AddInfrastructure` is missing. -- **DoD:** Application fails fast with a clear error if `AddInfrastructure()` is omitted. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Added `VerifyGroundednessAsync` to `IKnowledgeService` and implemented it in `KnowledgeService` (Infrastructure). Updated `VerifyGroundednessCommandHandler` in Application to inject `IKnowledgeService` instead of `IChatClient`. -- **DoD:** No `IChatClient` or `IEmbeddingGenerator` references remain in `NexusReader.Application`. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Threaded `tenantId` through all `IKnowledgeService` methods and `ProcessKnowledgeUnitsAsync`. Scoped `SemanticKnowledgeCache` and `KnowledgeUnit` lookups/writes to the provided `tenantId`. Updated API endpoints in `Program.cs` and `WasmKnowledgeService` to pass the authenticated user's `TenantId`. -- **DoD:** No hardcoded `"global"` TenantId in write paths. Extracted units are always scoped to the caller's tenant. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Changed `NexusUser.TenantId` from `Guid` to `string`. All entities now use `string` for `TenantId`, allowing the use of `"global"` as a sentinel value. -- **DoD:** All entities use the same `TenantId` type. All query filters are consistent. - ---- - -## 🟠 MAJOR β€” High Priority Fixes - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Added `File.Exists` check and granular `try-catch` around `EpubReader.ReadBookAsync` to prevent unhandled exceptions and provide descriptive error messages. -- **DoD:** Corrupted or missing files return `Result.Fail` instead of crashing. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Verified `IDbContextFactory` is correctly registered via `AddDbContextFactory` in `Infrastructure/DependencyInjection.cs`. -- **DoD:** Webhook and profile endpoints successfully resolve the factory. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Implemented `Coordinator.Clear()` (which calls `KnowledgeGraphService.Clear()`) in `ReaderCanvas.razor`'s `OnInitialized`. -- **DoD:** Stale graph data is cleared upon component initialization. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Created `UserProfileDto` to exclude sensitive internal IDs like `TenantId` and DB GUIDs. Updated `/identity/profile` endpoint to project into this DTO using `.Select()`. -- **DoD:** Internal IDs are no longer exposed in the profile API. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Added `HasIndex(x => x.TenantId)` to `NexusUser`, `Ebook`, and `QuizResult` in `AppDbContext`. `KnowledgeUnit` and `SemanticKnowledgeCache` already had them. -- **DoD:** Tenant-scoped queries are optimized via DB indexes. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Refactored `KnowledgeService.ProcessKnowledgeUnitsAsync` to pre-fetch all existing unit IDs in a single batch query, eliminating the N+1 `FindAsync` and `AnyAsync` calls. -- **DoD:** Batch processing performance is significantly improved. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Added `TenantId` property to `Ebook` entity with mandatory validation and index. Updated `AppDbContext` configuration. -- **DoD:** Ebooks are now isolated at the database level. - ---- - -- **Status:** βœ… Resolved (2026-05-03) -- **Implementation:** Added `TenantId` property to `QuizResult` entity with mandatory validation and index. -- **DoD:** Quiz results are now isolated at the database level. - ---- - -## 🟑 MINOR β€” Technical Debt & UX - -### [MN-01] Missing Logging in `KnowledgeCoordinator` -- **Action:** Add `ILogger` and log successful/failed extraction steps. - -### [MN-02] Hardcoded "Gemini-1.5-Flash" in Domain -- **File:** `Domain/Entities/SemanticKnowledgeCache.cs:20` -- **Action:** Move the default model ID to a constant in `AiSettings`. - -### [MN-03] UI: Shimmer Effect Lack Animation -- **File:** `UI.Shared/Components/Molecules/GroundednessBadge.razor` -- **Action:** Add `@keyframes` for the shimmer effect in CSS. - -### [MN-04] Identity: Google Callback Lack Error Handling -- **File:** `Web.New/Program.cs:340` -- **Action:** Better UI feedback when `ExternalLoginInfo` is null. - -### [MN-05] Tokenizer Initialization is Expensive -- **File:** `Infrastructure/Services/KnowledgeService.cs:43` -- **Action:** Make `_tokenizer` static or Singleton to avoid recreating it per request. - -### [MN-06] Mapster: Global Configuration Check -- **Action:** Ensure `TypeAdapterConfig.GlobalSettings.Scan(...)` is only called once. - -### [MN-07] SignalR: Missing Reconnection Logic -- **Action:** Implement `hubConnection.OnReconnected` in `SyncService.cs`. - -### [MN-10] Performance: Large EPUB Parsing -- **Action:** Implement streaming extraction for EPUBs over 10MB. - ---- - -## πŸ§ͺ TESTING β€” Coverage Gaps - -### [TEST-01] Integration Tests for KM-RAG Retrieval -- **Action:** Create `tests/NexusReader.IntegrationTests`. -- **Scenario:** Ingest a document, then verify that `GetRelevantContext` returns the correct snippets with tenant isolation active. - ---- - -## πŸ“Š Summary Table - -| Severity | Count | Status | -|---|---|---| -| πŸ”΄ Critical | 4 | 4 resolved | -| 🟠 Major | 8 | 8 resolved | -| 🟑 Minor | 8 | Unresolved | -| πŸ§ͺ Tests | 1 | Unresolved | -| **Total** | **21** | **12 resolved** | diff --git a/backlog-identity.md b/backlog-identity.md deleted file mode 100644 index b547acc..0000000 --- a/backlog-identity.md +++ /dev/null @@ -1,46 +0,0 @@ -# NexusArchitect - User Management Implementation Backlog - -**Project:** AI-Powered E-book Reader SaaS -**Architecture:** .NET 10, Blazor Hybrid, MAUI, ASP.NET Core Identity -**Primary Goal:** Implement a secure, scalable authentication and authorization system with SaaS-specific features (AI token limits, subscription tiers). - ---- - -## Phase 0: Backend Foundations (ASP.NET Core & EF Core) - -| ID | Task Title | Description & Acceptance Criteria | Tech Stack | -|:---|:---|:---|:---| -| **BACK-1** | Define Extended `NexusUser` Model | **Description:** Create a `NexusUser` class inheriting from `IdentityUser`. Add custom properties for SaaS logic.
**AC:**
- [x] Properties added: `AITokenLimit` (int), `AITokensUsed` (int), `TenantId` (Guid), `CurrentPlan` (string).
- [x] Model placed in `NexusArchitect.Core` project. | C# / Identity | -| **BACK-2** | Configure `ApplicationDbContext` for Identity | **Description:** Set up the DB context to inherit from `IdentityDbContext`.
**AC:**
- [x] Mapped standard Identity tables (Users, Roles, Claims).
- [x] Configured 1-to-Many relationship between `NexusUser` and `Ebooks`. | EF Core | -| **BACK-3** | Database Schema Migration | **Description:** Generate and apply the initial migration for Identity tables.
**AC:**
- [x] SQL schema contains all 7+ standard Identity tables.
- [x] Custom `NexusUser` fields are correctly reflected in the `AspNetUsers` table. | EF Core CLI | -| **BACK-4** | Implement Identity API Endpoints | **Description:** Enable native .NET Identity API endpoints in `Program.cs`.
**AC:**
- [x] Endpoints `/register`, `/login`, and `/refresh` are active.
- [x] Verified functionality via Swagger/OpenAPI. | ASP.NET Core | - ---- - -## Phase 1: Authentication & Authorization (UI & Logic) - -| ID | Task Title | Description & Acceptance Criteria | Tech Stack | -|:---|:---|:---|:---| -| **BACK-5** | Define Authorization Policies | **Description:** Implement Roles and Claims-based authorization (Free vs. Pro).
**AC:**
- [x] Created a `ProUser` policy.
- [x] Implemented a custom `Requirement` to check if `AITokensUsed < AITokenLimit`. | ASP.NET Core | -| **UI-1** | Implement Login Page (Blazor) | **Description:** Build the Login UI based on the Dark Mode mockup.
**AC:**
- [x] Theme: Dark mode with neon green accents.
- [x] Components: Email/Password fields, "Remember Me" toggle, "Login" button.
- [x] Integrates with `AuthenticationStateProvider`. | Blazor / CSS | -| **UI-2** | Google OAuth2 Integration | **Description:** Configure external login provider (Google) in the backend and UI.
**AC:**
- [x] Users can sign in via Google button.
- [x] New users are automatically provisioned in the database upon successful OAuth. | OAuth / Google Cloud | -| **UI-3** | Implement Registration Flow | **Description:** Create a registration form calling the `/register` endpoint.
**AC:**
- [x] Validation: Email format, password complexity (min 8 chars, uppercase, digit).
- [x] Proper error handling for existing users. | Blazor | - ---- - -## Phase 2: User Management & SaaS Scaling (Profile & Mobile) - -| ID | Task Title | Description & Acceptance Criteria | Tech Stack | -|:---|:---|:---|:---| -| **UI-4** | User Profile & Dashboard | **Description:** Build the User Profile UI focusing on "Active Learning" metrics.
**AC:**
- [x] Displays: Token usage bar (Used/Limit), average quiz score, and last read book.
- [x] Links to subscription management. | Blazor | -| **MAUI-1** | Mobile Auth Integration (Blazor Hybrid) | **Description:** Ensure the authentication state is shared and persists in the MAUI container.
**AC:**
- [x] Securely store JWT tokens in `SecureStorage`.
- [x] Automatic login on app launch if token is valid. | MAUI / Blazor Hybrid | -| **MAUI-2** | Secure Session Persistence | **Description:** Implement long-lived session management using encrypted device storage.
**AC:**
- [x] Refresh tokens implementation for mobile.
- [x] "Stay Signed In" functionality. | MAUI / Identity | -| **INTEG-1** | Stripe Subscription Webhooks | **Description:** Sync Identity Claims with Stripe subscription status.
**AC:**
- [x] Webhook updates `AITokenLimit` when a "Pro" plan is purchased.
- [x] User is downgraded back to "Free" limit upon cancellation. | Stripe SDK / .NET | - ---- - -## Definition of Done (DoD) -- All code follows the **NexusArchitect** architectural guidelines. -- Unit tests cover core Identity logic (e.g., token limit validation). -- UI is responsive and consistent with the provided Dark Mode design. -- Documentation updated with setup instructions for new developers. \ No newline at end of file