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,56 @@
+# ICommand
+
+- File ID: file:gg5jm5:icommand-cs
+- Path: NexusReader.Application/Abstractions/Messaging/ICommand.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines application-level command message contracts used with MediatR and FluentResults to represent commands that return operation Results.
+
+## Key Details
+
+Two marker interfaces mapping application commands to MediatR IRequest<Result> / IRequest<Result<T>> using FluentResults; no runtime logic in this file.
+
+## Symbols
+
+- ICommand: Marker interface for commands that produce a FluentResults.Result with no payload via MediatR.
+- ICommand<TResponse>: Generic marker interface for commands that produce a FluentResults.Result<TResponse> via MediatR.
+
+## 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
+
+### ICommand Neighborhood
+
+```mermaid
+flowchart LR
+    file_gg5jm5_icommand_cs("ICommand")
+    type_3fxux_icommand[/"ICommand"/]
+    type_l6ns3r_icommand_tresponse[/"ICommand<TResponse>"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,56 @@
+# ICommandHandler
+
+- File ID: file:kgb933:icommandhandler-cs
+- Path: NexusReader.Application/Abstractions/Messaging/ICommandHandler.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines application-level command handler contracts that adapt MediatR IRequestHandler to return FluentResults.Result wrappers for command operations.
+
+## Key Details
+
+Two small generic interfaces that adapt MediatR's IRequestHandler to return FluentResults.Result/Result<T>, serving as the application-layer command handler abstractions.
+
+## Symbols
+
+- ICommandHandler<TCommand>: Contract for handling command messages that returns a FluentResults.Result indicating success or failure.
+- ICommandHandler<TCommand, TResponse>: Contract for handling command messages that return a typed response wrapped in FluentResults.Result<TResponse>.
+
+## 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
+
+### ICommandHandler Neighborhood
+
+```mermaid
+flowchart LR
+    file_kgb933_icommandhandler_cs("ICommandHandler")
+    type_1a1s3lb_icommandhandler_tcommand_tresponse[/"ICommandHandler<TCommand, TResponse>"/]
+    type_l7ofd8_icommandhandler_tcommand[/"ICommandHandler<TCommand>"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,56 @@
+# IQuery
+
+- File ID: file:1k4g04u:iquery-cs
+- Path: NexusReader.Application/Abstractions/Messaging/IQuery.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Defines a generic marker/query contract for application queries that return a FluentResults-wrapped response via MediatR.
+
+## Key Details
+
+A tiny application-layer abstraction: a generic query contract that maps to MediatR IRequest<Result<TResponse>> enabling handlers to return FluentResults.
+
+## Symbols
+
+- IQuery<TResponse>: Defines a generic marker/query contract for application queries that return a FluentResults-wrapped response via MediatR.
+- IQuery<TResponse>: Marker interface representing a CQRS query that yields a Result-wrapped response handled by MediatR.
+
+## 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
+
+### IQuery Neighborhood
+
+```mermaid
+flowchart LR
+    class_4nrp60_iquery_tresponse("IQuery<TResponse>")
+    file_1k4g04u_iquery_cs("IQuery")
+    type_dj3u3k_iquery_tresponse[/"IQuery<TResponse>"/]
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,76 @@
+# IQueryHandler
+
+- File ID: file:ayj9r2:iqueryhandler-cs
+- Path: NexusReader.Application/Abstractions/Messaging/IQueryHandler.cs
+- Role: handler
+- Layer: application
+
+## Purpose
+
+Declares an application-layer abstraction for handling queries (CQRS) where handlers return a FluentResults.Result<TResponse> via MediatR.
+
+## Key Details
+
+Thin application-layer abstraction that binds the project's IQuery<TResponse> concept to MediatR's IRequestHandler and FluentResults.Result for uniform asynchronous query handling.
+
+## Symbols
+
+- IQueryHandler: Declares an application-layer abstraction for handling queries (CQRS) where handlers return a FluentResults.Result<TResponse> via MediatR.
+- Handle(): Implied contract method for handling a query and returning a Result-wrapped TResponse asynchronously (inherited from MediatR IRequestHandler).
+- IQueryHandler: Generic interface representing a query handler that processes a TQuery and returns a Result-wrapped TResponse using MediatR semantics.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: FluentResults
+- dependency-target: MediatR
+
+## Coverage
+
+- Symbols: 3
+- Executable symbols: 1
+- Executable symbols with control flow: 1
+- Grounded edges: 3
+- Unresolved references: 2
+- Control-flow fragments: 1
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- Handle: 4 nodes, 3 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IQueryHandler Neighborhood
+
+```mermaid
+flowchart LR
+    class_daunpv_iqueryhandler("IQueryHandler")
+    file_ayj9r2_iqueryhandler_cs("IQueryHandler")
+    method_7ldigq_handle[["Handle()"]]
+    type_tpv4sn_iqueryhandler[/"IQueryHandler"/]
+```
+
+### IQueryHandler Execution Overview
+
+```mermaid
+flowchart TD
+    class_daunpv_iqueryhandler("IQueryHandler")
+    method_7ldigq_handle[["Handle()"]]
+    class_daunpv_iqueryhandler -->|contains| method_7ldigq_handle
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,76 @@
+# ISyncBroadcaster
+
+- File ID: file:441s21:isyncbroadcaster-cs
+- Path: NexusReader.Application/Abstractions/Messaging/ISyncBroadcaster.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines an application-layer abstraction for broadcasting real-time synchronization and ingestion progress events to connected client devices (keeps Application layer decoupled from SignalR).
+
+## Key Details
+
+Interface intentionally defined in Application layer to avoid a direct dependency on SignalR; concrete implementations (in Infrastructure) will perform the actual SignalR or other transport operations.
+
+## Symbols
+
+- ISyncBroadcaster: Defines an application-layer abstraction for broadcasting real-time synchronization and ingestion progress events to connected client devices (keeps Application layer decoupled from SignalR).
+- BroadcastProgressAsync(): Declares an asynchronous broadcast of a user's reading progress to that user's devices, optionally excluding a specific connection.
+- BroadcastIngestionProgressAsync(): Declares an asynchronous broadcast of ingestion (background processing) status and progress to a specific user.
+- ISyncBroadcaster: Application-layer interface abstracting real-time broadcasting behavior (keeps handlers free of SignalR dependency).
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 4
+- Executable symbols: 2
+- Executable symbols with control flow: 2
+- Grounded edges: 4
+- Unresolved references: 0
+- Control-flow fragments: 2
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- BroadcastProgressAsync: 4 nodes, 3 edges, 0 jumps, 0 unsupported constructs
+- BroadcastIngestionProgressAsync: 4 nodes, 3 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### ISyncBroadcaster Neighborhood
+
+```mermaid
+flowchart LR
+    class_1kfpdx9_isyncbroadcaster("ISyncBroadcaster")
+    file_441s21_isyncbroadcaster_cs("ISyncBroadcaster")
+    method_3uewqk_broadcastprogressasync[["BroadcastProgressAsync()"]]
+    method_uqgfbl_broadcastingestionprogressasync[["BroadcastIngestionProgressAsync()"]]
+    type_dqp6wm_isyncbroadcaster[/"ISyncBroadcaster"/]
+```
+
+### ISyncBroadcaster Execution Overview
+
+```mermaid
+flowchart TD
+    class_1kfpdx9_isyncbroadcaster("ISyncBroadcaster")
+    method_3uewqk_broadcastprogressasync[["BroadcastProgressAsync()"]]
+    method_uqgfbl_broadcastingestionprogressasync[["BroadcastIngestionProgressAsync()"]]
+    class_1kfpdx9_isyncbroadcaster -->|contains| method_3uewqk_broadcastprogressasync
+    class_1kfpdx9_isyncbroadcaster -->|contains| method_uqgfbl_broadcastingestionprogressasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,93 @@
+# IEbookRepository
+
+- File ID: file:1hlb3r7:iebookrepository-cs
+- Path: NexusReader.Application/Abstractions/Persistence/IEbookRepository.cs
+- Role: repository
+- Layer: application
+
+## Purpose
+
+Defines the application-layer abstraction for ebook and author persistence operations (repository interface) so the Application layer can depend on an interface rather than EF Core or other infra implementations.
+
+## Key Details
+
+Interface lives in Application.Abstractions.Persistence to decouple application logic from EF Core; methods indicate staged add semantics and an explicit SaveChangesAsync for committing changes.
+
+## Symbols
+
+- IEbookRepository: Defines the application-layer abstraction for ebook and author persistence operations (repository interface) so the Application layer can depend on an interface rather than EF Core or other infra implementations.
+- FindAuthorByNameAsync(): Asynchronously finds an Author by name using a case-insensitive comparison.
+- AddAuthor(): Stages a new Author in the repository (adds to the change tracker / in-memory unit-of-work) but does not persist.
+- AddEbook(): Stages a new Ebook in the repository (adds to the change tracker / in-memory unit-of-work) but does not persist.
+- SaveChangesAsync(): Persists all staged changes to the underlying store and returns the number of affected entries.
+- IEbookRepository: Application-layer abstraction describing persistence operations for Ebook and Author to avoid a direct dependency on EF Core.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Domain/Entities
+- interaction-target: Task<Author?> FindAuthorByNameAsync(string name, CancellationToken cancellationToken = default);
+
+## Coverage
+
+- Symbols: 6
+- Executable symbols: 4
+- Executable symbols with control flow: 4
+- Grounded edges: 6
+- Unresolved references: 2
+- Control-flow fragments: 4
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- FindAuthorByNameAsync: 5 nodes, 4 edges, 0 jumps, 0 unsupported constructs
+- AddAuthor: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- AddEbook: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SaveChangesAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IEbookRepository Neighborhood
+
+```mermaid
+flowchart LR
+    class_ir9z2o_iebookrepository("IEbookRepository")
+    file_1hlb3r7_iebookrepository_cs("IEbookRepository")
+    method_2iyuvn_addauthor[["AddAuthor()"]]
+    method_3jcuy_findauthorbynameasync[["FindAuthorByNameAsync()"]]
+    method_grwwrg_savechangesasync[["SaveChangesAsync()"]]
+    method_ij0vl0_addebook[["AddEbook()"]]
+    type_sv23ol_iebookrepository[/"IEbookRepository"/]
+```
+
+### IEbookRepository Execution Overview
+
+```mermaid
+flowchart TD
+    class_ir9z2o_iebookrepository("IEbookRepository")
+    method_2iyuvn_addauthor[["AddAuthor()"]]
+    method_3jcuy_findauthorbynameasync[["FindAuthorByNameAsync()"]]
+    method_grwwrg_savechangesasync[["SaveChangesAsync()"]]
+    method_ij0vl0_addebook[["AddEbook()"]]
+    unresolved_unresolved_1bf761s_interaction_target{"Unresolved: Task<Author?> FindAuthorByNameAsync(string name, CancellationToken cancellationToken = default);"}
+    class_ir9z2o_iebookrepository -->|contains| method_2iyuvn_addauthor
+    class_ir9z2o_iebookrepository -->|contains| method_3jcuy_findauthorbynameasync
+    class_ir9z2o_iebookrepository -->|contains| method_grwwrg_savechangesasync
+    class_ir9z2o_iebookrepository -->|contains| method_ij0vl0_addebook
+    class_ir9z2o_iebookrepository -->|unresolved interaction| unresolved_unresolved_1bf761s_interaction_target
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,81 @@
+# IBillingService
+
+- File ID: file:rfn6bc:ibillingservice-cs
+- Path: NexusReader.Application/Abstractions/Services/IBillingService.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines an application-layer billing service abstraction that declares handlers for subscription updates and deletions (used by infrastructure implementations to react to Stripe/customer events).
+
+## Key Details
+
+Pure interface in the Application.Abstractions layer; no runtime behavior here—concrete implementations will perform persistence, external calls, mapping, and error handling and return FluentResults.Result.
+
+## Symbols
+
+- IBillingService: Defines an application-layer billing service abstraction that declares handlers for subscription updates and deletions (used by infrastructure implementations to react to Stripe/customer events).
+- HandleSubscriptionUpdatedAsync(): Contract for handling when a customer's subscription is created or updated (by Stripe or equivalent).
+- HandleSubscriptionDeletedAsync(): Contract for handling when a customer's subscription is deleted (cleanup or downgrade actions).
+- IBillingService: Abstraction exposing billing/subscription lifecycle handlers to be implemented by infrastructure or application services.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Domain.Entities (using)
+- dependency-target: FluentResults (using)
+
+## Coverage
+
+- Symbols: 4
+- Executable symbols: 2
+- Executable symbols with control flow: 2
+- Grounded edges: 4
+- Unresolved references: 2
+- Control-flow fragments: 2
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- HandleSubscriptionUpdatedAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- HandleSubscriptionDeletedAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IBillingService Neighborhood
+
+```mermaid
+flowchart LR
+    class_qlxnhj_ibillingservice("IBillingService")
+    file_rfn6bc_ibillingservice_cs("IBillingService")
+    method_16n7wyr_handlesubscriptiondeletedasync[["HandleSubscriptionDeletedAsync()"]]
+    method_1px2su2_handlesubscriptionupdatedasync[["HandleSubscriptionUpdatedAsync()"]]
+    type_dvqqtf_ibillingservice[/"IBillingService"/]
+```
+
+### IBillingService Execution Overview
+
+```mermaid
+flowchart TD
+    class_qlxnhj_ibillingservice("IBillingService")
+    method_16n7wyr_handlesubscriptiondeletedasync[["HandleSubscriptionDeletedAsync()"]]
+    method_1px2su2_handlesubscriptionupdatedasync[["HandleSubscriptionUpdatedAsync()"]]
+    class_qlxnhj_ibillingservice -->|contains| method_16n7wyr_handlesubscriptiondeletedasync
+    class_qlxnhj_ibillingservice -->|contains| method_1px2su2_handlesubscriptionupdatedasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,86 @@
+# IBookStorageService
+
+- File ID: file:9fivst:ibookstorageservice-cs
+- Path: NexusReader.Application/Abstractions/Services/IBookStorageService.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines an application-level abstraction for saving ebook and cover files, returning relative paths/URLs; implementations handle actual storage persistence.
+
+## Key Details
+
+Interface provides async contracts for saving ebooks and covers (byte[] or Stream) and returning relative paths/URLs; cover methods explicitly allow null return when no data is provided.
+
+## Symbols
+
+- IBookStorageService: Defines an application-level abstraction for saving ebook and cover files, returning relative paths/URLs; implementations handle actual storage persistence.
+- SaveEbookAsync(): Contract to save ebook binary data and return a relative path/URL.
+- SaveEbookAsync(): Contract to save ebook data from a Stream and return a relative path/URL.
+- SaveCoverAsync(): Contract to save cover image binary data and return a relative path/URL, or null if no cover provided.
+- SaveCoverAsync(): Contract to save cover image from a Stream and return a relative path/URL, or null if no cover provided.
+- IBookStorageService: Interface describing methods to persist ebooks and cover images and return their relative paths/URLs.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 6
+- Executable symbols: 4
+- Executable symbols with control flow: 4
+- Grounded edges: 6
+- Unresolved references: 0
+- Control-flow fragments: 4
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- SaveEbookAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SaveEbookAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SaveCoverAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SaveCoverAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IBookStorageService Neighborhood
+
+```mermaid
+flowchart LR
+    class_lhjxtl_ibookstorageservice("IBookStorageService")
+    file_9fivst_ibookstorageservice_cs("IBookStorageService")
+    method_1bjnsl7_saveebookasync[["SaveEbookAsync()"]]
+    method_1cxlt22_saveebookasync[["SaveEbookAsync()"]]
+    method_1pww9i7_savecoverasync[["SaveCoverAsync()"]]
+    method_1sosafx_savecoverasync[["SaveCoverAsync()"]]
+    type_gqvtnh_ibookstorageservice[/"IBookStorageService"/]
+```
+
+### IBookStorageService Execution Overview
+
+```mermaid
+flowchart TD
+    class_lhjxtl_ibookstorageservice("IBookStorageService")
+    method_1bjnsl7_saveebookasync[["SaveEbookAsync()"]]
+    method_1cxlt22_saveebookasync[["SaveEbookAsync()"]]
+    method_1pww9i7_savecoverasync[["SaveCoverAsync()"]]
+    method_1sosafx_savecoverasync[["SaveCoverAsync()"]]
+    class_lhjxtl_ibookstorageservice -->|contains| method_1bjnsl7_saveebookasync
+    class_lhjxtl_ibookstorageservice -->|contains| method_1cxlt22_saveebookasync
+    class_lhjxtl_ibookstorageservice -->|contains| method_1pww9i7_savecoverasync
+    class_lhjxtl_ibookstorageservice -->|contains| method_1sosafx_savecoverasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,75 @@
+# IEpubMetadataExtractor
+
+- File ID: file:vdwqp9:iepubmetadataextractor-cs
+- Path: NexusReader.Application/Abstractions/Services/IEpubMetadataExtractor.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines an application-layer abstraction for extracting metadata from an EPUB stream, returning a Result-wrapped LocalEpubMetadata asynchronously.
+
+## Key Details
+
+Interface exposes a single async method returning Task<Result<LocalEpubMetadata>>; implementation responsibilities include stream parsing and error/result handling via FluentResults.
+
+## Symbols
+
+- IEpubMetadataExtractor: Defines an application-layer abstraction for extracting metadata from an EPUB stream, returning a Result-wrapped LocalEpubMetadata asynchronously.
+- ExtractMetadataAsync(): Asynchronously extracts metadata from the provided EPUB stream and returns it wrapped in a FluentResults Result.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: FluentResults (NuGet/namespace)
+- dependency-target: NexusReader.Application.Queries.Reader (namespace containing LocalEpubMetadata)
+- dependency-target: System.IO (Stream)
+
+## Coverage
+
+- Symbols: 2
+- Executable symbols: 1
+- Executable symbols with control flow: 1
+- Grounded edges: 2
+- Unresolved references: 3
+- Control-flow fragments: 1
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- ExtractMetadataAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IEpubMetadataExtractor Neighborhood
+
+```mermaid
+flowchart LR
+    class_18sfucp_iepubmetadataextractor("IEpubMetadataExtractor")
+    file_vdwqp9_iepubmetadataextractor_cs("IEpubMetadataExtractor")
+    method_hwn6lg_extractmetadataasync[["ExtractMetadataAsync()"]]
+```
+
+### IEpubMetadataExtractor Execution Overview
+
+```mermaid
+flowchart TD
+    class_18sfucp_iepubmetadataextractor("IEpubMetadataExtractor")
+    method_hwn6lg_extractmetadataasync[["ExtractMetadataAsync()"]]
+    class_18sfucp_iepubmetadataextractor -->|contains| method_hwn6lg_extractmetadataasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,76 @@
+# IEpubReader
+
+- File ID: file:1mo9e25:iepubreader-cs
+- Path: NexusReader.Application/Abstractions/Services/IEpubReader.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines the application service contract for reading and parsing EPUB content for a specific ebook and chapter (async, tenant-aware).
+
+## Key Details
+
+Single-method interface; method is async, returns FluentResults-wrapped ReaderPageViewModel, accepts optional userId for tenant isolation and CancellationToken for cancellation.
+
+## Symbols
+
+- IEpubReader: Defines the application service contract for reading and parsing EPUB content for a specific ebook and chapter (async, tenant-aware).
+- GetEpubContentAsync(): Asynchronously retrieves parsed EPUB content blocks (a ReaderPageViewModel) for the specified ebook and zero-based chapter index, optionally scoped to a user and cancellable.
+- IEpubReader: Service contract that exposes EPUB reading/parsing behavior for ebooks and chapters.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: NexusReader.Application.Queries.Reader (ReaderPageViewModel referenced)
+- dependency-target: FluentResults (Result<T> usage)
+
+## Coverage
+
+- Symbols: 3
+- Executable symbols: 1
+- Executable symbols with control flow: 1
+- Grounded edges: 3
+- Unresolved references: 2
+- Control-flow fragments: 1
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- GetEpubContentAsync: 6 nodes, 5 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IEpubReader Neighborhood
+
+```mermaid
+flowchart LR
+    class_euc6fx_iepubreader("IEpubReader")
+    file_1mo9e25_iepubreader_cs("IEpubReader")
+    method_121clyd_getepubcontentasync[["GetEpubContentAsync()"]]
+    type_1yqx104_iepubreader[/"IEpubReader"/]
+```
+
+### IEpubReader Execution Overview
+
+```mermaid
+flowchart TD
+    class_euc6fx_iepubreader("IEpubReader")
+    method_121clyd_getepubcontentasync[["GetEpubContentAsync()"]]
+    class_euc6fx_iepubreader -->|contains| method_121clyd_getepubcontentasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,100 @@
+# IIdentityService
+
+- File ID: file:1ud0jop:iidentityservice-cs
+- Path: NexusReader.Application/Abstractions/Services/IIdentityService.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines the identity/authentication abstraction for the Application layer: registration, login/logout, profile retrieval, token refresh, and an event for state invalidation.
+
+## Key Details
+
+This file only declares the IIdentityService interface and an OnStateInvalidated event; concrete implementations elsewhere will perform orchestration, external calls, persistence, and error handling.
+
+## Symbols
+
+- OnStateInvalidated(): Event triggered when identity/authentication state becomes invalid and consumers should react (e.g., clear state or re-authenticate).
+- RegisterAsync(): Registers a new user account using email and password and returns a success/failure Result.
+- LoginAsync(): Authenticates a user with credentials and optional persistence (rememberMe) and returns a Result.
+- LogoutAsync(): Logs out the current user and returns a Result indicating success/failure.
+- GetProfileAsync(): Retrieves the current user's profile wrapped in a Result with UserProfileDto on success.
+- RefreshTokenAsync(): Requests a token refresh for the current authentication session and returns a Result indicating success/failure.
+- IIdentityService: Service contract defining identity/authentication operations and an event for invalidation.
+
+## Dependencies
+
+- imports NexusReader.Application/DTOs/User/UserProfileDto.cs
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: FluentResults (external package)
+
+## Coverage
+
+- Symbols: 7
+- Executable symbols: 6
+- Executable symbols with control flow: 6
+- Grounded edges: 8
+- Unresolved references: 1
+- Control-flow fragments: 6
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- OnStateInvalidated: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- RegisterAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- LoginAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- LogoutAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetProfileAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- RefreshTokenAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IIdentityService Neighborhood
+
+```mermaid
+flowchart LR
+    file_1ud0jop_iidentityservice_cs("IIdentityService")
+    method_12nj2l_registerasync[["RegisterAsync()"]]
+    method_1gbqw83_refreshtokenasync[["RefreshTokenAsync()"]]
+    method_1ww1s1_loginasync[["LoginAsync()"]]
+    method_d5t49u_onstateinvalidated[["OnStateInvalidated()"]]
+    method_urpd77_logoutasync[["LogoutAsync()"]]
+    method_yzr6ph_getprofileasync[["GetProfileAsync()"]]
+    file_1fs0p2c_userprofiledto_cs[/"UserProfileDto"/]
+    type_udpmrx_iidentityservice[/"IIdentityService"/]
+    file_1ud0jop_iidentityservice_cs -->|UserProfileDto| file_1fs0p2c_userprofiledto_cs
+```
+
+### IIdentityService Execution Overview
+
+```mermaid
+flowchart TD
+    file_1ud0jop_iidentityservice_cs("IIdentityService")
+    method_12nj2l_registerasync[["RegisterAsync()"]]
+    method_1gbqw83_refreshtokenasync[["RefreshTokenAsync()"]]
+    method_1ww1s1_loginasync[["LoginAsync()"]]
+    method_d5t49u_onstateinvalidated[["OnStateInvalidated()"]]
+    method_urpd77_logoutasync[["LogoutAsync()"]]
+    method_yzr6ph_getprofileasync[["GetProfileAsync()"]]
+    file_1ud0jop_iidentityservice_cs -->|contains| method_12nj2l_registerasync
+    file_1ud0jop_iidentityservice_cs -->|contains| method_1gbqw83_refreshtokenasync
+    file_1ud0jop_iidentityservice_cs -->|contains| method_1ww1s1_loginasync
+    file_1ud0jop_iidentityservice_cs -->|contains| method_d5t49u_onstateinvalidated
+    file_1ud0jop_iidentityservice_cs -->|contains| method_urpd77_logoutasync
+    file_1ud0jop_iidentityservice_cs -->|contains| method_yzr6ph_getprofileasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,116 @@
+# IKnowledgeService
+
+- File ID: file:pvs6tn:iknowledgeservice-cs
+- Path: NexusReader.Application/Abstractions/Services/IKnowledgeService.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines the application-level abstraction for knowledge-related operations (semantic search, summarization, QA, groundedness checks, cache management) used by higher-level components.
+
+## Key Details
+
+Application-level abstraction returning FluentResults-wrapped DTOs (KnowledgePacket, GroundedResponseDto, SemanticSearchResultDto). No runtime logic in this file; it defines contracts for knowledge-related orchestration implemented elsewhere.
+
+## Symbols
+
+- IKnowledgeService: Defines the application-level abstraction for knowledge-related operations (semantic search, summarization, QA, groundedness checks, cache management) used by higher-level components.
+- GetKnowledgeAsync(): Return a KnowledgePacket for provided text scoped to a tenant and optional ebook.
+- GetGraphDataAsync(): Produce graph-structured knowledge data for the given text and tenant context.
+- GetKnowledgeMapAsync(): Generate a knowledge map (likely node/edge representation) for the supplied text and tenant.
+- GetSummaryAndQuizAsync(): Create a summary and quiz (assessment) artifact for given text within tenant/ebook scope.
+- GetRelevantContextAsync(): Retrieve a list of relevant context snippets for a query within a tenant.
+- VerifyGroundednessAsync(): Evaluate whether an answer is grounded in provided context and return a score/rationale.
+- SearchLibrarySemanticallyAsync(): Perform a semantic search over the library for a tenant and return top results up to a limit.
+- AskQuestionAsync(): Ask a question against tenant (and optional ebook) data and return a grounded response, limited by passed limit.
+- ClearCacheAsync(): Clear any service-level caches used by the knowledge subsystem.
+- GroundednessResult: Represents the outcome of a groundedness check with score, rationale, and boolean flag.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Unresolved References
+
+- dependency-target: FluentResults
+- dependency-target: NexusReader.Application.DTOs.AI
+
+## Coverage
+
+- Symbols: 11
+- Executable symbols: 9
+- Executable symbols with control flow: 9
+- Grounded edges: 11
+- Unresolved references: 2
+- Control-flow fragments: 9
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- GetKnowledgeAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetGraphDataAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetKnowledgeMapAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetSummaryAndQuizAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetRelevantContextAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- VerifyGroundednessAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SearchLibrarySemanticallyAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- AskQuestionAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- ClearCacheAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IKnowledgeService Neighborhood
+
+```mermaid
+flowchart LR
+    class_utixgx_iknowledgeservice("IKnowledgeService")
+    file_pvs6tn_iknowledgeservice_cs("IKnowledgeService")
+    method_1ckhg6n_getknowledgeasync[["GetKnowledgeAsync()"]]
+    method_1g8j6qo_getgraphdataasync[["GetGraphDataAsync()"]]
+    method_1oclqd_verifygroundednessasync[["VerifyGroundednessAsync()"]]
+    method_1odjeej_searchlibrarysemanticallyasync[["SearchLibrarySemanticallyAsync()"]]
+    method_1yhcrn6_getrelevantcontextasync[["GetRelevantContextAsync()"]]
+    method_26njdb_clearcacheasync[["ClearCacheAsync()"]]
+    method_7pcmld_getsummaryandquizasync[["GetSummaryAndQuizAsync()"]]
+    method_cuqhj0_getknowledgemapasync[["GetKnowledgeMapAsync()"]]
+    method_f76by4_askquestionasync[["AskQuestionAsync()"]]
+    type_1a84if1_groundednessresult[/"GroundednessResult"/]
+```
+
+### IKnowledgeService Execution Overview
+
+```mermaid
+flowchart TD
+    class_utixgx_iknowledgeservice("IKnowledgeService")
+    method_1ckhg6n_getknowledgeasync[["GetKnowledgeAsync()"]]
+    method_1g8j6qo_getgraphdataasync[["GetGraphDataAsync()"]]
+    method_1oclqd_verifygroundednessasync[["VerifyGroundednessAsync()"]]
+    method_1odjeej_searchlibrarysemanticallyasync[["SearchLibrarySemanticallyAsync()"]]
+    method_1yhcrn6_getrelevantcontextasync[["GetRelevantContextAsync()"]]
+    method_26njdb_clearcacheasync[["ClearCacheAsync()"]]
+    method_7pcmld_getsummaryandquizasync[["GetSummaryAndQuizAsync()"]]
+    method_cuqhj0_getknowledgemapasync[["GetKnowledgeMapAsync()"]]
+    method_f76by4_askquestionasync[["AskQuestionAsync()"]]
+    class_utixgx_iknowledgeservice -->|contains| method_1ckhg6n_getknowledgeasync
+    class_utixgx_iknowledgeservice -->|contains| method_1g8j6qo_getgraphdataasync
+    class_utixgx_iknowledgeservice -->|contains| method_1oclqd_verifygroundednessasync
+    class_utixgx_iknowledgeservice -->|contains| method_1odjeej_searchlibrarysemanticallyasync
+    class_utixgx_iknowledgeservice -->|contains| method_1yhcrn6_getrelevantcontextasync
+    class_utixgx_iknowledgeservice -->|contains| method_26njdb_clearcacheasync
+    class_utixgx_iknowledgeservice -->|contains| method_7pcmld_getsummaryandquizasync
+    class_utixgx_iknowledgeservice -->|contains| method_cuqhj0_getknowledgemapasync
+    class_utixgx_iknowledgeservice -->|contains| method_f76by4_askquestionasync
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,106 @@
+# INativeStorageService
+
+- File ID: file:1it42kj:inativestorageservice-cs
+- Path: NexusReader.Application/Abstractions/Services/INativeStorageService.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines an application-level abstraction for platform/native key-value storage including secure and non-secure reads, writes, and removals.
+
+## Key Details
+
+Interface-only file that declares async Result-wrapped operations for secure and non-secure platform storage; implementations will perform the actual native persistence and security handling.
+
+## Symbols
+
+- INativeStorageService: Defines an application-level abstraction for platform/native key-value storage including secure and non-secure reads, writes, and removals.
+- SaveStringAsync(): Persist a non-secure string value under the given key asynchronously.
+- GetStringAsync(): Retrieve a non-secure string value by key asynchronously.
+- SaveBoolAsync(): Persist a boolean value under the given key asynchronously.
+- GetBoolAsync(): Retrieve a boolean value by key asynchronously, returning a provided default if absent.
+- RemoveAsync(): Remove a non-secure entry by key from native storage asynchronously.
+- SaveSecureString(): Persist a string securely (platform secure storage) under the given key asynchronously.
+- GetSecureString(): Retrieve a secure string by key from platform secure storage asynchronously.
+- RemoveSecureAsync(): Remove a secure entry by key from platform secure storage asynchronously.
+- INativeStorageService: Abstraction for platform-specific key-value storage operations (secure and non-secure) used by application components.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 10
+- Executable symbols: 8
+- Executable symbols with control flow: 8
+- Grounded edges: 10
+- Unresolved references: 0
+- Control-flow fragments: 8
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- SaveStringAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetStringAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SaveBoolAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetBoolAsync: 7 nodes, 7 edges, 0 jumps, 0 unsupported constructs
+- RemoveAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- SaveSecureString: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- GetSecureString: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- RemoveSecureAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### INativeStorageService Neighborhood
+
+```mermaid
+flowchart LR
+    class_1owrs1t_inativestorageservice("INativeStorageService")
+    file_1it42kj_inativestorageservice_cs("INativeStorageService")
+    method_1070aok_getsecurestring[["GetSecureString()"]]
+    method_19tpzwe_getstringasync[["GetStringAsync()"]]
+    method_1oljw52_getboolasync[["GetBoolAsync()"]]
+    method_1wrq6fu_savestringasync[["SaveStringAsync()"]]
+    method_8lkc9b_saveboolasync[["SaveBoolAsync()"]]
+    method_ne3mm3_removeasync[["RemoveAsync()"]]
+    method_xfwbbe_removesecureasync[["RemoveSecureAsync()"]]
+    method_zxocvw_savesecurestring[["SaveSecureString()"]]
+    type_1vae1rw_inativestorageservice[/"INativeStorageService"/]
+```
+
+### INativeStorageService Execution Overview
+
+```mermaid
+flowchart TD
+    class_1owrs1t_inativestorageservice("INativeStorageService")
+    method_1070aok_getsecurestring[["GetSecureString()"]]
+    method_19tpzwe_getstringasync[["GetStringAsync()"]]
+    method_1oljw52_getboolasync[["GetBoolAsync()"]]
+    method_1wrq6fu_savestringasync[["SaveStringAsync()"]]
+    method_8lkc9b_saveboolasync[["SaveBoolAsync()"]]
+    method_ne3mm3_removeasync[["RemoveAsync()"]]
+    method_xfwbbe_removesecureasync[["RemoveSecureAsync()"]]
+    method_zxocvw_savesecurestring[["SaveSecureString()"]]
+    class_1owrs1t_inativestorageservice -->|contains| method_1070aok_getsecurestring
+    class_1owrs1t_inativestorageservice -->|contains| method_19tpzwe_getstringasync
+    class_1owrs1t_inativestorageservice -->|contains| method_1oljw52_getboolasync
+    class_1owrs1t_inativestorageservice -->|contains| method_1wrq6fu_savestringasync
+    class_1owrs1t_inativestorageservice -->|contains| method_8lkc9b_saveboolasync
+    class_1owrs1t_inativestorageservice -->|contains| method_ne3mm3_removeasync
+    class_1owrs1t_inativestorageservice -->|contains| method_xfwbbe_removesecureasync
+    class_1owrs1t_inativestorageservice -->|contains| method_zxocvw_savesecurestring
+```
+
+## Diagram Validation
+
+- Status: pass
@@ -0,0 +1,90 @@
+# IPlatformService
+
+- File ID: file:wb18l0:iplatformservice-cs
+- Path: NexusReader.Application/Abstractions/Services/IPlatformService.cs
+- Role: service
+- Layer: application
+
+## Purpose
+
+Defines a platform abstraction for device capabilities (vibration) and device metadata (device context) used by application code to remain platform-agnostic.
+
+## Key Details
+
+Uses FluentResults.Result for method returns, is an application-layer abstraction to be implemented by platform-specific code (likely in Infrastructure or UI platform projects).
+
+## Symbols
+
+- IPlatformService: Defines a platform abstraction for device capabilities (vibration) and device metadata (device context) used by application code to remain platform-agnostic.
+- VibrateSuccessAsync(): Contract for invoking a short/success vibration on the device.
+- VibrateErrorAsync(): Contract for invoking an error/alert vibration on the device.
+- VibrateAsync(): Contract for invoking a vibration for a specified duration in milliseconds.
+- GetDeviceContext(): Contract for obtaining device metadata (model, manufacturer, type, orientation) synchronously.
+- DeviceContext: Holds device metadata (model, manufacturer, device type, and display orientation).
+- DeviceType: Enumerates broad device categories.
+- DisplayOrientation: Enumerates display orientations.
+
+## Dependencies
+
+- No resolved dependencies.
+
+## Calls
+
+- No resolved calls.
+
+## Coverage
+
+- Symbols: 8
+- Executable symbols: 4
+- Executable symbols with control flow: 4
+- Grounded edges: 8
+- Unresolved references: 0
+- Control-flow fragments: 4
+- Unresolved jumps: 0
+- Unsupported constructs: 0
+- Control-flow coverage: 100%
+- Required diagrams: 2
+- Generated diagrams: 2
+
+## Control Flow Fragments
+
+- VibrateSuccessAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- VibrateErrorAsync: 3 nodes, 2 edges, 0 jumps, 0 unsupported constructs
+- VibrateAsync: 4 nodes, 3 edges, 0 jumps, 0 unsupported constructs
+- GetDeviceContext: 4 nodes, 3 edges, 0 jumps, 0 unsupported constructs
+
+## Diagrams
+
+### IPlatformService Neighborhood
+
+```mermaid
+flowchart LR
+    class_1gyz12d_iplatformservice("IPlatformService")
+    file_wb18l0_iplatformservice_cs("IPlatformService")
+    method_ptkxhj_vibratesuccessasync[["VibrateSuccessAsync()"]]
+    method_qdnq0x_vibrateerrorasync[["VibrateErrorAsync()"]]
+    method_sdo0jm_vibrateasync[["VibrateAsync()"]]
+    method_w31hua_getdevicecontext[["GetDeviceContext()"]]
+    type_1jksru0_devicetype[/"DeviceType"/]
+    type_1qhatfu_displayorientation[/"DisplayOrientation"/]
+    type_flcquz_devicecontext[/"DeviceContext"/]
+```
+
+### IPlatformService Execution Overview
+
+```mermaid
+flowchart TD
+    class_1gyz12d_iplatformservice("IPlatformService")
+    method_ptkxhj_vibratesuccessasync[["VibrateSuccessAsync()"]]
+    method_qdnq0x_vibrateerrorasync[["VibrateErrorAsync()"]]
+    method_sdo0jm_vibrateasync[["VibrateAsync()"]]
+    method_w31hua_getdevicecontext[["GetDeviceContext()"]]
+    class_1gyz12d_iplatformservice -->|contains| method_ptkxhj_vibratesuccessasync
+    class_1gyz12d_iplatformservice -->|contains| method_qdnq0x_vibrateerrorasync
+    class_1gyz12d_iplatformservice -->|contains| method_sdo0jm_vibrateasync
+    class_1gyz12d_iplatformservice -->|contains| method_w31hua_getdevicecontext
+```
+
+## Diagram Validation
+
+- Status: pass