# Glossary

Core terminology for the AyCode framework. Read this before working on unfamiliar areas.

## Core Abstractions

| Term | Definition |
|---|---|
| **IId<T>** | 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<T>** | 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 `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.