diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 074151b..db4ac79 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,4 +1,24 @@ -# Copilot Instructions +# AyCode.Core — Domain Rules -## Project Guidelines -- Ne ajánlj visszalépést/eltávolítást megoldásként — keress megoldást a problémára. \ No newline at end of file +> This is the **single source of truth** for domain rules. Do not duplicate these elsewhere. +> For detailed docs see: `README.md` → `docs/` + +## Key Abstractions +1. **IId** is the foundation interface — almost every entity implements it. Always preserve ID integrity. +2. **Generic entity hierarchy**: Interfaces (`AyCode.Interfaces`) → Entities (`AyCode.Entities`) → Models (`AyCode.Models`). Entities are abstract generics; concrete types live in consuming projects. +3. **TrackingState** enum (Added/Modified/Deleted/Unchanged) drives client-side change tracking, not EF Core. + +## Serialization +4. **Toon** (Token-Oriented Object Notation) — primary goal is **LLM accuracy**. @meta/@data sections. +5. **AcBinary** — primary goal is **speed**. Two-phase scan+serialize, reference tracking, string interning. +6. **AcJson** — Newtonsoft.Json wrapper with $id/$ref, IId-based reference resolution, and chain API. + +## Critical Warnings +7. **PasswordHasher** — PBKDF2-HMAC-SHA512. Do NOT modify the salt logic or iteration count — existing passwords become unverifiable. +8. **MeasuringStatus.Finnished** — intentional legacy typo in consuming projects. Do NOT fix the spelling. +9. **LogLevel enum values** — synchronized with database. Do NOT renumber. + +## Conventions +10. Do not suggest removal/rollback as a solution — find a fix for the problem. +11. Extension methods over instance methods for CRUD operations (see DbSets pattern). +12. Session pattern for reads, Transaction pattern for writes (see DataLayers). diff --git a/AyCode.Core.Tests.Internal/Entities/README.md b/AyCode.Core.Tests.Internal/Entities/README.md new file mode 100644 index 0000000..ed38f42 --- /dev/null +++ b/AyCode.Core.Tests.Internal/Entities/README.md @@ -0,0 +1,22 @@ +# Entities + +Concrete entity implementations inheriting from AyCode.Entities abstract generics. Used by database integration tests. + +## Key Files + +- **`User.cs`** — `AcUser`. +- **`Company.cs`** — `AcCompany`. +- **`UserToCompany.cs`** — `AcUserToCompany` junction entity. +- **`Profile.cs`** — `AcProfile
`. +- **`Address.cs`** — `AcAddress` + `IAcAddressDtoBase` with DTO support. +- **`UserToken.cs`** — `AcUserTokenBase` authentication token. +- **`EmailMessage.cs`** — `AcEmailMessage`. +- **`EmailRecipient.cs`** — `AcEmailRecipient`. + +## Relationships + +User ↔ Company (many-to-many via UserToCompany), User → Profile → Address (one-to-one chain), EmailMessage → EmailRecipient (one-to-many). + +--- + +> **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.Tests.Internal/README.md b/AyCode.Core.Tests.Internal/README.md new file mode 100644 index 0000000..cfe89c1 --- /dev/null +++ b/AyCode.Core.Tests.Internal/README.md @@ -0,0 +1,21 @@ +# AyCode.Core.Tests.Internal + +Concrete entity implementations for database integration testing. Exposes types to `AyCode.Database.Tests*` via `[InternalsVisibleTo]`. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Entities/`](Entities/README.md) | Concrete entity implementations (User, Company, Profile, Address, etc.) | + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `MSTest` | Test framework | +| `AyCode.Core.Tests` | Shared test utilities | +| `AyCode.Entities` / `AyCode.Entities.Server` | Abstract entity base classes | + +--- + +> **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.Tests/Compression/README.md b/AyCode.Core.Tests/Compression/README.md new file mode 100644 index 0000000..027143f --- /dev/null +++ b/AyCode.Core.Tests/Compression/README.md @@ -0,0 +1,11 @@ +# Compression Tests + +GZip compression utility tests. + +## Key Files + +- **`GzipHelperTests.cs`** — Tests GzipHelper.Compress(), DecompressToString(), DecompressToRentedBuffer() (ArrayPool), IsGzipCompressed() (magic byte detection). + +--- + +> **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.Tests/GeneratedWriters/README.md b/AyCode.Core.Tests/GeneratedWriters/README.md new file mode 100644 index 0000000..daf1a8d --- /dev/null +++ b/AyCode.Core.Tests/GeneratedWriters/README.md @@ -0,0 +1,11 @@ +# GeneratedWriters + +Hand-written examples of the code pattern that the AcBinarySerializable source generator produces. + +## Key Files + +- **`TestOrderWriter.cs`** — Example IGeneratedBinaryWriter: direct property access (no reflection), alphabetical order, value types inline, complex types delegate to runtime. Demonstrates ICache-friendly pattern (~500B vs 27KB runtime). + +--- + +> **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.Tests/README.md b/AyCode.Core.Tests/README.md new file mode 100644 index 0000000..9d3509e --- /dev/null +++ b/AyCode.Core.Tests/README.md @@ -0,0 +1,31 @@ +# AyCode.Core.Tests + +MSTest unit tests for AyCode.Core serialization, compression, and utilities. Covers binary/JSON round-trips, reference handling, nullable types, source generator integration, and performance benchmarks. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Serialization/`](Serialization/README.md) | Binary and JSON serialization tests (20+ test classes) | +| [`Compression/`](Compression/README.md) | GZip compression tests | +| [`TestModels/`](TestModels/README.md) | Shared test entities, enums, data factories, SignalR infrastructure | +| [`GeneratedWriters/`](GeneratedWriters/README.md) | Hand-written source generator output examples | + +## Key Files (Root) + +- **`GlobalUsings.cs`** — Global MSTest using. +- **`TestModelBase.cs`** — Abstract base for test models with configuration support. +- **`JsonExtensionTests.cs`** — JSON extension method tests. + +## Dependencies + +| Dependency | Purpose | +|---|---| +| `MSTest` | Test framework | +| `MessagePack` | Serialization comparison | +| `MemoryPack` | Serialization comparison | +| `MongoDB.Bson` | BSON comparison | + +--- + +> **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.Tests/Serialization/README.md b/AyCode.Core.Tests/Serialization/README.md new file mode 100644 index 0000000..7d997a5 --- /dev/null +++ b/AyCode.Core.Tests/Serialization/README.md @@ -0,0 +1,36 @@ +# Serialization Tests + +Comprehensive test suite for binary and JSON serialization: round-trips, reference handling, chains, and source generator integration. + +## Key Files + +### Basic Types +- **`AcBinarySerializerBasicTests.cs`** — Primitives: int, double, string, bool, DateTime, Guid. +- **`AcBinarySerializerDateTimeTests.cs`** — DateTime handling and type mismatch detection. +- **`AcBinarySerializerNullableTests.cs`** — Nullable types: int?, long?, etc. + +### Complex Objects +- **`AcBinarySerializerObjectTests.cs`** — Nested objects and hierarchies. +- **`AcBinarySerializerNavigationPropertyTests.cs`** — EF-style navigation properties. +- **`AcBinarySerializerGenericTypeTests.cs`** — Generic type parameters. + +### Reference Handling +- **`AcBinarySerializerChainTests.cs`** — Binary Chain API (CreateDeserializeChain, ThenDeserialize). +- **`AcBinarySerializerChainReferenceTests.cs`** — Chain with $id/$ref references. +- **`AcBinarySerializerCircularReferenceTests.cs`** — Circular/bidirectional references. +- **`AcBinarySerializerIIdReferenceTests.cs`** — IId interface-based reference tracking. +- **`AcBinarySerializerStringInterningTests.cs`** — String deduplication via [AcStringIntern]. + +### JSON +- **`AcJsonSerializerChainTests.cs`** — JSON chain operations. +- **`AcJsonSerializerIIdReferenceTests.cs`** — JSON $id/$ref handling. +- **`AcExpressionNodeSerializationTests.cs`** — Expression tree serialization. + +### Source Generator & Performance +- **`GeneratedSerializerIntegrationTests.cs`** — Verifies generated writer types implement IGeneratedBinaryWriter. +- **`QuickBenchmark.cs`** — Performance comparison: AcBinary vs MessagePack. +- **`AcSerializerTestHelper.cs`** — Factory methods for test data. + +--- + +> **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.Tests/TestModels/README.md b/AyCode.Core.Tests/TestModels/README.md new file mode 100644 index 0000000..be2f502 --- /dev/null +++ b/AyCode.Core.Tests/TestModels/README.md @@ -0,0 +1,17 @@ +# TestModels + +Shared test entities, enums, data factories, and SignalR test infrastructure. Used across test and benchmark projects. + +## Key Files + +- **`SharedTestModels.cs`** — Enums (TestStatus, TestPriority, TestUserRole) and shared IId types (SharedTag, SharedCategory, SharedUser, MetadataInfo). Multi-serializer: [AcBinarySerializable], [MessagePackObject], [MemoryPackable]. +- **`AcSerializerModels.cs`** — 30+ test models: simple, nested, collections, nullable, StockTaking hierarchy, circular references, generics, navigation properties, schema mismatch scenarios. +- **`GeneratedSerializerTestModels.cs`** — [AcBinarySerializable] models for source generator testing. +- **`StockTakingTestModels.cs`** — Production-like hierarchy: BaseEntity → MgEntityBase → MgStockTaking. +- **`TestDataFactory.cs`** — Centralized factory with ID sequencing: CreateTag(), CreateCategory(), CreateUser(), CreateOrder(), CreateOrderItem(). +- **`SignalRTestInfrastructure.cs`** — SignalRMessageFactory, DTOs, CommonSignalRTags, SignalRBenchmarkData. +- **`TestLogger.cs`** — Logger with capture for assertions: HasErrorLogs, HasWarningLogs, GetErrorMessages(). + +--- + +> **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.Tests.Internal/README.md b/AyCode.Database.Tests.Internal/README.md new file mode 100644 index 0000000..e7128c1 --- /dev/null +++ b/AyCode.Database.Tests.Internal/README.md @@ -0,0 +1,18 @@ +# AyCode.Database.Tests.Internal + +Concrete database integration tests using entity implementations from AyCode.Core.Tests.Internal. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Users/`](Users/README.md) | Concrete UserDbContext, UserDal, and UserDalTests | + +## Key Files (Root) + +- **`DatabaseTestBase.cs`** — Concrete [TestClass] with Setup/TearDown, implements AcDatabaseTestBase. +- **`appsettings.json`** — Test database connection configuration. + +--- + +> **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.Tests.Internal/Users/README.md b/AyCode.Database.Tests.Internal/Users/README.md new file mode 100644 index 0000000..32c82fc --- /dev/null +++ b/AyCode.Database.Tests.Internal/Users/README.md @@ -0,0 +1,13 @@ +# Users + +Concrete user database test implementations with real EF Core DbContext and DAL. + +## Key Files + +- **`UserDbContext.cs`** — Sealed `AcUserDbContextBase` with 8 concrete entity types, lazy loading proxies, detailed EF errors. +- **`UserDal.cs`** — Sealed `AcUserDalBase` providing concrete DAL for tests. +- **`UserDalTests.cs`** — Concrete tests: GetUserByEmail, GetUserById, AddUser (with profile + address). Currently disabled. + +--- + +> **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.Tests/README.md b/AyCode.Database.Tests/README.md new file mode 100644 index 0000000..29d817c --- /dev/null +++ b/AyCode.Database.Tests/README.md @@ -0,0 +1,19 @@ +# AyCode.Database.Tests + +MSTest base classes for database layer testing. Provides abstract test foundations for DAL and DbContext verification. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`Users/`](Users/README.md) | User DAL test base with authentication and CRUD tests | + +## Key Files (Root) + +- **`GlobalUsings.cs`** — Global MSTest using. +- **`AcDatabaseTestModelBase.cs`** — Generic base: pooled DAL access or direct DbContext access. +- **`AcDatabaseTestBase.cs`** — Abstract test class with `DatabaseExistsTest()` connectivity validation. + +--- + +> **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.Tests/Users/README.md b/AyCode.Database.Tests/Users/README.md new file mode 100644 index 0000000..a6e1175 --- /dev/null +++ b/AyCode.Database.Tests/Users/README.md @@ -0,0 +1,11 @@ +# Users + +Abstract base for comprehensive user DAL testing. + +## Key Files + +- **`AcUserDalTestBase.cs`** — 8 generic type parameters. Tests: GetUserById (validates nested profile/address), GetUserByEmail, GetUserModelDtoDetailById, GetUserByEmailAsync, AddUserTest (full object graph with profile + address, then cleanup). + +--- + +> **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.Tests/LoginServices/README.md b/AyCode.Services.Server.Tests/LoginServices/README.md new file mode 100644 index 0000000..1a2c62b --- /dev/null +++ b/AyCode.Services.Server.Tests/LoginServices/README.md @@ -0,0 +1,11 @@ +# LoginServices + +Abstract base for login service integration tests. + +## Key Files + +- **`AcLoginServiceServerTestBase.cs`** — 10 generic type parameters. Tests: RegisterUser (create + validate + cleanup), LoginUser (valid, wrong email, wrong password with error codes), ChangePassword (change + verify + restore). + +--- + +> **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.Tests/README.md b/AyCode.Services.Server.Tests/README.md new file mode 100644 index 0000000..a0a430e --- /dev/null +++ b/AyCode.Services.Server.Tests/README.md @@ -0,0 +1,19 @@ +# AyCode.Services.Server.Tests + +Comprehensive server-side tests for SignalR communication, DataSource operations, login services, and reflection-based method invocation. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`SignalRs/`](SignalRs/README.md) | Full SignalR client→hub→service test infrastructure | +| [`LoginServices/`](LoginServices/README.md) | Login service test base classes | + +## Key Files (Root) + +- **`TestLogger.cs`** — Re-exports TestLogger from AyCode.Core.Tests. +- **`InvokeMethodExtensionTests.cs`** — Tests MethodInfo.InvokeMethod: sync, async Task unwrapping, Task.FromResult (production bug fix), non-generic Task, complex objects. + +--- + +> **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.Tests/SignalRs/README.md b/AyCode.Services.Server.Tests/SignalRs/README.md new file mode 100644 index 0000000..7d3c089 --- /dev/null +++ b/AyCode.Services.Server.Tests/SignalRs/README.md @@ -0,0 +1,22 @@ +# SignalRs + +Full SignalR client→hub→service test infrastructure with testable components that bypass real network connections. + +## Key Files + +- **`SignalRClientToHubTest.cs`** — Abstract round-trip test base. Tests: Post_SingleInt, Post_TwoInts, Post_Bool, Post_String, Post_Guid, Post_Enum, and more. +- **`TestableSignalRClient2.cs`** — `AcSignalRClientBase` implementation: direct hub calls, zero network, zero delays. +- **`TestableSignalRHub2.cs`** — `AcWebSignalRHubBase` implementation: simulates connection state, user identity, claims. Captures responses. +- **`TestSignalRService2.cs`** — 50+ methods: primitives (23), complex objects (3), collections (9), arrays (6), mixed (4), async (4), Task.FromResult (4), large datasets, property mismatch, DataSource CRUD (7), production bug reproductions. +- **`TestSignalRTags.cs`** — 50+ const int message tags (100-500 range). +- **`SignalRTestHelper.cs`** — CreatePrimitiveParamsMessage, CreateComplexObjectMessage, GetResponseData, AssertSuccessResponse. + +## Subfolders + +| Folder | Purpose | +|---|---| +| [`SignalRDatasources/`](SignalRDatasources/README.md) | DataSource CRUD and collection tests | + +--- + +> **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.Tests/SignalRs/SignalRDatasources/README.md b/AyCode.Services.Server.Tests/SignalRs/SignalRDatasources/README.md new file mode 100644 index 0000000..9f613ac --- /dev/null +++ b/AyCode.Services.Server.Tests/SignalRs/SignalRDatasources/README.md @@ -0,0 +1,30 @@ +# SignalRDatasources + +DataSource CRUD, collection, tracking, and filter tests. Tested with List and AcObservableCollection over Binary and JSON serialization. + +## Key Files + +### Test Base (partial class) +- **`SignalRDataSourceTestBase.cs`** — Abstract generic base with SignalR infrastructure setup. +- **`SignalRDataSourceTestBase.Collections.cs`** — Count, Clear, Contains tests. +- **`SignalRDataSourceTestBase.ContextAndFilter.cs`** — ContextIds, FilterText, Expression filter with AcExpressionNode. +- **`SignalRDataSourceTestBase.CrudOperations.cs`** — Add (auto-save, tracking-only, duplicate/default ID validation). +- **`SignalRDataSourceTestBase.LoadDataSource.cs`** — Full DataSource load. +- **`SignalRDataSourceTestBase.LoadItem.cs`** — Single item load by ID. +- **`SignalRDataSourceTestBase.SaveChanges.cs`** — Persist tracked changes. +- **`SignalRDataSourceTestBase.Tracking.cs`** — Change tracking states (Add, Update, Delete). + +### Concrete Test Classes +- **`SignalRDataSourceTests_List_Binary.cs`** — List + Binary. +- **`SignalRDataSourceTests_List_Binary_NoRef.cs`** — List + Binary without references. +- **`SignalRDataSourceTests_List_Json.cs`** — List + JSON. +- **`SignalRDataSourceTests_Observable_Binary.cs`** — ObservableCollection + Binary. +- **`SignalRDataSourceTests_Observable_Json.cs`** — ObservableCollection + JSON. + +### Test DataSources +- **`TestOrderItemListDataSource.cs`** — DataSource with List. +- **`TestOrderItemObservableDataSource.cs`** — DataSource with AcObservableCollection. + +--- + +> **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.Tests/README.md b/AyCode.Services.Tests/README.md new file mode 100644 index 0000000..8547958 --- /dev/null +++ b/AyCode.Services.Tests/README.md @@ -0,0 +1,17 @@ +# AyCode.Services.Tests + +MSTest project for service layer testing. Focuses on SignalR message serialization round-trips. + +## Folder Structure + +| Folder | Purpose | +|---|---| +| [`SignalRs/`](SignalRs/README.md) | SignalR message serialization/deserialization tests | + +## Key Files (Root) + +- **`MSTestSettings.cs`** — Assembly-level parallel test execution (MethodLevel scope). + +--- + +> **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.Tests/SignalRs/README.md b/AyCode.Services.Tests/SignalRs/README.md new file mode 100644 index 0000000..a58036a --- /dev/null +++ b/AyCode.Services.Tests/SignalRs/README.md @@ -0,0 +1,11 @@ +# SignalRs + +SignalR message serialization and full round-trip tests. + +## Key Files + +- **`PostJsonDataMessageTests.cs`** — Full pipeline test: client creates message → binary serialize → server deserialize → parameter extract → service result → response create → binary response → client deserialize → type convert. Covers int, string, bool with [DataRow]. + +--- + +> **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/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b5aaf0b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,8 @@ +# AyCode.Core — Claude Code Instructions + +Before writing any code, read these files: +1. `.github/copilot-instructions.md` — Domain rules and key pitfalls (single source of truth) +2. `docs/GLOSSARY.md` — Core abstractions and terminology +3. The relevant project's `README.md` for folder-specific context + +When modifying code, update the corresponding README.md if it becomes out of sync with the code. diff --git a/README.md b/README.md new file mode 100644 index 0000000..cf5ea19 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# AyCode.Core Solution + +.NET 10 core framework providing serialization (Binary, JSON, Toon), entity abstractions, database access, services, and shared utilities. Used as the foundation layer for AyCode applications. + +## LLM Context + +Domain rules and key pitfalls live in a single file: [`.github/copilot-instructions.md`](.github/copilot-instructions.md) + +| Tool | Auto-loaded | Action needed | +|------|------------|---------------| +| GitHub Copilot | ✅ `copilot-instructions.md` | None | +| Claude Code | ✅ `CLAUDE.md` → references above | None | +| Cursor / Windsurf | ✅ `README.md` | Read `copilot-instructions.md` via @file | + +Detailed docs: [`docs/`](docs/) — GLOSSARY.md, ARCHITECTURE.md, CONVENTIONS.md + +## Solution Structure + +| Project | Purpose | README | +|---|---|---| +| [`AyCode.Core`](AyCode.Core/README.md) | Core library: serializers, compression, logging, validation | [README](AyCode.Core/README.md) | +| [`AyCode.Core.Server`](AyCode.Core.Server/README.md) | Server-side core extensions (GlobalLogger) | [README](AyCode.Core.Server/README.md) | +| [`AyCode.Core.Serializers.SourceGenerator`](AyCode.Core.Serializers.SourceGenerator/README.md) | Roslyn source generator for binary serializers | [README](AyCode.Core.Serializers.SourceGenerator/README.md) | +| [`AyCode.Core.Serializers.Console`](AyCode.Core.Serializers.Console/README.md) | Serializer benchmark console app | [README](AyCode.Core.Serializers.Console/README.md) | +| [`AyCode.Interfaces`](AyCode.Interfaces/README.md) | Entity interfaces: IId, IForeignKey, profiles, addresses | [README](AyCode.Interfaces/README.md) | +| [`AyCode.Interfaces.Server`](AyCode.Interfaces.Server/README.md) | Server-side interfaces (login services) | [README](AyCode.Interfaces.Server/README.md) | +| [`AyCode.Entities`](AyCode.Entities/README.md) | Abstract entity base classes (User, Profile, Address, Company) | [README](AyCode.Entities/README.md) | +| [`AyCode.Entities.Server`](AyCode.Entities.Server/README.md) | Server-side entities (LogItem) | [README](AyCode.Entities.Server/README.md) | +| [`AyCode.Models`](AyCode.Models/README.md) | DTOs and view models | [README](AyCode.Models/README.md) | +| [`AyCode.Models.Server`](AyCode.Models.Server/README.md) | Server-side models (Login, DynamicMethods) | [README](AyCode.Models.Server/README.md) | +| [`AyCode.Services`](AyCode.Services/README.md) | Client-side services (SignalR, logging, login) | [README](AyCode.Services/README.md) | +| [`AyCode.Services.Server`](AyCode.Services.Server/README.md) | Server-side services (SignalR hub, email, login) | [README](AyCode.Services.Server/README.md) | +| [`AyCode.Database`](AyCode.Database/README.md) | EF Core data access layer with DAL pattern | [README](AyCode.Database/README.md) | +| [`AyCode.Utils`](AyCode.Utils/README.md) | Zero-dependency utilities (string, datetime, lock wrappers) | [README](AyCode.Utils/README.md) | +| [`AyCode.Utils.Server`](AyCode.Utils.Server/README.md) | Server-side utilities (placeholder) | [README](AyCode.Utils.Server/README.md) | + +### Test & Benchmark Projects + +| Project | Purpose | README | +|---|---|---| +| [`AyCode.Benchmark`](AyCode.Benchmark/README.md) | BenchmarkDotNet performance suite | [README](AyCode.Benchmark/README.md) | +| [`AyCode.Core.Tests`](AyCode.Core.Tests/README.md) | Serialization, compression, and utility tests | [README](AyCode.Core.Tests/README.md) | +| [`AyCode.Core.Tests.Internal`](AyCode.Core.Tests.Internal/README.md) | Internal entity implementations for DB tests | [README](AyCode.Core.Tests.Internal/README.md) | +| [`AyCode.Database.Tests`](AyCode.Database.Tests/README.md) | Database layer test base classes | [README](AyCode.Database.Tests/README.md) | +| [`AyCode.Database.Tests.Internal`](AyCode.Database.Tests.Internal/README.md) | Concrete database integration tests | [README](AyCode.Database.Tests.Internal/README.md) | +| [`AyCode.Services.Tests`](AyCode.Services.Tests/README.md) | Service layer tests | [README](AyCode.Services.Tests/README.md) | +| [`AyCode.Services.Server.Tests`](AyCode.Services.Server.Tests/README.md) | Server-side SignalR and service tests | [README](AyCode.Services.Server.Tests/README.md) | + +--- + +> **LLM Maintenance:** If you modify this solution's structure, 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/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..9165455 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,70 @@ +# Architecture + +## Dependency Graph + +``` +AyCode.Utils (zero dependencies) + ↑ +AyCode.Interfaces → AyCode.Entities → AyCode.Models + ↑ ↑ ↑ +AyCode.Core ─────────────┘ │ + ↑ │ +AyCode.Database ────────────────────────────┘ + ↑ +AyCode.Services ← AyCode.Services.Server +``` + +**Rule:** Dependencies flow upward only. Lower layers never reference higher layers. + +## Project Roles + +### Foundation Layer +- **AyCode.Utils** — Zero-dependency utilities. String/DateTime extensions, lock wrappers. +- **AyCode.Interfaces** — Pure interfaces. `IId` is the root abstraction. +- **AyCode.Entities** — Abstract generic entity classes. Never instantiated directly. +- **AyCode.Models** — DTOs and view models for service boundaries. + +### Core Layer +- **AyCode.Core** — Serializers (Binary, JSON, Toon), compression (Brotli, GZip, LZ4), logging framework, constants, validation. +- **AyCode.Core.Serializers.SourceGenerator** — Roslyn incremental generator. Targets netstandard2.0. Generates `IGeneratedBinaryWriter` / `IGeneratedBinaryReader` for `[AcBinarySerializable]` types. + +### Data Layer +- **AyCode.Database** — EF Core with generic DAL pattern. Session for reads, Transaction for writes. DAL pooling via `PooledDal`. + +### Service Layer +- **AyCode.Services** — Client-side: SignalR client, login service, loggers. +- **AyCode.Services.Server** — Server-side: SignalR hub with custom binary protocol, email (SendGrid), JWT auth. + +### Server Extensions +- **AyCode.Core.Server**, **AyCode.Interfaces.Server**, **AyCode.Entities.Server**, **AyCode.Models.Server** — Server-only additions that don't belong in shared code. + +## Serialization Architecture + +Three serializers share a common infrastructure but serve different goals: + +| Serializer | Primary Goal | Use Case | +|---|---|---| +| **AcBinary** | Speed | Wire protocol, SignalR, storage | +| **AcJson** | Compatibility | REST APIs, debugging, interop | +| **Toon** | LLM Accuracy | AI context, schema documentation | + +## Generic Entity Pattern + +Entities use composition via generic type parameters: + +```csharp +// Interface layer +interface IAcUser : IId { ... } + +// Entity layer (abstract) +abstract class AcUser { ... } + +// Consuming project (concrete) +class User : AcUser { ... } +``` + +This allows the framework to define relationships without knowing concrete types. + +--- + +> **LLM Maintenance:** If you modify the project structure or dependency graph, update this document. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md new file mode 100644 index 0000000..86cfd4c --- /dev/null +++ b/docs/CONVENTIONS.md @@ -0,0 +1,41 @@ +# Conventions + +## Naming + +- **Prefix:** All framework types use `Ac` prefix (e.g., `AcDalBase`, `AcBinarySerializer`, `AcLoggerBase`). +- **Interfaces:** Standard `I` prefix + `Ac` (e.g., `IAcDbContextBase`, `IAcUserDbSetBase`). +- **Extensions:** `{Domain}Extensions.cs` (e.g., `StringExtensions`, `CollectionExtensions`, `AcDbSessionExtension`). +- **Test bases:** `Ac{Domain}TestBase` or `AcBase_{TestName}` for inherited test methods. + +## Patterns + +- **Extension methods over instance methods** for CRUD operations. Keeps interfaces clean, implementations composable. +- **Session/Transaction pattern** in DataLayers: `Session()` for reads, `Transaction()` for writes. Both are mutex-protected. +- **Generic interface hierarchy** for entities: Interface → Abstract Entity → Concrete (in consuming project). +- **Partial classes** for large serializers (AcBinarySerializer, AcToonSerializer split across 10+ files). +- **Source generation** for hot-path serialization. Runtime reflection only as fallback. + +## Serialization Conventions + +- Binary serializer properties are written in **alphabetical order** (matches source generator output). +- String interning is opt-in via `[AcStringIntern]` attribute or `enableInternString` flag. +- Chain API for multi-type deserialization with cross-reference resolution. +- Feature flags on `[AcBinarySerializable]` eliminate dead code from generated output. + +## Testing + +- **MSTest** framework across all test projects. +- **Abstract test bases** with `AcBase_` prefixed methods for reusable test logic. +- **TestDataFactory** for centralized test data creation with ID sequencing. +- **Testable infrastructure** for SignalR: `TestableSignalRClient2`, `TestableSignalRHub2` bypass real connections. + +## Critical Rules + +- **Never modify PasswordHasher salt/iteration logic** — breaks existing password verification. +- **Never renumber LogLevel enum values** — synchronized with database. +- **Never fix "Finnished" spelling** — intentional legacy typo in consuming projects. +- **Never suggest removal as a solution** — find a fix instead. + +--- + +> **LLM Maintenance:** If you establish new conventions or patterns, document them here. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md new file mode 100644 index 0000000..1597754 --- /dev/null +++ b/docs/GLOSSARY.md @@ -0,0 +1,62 @@ +# Glossary + +Core terminology for the AyCode framework. Read this before working on unfamiliar areas. + +## Core Abstractions + +| Term | Definition | +|---|---| +| **IId** | Generic identity interface (`T` = `Guid` or `int`). Foundation of the entity system. | +| **TrackingState** | Client-side change tracking enum: Added, Modified, Deleted, Unchanged. Not related to EF Core tracking. | +| **IForeignKey** | Marker interface for navigation property foreign keys. | +| **IForeignCollection** | Marker for collection navigation properties. | + +## Serialization Formats + +| Term | Definition | +|---|---| +| **AcBinary** | High-performance binary serializer. Two-phase: scan (collect metadata) then serialize. Supports reference tracking, string interning, ID-based deduplication. | +| **Toon** | Token-Oriented Object Notation. LLM-optimized format with @meta (schema) and @data (values) sections. Designed for maximum LLM comprehension accuracy. | +| **AcJson** | Newtonsoft.Json wrapper with $id/$ref reference handling, IId-based resolution, and chain deserialization API. | +| **Chain API** | Fluent deserialization: `CreateDeserializeChain().ThenDeserialize()...Execute()`. Resolves cross-references across multiple types. | +| **String Interning** | Binary serializer deduplicates repeated strings. Controlled via `[AcStringIntern]` attribute or `enableInternString` flag. | + +## Serialization Attributes + +| Attribute | Purpose | +|---|---| +| **[AcBinarySerializable]** | Marks type for source generator. Feature flags: enableMetadata, enableIdTracking, enableRefHandling, enableInternString. | +| **[AcStringIntern]** | Marks string property for deduplication during binary serialization. | +| **[ToonDescription]** | Per-property description for Toon @meta output. | + +## Architecture Layers + +| Layer | Projects | Role | +|---|---|---| +| **Interfaces** | AyCode.Interfaces, .Server | Contracts only — no implementation | +| **Entities** | AyCode.Entities, .Server | Abstract generic base classes | +| **Models** | AyCode.Models, .Server | DTOs, view models | +| **Services** | AyCode.Services, .Server | Business logic, SignalR | +| **Database** | AyCode.Database | EF Core DAL with Session/Transaction pattern | +| **Core** | AyCode.Core, .Server | Serializers, compression, logging, constants | +| **Utils** | AyCode.Utils, .Server | Zero-dependency utilities | + +## Database Patterns + +| Term | Definition | +|---|---| +| **DAL (Data Access Layer)** | `AcDalBase` — mutex-protected, supports Session (read) and Transaction (write) patterns. | +| **PooledDal** | Singleton pool managing DAL instances by SessionId/PlayerId. | +| **Session** | Read-only database operation pattern. No transaction, no mutex lock on DbContext. | +| **Transaction** | Write operation pattern with auto-rollback on failure. | + +## Logging + +| Term | Definition | +|---|---| +| **AcLoggerBase** | Custom logger with Detail(0)→Debug(1)→Info(2)→Warning(3)→Suggest(4)→Error(5)→Disabled(255). Values are DB-synced — do not renumber. | +| **GlobalLogger** | Server-side singleton (`AcGlobalLogger`) for cross-service logging. | + +--- + +> **LLM Maintenance:** If you modify code that changes terminology or introduces new abstractions, update this glossary.