AyCode.Core/.github/copilot-instructions.md

AyCode.Core — Domain Rules

@repo { name = "AyCode.Core" type = "framework" layer = 0 own-dep-repos = [] }

This is the single source of truth for domain rules. Do not duplicate these elsewhere. For detailed docs see: README.md → docs/ External repos in own-dep-repos are fully accessible — read their source code, docs, and .github/copilot-instructions.md freely when you need type definitions, base classes, or context. Do not limit yourself to the current workspace.

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.

SignalR

7. Single-method transport — all SignalR communication uses OnReceiveMessage(tag, bytes, requestId). Tags are int constants resolved via DynamicMethodRegistry. Never add conventional hub methods.
8. AcSignalRDataSource — generic IList<T> with change tracking, CRUD via SignalRCrudTags, binary merge, rollback. See AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md. Transport docs: AyCode.Services/docs/SIGNALR.md.
9. JSON-in-Binary tech debt — client→server request parameters are currently JSON inside a Binary envelope (SignalPostJsonDataMessage). Do NOT attempt to fix as a side effect — requires coordinated changes across all consuming projects.

Critical Warnings

10. PasswordHasher — PBKDF2-HMAC-SHA512. Do NOT modify the salt logic or iteration count — existing passwords become unverifiable.
11. MeasuringStatus.Finnished — intentional legacy typo in consuming projects. Do NOT fix the spelling.
12. LogLevel enum values — synchronized with database. Do NOT renumber.

Conventions

13. Do not suggest removal/rollback as a solution — find a fix for the problem.
14. Extension methods over instance methods for CRUD operations.
15. Session pattern for reads, Transaction pattern for writes.
16. Target framework is net9.0 (set in AyCode.Core.targets). The SourceGenerator targets netstandard2.0. Consuming projects (AyCode.Blazor, FruitBankHybridApp UI) may target net10.0 but reference AyCode.Core DLLs built as net9.0.
17. No redundant code — before writing new logic, check whether similar methods already exist in the current context. Reuse or extract shared logic into smaller methods rather than duplicating. If an existing method does most of what you need, split it into composable parts.
18. Keep all .md files in sync — when you modify code and you know which .md file documents it, update that .md file too. If you notice a contradiction between code and an .md file, automatically update the .md to match the code (code is the source of truth). When fixing a reference, check other .md files that may share the same broken reference. If the root cause is at a lower layer, fix it there first. During code review, if you find useful behavior or conventions not yet documented, briefly suggest what to document and where — but do not add new content without approval.
19. Documentation layering — write .md documentation at the defining layer (where the code lives). Higher-layer .md files reference the base docs (e.g. see AyCode.Core/docs/SIGNALR.md) and document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs.
20. Do not re-read .md files already in your context window. They only change if you modify them yourself (new content is already in context) or if the developer tells you they changed — in that case re-read them once.