Adam
/
AyCode.Core
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add comprehensive README docs for all core subfolders 

Added detailed README files for the root AyCode.Core library and each major subfolder (Compression, Consts, Enums, Extensions, Helpers, Interfaces, Loggers). Each README outlines folder purpose, key files, APIs, and critical notes, with tables and architecture diagrams where relevant. Included explicit instructions for LLM-based maintenance. This greatly improves project documentation and developer onboarding.
This commit is contained in:
Loretta 2026-03-28 16:24:03 +01:00
parent 0e912891b1
commit e606cd171b
8 changed files with 191 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
AyCode.Core/Compression/README.md Normal file
View File

@ -0,0 +1,28 @@
# Compression
Three compression algorithms with a unified static API. All implementations use `ArrayPool<byte>` and `stackalloc` for minimal GC pressure.
## Key Files
- **`BrotliHelper.cs`** — Brotli compress/decompress. Stack-allocates for small inputs, pools for large. `IsBrotliCompressed()` detection.
- **`GzipHelper.cs`** — GZip compress/decompress. Same API shape as BrotliHelper. `IsGzipCompressed()` checks magic bytes (0x1F, 0x8B).
- **`Lz4.cs`** — High-level LZ4 facade. Dispatches to Block or BlockArray mode via `Lz4CompressionMode`.
- **`Lz4Compressor.cs`** — Pure managed LZ4 block compressor. Hash table pattern matching (4K entries, 12-bit hash), MinMatch=4. WASM-compatible (no native dependencies).
- **`Lz4Decompressor.cs`** — LZ4 block/BlockArray decompressor. Handles overlapping copies for match references.
- **`Lz4CompressionMode.cs`** — Enum: `None`, `Block` (single), `BlockArray` (64KB chunked).
## LZ4 Modes
| Mode | Use Case |
|---|---|
| `Block` | Single contiguous block with 4-byte size header |
| `BlockArray` | Chunked (64KB default) for streaming/large data |
## Dependencies
- `System.IO.Compression` (Brotli, GZip)
- `System.Buffers` (ArrayPool)
---
> **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.

15
AyCode.Core/Consts/README.md Normal file
View File

@ -0,0 +1,15 @@
# Consts
Project-wide constants, error codes, environment configuration, regex patterns, and input validation.
## Key Files
- **`AcConst.cs`** — Central constants: `ProjectId`/`ProjectSalt` (loaded from appsettings), user/password length limits, TCP/messaging defaults, well-known Guids, `AvailableDomainSuffixes` (300+ TLDs). **Critical:** `GenerateProjectSalt()` must not be modified — it is tied to authentication.
- **`AcEnv.cs`** — Environment access: `AppConfiguration` (lazy-loaded from appsettings.json + env vars), `NL` (newline), `MaxLogItemsPerSession`, `GetEnum<T>()` config helper.
- **`AcErrorCode.cs`** — Byte enum with 60+ error codes (0=UnknownError ... 255=Unset). Used across the entire API layer.
- **`AcRegExpression.cs`** — Compile-time generated regex via `[GeneratedRegex]`: `EmailRegex()` (RFC-compliant), `PhoneNumberRegex()` (E.164 format).
- **`AcValidate.cs`** — Input validation methods returning `bool` + `out AcErrorCode`: email, password, username, player name, phone, domain, user token format checks.
---
> **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.

13
AyCode.Core/Enums/README.md Normal file
View File

@ -0,0 +1,13 @@
# Enums
Shared enums used across the platform. All are `byte`-based for compact serialization.
## Key Files
- **`AppType.cs`** — Identifies application type: None(0), Server(1), Relay(5), Game(10), Web(15), Mobile(20), Dissonance(25), TestUnit(255).
- **`MessageContextType.cs`** — Message routing context: Unset(0), System(5), Private(10), Group(15), Transfer(20), Product(25), Company(30).
- **`TrackingState.cs`** — Entity change tracking: None(0), Get(1), GetAll(2), Add(3), Update(4), Remove(5).
---
> **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.

22
AyCode.Core/Extensions/README.md Normal file
View File

