From fbe142c6f3bb0005a862331e27482e05e02ffc86 Mon Sep 17 00:00:00 2001 From: Loretta Date: Sat, 28 Mar 2026 17:24:56 +0100 Subject: [PATCH] Add detailed README.md files for all projects and folders Added comprehensive README.md documentation to every project and subfolder in the solution. Each README describes the purpose, key files, structure, dependencies, and design patterns for its area. This improves codebase navigability and maintainability, and includes a maintenance note to keep docs in sync with future code changes. --- AyCode.Benchmark/README.md | 27 +++++++++++ AyCode.Core.Serializers.Console/README.md | 34 ++++++++++++++ .../README.md | 34 ++++++++++++++ AyCode.Core.Server/Loggers/README.md | 11 +++++ AyCode.Core.Server/README.md | 27 +++++++++++ AyCode.Database/DataLayers/README.md | 19 ++++++++ AyCode.Database/DataLayers/Users/README.md | 12 +++++ AyCode.Database/DbContexts/Loggers/README.md | 12 +++++ AyCode.Database/DbContexts/README.md | 21 +++++++++ AyCode.Database/DbContexts/Users/README.md | 13 ++++++ AyCode.Database/DbSets/Addresses/README.md | 12 +++++ AyCode.Database/DbSets/Companies/README.md | 12 +++++ AyCode.Database/DbSets/Loggers/README.md | 11 +++++ AyCode.Database/DbSets/Messages/README.md | 12 +++++ AyCode.Database/DbSets/Profiles/README.md | 12 +++++ AyCode.Database/DbSets/README.md | 22 +++++++++ AyCode.Database/DbSets/Users/README.md | 16 +++++++ AyCode.Database/Extensions/README.md | 14 ++++++ .../ModelBuilders/Profiles/README.md | 12 +++++ AyCode.Database/ModelBuilders/README.md | 14 ++++++ AyCode.Database/ModelBuilders/Users/README.md | 12 +++++ AyCode.Database/README.md | 30 ++++++++++++ AyCode.Entities.Server/LogItems/README.md | 12 +++++ AyCode.Entities.Server/README.md | 22 +++++++++ AyCode.Entities/Addresses/README.md | 11 +++++ AyCode.Entities/Groups/README.md | 11 +++++ AyCode.Entities/Locations/README.md | 11 +++++ AyCode.Entities/LogItems/README.md | 11 +++++ AyCode.Entities/Messages/README.md | 12 +++++ AyCode.Entities/Profiles/README.md | 11 +++++ AyCode.Entities/README.md | 40 ++++++++++++++++ AyCode.Entities/ServiceProviders/README.md | 11 +++++ AyCode.Entities/Users/README.md | 13 ++++++ AyCode.Interfaces.Server/Logins/README.md | 13 ++++++ AyCode.Interfaces.Server/README.md | 24 ++++++++++ AyCode.Interfaces/Addresses/Dtos/README.md | 11 +++++ AyCode.Interfaces/Addresses/README.md | 13 ++++++ AyCode.Interfaces/Entities/README.md | 16 +++++++ AyCode.Interfaces/EntityComment/README.md | 11 +++++ AyCode.Interfaces/Enums/README.md | 11 +++++ AyCode.Interfaces/Groups/README.md | 11 +++++ AyCode.Interfaces/Locations/README.md | 11 +++++ AyCode.Interfaces/Logins/README.md | 13 ++++++ AyCode.Interfaces/MediaInfo/README.md | 13 ++++++ AyCode.Interfaces/Messages/README.md | 18 ++++++++ AyCode.Interfaces/Profiles/Dtos/README.md | 13 ++++++ AyCode.Interfaces/Profiles/README.md | 13 ++++++ AyCode.Interfaces/README.md | 46 +++++++++++++++++++ AyCode.Interfaces/ServiceProviders/README.md | 14 ++++++ AyCode.Interfaces/StorageHandlers/README.md | 11 +++++ AyCode.Interfaces/TimeStampInfo/README.md | 14 ++++++ AyCode.Interfaces/Users/Dtos/README.md | 13 ++++++ AyCode.Interfaces/Users/README.md | 23 ++++++++++ AyCode.Models.Server/DynamicMethods/README.md | 13 ++++++ AyCode.Models.Server/Logins/README.md | 11 +++++ AyCode.Models.Server/README.md | 37 +++++++++++++++ AyCode.Models/Enums/README.md | 12 +++++ AyCode.Models/Messages/README.md | 11 +++++ AyCode.Models/README.md | 41 +++++++++++++++++ AyCode.Models/Users/README.md | 16 +++++++ AyCode.Services.Server/Emails/README.md | 11 +++++ AyCode.Services.Server/Logins/README.md | 11 +++++ AyCode.Services.Server/README.md | 31 +++++++++++++ AyCode.Services.Server/SignalRs/README.md | 26 +++++++++++ AyCode.Services/Loggers/README.md | 15 ++++++ AyCode.Services/Logins/README.md | 12 +++++ AyCode.Services/README.md | 27 +++++++++++ AyCode.Services/SignalRs/README.md | 27 +++++++++++ AyCode.Utils.Server/README.md | 11 +++++ AyCode.Utils/Extensions/README.md | 13 ++++++ AyCode.Utils/README.md | 21 +++++++++ AyCode.Utils/Wrappers/README.md | 14 ++++++ 72 files changed, 1226 insertions(+) create mode 100644 AyCode.Benchmark/README.md create mode 100644 AyCode.Core.Serializers.Console/README.md create mode 100644 AyCode.Core.Serializers.SourceGenerator/README.md create mode 100644 AyCode.Core.Server/Loggers/README.md create mode 100644 AyCode.Core.Server/README.md create mode 100644 AyCode.Database/DataLayers/README.md create mode 100644 AyCode.Database/DataLayers/Users/README.md create mode 100644 AyCode.Database/DbContexts/Loggers/README.md create mode 100644 AyCode.Database/DbContexts/README.md create mode 100644 AyCode.Database/DbContexts/Users/README.md create mode 100644 AyCode.Database/DbSets/Addresses/README.md create mode 100644 AyCode.Database/DbSets/Companies/README.md create mode 100644 AyCode.Database/DbSets/Loggers/README.md create mode 100644 AyCode.Database/DbSets/Messages/README.md create mode 100644 AyCode.Database/DbSets/Profiles/README.md create mode 100644 AyCode.Database/DbSets/README.md create mode 100644 AyCode.Database/DbSets/Users/README.md create mode 100644 AyCode.Database/Extensions/README.md create mode 100644 AyCode.Database/ModelBuilders/Profiles/README.md create mode 100644 AyCode.Database/ModelBuilders/README.md create mode 100644 AyCode.Database/ModelBuilders/Users/README.md create mode 100644 AyCode.Database/README.md create mode 100644 AyCode.Entities.Server/LogItems/README.md create mode 100644 AyCode.Entities.Server/README.md create mode 100644 AyCode.Entities/Addresses/README.md create mode 100644 AyCode.Entities/Groups/README.md create mode 100644 AyCode.Entities/Locations/README.md create mode 100644 AyCode.Entities/LogItems/README.md create mode 100644 AyCode.Entities/Messages/README.md create mode 100644 AyCode.Entities/Profiles/README.md create mode 100644 AyCode.Entities/README.md create mode 100644 AyCode.Entities/ServiceProviders/README.md create mode 100644 AyCode.Entities/Users/README.md create mode 100644 AyCode.Interfaces.Server/Logins/README.md create mode 100644 AyCode.Interfaces.Server/README.md create mode 100644 AyCode.Interfaces/Addresses/Dtos/README.md create mode 100644 AyCode.Interfaces/Addresses/README.md create mode 100644 AyCode.Interfaces/Entities/README.md create mode 100644 AyCode.Interfaces/EntityComment/README.md create mode 100644 AyCode.Interfaces/Enums/README.md create mode 100644 AyCode.Interfaces/Groups/README.md create mode 100644 AyCode.Interfaces/Locations/README.md create mode 100644 AyCode.Interfaces/Logins/README.md create mode 100644 AyCode.Interfaces/MediaInfo/README.md create mode 100644 AyCode.Interfaces/Messages/README.md create mode 100644 AyCode.Interfaces/Profiles/Dtos/README.md create mode 100644 AyCode.Interfaces/Profiles/README.md create mode 100644 AyCode.Interfaces/README.md create mode 100644 AyCode.Interfaces/ServiceProviders/README.md create mode 100644 AyCode.Interfaces/StorageHandlers/README.md create mode 100644 AyCode.Interfaces/TimeStampInfo/README.md create mode 100644 AyCode.Interfaces/Users/Dtos/README.md create mode 100644 AyCode.Interfaces/Users/README.md create mode 100644 AyCode.Models.Server/DynamicMethods/README.md create mode 100644 AyCode.Models.Server/Logins/README.md create mode 100644 AyCode.Models.Server/README.md create mode 100644 AyCode.Models/Enums/README.md create mode 100644 AyCode.Models/Messages/README.md create mode 100644 AyCode.Models/README.md create mode 100644 AyCode.Models/Users/README.md create mode 100644 AyCode.Services.Server/Emails/README.md create mode 100644 AyCode.Services.Server/Logins/README.md create mode 100644 AyCode.Services.Server/README.md create mode 100644 AyCode.Services.Server/SignalRs/README.md create mode 100644 AyCode.Services/Loggers/README.md create mode 100644 AyCode.Services/Logins/README.md create mode 100644 AyCode.Services/README.md create mode 100644 AyCode.Services/SignalRs/README.md create mode 100644 AyCode.Utils.Server/README.md create mode 100644 AyCode.Utils/Extensions/README.md create mode 100644 AyCode.Utils/README.md create mode 100644 AyCode.Utils/Wrappers/README.md diff --git a/AyCode.Benchmark/README.md b/AyCode.Benchmark/README.md new file mode 100644 index 0000000..0980147 --- /dev/null +++ b/AyCode.Benchmark/README.md @@ -0,0 +1,27 @@ +# AyCode.Benchmark + +BenchmarkDotNet-based performance benchmarking console app. Compares AcBinary serializer against MessagePack, BSON, and JSON across various scenarios. + +## Key Files + +- **`Program.cs`** — CLI entry point with `--quick`, `--test`, `--minimal`, `--simple`, `--complex`, `--msgpack`, `--sizes`, `--jitasm` modes. Collects results to `Test_Benchmark_Results/` at solution root. +- **`SerializationBenchmarks.cs`** — Primary suite: MinimalBenchmark, SimpleBinaryBenchmark, ComplexBinaryBenchmark, MessagePackComparisonBenchmark, AcBinaryVsMessagePackFullBenchmark, SizeComparisonBenchmark, LargeScaleBenchmark (~25K objects), AcJsonVsSystemTextJsonBenchmark. +- **`SourceGeneratorBenchmarks.cs`** — Source-generated vs runtime reflection serializers. Includes PureContractlessBenchmark, SourceGeneratorVsRuntimeBenchmark, RepeatedStringBenchmark (string interning). +- **`SignalRCommunicationBenchmarks.cs`** — Full-stack SignalR message performance: client creation → MessagePack serialization → server deserialization → response → round-trip. +- **`SignalRRoundTripBenchmarks.cs`** — Real SignalR infrastructure benchmarks: primitives, complex objects, collections, mixed parameters. +- **`JitDisassemblyBenchmark.cs`** — JIT analysis: generates .asm files to verify inlining decisions on serialize/deserialize hot paths. +- **`TaskHelperBenchmarks.cs`** — Task/timing utilities: WaitToAsync, ThreadPool (custom vs Task.Run), timing methods (UtcNow.Ticks vs TickCount64). +- **`RefForeachBenchmark.cs`** — Collection iteration patterns: array vs list, foreach vs index, ref readonly vs by-value for large structs. +- **`ValueTypePassingBenchmark.cs`** — Copy-by-value vs `in` parameter for 16-byte types (Decimal, DateTimeOffset, Guid). + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `BenchmarkDotNet` | Benchmarking framework | +| `MessagePack` | Serialization comparison target | +| `MongoDB.Bson` | BSON comparison target | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Core.Serializers.Console/README.md b/AyCode.Core.Serializers.Console/README.md new file mode 100644 index 0000000..b19aef4 --- /dev/null +++ b/AyCode.Core.Serializers.Console/README.md @@ -0,0 +1,34 @@ +# AyCode.Core.Serializers.Console + +Standalone benchmark console application for comparing serializer performance. Targets .NET 9. Measures serialize/deserialize speed, output size, and compression across multiple serializers and data shapes. + +## Compared Serializers + +- **AcBinary** — Multiple configurations: Default, NoRef, FastMode, NoIntern, with/without source generation +- **MessagePack** +- **MemoryPack** + +(System.Text.Json and Newtonsoft.Json comparisons exist but are currently commented out.) + +## Key Files + +- **`Program.cs`** — Benchmark runner. Modes: `all` (default), `quick` (fewer iterations), `serialize`, `deserialize`, `profiler` (memory profiler warmup). Outputs results to `Test_Benchmark_Results/Benchmark/`. Iterations: 5000 warmup + 1000 test (Release), 0+1 (Debug). +- **`BenchmarkTestDataProvider.cs`** — Test data factory producing 5 data shapes: + - Small (2x2x2x2), Medium (3x3x3x4), Large (5x5x5x10) + - Repeated Strings (10 items, string deduplication testing) + - Deep Nested (2x4x4x8, depth stress test) + - Uses `TestOrder` model from `AyCode.Core.Tests` with configurable IId reference percentages. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Core library with AcBinary serializer | +| `AyCode.Core.Tests` | Test models (`TestOrder`, `TestDataFactory`, etc.) | +| `MemoryPack` | Competitor benchmark | +| `MessagePack` | Competitor benchmark | +| `Newtonsoft.Json` | Competitor benchmark | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Core.Serializers.SourceGenerator/README.md b/AyCode.Core.Serializers.SourceGenerator/README.md new file mode 100644 index 0000000..f0444b0 --- /dev/null +++ b/AyCode.Core.Serializers.SourceGenerator/README.md @@ -0,0 +1,34 @@ +# AyCode.Core.Serializers.SourceGenerator + +Roslyn incremental source generator that produces optimized `IGeneratedBinaryWriter` and `IGeneratedBinaryReader` implementations for types marked with `[AcBinarySerializable]`. Eliminates runtime reflection on serialization hot paths. + +Targets **netstandard2.0** (required for Roslyn analyzers/generators). + +## Key Files + +- **`AcBinarySourceGenerator.cs`** — Single-file `IIncrementalGenerator` (~2100 lines). Generates: + - `{ClassName}_GeneratedWriter` — Per-type writer with `ScanObject()` + `WriteProperties()` methods. Handles primitives, strings (with interning), collections, dictionaries, complex nested types, and polymorphic objects. + - `{ClassName}_GeneratedReader` — Per-type reader with `ReadProperties()` method. + - `ModuleInitializer` — Auto-registers all generated writers/readers at startup. + - Circular reference detection with `ACBIN001` diagnostic warning. + +## Feature Flags + +The `[AcBinarySerializable]` attribute supports per-type feature control: +- `enableMetadata` — Property hash metadata for cross-type deserialization +- `enableIdTracking` — IId-based reference tracking +- `enableRefHandling` — General reference tracking +- `enableInternString` — String interning/deduplication + +Disabled features eliminate corresponding code blocks from generated output (zero dead code). + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `Microsoft.CodeAnalysis.CSharp` | Roslyn syntax/semantic APIs | +| `Microsoft.CodeAnalysis.Analyzers` | Analyzer best practices | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Core.Server/Loggers/README.md b/AyCode.Core.Server/Loggers/README.md new file mode 100644 index 0000000..70b14f7 --- /dev/null +++ b/AyCode.Core.Server/Loggers/README.md @@ -0,0 +1,11 @@ +# Loggers + +Provides a singleton `GlobalLogger` for application-wide logging with multiple severity levels (Detail, Debug, Info, Warning, Suggest, Error) and support for pluggable log writers. + +## Key Files + +- **`GlobalLogger.cs`** — Singleton static logger that delegates to `AcLoggerBase`. Supports category names, caller member tracking, and configurable `LogLevel` and `AppType`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Core.Server/README.md b/AyCode.Core.Server/README.md new file mode 100644 index 0000000..547350a --- /dev/null +++ b/AyCode.Core.Server/README.md @@ -0,0 +1,27 @@ +# AyCode.Core.Server + +Server-side extension of AyCode.Core. Provides server-specific implementations that build on the shared core library. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| `Loggers/` | Server-side global logger singleton | + +## Key Files + +### Loggers/ +- **`GlobalLogger.cs`** — Static singleton facade for server-side logging. Wraps `AcGlobalLoggerBase` (sealed, derives from `AcLoggerBase`). Provides static methods (`Detail`, `Debug`, `Info`, `Warning`, `Suggest`, `Error`, `Write`) with `[CallerMemberName]` support. Default category: `"GLOBAL_LOGGER"`. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Core library (loggers, enums, serializers) | +| `MessagePack` | MessagePack serialization | +| `Newtonsoft.Json` | JSON serialization | +| `Microsoft.Extensions.Logging.Abstractions` | Logging abstractions | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DataLayers/README.md b/AyCode.Database/DataLayers/README.md new file mode 100644 index 0000000..e5f8a67 --- /dev/null +++ b/AyCode.Database/DataLayers/README.md @@ -0,0 +1,19 @@ +# DataLayers + +Generic Data Access Layer (DAL) abstraction with mutex-protected session/transaction patterns and singleton DAL pooling. + +## Key Files + +- **`IAcDalBase.cs`** — Base interface: Name, Context access, Mutex lock, DbContext lifecycle. +- **`AcDalBase.cs`** — Abstract implementation: Session/SessionAsync (reads), Transaction/TransactionAsync (writes), thread-safe Mutex, auto DbContext creation, model DTO conversion. +- **`PooledDal.cs`** — Singleton DAL pool: concurrent dictionary by SessionId/PlayerId, GetDalById, CreateDal, Remove. + +## Subfolders + +| Folder | Purpose | +|---|---| +| [`Users/`](Users/README.md) | User-specific DAL with authentication and CRUD | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DataLayers/Users/README.md b/AyCode.Database/DataLayers/Users/README.md new file mode 100644 index 0000000..b9de90f --- /dev/null +++ b/AyCode.Database/DataLayers/Users/README.md @@ -0,0 +1,12 @@ +# DataLayers / Users + +User-specific DAL extending AcDalBase with authentication, CRUD, and email validation support. + +## Key Files + +- **`AcUserDalBase.cs`** — GetUserById/ByEmail, AddUser, RemoveUser, UpdateUser, AuthenticateUser (with password verification + refresh token), GetUserModelDto (sync + async). +- **`AcUserDalExtension.cs`** — Reserved for future user DAL extensions (currently contains commented legacy code). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbContexts/Loggers/README.md b/AyCode.Database/DbContexts/Loggers/README.md new file mode 100644 index 0000000..91cb2c8 --- /dev/null +++ b/AyCode.Database/DbContexts/Loggers/README.md @@ -0,0 +1,12 @@ +# DbContexts / Loggers + +Logger-specific EF Core DbContext with NoTracking query behavior for read performance. + +## Key Files + +- **`IAcLoggerDbContextBase.cs`** — Interface for log item DbSet. +- **`AcLoggerDbContextBase.cs`** — Implementation with NoTracking default, optimized for log reads. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbContexts/README.md b/AyCode.Database/DbContexts/README.md new file mode 100644 index 0000000..758bb1b --- /dev/null +++ b/AyCode.Database/DbContexts/README.md @@ -0,0 +1,21 @@ +# DbContexts + +EF Core DbContext base classes with automatic timestamp management, UTC conversion, and lazy loading proxy support. + +## Key Files + +- **`IAcDbContextBase.cs`** — Base interface (Name, SessionId). +- **`AcDbContextBase.cs`** — Abstract base: SQL Server config, auto Created/Modified timestamps, DateTime UTC conversion, transaction/SaveChanges handling. +- **`AcDbContextExtension.cs`** — Extensions for entity keys, modified properties, value converters, UTC handling. +- **`IAcEntityTypeConfiguration.cs`** — Interface for EF entity type configurations. + +## Subfolders + +| Folder | Purpose | +|---|---| +| [`Users/`](Users/README.md) | User-specific DbContext with DbSets for User, Profile, Address, Company, UserToken, EmailMessage | +| [`Loggers/`](Loggers/README.md) | Logger DbContext with NoTracking for read performance | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbContexts/Users/README.md b/AyCode.Database/DbContexts/Users/README.md new file mode 100644 index 0000000..67b37f3 --- /dev/null +++ b/AyCode.Database/DbContexts/Users/README.md @@ -0,0 +1,13 @@ +# DbContexts / Users + +User-specific EF Core DbContext definitions. + +## Key Files + +- **`IAcUserDbContextBase.cs`** — Interface declaring DbSets for Users, Profiles, Addresses, Companies, UserTokens, EmailMessages. +- **`AcUserDbContextBase.cs`** — Implementation with lazy loading, auto timestamps, and entity configurations. +- **`IAcUserTokenDbContextBase.cs`** — Interface for UserToken DbSet access. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/Addresses/README.md b/AyCode.Database/DbSets/Addresses/README.md new file mode 100644 index 0000000..22c34bf --- /dev/null +++ b/AyCode.Database/DbSets/Addresses/README.md @@ -0,0 +1,12 @@ +# DbSets / Addresses + +Address entity CRUD operations. + +## Key Files + +- **`IAcAddressDbSetBase.cs`** — Address DbSet interface. +- **`AcAddressDbSetExtensions.cs`** — GetAddressById, UpdateAddress, RemoveAddress. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/Companies/README.md b/AyCode.Database/DbSets/Companies/README.md new file mode 100644 index 0000000..f151dba --- /dev/null +++ b/AyCode.Database/DbSets/Companies/README.md @@ -0,0 +1,12 @@ +# DbSets / Companies + +Company/ServiceProvider CRUD with profile and user-to-company relationship management. + +## Key Files + +- **`IAcCompanyDbSetBase.cs`** — Hierarchical interfaces with Profile and Address relations. +- **`AcCompanyDbSetExtensions.cs`** — AddCompany, UpdateCompany, RemoveCompany, GetCompanyById, GetCompaniesByOwnerId. Handles profile and user-to-company relationships. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/Loggers/README.md b/AyCode.Database/DbSets/Loggers/README.md new file mode 100644 index 0000000..c6e02d0 --- /dev/null +++ b/AyCode.Database/DbSets/Loggers/README.md @@ -0,0 +1,11 @@ +# DbSets / Loggers + +Log item DbSet interface. + +## Key Files + +- **`IAcLogItemDbSetBase.cs`** — Interface for LogItem DbSet. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/Messages/README.md b/AyCode.Database/DbSets/Messages/README.md new file mode 100644 index 0000000..92ef764 --- /dev/null +++ b/AyCode.Database/DbSets/Messages/README.md @@ -0,0 +1,12 @@ +# DbSets / Messages + +Email message querying and CRUD operations with sender/recipient/context filtering. + +## Key Files + +- **`IAcEmailMessageDbSet.cs`** — EmailMessage DbSet interface. +- **`AcEmailMessageDbSetExtension.cs`** — GetEmailMessageById, GetEmailMessagesByContextId/SenderId, filter by sender/recipient, AddEmailMessage, UpdateEmailMessage, RemoveEmailMessage. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/Profiles/README.md b/AyCode.Database/DbSets/Profiles/README.md new file mode 100644 index 0000000..a1268a4 --- /dev/null +++ b/AyCode.Database/DbSets/Profiles/README.md @@ -0,0 +1,12 @@ +# DbSets / Profiles + +Profile CRUD operations with address relationship support. + +## Key Files + +- **`IAcProfileDbSetBase.cs`** — Interface with Address dependency. +- **`AcProfileDbSetExtensions.cs`** — GetProfileById, AddProfile, UpdateProfile, RemoveProfile. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/README.md b/AyCode.Database/DbSets/README.md new file mode 100644 index 0000000..284d105 --- /dev/null +++ b/AyCode.Database/DbSets/README.md @@ -0,0 +1,22 @@ +# DbSets + +Generic DbSet interfaces with extension method-based CRUD operations. Each entity domain has its own subfolder. + +## Key Files + +- **`IAcDbTableBase.cs`** — Base interface for all DbSets. + +## Subfolders + +| Folder | Purpose | +|---|---| +| [`Users/`](Users/README.md) | User CRUD, authentication, JWT token management | +| [`Profiles/`](Profiles/README.md) | Profile CRUD with address relations | +| [`Addresses/`](Addresses/README.md) | Address CRUD operations | +| [`Companies/`](Companies/README.md) | Company CRUD with profile and user-to-company relations | +| [`Messages/`](Messages/README.md) | Email message querying and CRUD | +| [`Loggers/`](Loggers/README.md) | Log item DbSet interface | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/DbSets/Users/README.md b/AyCode.Database/DbSets/Users/README.md new file mode 100644 index 0000000..a079b9c --- /dev/null +++ b/AyCode.Database/DbSets/Users/README.md @@ -0,0 +1,16 @@ +# DbSets / Users + +User entity CRUD operations, authentication, and JWT token management via extension methods. + +## Key Files + +- **`IAcUserDbSetBase.cs`** — Hierarchical interfaces with optional Profile, Company, Address dependencies. +- **`AcUserDbSetExtensions.cs`** — AuthenticateUser, GetUserById/ByEmail, AddUser, UpdateUser, RemoveUser, UpdateJwtRefreshToken (sync + async). +- **`IAcUserTokenDbSet.cs`** — UserToken DbSet interface. +- **`AcUserTokenDbSetExtensions.cs`** — CreateUserToken, GetActiveUserToken, IsValidToken, DeactivateTokens, ChangePassword. +- **`IAcUserChangePasswordDbSet.cs`** — Combined interface for password change operations. +- **`IAcUserToCompanyDbSetBase.cs`** — UserToCompany mapping interface. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/Extensions/README.md b/AyCode.Database/Extensions/README.md new file mode 100644 index 0000000..c1b5485 --- /dev/null +++ b/AyCode.Database/Extensions/README.md @@ -0,0 +1,14 @@ +# Extensions + +Database utility extensions for DTO conversion, read-only sessions, and transaction management with rollback support. + +## Key Files + +- **`AcDbModelDtoExtension.cs`** — GetModelDtoById, GetAllModelDto for DTO projections. +- **`AcDbSessionExtension.cs`** — Session/SessionAsync for read-only operations with error logging. +- **`AcDbTransactionExtension.cs`** — Transaction/TransactionAsync with auto-rollback on failure, OpenTransaction/CommitTransaction helpers. +- **`AcDalExtension.cs`** — DAL-level mutex-locked session/transaction wrappers, UpdateSafe/UpdateSafeAsync for optimistic updates with optional callbacks. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/ModelBuilders/Profiles/README.md b/AyCode.Database/ModelBuilders/Profiles/README.md new file mode 100644 index 0000000..800dad1 --- /dev/null +++ b/AyCode.Database/ModelBuilders/Profiles/README.md @@ -0,0 +1,12 @@ +# ModelBuilders / Profiles + +EF Core entity type configuration for Profile↔Address relationship. + +## Key Files + +- **`AcProfileEntityTypeConfigurations.cs`** — Default config mapping Profile to Address. +- **`AcProfileEntityTypeBuilderExtensions.cs`** — BuildEntityToAddressRelation (one-to-one). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/ModelBuilders/README.md b/AyCode.Database/ModelBuilders/README.md new file mode 100644 index 0000000..8a2247b --- /dev/null +++ b/AyCode.Database/ModelBuilders/README.md @@ -0,0 +1,14 @@ +# ModelBuilders + +EF Core Fluent API configurations for entity relationships (one-to-one, many-to-many). + +## Subfolders + +| Folder | Purpose | +|---|---| +| [`Users/`](Users/README.md) | User↔Profile and User↔Company relationship configs | +| [`Profiles/`](Profiles/README.md) | Profile↔Address relationship config | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/ModelBuilders/Users/README.md b/AyCode.Database/ModelBuilders/Users/README.md new file mode 100644 index 0000000..25fc338 --- /dev/null +++ b/AyCode.Database/ModelBuilders/Users/README.md @@ -0,0 +1,12 @@ +# ModelBuilders / Users + +EF Core entity type configurations for User and Company relationships. + +## Key Files + +- **`AcUserEntityTypeConfigurations.cs`** — Default configs: User↔Profile (one-to-one), Company↔Profile with auto-include navigation. +- **`AcUserEntityTypeBuilderExtensions.cs`** — BuildEntityToProfileRelation (cascade delete), BuildEntityToServiceProviderRelation (many-to-many via UsingEntity). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Database/README.md b/AyCode.Database/README.md new file mode 100644 index 0000000..650b3c8 --- /dev/null +++ b/AyCode.Database/README.md @@ -0,0 +1,30 @@ +# AyCode.Database + +Entity Framework Core data access layer with generic DAL pattern, session/transaction management, and DAL pooling. Supports multi-tenant user, company, profile, address, and email entities. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`DbContexts/`](DbContexts/README.md) | EF Core DbContext base classes and configurations | +| [`DbSets/`](DbSets/README.md) | Generic DbSet interfaces with extension-based CRUD | +| [`DataLayers/`](DataLayers/README.md) | DAL abstraction with session/transaction and pooling | +| [`ModelBuilders/`](ModelBuilders/README.md) | Fluent API entity relationship configurations | +| [`Extensions/`](Extensions/README.md) | Session, transaction, and DTO conversion helpers | + +## Key Files (Root) + +- **`PermissionViewSql.cs`** — SQL view definitions for permission management. +- **`AcDbLogItemWriter.cs`** — Writes log items to the database via logger base class. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `Microsoft.EntityFrameworkCore.SqlServer` | SQL Server EF Core provider | +| `MessagePack` | Serialization annotations | +| `Newtonsoft.Json` | JSON support | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities.Server/LogItems/README.md b/AyCode.Entities.Server/LogItems/README.md new file mode 100644 index 0000000..3f02413 --- /dev/null +++ b/AyCode.Entities.Server/LogItems/README.md @@ -0,0 +1,12 @@ +# LogItems + +Server-side log item entity and interface, extending the client-side `AcLogItemClient` with a database-mapped identity and header reference. + +## Key Files + +- **`IAcLogItem.cs`** — Interface extending `IAcLogItemClient` and `IEntityInt`, adding a `LogHeaderId` property. +- **`AcLogItem.cs`** — Entity class mapped to the `LogItem` database table with MessagePack serialization. Provides `Id` (auto-generated) and `LogHeaderId`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities.Server/README.md b/AyCode.Entities.Server/README.md new file mode 100644 index 0000000..3534fae --- /dev/null +++ b/AyCode.Entities.Server/README.md @@ -0,0 +1,22 @@ +# AyCode.Entities.Server + +Server-side entity implementations extending `AyCode.Entities`. Currently contains the database-persistable log item entity. + +## Key Files + +### LogItems/ +- **`IAcLogItem.cs`** — Interface extending `IAcLogItemClient` + `IEntityInt`. Adds `int LogHeaderId` for log header foreign key. +- **`AcLogItem.cs`** — Concrete log item entity mapped to `[Table("LogItem")]`. Inherits `AcLogItemClient`, implements `IAcLogItem`. Auto-increment `int Id` primary key. MessagePack-serializable with `[MessagePackObject]`. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Enums, loggers | +| `AyCode.Entities` | `AcLogItemClient` base class | +| `AyCode.Utils` | Shared utilities | +| `MessagePack.Annotations` | `[MessagePackObject]`, `[Key]` for serialization | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/Addresses/README.md b/AyCode.Entities/Addresses/README.md new file mode 100644 index 0000000..e1cf823 --- /dev/null +++ b/AyCode.Entities/Addresses/README.md @@ -0,0 +1,11 @@ +# Addresses + +Abstract base entity for physical addresses, storing geocoordinates and address text. Mapped to the `Address` database table. + +## Key Files + +- **`AcAddress.cs`** — Abstract class implementing `IAcAddress` with `Latitude`, `Longitude`, `AddressText`, and validity flags (`IsValid`, `IsHelper`). Uses a non-database-generated `Guid` primary key. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/Groups/README.md b/AyCode.Entities/Groups/README.md new file mode 100644 index 0000000..5a1d9f4 --- /dev/null +++ b/AyCode.Entities/Groups/README.md @@ -0,0 +1,11 @@ +# Groups + +Abstract base entity for groups with public/private visibility. Implements `IGroupBase`. + +## Key Files + +- **`GroupBase.cs`** — Abstract class with `Id` (Guid), `IsPublic` flag, and `Created`/`Modified` timestamps. Provides constructors for creating groups with optional explicit IDs. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/Locations/README.md b/AyCode.Entities/Locations/README.md new file mode 100644 index 0000000..7b77e7a --- /dev/null +++ b/AyCode.Entities/Locations/README.md @@ -0,0 +1,11 @@ +# Locations + +Abstract base entity for geographic locations with longitude, latitude, and an optional address string. Implements `ILocationBase`. + +## Key Files + +- **`LocationBase.cs`** — Abstract class with `Id` (Guid), `Longitude`, `Latitude`, and `Address` properties. Provides constructors that auto-generate IDs or accept explicit ones. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/LogItems/README.md b/AyCode.Entities/LogItems/README.md new file mode 100644 index 0000000..1867718 --- /dev/null +++ b/AyCode.Entities/LogItems/README.md @@ -0,0 +1,11 @@ +# LogItems + +Client-side log item entity used for structured logging. Serialized with MessagePack for efficient transport. + +## Key Files + +- **`AcLogItemClient.cs`** — Implements `IAcLogItemClient` with fields for `AppType`, `LogLevel`, `ThreadId`, `CategoryName`, `CallerName`, `Text`, and exception details. Uses `[MessagePackObject]` serialization with explicit key indices. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/Messages/README.md b/AyCode.Entities/Messages/README.md new file mode 100644 index 0000000..bac4601 --- /dev/null +++ b/AyCode.Entities/Messages/README.md @@ -0,0 +1,12 @@ +# Messages + +Abstract base entities for email messaging, covering both messages and their recipients. Mapped to `EmailMessage` and `EmailRecipient` database tables. + +## Key Files + +- **`AcEmailMessage.cs`** — Generic abstract class (`AcEmailMessage`) implementing `IAcEmailMessage`. Holds sender, context, subject, body text, email address, read status, and a list of recipients. +- **`AcEmailRecipient.cs`** — Generic abstract class (`AcEmailRecipient`) implementing `IAcEmailRecipient`. Links a recipient to an email message via `EmailMessageId` with navigation back to the message entity. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/Profiles/README.md b/AyCode.Entities/Profiles/README.md new file mode 100644 index 0000000..30abcc8 --- /dev/null +++ b/AyCode.Entities/Profiles/README.md @@ -0,0 +1,11 @@ +# Profiles + +Abstract base entity for user/company profiles with name, contact info, and a linked address. Mapped to the `Profile` database table. + +## Key Files + +- **`AcProfile.cs`** — Generic abstract class (`AcProfile`) implementing `IAcProfile`. Contains `Name`, `FirstName`, `LastName`, `EmailAddress`, `Description`, `ThumbnailUrl`, and a foreign-key relationship to an `Address` entity. Provides `SetAddress()` and `GetFullName()` helpers with language-aware name ordering. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/README.md b/AyCode.Entities/README.md new file mode 100644 index 0000000..2013a55 --- /dev/null +++ b/AyCode.Entities/README.md @@ -0,0 +1,40 @@ +# AyCode.Entities + +Abstract base entity implementations for the AyCode domain model. All entities are abstract and generic — concrete implementations live in application-specific projects. Implements the interfaces defined in `AyCode.Interfaces`. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| `Addresses/` | `AcAddress` — address entity with lat/lng, validation flag | +| `Groups/` | `GroupBase` — base group entity with `IsPublic` flag | +| `Locations/` | `LocationBase` — read-only location (lat/lng/address) | +| `LogItems/` | `AcLogItemClient` — MessagePack-serializable log item DTO | +| `Messages/` | `AcEmailMessage`, `AcEmailRecipient` — email messaging system | +| `Profiles/` | `AcProfile` — user profile with name, media, address FK | +| `ServiceProviders/` | `AcCompany<...>` — company entity with owner, users, commission | +| `Users/` | `AcUser<...>`, `AcUserToCompany<...>`, `AcUserTokenBase` — user, junction table, auth tokens | + +## Root Files + +- **`PermissionContextMappingSubjectType.cs`** — Enum: `NotDefined`(0), `User`(5), `Group`(10). +- **`AcLogItemWriterBase.cs`** — Generic log writer `AcLogItemWriterBase` extending `AcLogWriterBase`. Thread-safe via mutex. Abstract `WriteLogItemCallback()` for concrete implementations. +- **`AcModelDtoExtension.cs`** — Extension methods for entity-to-DTO conversion via `Activator.CreateInstance`. + +## Key Design Patterns + +- **Abstract + Generic** — All entities are `abstract` with generic type parameters for navigation properties (e.g., `AcCompany`). This allows different applications to compose concrete types. +- **Interface implementation** — Each entity implements its corresponding `AyCode.Interfaces` interface. +- **Timestamps** — All entities implement `ITimeStampInfo` (`Created`, `Modified`). +- **Guid PKs** — Most entities use `Guid Id` as primary key; `AcUserTokenBase` uses `int Id` (auto-increment). + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Interfaces` | Interface contracts this project implements | +| `MessagePack.Annotations` | `[MessagePackObject]` on `AcLogItemClient` | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/ServiceProviders/README.md b/AyCode.Entities/ServiceProviders/README.md new file mode 100644 index 0000000..078b51f --- /dev/null +++ b/AyCode.Entities/ServiceProviders/README.md @@ -0,0 +1,11 @@ +# ServiceProviders + +Abstract base entity for companies/service providers, linking owners, profiles, users, and affiliate tracking. Mapped to the `ServiceProviders` database table. + +## Key Files + +- **`AcCompany.cs`** — Generic abstract class (`AcCompany`) implementing `IAcCompany`. Holds `Name`, `OwnerId`, `CommissionPercent`, `AffiliateId`, `ReferralId`, and navigation properties to `Profile`, `Users`, and `UserToServiceProviders`. Provides `SetProfile()`, `HasUser()`, and `AddUser()` helper methods. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Entities/Users/README.md b/AyCode.Entities/Users/README.md new file mode 100644 index 0000000..46b73ae --- /dev/null +++ b/AyCode.Entities/Users/README.md @@ -0,0 +1,13 @@ +# Users + +Abstract base entities for user accounts, authentication tokens, and user-to-company membership mappings. Mapped to the `Users`, `UserToken`, and `UserToServiceProvider` database tables. + +## Key Files + +- **`AcUser.cs`** — Generic abstract class (`AcUser`) implementing `IAcUser`. Holds email, password, phone, refresh token, affiliate/referral IDs, and navigation properties to `Profile`, `ServiceProviders`, and `UserToServiceProviders`. +- **`AcUserTokenBase.cs`** — Abstract class for user verification tokens with `Token`, `IsActive`, `TokenSent`, and `TokenExpiration` fields. Uses an auto-incremented `int` primary key. +- **`AcUserToCompany.cs`** — Generic abstract class (`AcUserToCompany`) implementing `IAcUserToCompany`. Many-to-many join entity linking users to companies with a `Permissions` field. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces.Server/Logins/README.md b/AyCode.Interfaces.Server/Logins/README.md new file mode 100644 index 0000000..edc2387 --- /dev/null +++ b/AyCode.Interfaces.Server/Logins/README.md @@ -0,0 +1,13 @@ +# Logins + +Server-side login interfaces defining contracts for login DTOs, authenticated session state, and login service operations. + +## Key Files + +- **`IAcLoginDtoBase.cs`** — Empty marker interface for login DTO types. +- **`IAcLoggedInModelBase.cs`** — Generic interface for authenticated session state, exposing `IsLoggedIn`, `LoggedInUser`, `AccessToken`, and `LoginErrorCode`, with methods for login and logout. +- **`IAcLoginServiceServer.cs`** — Server login service interface with `Login`/`LoginAsync` and `UpdatePassword` methods, generic over user, token, profile, and company types. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces.Server/README.md b/AyCode.Interfaces.Server/README.md new file mode 100644 index 0000000..a2670bd --- /dev/null +++ b/AyCode.Interfaces.Server/README.md @@ -0,0 +1,24 @@ +# AyCode.Interfaces.Server + +Server-side interface contracts extending `AyCode.Interfaces`. Defines authentication and login service contracts that are only relevant on the server. + +## Key Files + +### Logins/ +- **`IAcLoginDtoBase.cs`** — Empty marker interface for login DTOs. +- **`IAcLoggedInModelBase.cs`** — Generic interface for the logged-in user model. Properties: `IsLoggedIn`, `LoggedInUser`, `AccessToken`, `LoginErrorCode`. Methods: `AddLoggedInUser()`, `Logout()`. Heavily constrained generics (`TUser`, `TUserToken`, `TProfile`, `TCompany`, `TUserToServiceProvider`, `TProfileAddress`). +- **`IAcLoginServiceServer.cs`** — Server-side login service extending `IAcLoginServiceCommon`. Adds: `Login()`/`LoginAsync()` (returns `TResultLoggedInModel`), `UpdatePassword()`. Returns `AcErrorCode` for validation. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Interfaces` | Base interface contracts (users, profiles, companies, logins) | +| `AyCode.Core` | Error codes (`AcErrorCode`) | +| `AyCode.Core.Server` | Server-side core | +| `AyCode.Entities` | Entity base classes | +| `AyCode.Entities.Server` | Server-side entities | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Addresses/Dtos/README.md b/AyCode.Interfaces/Addresses/Dtos/README.md new file mode 100644 index 0000000..4e6473d --- /dev/null +++ b/AyCode.Interfaces/Addresses/Dtos/README.md @@ -0,0 +1,11 @@ +# Addresses/Dtos + +Data transfer object interface for address data, defining the minimal address shape used across DTOs. + +## Key Files + +- **`IAcAddressDtoBase.cs`** — Base address DTO interface with `IsValid`, `IsHelper`, `Latitude`, `Longitude`, and `AddressText` properties. Extends `IEntityGuid`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Addresses/README.md b/AyCode.Interfaces/Addresses/README.md new file mode 100644 index 0000000..f2eab5f --- /dev/null +++ b/AyCode.Interfaces/Addresses/README.md @@ -0,0 +1,13 @@ +# Addresses + +Interfaces for address entities, including the full address model, foreign key contracts, and navigation property relations. + +## Key Files + +- **`IAcAddress.cs`** — Full address interface combining `IAcAddressDtoBase` with `ITimeStampInfo`. +- **`IAcAddressRelation.cs`** — Generic navigation property interface for entities that hold an `Address` reference. +- **`IAcAddressForeignKey.cs`** — Foreign key contract exposing `AddressId` (Guid), extends `IForeignKey`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Entities/README.md b/AyCode.Interfaces/Entities/README.md new file mode 100644 index 0000000..60a87e8 --- /dev/null +++ b/AyCode.Interfaces/Entities/README.md @@ -0,0 +1,16 @@ +# Entities + +Core entity interfaces that define primary key contracts and soft-delete behavior for all domain entities. + +## Key Files + +- **`IEntity.cs`** — Root entity interface extending `IAcSerializableToJson`, with a generic `IEntity` variant for typed primary keys. +- **`IEntityGuid.cs`** — Entity with a `Guid` primary key (`IEntity`). +- **`IEntityInt.cs`** — Entity with an `int` primary key (`IEntity`). +- **`IAcSoftRemoveEntity.cs`** — Adds a `Deleted` boolean flag for soft-delete support. +- **`IAcSoftRemoveEntityInt.cs`** — Soft-delete entity with `int` key. +- **`IAcSoftRemoveEntityGuid.cs`** — Soft-delete entity with `Guid` key. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/EntityComment/README.md b/AyCode.Interfaces/EntityComment/README.md new file mode 100644 index 0000000..080109f --- /dev/null +++ b/AyCode.Interfaces/EntityComment/README.md @@ -0,0 +1,11 @@ +# EntityComment + +Interface for entities that support a comment/note field. + +## Key Files + +- **`IEntityComment.cs`** — Defines a single `Comment` string property for attaching comments to entities. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Enums/README.md b/AyCode.Interfaces/Enums/README.md new file mode 100644 index 0000000..d760126 --- /dev/null +++ b/AyCode.Interfaces/Enums/README.md @@ -0,0 +1,11 @@ +# Enums + +Interface defining message type enumerations used across the messaging system. + +## Key Files + +- **`IMessageTypes.cs`** — Contains the `IMessageTypes` interface with a nested `MessageTypesEnum` enum placeholder. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Groups/README.md b/AyCode.Interfaces/Groups/README.md new file mode 100644 index 0000000..0608a66 --- /dev/null +++ b/AyCode.Interfaces/Groups/README.md @@ -0,0 +1,11 @@ +# Groups + +Interface for group entities with identity and timestamp support. + +## Key Files + +- **`IGroupBase.cs`** — Base group interface extending `IEntityGuid` and `ITimeStampInfo`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Locations/README.md b/AyCode.Interfaces/Locations/README.md new file mode 100644 index 0000000..38ea1b6 --- /dev/null +++ b/AyCode.Interfaces/Locations/README.md @@ -0,0 +1,11 @@ +# Locations + +Interface for location entities providing geographic coordinates and address text. + +## Key Files + +- **`ILocationBase.cs`** — Defines `Longitude`, `Latitude`, and `Address` properties. Extends `IEntityGuid`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Logins/README.md b/AyCode.Interfaces/Logins/README.md new file mode 100644 index 0000000..17269a5 --- /dev/null +++ b/AyCode.Interfaces/Logins/README.md @@ -0,0 +1,13 @@ +# Logins + +Interfaces for authentication and login service contracts, covering login state, registration, and password management. + +## Key Files + +- **`IAcLoginServiceBase.cs`** — Base login service with `IsLoggedIn` and `LoggedInUser` properties, generic over user/profile/company types. +- **`IAcLoginServiceCommon.cs`** — Extends the base with `Logout`, `Registration`, `ChangePassword`, and `ForgotPassword` methods (sync and async). +- **`IAcLoginServiceClient.cs`** — Client-side login service marker interface extending `IAcLoginServiceCommon`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/MediaInfo/README.md b/AyCode.Interfaces/MediaInfo/README.md new file mode 100644 index 0000000..2ed5f20 --- /dev/null +++ b/AyCode.Interfaces/MediaInfo/README.md @@ -0,0 +1,13 @@ +# MediaInfo + +Interfaces for media-related properties such as thumbnail URLs and user media identifiers. + +## Key Files + +- **`IMediaInfo.cs`** — Composite interface combining `IMediaThumbnailUrl` and `IMediaUserMediaId`. +- **`IMediaThumbnailUrl.cs`** — Defines an optional `ThumbnailUrl` string property. +- **`IMediaUserMediaId.cs`** — Defines an optional `UserMediaId` (Guid?) property. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Messages/README.md b/AyCode.Interfaces/Messages/README.md new file mode 100644 index 0000000..53a560e --- /dev/null +++ b/AyCode.Interfaces/Messages/README.md @@ -0,0 +1,18 @@ +# Messages + +Interfaces for the email/messaging system, covering message entities, recipients, relations, and the message sender service. + +## Key Files + +- **`IAcEmailMessageBase.cs`** — Base email message with `ContextId`, `SenderId`, `Subject`, `Text`, `IsReaded`, and `ContextType`. Extends `IEntityGuid`, `ITimeStampInfo`, `IAcEmailAddress`. +- **`IAcEmailMessage.cs`** — Full email message combining `IAcEmailMessageBase` with a recipients relation. +- **`IAcEmailRecipientBase.cs`** — Base recipient with `RecipientId`, `EmailMessageId`, and `IsReaded`. +- **`IAcEmailRecipient.cs`** — Full recipient combining base recipient with an email message relation. +- **`IAcEmailMessageRelation.cs`** — Navigation property for entities holding an `EmailMessage` reference. +- **`IAcEmailRecipientsRelation.cs`** — Navigation property exposing a `List` collection. +- **`IAcEmailMessageForeignKey.cs`** — Foreign key contract for `EmailMessageId` (generic and Guid variants). +- **`IAcMessageSenderService.cs`** — Service interface with `SendMessageAsync` for dispatching messages. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Profiles/Dtos/README.md b/AyCode.Interfaces/Profiles/Dtos/README.md new file mode 100644 index 0000000..4c097d7 --- /dev/null +++ b/AyCode.Interfaces/Profiles/Dtos/README.md @@ -0,0 +1,13 @@ +# Profiles/Dtos + +DTO interfaces for profile data, defining name fields and the base profile DTO shape. + +## Key Files + +- **`IAcFullName.cs`** — Defines `FullName` (read-only), `FirstName`, and `LastName` properties. +- **`IAcProfileName.cs`** — Extends `IAcFullName` with a `Name` property. +- **`IAcProfileDtoBase.cs`** — Base profile DTO with `EmailAddress`, `Description`, media info, and address foreign key. Generic variant adds an address relation. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Profiles/README.md b/AyCode.Interfaces/Profiles/README.md new file mode 100644 index 0000000..52e6c81 --- /dev/null +++ b/AyCode.Interfaces/Profiles/README.md @@ -0,0 +1,13 @@ +# Profiles + +Interfaces for user/company profile entities, including navigation relations and foreign key contracts. + +## Key Files + +- **`IAcProfile.cs`** — Full profile interface with `GetFullName` and `SetAddress` methods, extends `IAcProfileDtoBase` and `ITimeStampInfo`. +- **`IAcProfileRelation.cs`** — Generic navigation property for entities holding a `Profile` reference. +- **`IAcProfileForeignKey.cs`** — Foreign key contract exposing `ProfileId` (Guid), extends `IForeignKey`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/README.md b/AyCode.Interfaces/README.md new file mode 100644 index 0000000..9f3c4bf --- /dev/null +++ b/AyCode.Interfaces/README.md @@ -0,0 +1,46 @@ +# AyCode.Interfaces + +Domain interface contracts for the AyCode platform. Defines the shape of entities, DTOs, relationships, and service contracts. All interfaces are composable — small, single-responsibility interfaces are combined via inheritance to build up complex types. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| `Addresses/` | Address entity, DTO, relation, and foreign key interfaces | +| `Entities/` | Base entity interfaces: `IEntity`, `IEntityGuid`, `IEntityInt`, soft-delete support | +| `EntityComment/` | `IEntityComment` — adds `Comment` property | +| `Enums/` | `IMessageTypes` — message type enum container | +| `Groups/` | `IGroupBase` — base group entity (Guid + timestamps) | +| `Locations/` | `ILocationBase` — read-only lat/lng/address | +| `Logins/` | Login service contracts: `Logout`, `Registration`, `ChangePassword`, `ForgotPassword` | +| `MediaInfo/` | Media metadata: thumbnail URL, user media ID | +| `Messages/` | Email message system: message, recipient, sender service interfaces | +| `Profiles/` | User profile: name, full name, media, address, DTOs | +| `ServiceProviders/` | Company/service provider entity and relationship interfaces | +| `StorageHandlers/` | `ISecureStorageHandler` — async secure key-value storage | +| `TimeStampInfo/` | `Created`/`Modified` timestamps, `ITimeStampDisableAutoSet` marker | +| `Users/` | User entity, base, token, email, password, company relations, DTOs | + +## Root Interfaces + +- **`IOwnerId.cs`** — `Guid OwnerId` property. +- **`IAcModelDtoBase.cs`** — Base DTO interface (`IEntityGuid`); generic version adds `CreateMainEntity()`. +- **`ICustomForeignKey.cs`** — Generic marker for custom foreign keys (int/Guid variants). + +## Design Patterns + +- **Composition over inheritance** — Small interfaces (`ITimeStampInfo`, `IAcEmailAddress`, `IPassword`) are mixed in as needed. +- **Generic relations** — `IAcXxxRelation` pattern for navigation properties and collections. +- **Separate FK interfaces** — `IAcXxxForeignKey` for type-safe foreign key declarations. +- **DTO hierarchy** — `DtoBase` interfaces separate from full entity interfaces. +- **Soft delete** — Optional via `IAcSoftRemoveEntity` / `IAcSoftRemoveEntityGuid` / `IAcSoftRemoveEntityInt`. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Core library (`IId`, `IForeignKey`, enums, error codes) | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/ServiceProviders/README.md b/AyCode.Interfaces/ServiceProviders/README.md new file mode 100644 index 0000000..44c943d --- /dev/null +++ b/AyCode.Interfaces/ServiceProviders/README.md @@ -0,0 +1,14 @@ +# ServiceProviders + +Interfaces for company/service provider entities, covering base properties, profile relations, user associations, and foreign keys. + +## Key Files + +- **`IAcCompanyBase.cs`** — Base company interface with `OwnerId`, `Name`, `CommissionPercent`, `AffiliateId`, `ReferralId`, and `HasUser`/`AddUser` methods. +- **`IAcCompany.cs`** — Multiple generic variants linking a company to its profile, address, and user collections. +- **`IAcCompanyRelation.cs`** — Navigation property for entities holding `ServiceProviders` and `UserToServiceProviders` lists. +- **`IAcCompanyForeignKey.cs`** — Foreign key contract exposing `ServiceProviderId` (Guid). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/StorageHandlers/README.md b/AyCode.Interfaces/StorageHandlers/README.md new file mode 100644 index 0000000..05d0a9a --- /dev/null +++ b/AyCode.Interfaces/StorageHandlers/README.md @@ -0,0 +1,11 @@ +# StorageHandlers + +Interface for secure key-value storage operations (save, get, delete, clear). + +## Key Files + +- **`ISecureStorageHandler.cs`** — Async methods: `SaveToSecureStorageAsync`, `GetFromSecureStorageAsync`, `DeleteFromSecureStorageAsync`, and `ClearAllSecureStorageAsync`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/TimeStampInfo/README.md b/AyCode.Interfaces/TimeStampInfo/README.md new file mode 100644 index 0000000..cbd9e97 --- /dev/null +++ b/AyCode.Interfaces/TimeStampInfo/README.md @@ -0,0 +1,14 @@ +# TimeStampInfo + +Interfaces for entity timestamp tracking (created/modified) and a marker to disable automatic timestamp setting. + +## Key Files + +- **`ITimeStampCreated.cs`** — Defines a `Created` DateTime property. +- **`ITimeStampModified.cs`** — Defines a `Modified` DateTime property. +- **`ITimeStampInfo.cs`** — Composite interface combining `ITimeStampCreated` and `ITimeStampModified`. +- **`ITimeStampDisableAutoSet.cs`** — Marker interface to opt out of automatic timestamp population. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Users/Dtos/README.md b/AyCode.Interfaces/Users/Dtos/README.md new file mode 100644 index 0000000..bbba420 --- /dev/null +++ b/AyCode.Interfaces/Users/Dtos/README.md @@ -0,0 +1,13 @@ +# Users/Dtos + +DTO interfaces for user data at different detail levels -- minimal, base, and detailed -- with generic variants for profile and company associations. + +## Key Files + +- **`IAcUserDtoMinBase.cs`** — Minimal user DTO with `AffiliateId`. Generic variant adds a profile relation. +- **`IAcUserDtoBase.cs`** — Base user DTO extending the minimal DTO. Generic variants add profile and company relations. +- **`IAcUserDtoDetailBase.cs`** — Detailed user DTO combining `IAcUserBase` with DTO base interfaces. Generic variants add profile, company, and address type parameters. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Interfaces/Users/README.md b/AyCode.Interfaces/Users/README.md new file mode 100644 index 0000000..3efbe53 --- /dev/null +++ b/AyCode.Interfaces/Users/README.md @@ -0,0 +1,23 @@ +# Users + +Interfaces for user entities, covering base properties, authentication fields, company associations, relations, and foreign keys. + +## Key Files + +- **`IAcUserBase.cs`** — Core user interface with `FullName`, `PhoneNumber`, `RefreshToken`, `RefferalId`, email, password, and timestamps. +- **`IAcUser.cs`** — Full user interface generic over profile, company, and address types. +- **`IAcEmailAddress.cs`** — Defines an `EmailAddress` string property with max length 150. +- **`IPassword.cs`** — Defines a `Password` string property. +- **`IEmailConfirmed.cs`** — Defines an `EmailConfirmed` boolean property. +- **`IAcUserTokenBase.cs`** — User token interface with `Token`, `TokenSent`, `TokenExpiration`, and `IsActive`. +- **`IAcUserRelation.cs`** — Navigation property for entities holding a `User` reference. +- **`IAcUsersRelation.cs`** — Navigation property for `Users` and `UserToServiceProviders` collections. +- **`IAcUserToCompanyBase.cs`** — Base user-to-company join with `Permissions`, user/company foreign keys. +- **`IAcUserToCompany.cs`** — Generic join entity with `User` and `Company` navigation properties. +- **`IAcUserToServiceProviderRelation.cs`** — Relation linking a user to a service provider. +- **`IAcUserModelDtoMinBase.cs`** — Minimal user model DTO marker extending `IAcModelDtoBase`. +- **`IAcUserForeignKey.cs`** — Foreign key contract exposing `UserId` (Guid). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models.Server/DynamicMethods/README.md b/AyCode.Models.Server/DynamicMethods/README.md new file mode 100644 index 0000000..1a70a07 --- /dev/null +++ b/AyCode.Models.Server/DynamicMethods/README.md @@ -0,0 +1,13 @@ +# DynamicMethods + +Reflection-based infrastructure for dynamically dispatching method calls by message tag, primarily used for SignalR message routing. + +## Key Files + +- **`AcMethodInfoModel.cs`** — Wraps a `MethodInfo` and its `TagAttribute` with cached parameter metadata. +- **`AcDynamicMethodCallModel.cs`** — Binds an object instance to its attributed methods, using a static `ConcurrentDictionary` and `FrozenDictionary` cache keyed by message tag. Reflection runs once per type. +- **`AcDynamicMethodRegistry.cs`** — Registry with lazy method lookup across multiple registered instances. Caches discovered methods statically by message tag and resolves instances per request. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models.Server/Logins/README.md b/AyCode.Models.Server/Logins/README.md new file mode 100644 index 0000000..e2ea7c4 --- /dev/null +++ b/AyCode.Models.Server/Logins/README.md @@ -0,0 +1,11 @@ +# Logins + +Server-side implementation of the logged-in session model, managing user authentication state and access tokens. + +## Key Files + +- **`AcLoggedInModelServer.cs`** — Generic implementation of `IAcLoggedInModelBase`. Tracks `LoggedInUser`, `AccessToken`, and `LoginErrorCode`, with `AddLoggedInUser` and `Logout` methods. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models.Server/README.md b/AyCode.Models.Server/README.md new file mode 100644 index 0000000..27eb4cc --- /dev/null +++ b/AyCode.Models.Server/README.md @@ -0,0 +1,37 @@ +# AyCode.Models.Server + +Server-side models: authentication state and dynamic method dispatch for SignalR message routing. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| `Logins/` | Server-side logged-in user model | +| `DynamicMethods/` | Reflection-based method registry for SignalR message tag routing | + +## Key Files + +### Logins/ +- **`AcLoggedInModelServer.cs`** — Implements `IAcLoggedInModelBase<...>`. Tracks `LoggedInUser`, `AccessToken`, `LoginErrorCode`. Methods: `AddLoggedInUser()`, `Logout()`. + +### DynamicMethods/ +- **`AcMethodInfoModel.cs`** — Wraps a `MethodInfo` + its `TagAttribute` + `ParameterInfo[]`. Generic over `TAttribute : TagAttribute`. +- **`AcDynamicMethodCallModel.cs`** — Binds an object instance to its attributed methods. Static `ConcurrentDictionary` + `FrozenDictionary` cache — reflection runs once per type. Lookup by `MessageTag` (int). +- **`AcDynamicMethodRegistry.cs`** — Per-request registry for dynamic method dispatch. `Register()` stores instances, `GetMethodByMessageTag()` resolves method + instance with lazy search and static cache. Optimized for small instance counts (array-backed, no List). + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Error codes | +| `AyCode.Core.Server` | Server-side core | +| `AyCode.Entities` | Entity base classes | +| `AyCode.Entities.Server` | Server entities | +| `AyCode.Interfaces` | Interface contracts | +| `AyCode.Interfaces.Server` | `IAcLoggedInModelBase` | +| `AyCode.Models` | Shared models | +| `AyCode.Services` | `TagAttribute` for SignalR method tagging | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models/Enums/README.md b/AyCode.Models/Enums/README.md new file mode 100644 index 0000000..278d2c5 --- /dev/null +++ b/AyCode.Models/Enums/README.md @@ -0,0 +1,12 @@ +# Enums + +Enumerations for messaging-related types used across the application models. + +## Key Files + +- **`MessageContentType.cs`** — Defines content types for messages: Text, Image, Video, Audio, File, Location, Contact, Sticker, Gif, VoiceNote, System. +- **`MessageTypesEnum.cs`** — Defines message delivery channels: email (1), sms (2), push (3), chat (4). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models/Messages/README.md b/AyCode.Models/Messages/README.md new file mode 100644 index 0000000..0449ef7 --- /dev/null +++ b/AyCode.Models/Messages/README.md @@ -0,0 +1,11 @@ +# Messages + +Placeholder namespace for message models. The `EmailMessage` class is currently commented out. + +## Key Files + +- **`EmailMessage.cs`** — Contains a commented-out `EmailMessage` class (with Subject and HtmlContent properties) that previously extended `NoticeBase`. Currently inactive. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models/README.md b/AyCode.Models/README.md new file mode 100644 index 0000000..07fbbc3 --- /dev/null +++ b/AyCode.Models/README.md @@ -0,0 +1,41 @@ +# AyCode.Models + +Shared DTOs (Data Transfer Objects) and view models for the AyCode platform. Bridges entities and interfaces into client/server-transferable models. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| `Enums/` | Message-related enums (content types, message types) | +| `Messages/` | Email message model (currently inactive) | +| `Users/` | User DTOs: minimal, standard, detail variants + password DTOs | + +## Root Files + +- **`AcModelDtoBase.cs`** — Abstract base DTO with `Guid Id`. Generic version `AcModelDtoBase` adds `CreateMainEntity()` for DTO-to-entity instantiation via reflection. + +## Key Files + +### Enums/ +- **`MessageContentType.cs`** — Enum: Text, Image, Video, Audio, File, Location, Contact, Sticker, Gif, VoiceNote, System. +- **`MessageTypesEnum.cs`** — Enum: email(1), sms(2), push(3), chat(4). + +### Users/ +- **`AcUserModelDtoMinBase.cs`** — Minimal user DTO with `UserDto` and `ProfileDto`. `CopyUserDtoValuesToUser()` for reverse mapping. +- **`AcUserModelDtoBase.cs`** — Extends min base with `ServiceProviders` and `UserToServiceProviders` lists. +- **`AcUserModelDtoDetailBase.cs`** — Full detail DTO: populates email, phone, address, timestamps. Bidirectional mapping via `CopyUserDtoValuesToUser()`. +- **`AcPasswordDtoBase.cs`** — Base with `NewPassword` property. +- **`AcChangePasswordDto.cs`** — Extends password base with `UserId` + `OldPassword`. +- **`AcForgotPasswordDto.cs`** — Extends password base with `Email`. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Core types | +| `AyCode.Entities` | Entity base classes for DTO-entity mapping | +| `AyCode.Interfaces` | Interface contracts implemented by DTOs | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Models/Users/README.md b/AyCode.Models/Users/README.md new file mode 100644 index 0000000..b026896 --- /dev/null +++ b/AyCode.Models/Users/README.md @@ -0,0 +1,16 @@ +# Users + +Abstract base DTOs for user data transfer, including minimal, standard, and detailed user models, plus password-related DTOs. + +## Key Files + +- **`AcUserModelDtoMinBase.cs`** — Minimal user DTO with `UserDto` and `ProfileDto` properties (name, affiliate ID). +- **`AcUserModelDtoBase.cs`** — Extends the minimal DTO with `ServiceProviders` and `UserToServiceProviders` lists. +- **`AcUserModelDtoDetailBase.cs`** — Full detail DTO adding email, phone, address, referral, and timestamp fields. +- **`AcPasswordDtoBase.cs`** — Base class for password operations with a `NewPassword` property. +- **`AcChangePasswordDto.cs`** — Extends `AcPasswordDtoBase` with `UserId` and `OldPassword` for password change requests. +- **`AcForgotPasswordDto.cs`** — Extends `AcPasswordDtoBase` with `Email` for forgot-password flows. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services.Server/Emails/README.md b/AyCode.Services.Server/Emails/README.md new file mode 100644 index 0000000..cc40eca --- /dev/null +++ b/AyCode.Services.Server/Emails/README.md @@ -0,0 +1,11 @@ +# Emails + +Server-side email delivery via SendGrid. + +## Key Files + +- **`AcEmailServiceServer.cs`** — Implements `IAcEmailServiceServer`. Uses `SendGridClient` to send templated emails. Methods: `SendLostPasswordEmailAsync()` (password reset with token), `SendRegistrationEmailAsync()` (confirmation with token). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services.Server/Logins/README.md b/AyCode.Services.Server/Logins/README.md new file mode 100644 index 0000000..6d597da --- /dev/null +++ b/AyCode.Services.Server/Logins/README.md @@ -0,0 +1,11 @@ +# Logins + +Server-side login service with JWT token management. + +## Key Files + +- **`AcLoginServiceServer.cs`** — Heavily generic class extending `AcLoginServiceBase`, implementing `IAcLoginServiceServer`. Full authentication flow: `Login()`, `Logout()`, `Registration()`, `ChangePassword()`, `ForgotPassword()`. JWT methods: `GenerateAccessToken()`, `GenerateRefreshToken()`, `GetPrincipalFromExpiredToken()`. Uses DAL for database access. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services.Server/README.md b/AyCode.Services.Server/README.md new file mode 100644 index 0000000..c594fa7 --- /dev/null +++ b/AyCode.Services.Server/README.md @@ -0,0 +1,31 @@ +# AyCode.Services.Server + +Server-side service implementations: JWT authentication, SendGrid email delivery, SignalR hub infrastructure with binary protocol, session management, and change-tracked data sources. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Emails/`](Emails/README.md) | SendGrid email service (registration, password reset) | +| [`Logins/`](Logins/README.md) | Server-side login with JWT token generation | +| [`SignalRs/`](SignalRs/README.md) | SignalR hub base, session service, data source with change tracking, client broadcast | + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Core types, serializers | +| `AyCode.Core.Server` | GlobalLogger | +| `AyCode.Database` | Data access layer | +| `AyCode.Entities` / `AyCode.Entities.Server` | Entity types | +| `AyCode.Interfaces` / `AyCode.Interfaces.Server` | Service contracts | +| `AyCode.Models` / `AyCode.Models.Server` | DTOs, dynamic method dispatch | +| `AyCode.Services` | Client-side SignalR base, tag attributes | +| `SendGrid` | Email delivery | +| `Microsoft.AspNetCore.SignalR.*` | SignalR server | +| `Microsoft.AspNetCore.Cryptography.KeyDerivation` | Password hashing | +| `Microsoft.AspNetCore.Authentication.JwtBearer` | JWT auth (transitive) | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services.Server/SignalRs/README.md b/AyCode.Services.Server/SignalRs/README.md new file mode 100644 index 0000000..2a10697 --- /dev/null +++ b/AyCode.Services.Server/SignalRs/README.md @@ -0,0 +1,26 @@ +# SignalRs + +Server-side SignalR hub infrastructure: hub base class, session management, data source with change tracking, and client broadcast service. + +## Key Files + +### Hub +- **`AcWebSignalRHubBase.cs`** — Abstract hub extending `Hub`. Manages connection lifecycle, message dispatch via `DynamicMethodRegistry`, binary/JSON parameter deserialization. Response methods: `ResponseToCaller()`, `SendMessageToOthers()`, `SendMessageToUserIdInternal()`. +- **`IAcSignalRHubItemServer.cs`** — Server hub interfaces: `IAcSignalRHubItemServer`, `IAcSignalRHubServer`. +- **`AcLoggerSignalRHub.cs`** — Specialized hub for receiving log items via SignalR (`AddLogItem()`). + +### Session & Broadcast +- **`AcSessionService.cs`** — Generic session manager with `ConcurrentDictionary`. +- **`IAcSessionItem.cs`** — Session item interface with `SessionId` property. +- **`AcSignalRSendToClientService.cs`** — Abstract broadcast service: `SendMessageToClient()`, `SendMessageToAllClients()`, `SendMessageToConnection()`, `SendMessageToUser()`. + +### Data Source +- **`AcSignalRDataSource.cs`** — Server-side data source implementing `IList` with change tracking (`TrackingItem`, `ChangeTracking`). Supports `LoadDataSource()`, `LoadDataSourceFromResponseData()` with binary/JSON deserialization. + +### Utilities +- **`ExtensionMethods.cs`** — `InvokeMethod()` — invokes methods and unwraps `Task`/`Task`/`ValueTask` results. +- **`TrackingItemHelpers.cs`** — Deep clone helpers: `JsonClone()`, `ReflectionClone()`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services/Loggers/README.md b/AyCode.Services/Loggers/README.md new file mode 100644 index 0000000..3c97cac --- /dev/null +++ b/AyCode.Services/Loggers/README.md @@ -0,0 +1,15 @@ +# Loggers + +Remote log writers for sending log items over HTTP, SignalR, or to the browser console. + +## Key Files + +- **`AcHttpClientLogItemWriter.cs`** — Abstract generic writer extending `AcLogItemWriterBase`. Sends log items via HTTP POST as JSON. Manages its own `HttpClient` lifecycle. +- **`AcBrowserConsoleLogWriter.cs`** — Browser console writer via JS interop (`IJSRuntime`). Maps `LogLevel` to console methods (log, warn, error). Used in Blazor apps. +- **`AcSignaRClientLogItemWriter.cs`** — Sends `AcLogItemClient` items to a SignalR hub. Manages `HubConnection` lifecycle with `StartConnection()`/`StopConnection()`. + +All three implement `IAcLogWriterClientBase`. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services/Logins/README.md b/AyCode.Services/Logins/README.md new file mode 100644 index 0000000..fb2b161 --- /dev/null +++ b/AyCode.Services/Logins/README.md @@ -0,0 +1,12 @@ +# Logins + +Base and client-side login service implementations. + +## Key Files + +- **`AcLoginServiceBase.cs`** — Abstract generic base implementing `IAcLoginServiceBase`. Provides `IsLoggedIn` and `LoggedInUser` properties. Heavily constrained generics (TUser, TProfile, TCompany, TUserToServiceProvider, TProfileAddress). +- **`AcLoginServiceClient.cs`** — Client-side login service extending `AcLoginServiceBase`, implementing `IAcLoginServiceClient`. Provides stubs for `Login`, `Logout`, `Registration`, `ChangePassword`, `ForgotPassword` (sync + async variants). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services/README.md b/AyCode.Services/README.md new file mode 100644 index 0000000..b0feb41 --- /dev/null +++ b/AyCode.Services/README.md @@ -0,0 +1,27 @@ +# AyCode.Services + +Shared service implementations: SignalR communication (custom binary protocol), login services, and remote log writers. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Loggers/`](Loggers/README.md) | Remote log writers: HTTP, browser console (JS interop), SignalR | +| [`Logins/`](Logins/README.md) | Base and client-side login service implementations | +| [`SignalRs/`](SignalRs/README.md) | Custom binary SignalR protocol, client base, message tagging, serialization | + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `AyCode.Core` | Core types, serializers, compression | +| `AyCode.Entities` | Entity base classes | +| `AyCode.Interfaces` | Service contracts | +| `AyCode.Models` | DTOs | +| `Microsoft.AspNetCore.SignalR.Client` | SignalR client | +| `Microsoft.AspNetCore.SignalR.Common` | `IHubProtocol` for custom binary protocol | +| `Microsoft.AspNetCore.Authentication.JwtBearer` | JWT authentication | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Services/SignalRs/README.md b/AyCode.Services/SignalRs/README.md new file mode 100644 index 0000000..940a117 --- /dev/null +++ b/AyCode.Services/SignalRs/README.md @@ -0,0 +1,27 @@ +# SignalRs + +Custom binary SignalR protocol, client infrastructure, message tagging, and serialization helpers. + +## Key Files + +### Protocol +- **`AcBinaryHubProtocol.cs`** — Custom `IHubProtocol` replacing JSON+Base64 with `AcBinarySerializer`. Handles all 9 SignalR message types (Invocation, StreamItem, Completion, Ping, Close, etc.). Inner `SpanReader` ref struct for zero-alloc parsing. + +### Client +- **`AcSignalRClientBase.cs`** — Abstract SignalR client managing `HubConnection`, request/response tracking via pooled `SignalRRequestModel`. Methods: `SendMessageToServerAsync()`, CRUD helpers (Post, Get, GetAll, GetAllInto). Configurable timeouts. +- **`IAcSignalRHubClient.cs`** — Client interface + `SignalResponseDataMessage` (sealed, supports JSON/Binary with GZip, caching, diagnostics). +- **`IAcSignalRHubBase.cs`** — Base hub interface: `OnReceiveMessage(int messageTag, byte[] messageBytes, int? requestId)`. + +### Message Tagging +- **`SignalMessageTagAttribute.cs`** — Three attributes: `TagAttribute` (base, int messageTag), `SignalRAttribute` (server method routing + client notification), `SignalRSendToClientAttribute` (client-side receive). +- **`AcSignalRTags.cs`** — Static constants: `None`, `PingTag`, `EchoTag`. +- **`SignalRCrudTags.cs`** — Sealed record mapping 5 CRUD tags. `GetMessageTagByTrackingState()` maps `TrackingState` → tag. +- **`SendToClientType.cs`** — Enum: None, Others, Caller, All. + +### Serialization & Pooling +- **`SignalRSerializationHelper.cs`** — Static helpers: `SerializeToBinary()`, `DeserializeFromBinary()`, compressed JSON variants, `CreateResponseData()`. +- **`SignalRRequestModel.cs`** — Poolable (`IResettable`) request tracking model with `ObjectPool` for reuse. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Utils.Server/README.md b/AyCode.Utils.Server/README.md new file mode 100644 index 0000000..f5dc7d9 --- /dev/null +++ b/AyCode.Utils.Server/README.md @@ -0,0 +1,11 @@ +# AyCode.Utils.Server + +Server-side utility library placeholder. Currently empty — reserved for future server-specific utilities. + +## Dependencies + +None. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Utils/Extensions/README.md b/AyCode.Utils/Extensions/README.md new file mode 100644 index 0000000..5169441 --- /dev/null +++ b/AyCode.Utils/Extensions/README.md @@ -0,0 +1,13 @@ +# Extensions + +String, DateTime, and lock utility extensions. + +## Key Files + +- **`StringExtensions.cs`** — `IsNullOrEmpty()`, `IsNullOrWhiteSpace()` (with `[NotNullWhen]`), `FirstLetterToUpper()`, `MixCharacters()` (interleaves two char sequences: ABC+DEF→ADBECF). +- **`DateTimeExtension.cs`** — `IsNullOrEmpty()` for `DateTime`/`DateTime?`, `IsEqualSqlDateTime2()` for SQL Server datetime2 precision comparison. +- **`LockExtensions.cs`** — `using` pattern for locks: `mutex.UseWaitOne()`, `semaphore.UseWait()`, `semaphore.UseWaitAsync()`. Returns `IDisposable` wrappers that auto-release on dispose. + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Utils/README.md b/AyCode.Utils/README.md new file mode 100644 index 0000000..c9e950a --- /dev/null +++ b/AyCode.Utils/README.md @@ -0,0 +1,21 @@ +# AyCode.Utils + +Low-level utility library with zero project dependencies. Provides string/datetime extensions, and disposable lock wrappers for `using` pattern with `Mutex`/`SemaphoreSlim`. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Extensions/`](Extensions/README.md) | String, DateTime, and lock extension methods | +| [`Wrappers/`](Wrappers/README.md) | Disposable wrappers for Mutex and SemaphoreSlim | + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `JetBrains.Annotations` | `[ContractAnnotation]` for nullability hints | +| `Microsoft.AspNetCore.Cryptography.KeyDerivation` | Key derivation (available to dependents) | + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code. diff --git a/AyCode.Utils/Wrappers/README.md b/AyCode.Utils/Wrappers/README.md new file mode 100644 index 0000000..a35cca1 --- /dev/null +++ b/AyCode.Utils/Wrappers/README.md @@ -0,0 +1,14 @@ +# Wrappers + +Disposable wrappers enabling `using` pattern for synchronization primitives. + +## Key Files + +- **`ReleaseWrapperMutex.cs`** — `IDisposable` wrapper for `Mutex`. Calls `ReleaseMutex()` on dispose. Used via `mutex.UseWaitOne()`. +- **`ReleaseWrapperSemaphore.cs`** — `IDisposable` wrapper for `SemaphoreSlim`. Calls `Release()` on dispose. Used via `semaphore.UseWait()` / `UseWaitAsync()`. + +Both are idempotent (safe to dispose multiple times via `_isDisposed` flag). + +--- + +> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.