# Conventions

For core framework conventions (Ac prefix, Session/Transaction pattern, etc.) see [`../../AyCode.Core/docs/CONVENTIONS.md`](../../AyCode.Core/docs/CONVENTIONS.md).

## Naming

- **Grid components:** `Grid{Entity}Base` (e.g., `GridPartnerBase`, `GridShippingBase`). Suffix `Base` because consuming projects may extend them.
- **CardView components:** Inside `Components/CardViews/` — card-style wrappers around DxGrid for mobile-friendly layouts.
- **Services:** `Ac{Domain}ServiceBase` for abstract bases. Platform-specific implementations in consuming projects.
- **ViewModels:** In `AyCode.Blazor.Models/ViewModels/` — suffixed with `ViewModel` or kept as plain model classes.

## Component Patterns

- **DevExpress 25.1.3 exclusively** — never mix with other Blazor component libraries.
- **DxGrid + AcSignalRDataSource** — grids always bind to SignalR-backed data sources, not REST.
- **AcExpressionNode** for grid filters — LINQ expressions are serialized client-side and evaluated server-side.
- **Layout persistence** — grid column order/width saved to localStorage via `MgGridBase`.
- **ExpressionHelper** services handle AcLinq ↔ DevExpress filter conversion.

## MAUI Patterns

- **Platform folders** (`Platforms/Android/`, `iOS/`, `Windows/`) for platform-specific code.
- **BlazorWebView** hosts the same Blazor components used in Server mode.
- **IFormFactor** interface — each platform provides its own implementation (Phone, Tablet, Desktop, Web, WebAssembly).

## Blazor Patterns

- **Razor component + code-behind** — `.razor` for markup, `.razor.cs` for logic.
- **Cascading parameters** for authentication state and layout context.
- **JS interop** via scoped modules (`ExampleJsInterop.cs` pattern).

## DLL References

- All AyCode.Core project references are via **DLL** (not ProjectReference) — this is intentional to separate build graphs.
- DevExpress references are NuGet packages pinned to **25.1.3**.

## Code Reuse

- Before writing new code, search the codebase for existing implementations.
- If a method does most of what you need, extract the shared part into a smaller reusable method rather than copying and modifying.
- Prefer composing existing helpers over creating parallel implementations.

## Critical Rules

- Do not suggest removal/rollback as a solution — find a fix for the problem.
- SignalR uses **AcBinaryHubProtocol** — never switch to default JSON protocol.
- Grid data always flows through SignalR, never direct REST calls.