NewDocV1

2026-05-25 14:02:56 +02:00
parent 29bd42e52e
commit 758b152a0c
1798 changed files with 1991205 additions and 481068 deletions
@@ -0,0 +1,108 @@
+# VerifyGroundednessCommand
+
+- File ID: file:2eckht:verifygroundednesscommand-cs
+- Path: NexusReader.Application/Commands/AI/VerifyGroundednessCommand.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines a MediatR command and its handler that delegates verification of an answer's groundedness to the application's IKnowledgeService.
+
+## Key Details
+
+This file is a thin MediatR command handler that forwards the request to IKnowledgeService.VerifyGroundednessAsync without additional logic or validation. GroundednessResult is returned inside a FluentResults.Result wrapper.
+
+## Symbols
+
+- VerifyGroundednessCommandHandler: Defines a MediatR command and its handler that delegates verification of an answer's groundedness to the application's IKnowledgeService.
+- VerifyGroundednessCommandHandler(): Constructor that receives and stores the IKnowledgeService dependency via DI.
+- Handle(): Handles the VerifyGroundednessCommand by calling the knowledge service to verify groundedness and returning the service result.
+- VerifyGroundednessCommand: Command DTO carrying an answer, context, and tenant id to be verified for groundedness.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Application.Abstractions.Services (IKnowledgeService)
+- dependency-target: FluentResults (Result<>)
+- dependency-target: MediatR (IRequestHandler/IRequest)
+- call-target: unknown
+- interaction-target: await _knowledgeService.VerifyGroundednessAsync(...) and return its Result<GroundednessResult>
+
+## Coverage
+
+- Symbols: 4
+- Executable symbols: 2
+- Executable symbols with control flow: 2
+- Grounded edges: 4
+- Unresolved references: 5
+- Control-flow fragments: 2
+- Unresolved jumps: 1
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 3
+
+## Control Flow Fragments
+
+- VerifyGroundednessCommandHandler: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- Handle: 7 nodes, 6 edges, 1 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### VerifyGroundednessCommand Neighborhood
+
+```mermaid
+flowchart LR
+    class_109ebx2_verifygroundednesscommandhandler("VerifyGroundednessCommandHandler")
+    file_2eckht_verifygroundednesscommand_cs("VerifyGroundednessCommand")
+    method_10jkor8_verifygroundednesscommandhandler[["VerifyGroundednessCommandHandler()"]]
+    method_1fl6nt2_handle[["Handle()"]]
+    type_6i8iop_verifygroundednesscommand[/"VerifyGroundednessCommand"/]
+```
+
+### VerifyGroundednessCommand Execution Overview
+
+```mermaid
+flowchart TD
+    class_109ebx2_verifygroundednesscommandhandler("VerifyGroundednessCommandHandler")
+    method_10jkor8_verifygroundednesscommandhandler[["VerifyGroundednessCommandHandler()"]]
+    method_1fl6nt2_handle[["Handle()"]]
+    unresolved_unresolved_1d98nmq_interaction_target{"Unresolved: await _knowledgeService.VerifyGroundednessAsync(...) and return its Result<GroundednessResult>"}
+    unresolved_unresolved_1x6qoip_call_target{"Unresolved: VerifyGroundednessAsync"}
+    class_109ebx2_verifygroundednesscommandhandler -->|contains| method_10jkor8_verifygroundednesscommandhandler
+    class_109ebx2_verifygroundednesscommandhandler -->|contains| method_1fl6nt2_handle
+    class_109ebx2_verifygroundednesscommandhandler -->|unresolved interaction| unresolved_unresolved_1d98nmq_interaction_target
+    method_1fl6nt2_handle -->|unresolved call| unresolved_unresolved_1x6qoip_call_target
+```
+
+### Handle() Control Flow
+
+```mermaid
+flowchart TD
+    method_1fl6nt2_handle__call_20_VerifyGroundednessAsync[["VerifyGroundednessAsync"]]
+    method_1fl6nt2_handle__action_20_async_return_20__linear("Return result from external service")
+    method_1fl6nt2_handle__action_20_handle_await_20_0__await[["Waits for async work"]]
+    method_1fl6nt2_handle__entry(["Handle entry"])
+    method_1fl6nt2_handle__action_20_external_call_20__linear("Delegate groundedness verification to knowledge service")
+    method_1fl6nt2_handle__action_20_handle_return_20_1__return(["Returns result"])
+    method_1fl6nt2_handle__implicit_return(["return"])
+    method_1fl6nt2_handle__action_20_async_return_20__linear -->|next| method_1fl6nt2_handle__action_20_external_call_20__linear
+    method_1fl6nt2_handle__action_20_external_call_20__linear -->|request.Answer, request.Context, request.TenantId, cancellationToken| method_1fl6nt2_handle__call_20_VerifyGroundednessAsync
+    method_1fl6nt2_handle__action_20_handle_await_20_0__await -->|return| method_1fl6nt2_handle__action_20_handle_return_20_1__return
+    method_1fl6nt2_handle__action_20_handle_return_20_1__return -->|next| method_1fl6nt2_handle__action_20_async_return_20__linear
+    method_1fl6nt2_handle__call_20_VerifyGroundednessAsync -->|return| method_1fl6nt2_handle__implicit_return
+    method_1fl6nt2_handle__entry -->|next| method_1fl6nt2_handle__action_20_handle_await_20_0__await
+```
+
+## Diagram Validation
+
+- Status: warn
+- Warning: Control-flow extraction left 1 unresolved jumps.
@@ -0,0 +1,56 @@
+# IngestEbookCommand
+
+- File ID: file:1tk8lz4:ingestebookcommand-cs
+- Path: NexusReader.Application/Commands/Library/IngestEbookCommand.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines a CQRS command DTO used to ingest a new ebook into the library, carrying ebook metadata and binary payloads (cover and EPUB) across the application boundary.
+
+## Key Details
+
+Record implements ICommand<Guid>; TenantId defaults to "global" enabling single-tenant default behavior; carries binary payloads (CoverImage and EpubData) so consumers will perform IO/persistence when handling this command.
+
+## Symbols
+
+- IngestEbookCommand: Defines a CQRS command DTO used to ingest a new ebook into the library, carrying ebook metadata and binary payloads (cover and EPUB) across the application boundary.
+- IngestEbookCommand: Represents the data required to ingest an ebook (metadata + binary payloads) and is dispatched as a command returning a Guid identifier.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 2
+- Executable symbols: 0
+- Executable symbols with control flow: 0
+- Grounded edges: 2
+- Unresolved references: 0
+- Control-flow fragments: 0
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 1
+- Generated diagrams: 1
+
+## Diagrams
+
+### IngestEbookCommand Neighborhood
+
+```mermaid
+flowchart LR
+    class_byhisx_ingestebookcommand("IngestEbookCommand")
+    file_1tk8lz4_ingestebookcommand_cs("IngestEbookCommand")
+    type_dgxlfz_ingestebookcommand[/"IngestEbookCommand"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,202 @@
+# IngestEbookCommandHandler
+
+- File ID: file:lqr4h8:ingestebookcommandhandler-cs
+- Path: NexusReader.Application/Commands/Library/IngestEbookCommandHandler.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Handles ingestion of an uploaded ebook: saves files to storage, resolves/creates author, creates Ebook entity and persists it to the repository, returning the new Ebook Id or a failure result.
+
+## Key Details
+
+Two-phase ingestion: first persist files to storage (with I/O error mapping), then create/resolve author and persist Ebook in DB (with DB error mapping). Uses MediatR IRequestHandler and repository/service abstractions to keep side effects encapsulated.
+
+## Symbols
+
+- IngestEbookCommandHandler: Handles ingestion of an uploaded ebook: saves files to storage, resolves/creates author, creates Ebook entity and persists it to the repository, returning the new Ebook Id or a failure result.
+- IngestEbookCommandHandler(): Constructor; receives repository and storage service via DI and assigns to fields.
+- Handle(): Orchestrates ebook ingestion: saves epub/cover to storage, resolves or creates author, constructs Ebook entity, persists it and returns the created Ebook Id or failure.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Application.Abstractions.Persistence/IEbookRepository.cs
+- dependency-target: NexusReader.Application.Abstractions.Services/IBookStorageService.cs
+- dependency-target: NexusReader.Domain.Entities/Ebook.cs
+- dependency-target: NexusReader.Domain.Entities/Author.cs
+- call-target: NexusReader.Application.Abstractions.Services/IBookStorageService.cs
+- call-target: NexusReader.Application.Abstractions.Services/IBookStorageService.cs
+- call-target: NexusReader.Application.Abstractions.Persistence/IEbookRepository.cs
+- call-target: NexusReader.Application.Abstractions.Persistence/IEbookRepository.cs
+- call-target: NexusReader.Application.Abstractions.Persistence/IEbookRepository.cs
+- call-target: NexusReader.Application.Abstractions.Persistence/IEbookRepository.cs
+- interaction-target: var author = await _ebookRepository.FindAuthorByNameAsync(authorName, cancellationToken);
+- interaction-target: Calls AddEbook and SaveChangesAsync to persist the new entity
+
+## Coverage
+
+- Symbols: 3
+- Executable symbols: 2
+- Executable symbols with control flow: 2
+- Grounded edges: 3
+- Unresolved references: 12
+- Control-flow fragments: 2
+- Unresolved jumps: 6
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 3
+
+## Control Flow Fragments
+
+- IngestEbookCommandHandler: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- Handle: 40 nodes, 42 edges, 6 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IngestEbookCommandHandler Neighborhood
+
+```mermaid
+flowchart LR
+    class_1kfw737_ingestebookcommandhandler("IngestEbookCommandHandler")
+    file_lqr4h8_ingestebookcommandhandler_cs("IngestEbookCommandHandler")
+    method_gy7qh_handle[["Handle()"]]
+    method_jlw375_ingestebookcommandhandler[["IngestEbookCommandHandler()"]]
+```
+
+### IngestEbookCommandHandler Execution Overview
+
+```mermaid
+flowchart TD
+    class_1kfw737_ingestebookcommandhandler("IngestEbookCommandHandler")
+    method_gy7qh_handle[["Handle()"]]
+    method_jlw375_ingestebookcommandhandler[["IngestEbookCommandHandler()"]]
+    unresolved_unresolved_100nowa_interaction_target{"Unresolved: var author = await _ebookRepository.FindAuthorByNameAsync(authorName, cancellationToken);"}
+    unresolved_unresolved_1foxj00_call_target{"Unresolved: FindAuthorByNameAsync"}
+    unresolved_unresolved_1hkxnh3_call_target{"Unresolved: SaveEbookAsync"}
+    unresolved_unresolved_1jnlalo_call_target{"Unresolved: SaveCoverAsync"}
+    unresolved_unresolved_1o7j1ya_call_target{"Unresolved: AddAuthor"}
+    unresolved_unresolved_6ikjt_call_target{"Unresolved: AddEbook"}
+    unresolved_unresolved_syqfv0_call_target{"Unresolved: SaveChangesAsync"}
+    unresolved_unresolved_yctv9m_interaction_target{"Unresolved: Calls AddEbook and SaveChangesAsync to persist the new entity"}
+    class_1kfw737_ingestebookcommandhandler -->|contains| method_gy7qh_handle
+    class_1kfw737_ingestebookcommandhandler -->|contains| method_jlw375_ingestebookcommandhandler
+    class_1kfw737_ingestebookcommandhandler -->|unresolved interaction| unresolved_unresolved_100nowa_interaction_target
+    class_1kfw737_ingestebookcommandhandler -->|unresolved interaction| unresolved_unresolved_yctv9m_interaction_target
+    method_gy7qh_handle -->|unresolved call| unresolved_unresolved_1foxj00_call_target
+    method_gy7qh_handle -->|unresolved call| unresolved_unresolved_1hkxnh3_call_target
+    method_gy7qh_handle -->|unresolved call| unresolved_unresolved_1jnlalo_call_target
+    method_gy7qh_handle -->|unresolved call| unresolved_unresolved_1o7j1ya_call_target
+    method_gy7qh_handle -->|unresolved call| unresolved_unresolved_6ikjt_call_target
+    method_gy7qh_handle -->|unresolved call| unresolved_unresolved_syqfv0_call_target
+```
+
+### Handle() Control Flow
+
+_Warnings: diagram method_gy7qh_handle__fragment_diagram exceeds preferred complexity thresholds (40 nodes, 42 edges)._
+
+```mermaid
+---
+config:
+  flowchart:
+    defaultRenderer: "elk"
+---
+flowchart TD
+    method_gy7qh_handle__call_31_SaveEbookAsync[["SaveEbookAsync"]]
+    method_gy7qh_handle__call_33_SaveCoverAsync[["SaveCoverAsync"]]
+    method_gy7qh_handle__call_52_FindAuthorByNameAsync[["FindAuthorByNameAsync"]]
+    method_gy7qh_handle__call_56_AddAuthor[["AddAuthor"]]
+    method_gy7qh_handle__call_72_AddEbook[["AddEbook"]]
+    method_gy7qh_handle__call_73_SaveChangesAsync[["SaveChangesAsync"]]
+    method_gy7qh_handle__action_28_handle_try_28_0__try("Begins protected execution")
+    method_gy7qh_handle__action_28_try_catch_28__linear("Storage save with I/O and generic exception handling")
+    method_gy7qh_handle__action_31_handle_await_31_1__await[["Waits for async work"]]
+    method_gy7qh_handle__action_32_branch_32__condition{"request.CoverImage != null && request.CoverImage.Length > 0"}
+    method_gy7qh_handle__action_32_branch_32__false("no cover (coverUrl = null)")
+    method_gy7qh_handle__action_32_branch_32__merge("merge")
+    method_gy7qh_handle__action_32_branch_32__true("save cover and set coverUrl")
+    method_gy7qh_handle__action_33_handle_await_33_2__await[["Waits for async work"]]
+    method_gy7qh_handle__action_36_handle_catch_36_3__catch("catch IOException ex")
+    method_gy7qh_handle__action_40_handle_catch_40_5__catch("catch Exception ex")
+    method_gy7qh_handle__action_45_handle_try_45_7__try("Begins protected execution")
+    method_gy7qh_handle__action_48_guard_clause_48__condition{"string.IsNullOrWhiteSpace(request.AuthorName)"}
+    method_gy7qh_handle__action_48_guard_clause_48__false("use trimmed request.AuthorName")
+    method_gy7qh_handle__action_48_guard_clause_48__merge("merge")
+    method_gy7qh_handle__action_48_guard_clause_48__true("use 'Unknown Author'")
+    method_gy7qh_handle__action_52_external_repository_read_52__linear("Find author case-insensitively (via repository)")
+    method_gy7qh_handle__action_52_handle_await_52_9__await[["Waits for async work"]]
+    method_gy7qh_handle__action_53_branch_fallback_53__linear("Create missing author")
+    method_gy7qh_handle__action_53_handle_branch_53_10__condition{"author == null"}
+    method_gy7qh_handle__action_53_handle_branch_53_10__false("false")
+    method_gy7qh_handle__action_53_handle_branch_53_10__merge("merge")
+    method_gy7qh_handle__action_53_handle_branch_53_10__true("true")
+    method_gy7qh_handle__action_60_entity_construction_60__linear("Construct Ebook entity")
+    method_gy7qh_handle__action_73_handle_await_73_11__await[["Waits for async work"]]
+    method_gy7qh_handle__action_77_handle_catch_77_13__catch("catch Exception ex")
+    method_gy7qh_handle__action_77_try_catch_77__linear("Database error handling during persistence")
+    method_gy7qh_handle__entry(["Handle entry"])
+    method_gy7qh_handle__action_52_handle_repository_read_52_8__linear[("Reads repository or persistence state")]
+    method_gy7qh_handle__action_72_repository_write_72__linear[("Add ebook and persist")]
+    method_gy7qh_handle__action_38_handle_return_38_4__return(["Returns result"])
+    method_gy7qh_handle__action_42_handle_return_42_6__return(["Returns result"])
+    method_gy7qh_handle__action_75_handle_return_75_12__return(["Returns result"])
+    method_gy7qh_handle__action_75_return_75__return(["Return success with Ebook Id"])
+    method_gy7qh_handle__action_79_handle_return_79_14__return(["Returns result"])
+    method_gy7qh_handle__action_28_handle_try_28_0__try -->|next| method_gy7qh_handle__action_31_handle_await_31_1__await
+    method_gy7qh_handle__action_28_try_catch_28__linear -->|next| method_gy7qh_handle__action_28_handle_try_28_0__try
+    method_gy7qh_handle__action_31_handle_await_31_1__await -->|request.EpubData, filename = request.Title .epub| method_gy7qh_handle__call_31_SaveEbookAsync
+    method_gy7qh_handle__action_32_branch_32__condition -->|no cover coverUrl = null| method_gy7qh_handle__action_32_branch_32__false
+    method_gy7qh_handle__action_32_branch_32__condition -->|save cover and set coverUrl| method_gy7qh_handle__action_32_branch_32__true
+    method_gy7qh_handle__action_32_branch_32__false -->|next| method_gy7qh_handle__action_32_branch_32__merge
+    method_gy7qh_handle__action_32_branch_32__merge -->|next| method_gy7qh_handle__action_33_handle_await_33_2__await
+    method_gy7qh_handle__action_32_branch_32__true -->|next| method_gy7qh_handle__action_32_branch_32__merge
+    method_gy7qh_handle__action_33_handle_await_33_2__await -->|request.CoverImage, filename = request.Title _cover.jpg called only if CoverImage present| method_gy7qh_handle__call_33_SaveCoverAsync
+    method_gy7qh_handle__action_36_handle_catch_36_3__catch -->|return| method_gy7qh_handle__action_38_handle_return_38_4__return
+    method_gy7qh_handle__action_38_handle_return_38_4__return -->|exception| method_gy7qh_handle__action_40_handle_catch_40_5__catch
+    method_gy7qh_handle__action_40_handle_catch_40_5__catch -->|return| method_gy7qh_handle__action_42_handle_return_42_6__return
+    method_gy7qh_handle__action_42_handle_return_42_6__return -->|next| method_gy7qh_handle__action_45_handle_try_45_7__try
+    method_gy7qh_handle__action_45_handle_try_45_7__try -->|next| method_gy7qh_handle__action_48_guard_clause_48__condition
+    method_gy7qh_handle__action_48_guard_clause_48__condition -->|use trimmed request.AuthorName| method_gy7qh_handle__action_48_guard_clause_48__false
+    method_gy7qh_handle__action_48_guard_clause_48__condition -->|transforms input| method_gy7qh_handle__action_48_guard_clause_48__true
+    method_gy7qh_handle__action_48_guard_clause_48__false -->|next| method_gy7qh_handle__action_48_guard_clause_48__merge
+    method_gy7qh_handle__action_48_guard_clause_48__merge -->|next| method_gy7qh_handle__action_52_handle_await_52_9__await
+    method_gy7qh_handle__action_48_guard_clause_48__true -->|next| method_gy7qh_handle__action_48_guard_clause_48__merge
+    method_gy7qh_handle__action_52_external_repository_read_52__linear -->|calls| method_gy7qh_handle__call_52_FindAuthorByNameAsync
+    method_gy7qh_handle__action_52_handle_await_52_9__await -->|next| method_gy7qh_handle__action_52_handle_repository_read_52_8__linear
+    method_gy7qh_handle__action_52_handle_repository_read_52_8__linear -->|next| method_gy7qh_handle__action_52_external_repository_read_52__linear
+    method_gy7qh_handle__action_53_branch_fallback_53__linear -->|new Author Name = authorName when author not found| method_gy7qh_handle__call_56_AddAuthor
+    method_gy7qh_handle__action_53_handle_branch_53_10__condition -->|false| method_gy7qh_handle__action_53_handle_branch_53_10__false
+    method_gy7qh_handle__action_53_handle_branch_53_10__condition -->|true| method_gy7qh_handle__action_53_handle_branch_53_10__true
+    method_gy7qh_handle__action_53_handle_branch_53_10__false -->|next| method_gy7qh_handle__action_53_handle_branch_53_10__merge
+    method_gy7qh_handle__action_53_handle_branch_53_10__merge -->|next| method_gy7qh_handle__action_53_branch_fallback_53__linear
+    method_gy7qh_handle__action_53_handle_branch_53_10__true -->|next| method_gy7qh_handle__action_53_handle_branch_53_10__merge
+    method_gy7qh_handle__action_60_entity_construction_60__linear -->|next| method_gy7qh_handle__action_72_repository_write_72__linear
+    method_gy7qh_handle__action_72_repository_write_72__linear -->|ebook Ebook entity constructed from request + paths + metadata| method_gy7qh_handle__call_72_AddEbook
+    method_gy7qh_handle__action_73_handle_await_73_11__await -->|cancellationToken| method_gy7qh_handle__call_73_SaveChangesAsync
+    method_gy7qh_handle__action_75_handle_return_75_12__return -->|return| method_gy7qh_handle__action_75_return_75__return
+    method_gy7qh_handle__action_75_return_75__return -->|exception| method_gy7qh_handle__action_77_handle_catch_77_13__catch
+    method_gy7qh_handle__action_77_handle_catch_77_13__catch -->|next| method_gy7qh_handle__action_77_try_catch_77__linear
+    method_gy7qh_handle__action_77_try_catch_77__linear -->|return| method_gy7qh_handle__action_79_handle_return_79_14__return
+    method_gy7qh_handle__call_31_SaveEbookAsync -->|next| method_gy7qh_handle__action_32_branch_32__condition
+    method_gy7qh_handle__call_33_SaveCoverAsync -->|exception| method_gy7qh_handle__action_36_handle_catch_36_3__catch
+    method_gy7qh_handle__call_52_FindAuthorByNameAsync -->|next| method_gy7qh_handle__action_53_handle_branch_53_10__condition
+    method_gy7qh_handle__call_56_AddAuthor -->|next| method_gy7qh_handle__action_60_entity_construction_60__linear
+    method_gy7qh_handle__call_72_AddEbook -->|next| method_gy7qh_handle__action_73_handle_await_73_11__await
+    method_gy7qh_handle__call_73_SaveChangesAsync -->|return| method_gy7qh_handle__action_75_handle_return_75_12__return
+    method_gy7qh_handle__entry -->|next| method_gy7qh_handle__action_28_try_catch_28__linear
+```
+
+## Diagram Validation
+
+- Status: warn
+- Warning: Control-flow extraction left 6 unresolved jumps.
+- Warning: control-flow: diagram method_gy7qh_handle__fragment_diagram exceeds preferred complexity thresholds (40 nodes, 42 edges).
@@ -0,0 +1,54 @@
+# IngestEbookRequest
+
+- File ID: file:1qcpa0s:ingestebookrequest-cs
+- Path: NexusReader.Application/Commands/Library/IngestEbookRequest.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines a command/DTO that carries data needed to ingest an EPUB ebook into the application (title, author, cover image, base64 epub payload, and optional description).
+
+## Key Details
+
+Simple immutable record used as an application-layer command/DTO; no methods or behavior in this file.
+
+## Symbols
+
+- IngestEbookRequest: Payload/DTO for requesting ingestion of an ebook into the library.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 1
+- Executable symbols: 0
+- Executable symbols with control flow: 0
+- Grounded edges: 1
+- Unresolved references: 0
+- Control-flow fragments: 0
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 1
+- Generated diagrams: 1
+
+## Diagrams
+
+### IngestEbookRequest Neighborhood
+
+```mermaid
+flowchart LR
+    file_1qcpa0s_ingestebookrequest_cs("IngestEbookRequest")
+    type_1eqmnca_ingestebookrequest[/"IngestEbookRequest"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,60 @@
+# SubmitAnswerCommand
+
+- File ID: file:dskay:submitanswercommand-cs
+- Path: NexusReader.Application/Commands/Quiz/SubmitAnswerCommand.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines a simple application command that carries a quiz answer selection (selected index and correct index) to be handled by the application's command pipeline.
+
+## Key Details
+
+Minimal DTO/command type used to submit a quiz answer; no methods or behavior in this file beyond the record declaration.
+
+## Symbols
+
+- SubmitAnswerCommand: Defines a simple application command that carries a quiz answer selection (selected index and correct index) to be handled by the application's command pipeline.
+- SubmitAnswerCommand: Represents a CQRS command carrying the user's selected answer index and the correct answer index for a quiz question.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Application.Abstractions.Messaging
+
+## Coverage
+
+- Symbols: 2
+- Executable symbols: 0
+- Executable symbols with control flow: 0
+- Grounded edges: 2
+- Unresolved references: 1
+- Control-flow fragments: 0
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 1
+- Generated diagrams: 1
+
+## Diagrams
+
+### SubmitAnswerCommand Neighborhood
+
+```mermaid
+flowchart LR
+    class_cmiilf_submitanswercommand("SubmitAnswerCommand")
+    file_dskay_submitanswercommand_cs("SubmitAnswerCommand")
+    type_dvy3sa_submitanswercommand[/"SubmitAnswerCommand"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,120 @@
+# SubmitAnswerCommandHandler
+
+- File ID: file:hc4koi:submitanswercommandhandler-cs
+- Path: NexusReader.Application/Commands/Quiz/SubmitAnswerCommandHandler.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Handles quiz answer submission: verifies the selected answer against the correct index, triggers a platform vibration on correct answers, and returns a success/failure Result.
+
+## Key Details
+
+Uses FluentResults.Result for success/failure; relies on IPlatformService for haptic feedback; trivial constructor injects dependency (_platformService at line 9).
+
+## Symbols
+
+- SubmitAnswerCommandHandler: Handles quiz answer submission: verifies the selected answer against the correct index, triggers a platform vibration on correct answers, and returns a success/failure Result.
+- Handle(): Checks the submitted answer; vibrates the device and returns success if correct, otherwise returns a failure Result.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Application.Abstractions.Services/IPlatformService.cs
+- dependency-target: NexusReader.Application.Commands.Quiz/SubmitAnswerCommand.cs
+- call-target: NexusReader.Application.Abstractions.Services/IPlatformService.cs
+- interaction-target: _platformService.VibrateAsync(50) invoked to provide haptic feedback on correct answer
+
+## Coverage
+
+- Symbols: 2
+- Executable symbols: 1
+- Executable symbols with control flow: 1
+- Grounded edges: 2
+- Unresolved references: 4
+- Control-flow fragments: 1
+- Unresolved jumps: 1
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 3
+
+## Control Flow Fragments
+
+- Handle: 16 nodes, 17 edges, 1 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### SubmitAnswerCommandHandler Neighborhood
+
+```mermaid
+flowchart LR
+    class_andjgd_submitanswercommandhandler("SubmitAnswerCommandHandler")
+    file_hc4koi_submitanswercommandhandler_cs("SubmitAnswerCommandHandler")
+    method_e8akyb_handle[["Handle()"]]
+```
+
+### SubmitAnswerCommandHandler Execution Overview
+
+```mermaid
+flowchart TD
+    class_andjgd_submitanswercommandhandler("SubmitAnswerCommandHandler")
+    method_e8akyb_handle[["Handle()"]]
+    unresolved_unresolved_gdtbd6_call_target{"Unresolved: VibrateAsync"}
+    unresolved_unresolved_h9q2v9_interaction_target{"Unresolved: _platformService.VibrateAsync(50) invoked to provide haptic feedback on correct answer"}
+    class_andjgd_submitanswercommandhandler -->|contains| method_e8akyb_handle
+    class_andjgd_submitanswercommandhandler -->|unresolved interaction| unresolved_unresolved_h9q2v9_interaction_target
+    method_e8akyb_handle -->|unresolved call| unresolved_unresolved_gdtbd6_call_target
+```
+
+### Handle() Control Flow
+
+```mermaid
+flowchart TD
+    method_e8akyb_handle__call_20_VibrateAsync[["VibrateAsync"]]
+    method_e8akyb_handle__action_18_guard_clause_18__condition{"request.SelectedIndex == request.CorrectIndex"}
+    method_e8akyb_handle__action_18_guard_clause_18__false("incorrect -> return failure")
+    method_e8akyb_handle__action_18_guard_clause_18__merge("merge")
+    method_e8akyb_handle__action_18_guard_clause_18__true("correct -> vibrate and return success")
+    method_e8akyb_handle__action_18_handle_branch_18_0__condition{"request.SelectedIndex == request.CorrectIndex"}
+    method_e8akyb_handle__action_18_handle_branch_18_0__false("false")
+    method_e8akyb_handle__action_18_handle_branch_18_0__merge("merge")
+    method_e8akyb_handle__action_18_handle_branch_18_0__true("true")
+    method_e8akyb_handle__action_20_handle_await_20_1__await[["Waits for async work"]]
+    method_e8akyb_handle__entry(["Handle entry"])
+    method_e8akyb_handle__action_20_external_call_20__linear("platform vibrate")
+    method_e8akyb_handle__action_21_handle_return_21_2__return(["Returns result"])
+    method_e8akyb_handle__action_21_return_21__return(["success-return"])
+    method_e8akyb_handle__action_24_handle_return_24_3__return(["Returns result"])
+    method_e8akyb_handle__action_24_return_24__return(["failure-return"])
+    method_e8akyb_handle__action_18_guard_clause_18__condition -->|incorrect -> return failure| method_e8akyb_handle__action_18_guard_clause_18__false
+    method_e8akyb_handle__action_18_guard_clause_18__condition -->|correct -> vibrate and return success| method_e8akyb_handle__action_18_guard_clause_18__true
+    method_e8akyb_handle__action_18_guard_clause_18__false -->|next| method_e8akyb_handle__action_18_guard_clause_18__merge
+    method_e8akyb_handle__action_18_guard_clause_18__merge -->|next| method_e8akyb_handle__action_20_handle_await_20_1__await
+    method_e8akyb_handle__action_18_guard_clause_18__true -->|next| method_e8akyb_handle__action_18_guard_clause_18__merge
+    method_e8akyb_handle__action_18_handle_branch_18_0__condition -->|false| method_e8akyb_handle__action_18_handle_branch_18_0__false
+    method_e8akyb_handle__action_18_handle_branch_18_0__condition -->|true| method_e8akyb_handle__action_18_handle_branch_18_0__true
+    method_e8akyb_handle__action_18_handle_branch_18_0__false -->|next| method_e8akyb_handle__action_18_handle_branch_18_0__merge
+    method_e8akyb_handle__action_18_handle_branch_18_0__merge -->|next| method_e8akyb_handle__action_18_guard_clause_18__condition
+    method_e8akyb_handle__action_18_handle_branch_18_0__true -->|next| method_e8akyb_handle__action_18_handle_branch_18_0__merge
+    method_e8akyb_handle__action_20_external_call_20__linear -->|50 int milliseconds| method_e8akyb_handle__call_20_VibrateAsync
+    method_e8akyb_handle__action_20_handle_await_20_1__await -->|next| method_e8akyb_handle__action_20_external_call_20__linear
+    method_e8akyb_handle__action_21_handle_return_21_2__return -->|return| method_e8akyb_handle__action_24_handle_return_24_3__return
+    method_e8akyb_handle__action_21_return_21__return -->|return| method_e8akyb_handle__action_21_handle_return_21_2__return
+    method_e8akyb_handle__action_24_handle_return_24_3__return -->|return| method_e8akyb_handle__action_24_return_24__return
+    method_e8akyb_handle__call_20_VibrateAsync -->|return| method_e8akyb_handle__action_21_return_21__return
+    method_e8akyb_handle__entry -->|next| method_e8akyb_handle__action_18_handle_branch_18_0__condition
+```
+
+## Diagram Validation
+
+- Status: warn
+- Warning: Control-flow extraction left 1 unresolved jumps.
@@ -0,0 +1,56 @@
+# UpdateReadingProgressCommand
+
+- File ID: file:xocicc:updatereadingprogresscommand-cs
+- Path: NexusReader.Application/Commands/Sync/UpdateReadingProgressCommand.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines a MediatR command record that carries data for updating a user's reading progress for an ebook (used in sync operations).
+
+## Key Details
+
+Simple immutable record used as a MediatR IRequest<Result> to trigger update logic elsewhere; contains nullable fields for optional metadata and an excluded connection id to avoid echoing updates.
+
+## Symbols
+
+- UpdateReadingProgressCommand: Defines a MediatR command record that carries data for updating a user's reading progress for an ebook (used in sync operations).
+- UpdateReadingProgressCommand: Carries parameters required to update a user's reading progress for an ebook in synchronization workflows.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 2
+- Executable symbols: 0
+- Executable symbols with control flow: 0
+- Grounded edges: 2
+- Unresolved references: 0
+- Control-flow fragments: 0
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 1
+- Generated diagrams: 1
+
+## Diagrams
+
+### UpdateReadingProgressCommand Neighborhood
+
+```mermaid
+flowchart LR
+    class_1onwz_updatereadingprogresscommand("UpdateReadingProgressCommand")
+    file_xocicc_updatereadingprogresscommand_cs("UpdateReadingProgressCommand")
+    type_lwz5af_updatereadingprogresscommand[/"UpdateReadingProgressCommand"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,200 @@
+# UpdateReadingProgressCommandHandler
+
+- File ID: file:13c5eb4:updatereadingprogresscommandhandler-cs
+- Path: NexusReader.Application/Commands/Sync/UpdateReadingProgressCommandHandler.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+MediatR handler that persists a user's reading position (User and Ebook entities) and broadcasts the progress update to other connected devices.
+
+## Key Details
+
+Checks for user presence and returns failure if missing; updates user and optionally ebook, saves changes and broadcasts update to other devices while honoring an excluded connection id; cancellationToken is propagated to async DB and broadcaster calls.
+
+## Symbols
+
+- UpdateReadingProgressCommandHandler: MediatR handler that persists a user's reading position (User and Ebook entities) and broadcasts the progress update to other connected devices.
+- UpdateReadingProgressCommandHandler(): Constructor: injects the AppDbContext factory and an ISyncBroadcaster.
+- Handle(): Load user and ebook, update reading progress and timestamps, persist changes, then broadcast the progress to other devices; returns success or failure if user missing.
+- UpdateReadingProgressCommandHandler: MediatR request handler that orchestrates persistence of reading progress and broadcasting updates.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Data.Persistence
+- dependency-target: NexusReader.Application.Abstractions.Messaging
+- call-target: unknown
+- call-target: NexusReader.Data.Persistence
+- call-target: NexusReader.Data.Persistence
+- call-target: NexusReader.Data.Persistence
+- call-target: unknown
+- interaction-target: var user = await context.Users.FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);
+- interaction-target: var ebook = await context.Ebooks.FirstOrDefaultAsync(e => e.Id == request.EbookId, cancellationToken);
+- interaction-target: await context.SaveChangesAsync(cancellationToken);
+- interaction-target: await _broadcaster.BroadcastProgressAsync(request.UserId, request.PageId, now, request.ExcludedConnectionId, cancellationToken);
+
+## Coverage
+
+- Symbols: 4
+- Executable symbols: 2
+- Executable symbols with control flow: 2
+- Grounded edges: 4
+- Unresolved references: 11
+- Control-flow fragments: 2
+- Unresolved jumps: 5
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 3
+
+## Control Flow Fragments
+
+- UpdateReadingProgressCommandHandler: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- Handle: 37 nodes, 40 edges, 5 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### UpdateReadingProgressCommandHandler Neighborhood
+
+```mermaid
+flowchart LR
+    class_2zm0w9_updatereadingprogresscommandhandler("UpdateReadingProgressCommandHandler")
+    file_13c5eb4_updatereadingprogresscommandhandler_cs("UpdateReadingProgressCommandHandler")
+    method_1ed5bhs_updatereadingprogresscommandhandler[["UpdateReadingProgressCommandHandler()"]]
+    method_1jqlijy_handle[["Handle()"]]
+    type_1hf0y4h_updatereadingprogresscommandhandler[/"UpdateReadingProgressCommandHandler"/]
+```
+
+### UpdateReadingProgressCommandHandler Execution Overview
+
+```mermaid
+flowchart TD
+    class_2zm0w9_updatereadingprogresscommandhandler("UpdateReadingProgressCommandHandler")
+    method_1ed5bhs_updatereadingprogresscommandhandler[["UpdateReadingProgressCommandHandler()"]]
+    method_1jqlijy_handle[["Handle()"]]
+    unresolved_unresolved_167ab0v_call_target{"Unresolved: AppDbContext.Users.FirstOrDefaultAsync"}
+    unresolved_unresolved_197jdm1_call_target{"Unresolved: IDbContextFactory<AppDbContext>.CreateDbContextAsync"}
+    unresolved_unresolved_1mfbj3f_interaction_target{"Unresolved: var ebook = await context.Ebooks.FirstOrDefaultAsync(e => e.Id == request.EbookId, cancellationToken);"}
+    unresolved_unresolved_1n2eft4_interaction_target{"Unresolved: await _broadcaster.BroadcastProgressAsync(request.UserId, request.PageId, now, request.ExcludedConnectionId, cancellationToken);"}
+    unresolved_unresolved_1rw33m5_call_target{"Unresolved: AppDbContext.SaveChangesAsync"}
+    unresolved_unresolved_35czhy_interaction_target{"Unresolved: var user = await context.Users.FirstOrDefaultAsync(u => u.Id == request.UserId, cancellationToken);"}
+    unresolved_unresolved_eld0cu_call_target{"Unresolved: AppDbContext.Ebooks.FirstOrDefaultAsync"}
+    unresolved_unresolved_jg0l72_call_target{"Unresolved: ISyncBroadcaster.BroadcastProgressAsync"}
+    unresolved_unresolved_k7dskm_interaction_target{"Unresolved: await context.SaveChangesAsync(cancellationToken);"}
+    class_2zm0w9_updatereadingprogresscommandhandler -->|contains| method_1ed5bhs_updatereadingprogresscommandhandler
+    class_2zm0w9_updatereadingprogresscommandhandler -->|contains| method_1jqlijy_handle
+    class_2zm0w9_updatereadingprogresscommandhandler -->|unresolved interaction| unresolved_unresolved_1mfbj3f_interaction_target
+    class_2zm0w9_updatereadingprogresscommandhandler -->|unresolved interaction| unresolved_unresolved_1n2eft4_interaction_target
+    class_2zm0w9_updatereadingprogresscommandhandler -->|unresolved interaction| unresolved_unresolved_35czhy_interaction_target
+    class_2zm0w9_updatereadingprogresscommandhandler -->|unresolved interaction| unresolved_unresolved_k7dskm_interaction_target
+    method_1jqlijy_handle -->|unresolved call| unresolved_unresolved_167ab0v_call_target
+    method_1jqlijy_handle -->|unresolved call| unresolved_unresolved_197jdm1_call_target
+    method_1jqlijy_handle -->|unresolved call| unresolved_unresolved_1rw33m5_call_target
+    method_1jqlijy_handle -->|unresolved call| unresolved_unresolved_eld0cu_call_target
+    method_1jqlijy_handle -->|unresolved call| unresolved_unresolved_jg0l72_call_target
+```
+
+### Handle() Control Flow
+
+_Warnings: diagram method_1jqlijy_handle__fragment_diagram exceeds preferred complexity thresholds (37 nodes, 40 edges)._
+
+```mermaid
+---
+config:
+  flowchart:
+    defaultRenderer: "elk"
+---
+flowchart TD
+    method_1jqlijy_handle__call_28_IDbContextFactory_AppDbContext_CreateDbContextAsync[["IDbContextFactory<AppDbContext>.CreateDbContextAsync"]]
+    method_1jqlijy_handle__call_30_AppDbContext_Users_FirstOrDefaultAsync[["AppDbContext.Users.FirstOrDefaultAsync"]]
+    method_1jqlijy_handle__call_40_AppDbContext_Ebooks_FirstOrDefaultAsync[["AppDbContext.Ebooks.FirstOrDefaultAsync"]]
+    method_1jqlijy_handle__call_49_AppDbContext_SaveChangesAsync[["AppDbContext.SaveChangesAsync"]]
+    method_1jqlijy_handle__call_52_ISyncBroadcaster_BroadcastProgressAsync[["ISyncBroadcaster.BroadcastProgressAsync"]]
+    method_1jqlijy_handle__action_28_handle_await_28_0__await[["Waits for async work"]]
+    method_1jqlijy_handle__action_28_resource_acquire_28__linear("Create DbContext scope")
+    method_1jqlijy_handle__action_30_handle_await_30_2__await[["Waits for async work"]]
+    method_1jqlijy_handle__action_31_guard_clause_31__condition{"user == null"}
+    method_1jqlijy_handle__action_31_guard_clause_31__false("continue")
+    method_1jqlijy_handle__action_31_guard_clause_31__merge("merge")
+    method_1jqlijy_handle__action_31_guard_clause_31__true("return Fail")
+    method_1jqlijy_handle__action_31_handle_branch_31_3__condition{"user == null"}
+    method_1jqlijy_handle__action_31_handle_branch_31_3__false("false")
+    method_1jqlijy_handle__action_31_handle_branch_31_3__merge("merge")
+    method_1jqlijy_handle__action_31_handle_branch_31_3__true("true")
+    method_1jqlijy_handle__action_37_field_update_37__linear("Update user reading pointers/timestamps")
+    method_1jqlijy_handle__action_40_handle_await_40_6__await[["Waits for async work"]]
+    method_1jqlijy_handle__action_41_branch_41__condition{"ebook != null"}
+    method_1jqlijy_handle__action_41_branch_41__false("skip")
+    method_1jqlijy_handle__action_41_branch_41__merge("merge")
+    method_1jqlijy_handle__action_41_branch_41__true("update ebook fields")
+    method_1jqlijy_handle__action_41_handle_branch_41_7__condition{"ebook != null"}
+    method_1jqlijy_handle__action_41_handle_branch_41_7__false("false")
+    method_1jqlijy_handle__action_41_handle_branch_41_7__merge("merge")
+    method_1jqlijy_handle__action_41_handle_branch_41_7__true("true")
+    method_1jqlijy_handle__action_49_handle_await_49_9__await[["Waits for async work"]]
+    method_1jqlijy_handle__action_49_persist_49__linear("Persist entity changes")
+    method_1jqlijy_handle__action_52_handle_await_52_10__await[["Waits for async work"]]
+    method_1jqlijy_handle__entry(["Handle entry"])
+    method_1jqlijy_handle__action_30_handle_repository_read_30_1__linear[("Reads repository or persistence state")]
+    method_1jqlijy_handle__action_40_handle_repository_read_40_5__linear[("Reads repository or persistence state")]
+    method_1jqlijy_handle__action_49_handle_repository_read_49_8__linear[("Reads repository or persistence state")]
+    method_1jqlijy_handle__action_52_external_call_52__linear("Broadcast progress to other devices")
+    method_1jqlijy_handle__action_33_handle_return_33_4__return(["Returns result"])
+    method_1jqlijy_handle__action_59_handle_return_59_11__return(["Returns result"])
+    method_1jqlijy_handle__action_59_return_59__return(["Return success result"])
+    method_1jqlijy_handle__action_28_handle_await_28_0__await -->|next| method_1jqlijy_handle__action_28_resource_acquire_28__linear
+    method_1jqlijy_handle__action_28_resource_acquire_28__linear -->|cancellationToken| method_1jqlijy_handle__call_28_IDbContextFactory_AppDbContext_CreateDbContextAsync
+    method_1jqlijy_handle__action_30_handle_await_30_2__await -->|next| method_1jqlijy_handle__action_30_handle_repository_read_30_1__linear
+    method_1jqlijy_handle__action_30_handle_repository_read_30_1__linear -->|predicate u => u.Id == request.UserId, cancellationToken| method_1jqlijy_handle__call_30_AppDbContext_Users_FirstOrDefaultAsync
+    method_1jqlijy_handle__action_31_guard_clause_31__condition -->|continue| method_1jqlijy_handle__action_31_guard_clause_31__false
+    method_1jqlijy_handle__action_31_guard_clause_31__condition -->|return Fail| method_1jqlijy_handle__action_31_guard_clause_31__true
+    method_1jqlijy_handle__action_31_guard_clause_31__false -->|next| method_1jqlijy_handle__action_31_guard_clause_31__merge
+    method_1jqlijy_handle__action_31_guard_clause_31__merge -->|next| method_1jqlijy_handle__action_31_handle_branch_31_3__condition
+    method_1jqlijy_handle__action_31_guard_clause_31__true -->|next| method_1jqlijy_handle__action_31_guard_clause_31__merge
+    method_1jqlijy_handle__action_31_handle_branch_31_3__condition -->|false| method_1jqlijy_handle__action_31_handle_branch_31_3__false
+    method_1jqlijy_handle__action_31_handle_branch_31_3__condition -->|true| method_1jqlijy_handle__action_31_handle_branch_31_3__true
+    method_1jqlijy_handle__action_31_handle_branch_31_3__false -->|next| method_1jqlijy_handle__action_31_handle_branch_31_3__merge
+    method_1jqlijy_handle__action_31_handle_branch_31_3__merge -->|return| method_1jqlijy_handle__action_33_handle_return_33_4__return
+    method_1jqlijy_handle__action_31_handle_branch_31_3__true -->|next| method_1jqlijy_handle__action_31_handle_branch_31_3__merge
+    method_1jqlijy_handle__action_33_handle_return_33_4__return -->|next| method_1jqlijy_handle__action_37_field_update_37__linear
+    method_1jqlijy_handle__action_37_field_update_37__linear -->|next| method_1jqlijy_handle__action_40_handle_await_40_6__await
+    method_1jqlijy_handle__action_40_handle_await_40_6__await -->|next| method_1jqlijy_handle__action_40_handle_repository_read_40_5__linear
+    method_1jqlijy_handle__action_40_handle_repository_read_40_5__linear -->|predicate e => e.Id == request.EbookId, cancellationToken| method_1jqlijy_handle__call_40_AppDbContext_Ebooks_FirstOrDefaultAsync
+    method_1jqlijy_handle__action_41_branch_41__condition -->|skip| method_1jqlijy_handle__action_41_branch_41__false
+    method_1jqlijy_handle__action_41_branch_41__condition -->|update ebook fields| method_1jqlijy_handle__action_41_branch_41__true
+    method_1jqlijy_handle__action_41_branch_41__false -->|next| method_1jqlijy_handle__action_41_branch_41__merge
+    method_1jqlijy_handle__action_41_branch_41__merge -->|next| method_1jqlijy_handle__action_41_handle_branch_41_7__condition
+    method_1jqlijy_handle__action_41_branch_41__true -->|next| method_1jqlijy_handle__action_41_branch_41__merge
+    method_1jqlijy_handle__action_41_handle_branch_41_7__condition -->|false| method_1jqlijy_handle__action_41_handle_branch_41_7__false
+    method_1jqlijy_handle__action_41_handle_branch_41_7__condition -->|true| method_1jqlijy_handle__action_41_handle_branch_41_7__true
+    method_1jqlijy_handle__action_41_handle_branch_41_7__false -->|next| method_1jqlijy_handle__action_41_handle_branch_41_7__merge
+    method_1jqlijy_handle__action_41_handle_branch_41_7__merge -->|next| method_1jqlijy_handle__action_49_handle_await_49_9__await
+    method_1jqlijy_handle__action_41_handle_branch_41_7__true -->|next| method_1jqlijy_handle__action_41_handle_branch_41_7__merge
+    method_1jqlijy_handle__action_49_handle_await_49_9__await -->|next| method_1jqlijy_handle__action_49_handle_repository_read_49_8__linear
+    method_1jqlijy_handle__action_49_handle_repository_read_49_8__linear -->|next| method_1jqlijy_handle__action_49_persist_49__linear
+    method_1jqlijy_handle__action_49_persist_49__linear -->|cancellationToken| method_1jqlijy_handle__call_49_AppDbContext_SaveChangesAsync
+    method_1jqlijy_handle__action_52_external_call_52__linear -->|request.UserId, request.PageId, now DateTime.UtcNow , request.ExcludedConnectionId, cancellationToken| method_1jqlijy_handle__call_52_ISyncBroadcaster_BroadcastProgressAsync
+    method_1jqlijy_handle__action_52_handle_await_52_10__await -->|next| method_1jqlijy_handle__action_52_external_call_52__linear
+    method_1jqlijy_handle__action_59_handle_return_59_11__return -->|return| method_1jqlijy_handle__action_59_return_59__return
+    method_1jqlijy_handle__call_28_IDbContextFactory_AppDbContext_CreateDbContextAsync -->|next| method_1jqlijy_handle__action_30_handle_await_30_2__await
+    method_1jqlijy_handle__call_30_AppDbContext_Users_FirstOrDefaultAsync -->|next| method_1jqlijy_handle__action_31_guard_clause_31__condition
+    method_1jqlijy_handle__call_40_AppDbContext_Ebooks_FirstOrDefaultAsync -->|next| method_1jqlijy_handle__action_41_branch_41__condition
+    method_1jqlijy_handle__call_49_AppDbContext_SaveChangesAsync -->|next| method_1jqlijy_handle__action_52_handle_await_52_10__await
+    method_1jqlijy_handle__call_52_ISyncBroadcaster_BroadcastProgressAsync -->|return| method_1jqlijy_handle__action_59_handle_return_59_11__return
+    method_1jqlijy_handle__entry -->|next| method_1jqlijy_handle__action_28_handle_await_28_0__await
+```
+
+## Diagram Validation
+
+- Status: warn
+- Warning: Control-flow extraction left 5 unresolved jumps.
+- Warning: control-flow: diagram method_1jqlijy_handle__fragment_diagram exceeds preferred complexity thresholds (37 nodes, 40 edges).