5.9 KiB

Raw Blame History

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<T>().ThenDeserialize<U>()...Execute()`. Resolves cross-references across multiple types.
String Interning	Binary serializer deduplicates repeated strings. Controlled via `[AcStringIntern]` attribute or `StringInterningMode`. See BINARY_FORMAT.md.

Binary Wire Format

For full specification see BINARY_FORMAT.md.

Term	Definition
BinaryTypeCode	Single-byte marker that identifies the type of the next value in the binary stream. 100+ codes defined in `BinaryTypeCode.cs`.
FixObj	Compact object marker (0–63). The byte itself is the type slot index — no additional identifier needed.
FixStr	Compact string marker (103–134). Encodes type + length in one byte for ASCII strings ≤31 bytes.
TinyInt	Compact integer marker (192–255). Encodes small integers (−16 to 47) in a single byte.
VarInt / VarUInt	Variable-length integer encoding. LEB128 for unsigned, ZigZag + LEB128 for signed.
HeaderFlags	Byte at stream position 1 encoding serialization options: metadata, reference handling mode, cache count presence. Base `0x90`.
Two-Phase Serialization	Scan pass detects multi-referenced objects, serialize pass writes output using reference table. Required for `ReferenceHandling.All`.

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.

SignalR Dispatch

For full architecture see SIGNALR_ARCHITECTURE.md.

Term	Definition
OnReceiveMessage	The single SignalR method used for all communication in both directions. Signature: `(int messageTag, byte[] messageBytes, int? requestId)`.
Message Tag	Integer identifier that maps to a specific method via `[SignalR(tag)]` or `[SignalRSendToClient(tag)]` attributes.
TagAttribute	Base attribute associating an integer tag with a method. `SignalRAttribute` and `SignalRSendToClientAttribute` extend it.
DynamicMethodRegistry	Reflection-based registry that resolves message tags to `MethodInfo` at runtime. Uses `ConcurrentDictionary` + `FrozenDictionary` caching.
AcDynamicMethodCallModel	Per-instance-type method cache. Builds a `FrozenDictionary<int, AcMethodInfoModel>` once per type via reflection.
SignalRCrudTags	Sealed record mapping 5 sequential tags (GetAll, GetItem, Add, Update, Remove) for entity CRUD. `GetMessageTagByTrackingState()` maps `TrackingState` → tag.
AcBinaryHubProtocol	Custom `IHubProtocol` replacing SignalR's JSON+Base64 with `AcBinarySerializer`. Protocol name: `"acbinary"`.
SignalPostJsonDataMessage<T>	⚠️ TEMPORARY — Message that serializes request parameters to JSON inside a Binary envelope. Planned for replacement with pure Binary.
SignalResponseDataMessage	Response message supporting Binary or JSON+GZip serialization. Responses already use pure Binary (no JSON overhead).
AcSignalRDataSource	Server-side `IList<T>` with `ChangeTracking` and SignalR CRUD via `SignalRCrudTags`. Supports binary merge for incremental updates.
SendToClientType	Enum controlling broadcast scope: None, Others, Caller, All.

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.