@ -0,0 +1,22 @@
# Extensions
Extension methods for collections, serialization, and common utilities.
## Key Files
- **`CollectionExtensions.cs`** — `IList<T>` extensions for `IId<Guid>` entities: `UpdateCollection()` (add/update/remove with `TrackingState`), `FindIndex()`, `BinarySearch()`, safe indexing.
- **`CollectionExtensionsInt.cs`** — Same as above but for `IId<int>` entities.
- **`SerializeObjectExtensions.cs`** — Unified serialization API via extension methods:
- `.ToJson()`, `.JsonTo<T>()` — JSON serialization (Newtonsoft + custom `HybridReferenceResolver` with Base62 semantic IDs)
- `.ToBinary()`, `.BinaryTo<T>()` — Binary serialization
- `.CloneTo<TDest>()`, `.CopyTo()` — Object cloning
- `.JsonToChain<T>()`, `.BinaryToChain<T>()` — Multi-deserialize chains
- `.BinaryToMerge<T>()` — IId-aware collection merging
- Includes: `JsonReferencePostProcessor` (strips unreferenced `$id`), `PooledStringWriter` (StringBuilder pooling)
- **`EnumExtensions.cs`** — `GetDisplayName()` via `DisplayAttribute` reflection.
- **`ExceptionExtensions.cs`** — `GetCategoryAndMemberNameFromStackTraceString()` for structured caller info extraction.
- **`GuidExtensions.cs`** — `IsNullOrEmpty()` for `Guid` and `Guid?` with `[NotNullWhen]` annotations.
---
> **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.

23
AyCode.Core/Helpers/README.md Normal file
View File

@ -0,0 +1,23 @@
# Helpers
Utility classes for token generation, observable collections, type metadata, password security, and async patterns.
## Key Files
- **`AcCharsGenerator.cs`** — Random token/password generation from predefined char pools (`Letters`, `Numbers`, `LettersAndNumbers`). `NewToken()` (8-12 chars), `NewPassword()` (configurable length).
- **`AcObservableCollection.cs`** — Thread-safe `ObservableCollection<T>` with batch updates (`BeginUpdate()`/`EndUpdate()`), `SynchronizationContext` capture for UI thread marshalling (Blazor), `PopulateFromJson()`, `SortAndReplace()`.
- **`ConstHelper.cs`** — Reflection-cached lookup of `const int` field names by value. Used for debug/logging to show human-readable constant names.
- **`JsonUtilities.cs`** — Central type metadata and detection utilities:
- Pre-cached `Type` handles for primitives, generics, collections
- `FrozenSet<Type>` for fast primitive checks
- `IsPrimitiveOrStringFast()`, `IsGenericCollectionType()`, `IsDictionaryType()`, `GetCollectionElementType()`
- `DetectSerializerType()` — auto-detect JSON vs Binary from bytes/string
- UTF8 buffer pool: `RentUtf8Buffer()`, `ReturnUtf8Buffer()`
- String escaping: `NeedsEscaping()`, `WriteEscapedString()`
- **`PasswordHasher.cs`** — PBKDF2-HMAC-SHA512 with 10,000 iterations. **Critical: do not modify `GenerateDynamicSalt()` or `GenerateFinallySalt()` — login will break.** Format: `$bcrypt$v=1$salt=...base64...$hash=...base64...`
- **`PropertyHelper.cs`** — `CopyPublicValueTypeProperties<TSource, TDest>()` for DTO/entity mapping via reflection.
- **`TaskHelper.cs`** — `WaitTo()`/`WaitToAsync()` (poll predicate with timeout using `PeriodicTimer`), `Forget()` (fire-and-forget), `RunOnThreadPool()`.
---
> **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.

16
AyCode.Core/Interfaces/README.md Normal file
View File

@ -0,0 +1,16 @@
# Interfaces
Core interfaces used throughout the framework.
## Key Files
- **`IId.cs`** — `IId<T>` with `T Id { get; set; }`. The foundational interface for ID-bearing entities. Used by `CollectionExtensions` (merge/sync), `IdentityMap` (reference tracking), and all three serializers for reference resolution.
- **`IForeignKey.cs`** — Marker interfaces for navigation property detection:
- `IForeignKey` — empty marker
- `IForeignCollection<T>` — generic collection navigation marker (`T : IEnumerable`)
- `IForeignCollection` — non-generic variant
- **`IAcSerializableToJson.cs`** — Empty marker interface tagging types that can serialize to JSON. Used for query-time type filtering.
---
> **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.

38
AyCode.Core/Loggers/README.md Normal file
View File

