# Architecture

## Framework vs. Consumer Boundary

This is **Layer 1 — UI framework**, building on Layer 0 (AyCode.Core) and consumed by Layer 2/3 projects. Full doctrine: `../AyCode.Core/docs/ARCHITECTURE.md#framework-vs-consumer-boundary`.

### Blazor/MAUI-specific notes

- Components use **generic type parameters** for consumer types (e.g. the MgGrid generic hierarchy)
- DevExpress wrappers stay generic — no consumer-entity specialization in framework components
- MAUI platform folders (`AyCode.Maui.Core/Platforms/`) provide platform abstractions only; consumer-app manifest / splash screens / app-specific assets belong in the consumer app
- UI patterns maximize **generic base + consumer derives**

## Dependency Graph

```
AyCode.Core Solution  ../AyCode.Core/AyCode.Core.sln  (DLL references)
    ↑
AyCode.Blazor.Models ← AyCode.Blazor.Models.Server
    ↑
AyCode.Blazor.Components ← AyCode.Blazor.Controllers
    ↑
AyCode.Maui.Core (MAUI Hybrid host)
```

**Rule:** UI projects reference AyCode.Core via DLL (not ProjectReference). This separates build graphs.
**Context:** When a core type is not found in this solution, browse `../AyCode.Core/` for its definition.

## How It Works

### Blazor Server
1. **AyCode.Blazor.Components** provides all UI components (grids, card views, forms)
2. Components use **AcSignalRDataSource** to communicate with server via SignalR
3. SignalR uses **AcBinaryHubProtocol** for high-performance binary serialization
4. Grid filters are serialized as **AcExpressionNode** trees

### MAUI Hybrid
1. **AyCode.Maui.Core** hosts Blazor components in a WebView
2. Same components, same SignalR connection — different host
3. Platform-specific code in `Platforms/` folders (Android, iOS, Windows)

## Data Flow

```
User → DxGrid → AcSignalRDataSource → SignalR (AcBinary) → Server Hub → DAL → Database
                                                                    ↓
User ← DxGrid ← AcSignalRDataSource ← SignalR (AcBinary) ← Server Hub
```

## MgGrid Component System

The primary UI pattern for data screens. Overview and index: `AyCode.Blazor.Components/docs/MGGRID/README.md`

```
DxGrid (DevExpress)
  └── MgGridBase<TSignalRDataSource, TDataItem, TId, TLoggerClient>
        └── [Project adapter, e.g. FruitBankGridBase<TDataItem>]
              └── [Concrete grid, e.g. GridShippingBase]
```

| Component | Role |
|---|---|
| **MgGridBase** | Abstract base — SignalR CRUD, layout persistence, master-detail, edit state |
| **MgGridWithInfoPanel** | `DxSplitter` wrapper — grid + collapsible InfoPanel + fullscreen |
| **MgGridToolbarTemplate** | Full toolbar: CRUD, navigation, layout, export, fullscreen |
| **MgGridDataColumn** | `DxGridDataColumn` with InfoPanel parameters and URL template support |
| **MgGridInfoPanel** | Default InfoPanel — column-value display with edit mode |
| **MgGridSignalRDataSource** | `GridCustomDataSource` with local cache and background refresh |

## Key Design Decisions

- **DevExpress 25.1.3** exclusively — no mixing with other component libraries
- **SignalR over REST** for grid data — enables real-time updates and binary protocol
- **Expression serialization** — grid filters evaluated server-side, not client-side
- **Shared components** — Blazor Server and MAUI Hybrid use the exact same component library