@ -0,0 +1,38 @@
# Loggers
Custom logging framework with `Microsoft.Extensions.Logging` integration. Supports multiple output writers, colored console output, and structured log formatting.
## Architecture
```
IAcLoggerBase (: IAcLogWriterBase, ILogger)
└─ AcLoggerBase (abstract, delegates to writers)
└─ [concrete loggers per app]
IAcLogWriterBase
└─ AcLogWriterBase (abstract, config from appsettings)
└─ AcTextLogWriterBase (abstract, text formatting)
└─ AcConsoleLogWriter (colored console output)
```
## Key Files
### Logger Core
- **`IAcLoggerBase.cs`** — Unified interface combining `IAcLogWriterBase` + `ILogger`. Exposes `GetWriters` and `Writer<T>()`.
- **`AcLoggerBase.cs`** — Abstract logger implementing `ILogger`. Manages a list of `IAcLogWriterBase` writers. Maps MS `LogLevel` to `AcLogLevel`. Reads writer config from `appsettings.json` (`AyCode:Logger:LogWriters`).
- **`AcLoggerAdapter.cs`** — `AcLoggerProvider<TLogger>` implementing `ILoggerProvider` for DI integration. Extension methods: `AddAcLogger<T>()`, `UseOnlyAcLogger<T>()`.
### Writers
- **`IAcLogWriterBase.cs`** — Writer contract: `Detail()`, `Debug()`, `Info()`, `Warning()`, `Suggest()`, `Error()`, `Write()`.
- **`IAcLogWriterClientBase.cs`** — Marker interface for client-side writers.
- **`AcLogWriterBase.cs`** — Abstract base with config loading from appsettings.
- **`AcTextLogWriterBase.cs`** — Abstract text formatter. Output format: `[TIME] [APP] [LEVEL] [CATEGORY->METHOD] [THREADID] TEXT [ERROR]`.
- **`AcConsoleLogWriter.cs`** — Colored console writer (Gray=Trace, Cyan=Suggest, Yellow=Warning, Red=Error). Thread-safe via lock.
### Supporting
- **`IAcLogItemClient.cs`** — Structured log item DTO for remote transmission.
- **`LogLevel.cs`** — Byte enum: Detail(0), Trace(5), Debug(10), Info(15), Suggest(17), Warning(20), Error(25), Disabled(255). **Must match the database LogLevel table.**
---
> **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.

36
AyCode.Core/README.md Normal file
View File

@ -0,0 +1,36 @@
# AyCode.Core
Core library for the AyCode platform. Targets .NET 10. Provides serialization (Binary, JSON, Toon), compression, logging, validation, and shared utilities.
## Folder Structure
| Folder | Purpose | README |
|---|---|---|
| [`Compression/`](Compression/README.md) | Brotli, GZip, LZ4 compression (pure managed, WASM-compatible) | [README](Compression/README.md) |
| [`Consts/`](Consts/README.md) | Project-wide constants, error codes, regex validation, environment config | [README](Consts/README.md) |
| [`Enums/`](Enums/README.md) | Shared enums: AppType, MessageContextType, TrackingState | [README](Enums/README.md) |
| [`Extensions/`](Extensions/README.md) | Collection merge/sync, serialization extensions, utility extensions | [README](Extensions/README.md) |
| [`Helpers/`](Helpers/README.md) | Token generation, observable collections, JSON utilities, password hashing, task helpers | [README](Helpers/README.md) |
| [`Interfaces/`](Interfaces/README.md) | Core interfaces: IId&lt;T&gt;, IForeignKey, IAcSerializableToJson | [README](Interfaces/README.md) |
| [`Loggers/`](Loggers/README.md) | Custom logging framework with MS.Extensions.Logging integration | [README](Loggers/README.md) |
| [`Serializers/`](Serializers/README.md) | Serialization framework: Binary, JSON, Toon formats on shared infrastructure | [README](Serializers/README.md) |
## Root Files
- **`AcDomain.cs`** — Singleton for process-level state: process name, build type detection (`IsDeveloperVersion`/`IsProductVersion`), processor count, thread-safe unique ID generators (`NextUniqueInt32`, `NextUniqueInt64`).
## Dependencies
| Dependency | Purpose |
|---|---|
| `AyCode.Utils` | Shared utilities (project reference) |
| `AyCode.Core.Serializers.SourceGenerator` | Binary serializer source generation (analyzer) |
| `AutoMapper` | Object mapping |
| `MessagePack` | MessagePack serialization |
| `Newtonsoft.Json` | JSON serialization (legacy, alongside System.Text.Json) |
| `Microsoft.Extensions.Configuration.*` | appsettings.json + environment variable support |
| `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.