Add LLM onboarding docs and standardize project READMEs
- Introduced `.github/copilot-instructions.md` as the single source of truth for domain rules, conventions, and pitfalls in each solution. - Added `CLAUDE.md` to guide Claude to read domain rules, glossary, and README before code generation. - Updated all solution and project `README.md` files to document project purpose, structure, key files, and LLM context (Copilot/Claude/Cursor). - Added or revised `docs/ARCHITECTURE.md`, `docs/CONVENTIONS.md`, and `docs/GLOSSARY.md` to clarify dependency graphs, naming, patterns, and terminology. - For FruitBankHybridApp, added `docs/SCHEMA.md` (Toon format) and expanded the glossary with business/measurement terms and common traps. - Updated all subfolder READMEs to list key files, conventions, and LLM maintenance notes. - Ensured all documentation is cross-referenced, up-to-date, and includes explicit instructions for LLMs to keep docs in sync with code and avoid suggesting removal/rollback as a solution. - Standardized documentation and onboarding for maintainability and LLM/code quality across all solutions.
This commit is contained in:
parent
85dbb853c7
commit
79eceff47a
|
|
@ -0,0 +1,24 @@
|
|||
# AyCode.Blazor — Domain Rules
|
||||
|
||||
> This is the **single source of truth** for Blazor/MAUI UI domain rules. Do not duplicate these elsewhere.
|
||||
> For core framework rules see: `../AyCode.Core/.github/copilot-instructions.md`
|
||||
> For detailed docs see: `README.md` → `docs/`
|
||||
|
||||
## DevExpress Components
|
||||
1. **DevExpress Blazor 25.1.3** — always use `DxGrid`, `DxFormLayout`, etc. Do NOT mix with generic Blazor component libraries.
|
||||
2. **Grid system** uses `AcSignalRDataSource` for real-time data — grids fetch data via SignalR, not REST.
|
||||
3. **CardView components** wrap DevExpress grids with card-style layout for mobile-friendly display.
|
||||
|
||||
## Architecture
|
||||
4. **Blazor.Components** is the main UI library — both Blazor Server and MAUI Hybrid consume it.
|
||||
5. **Blazor.Models** = shared view models (client + server). **Blazor.Models.Server** = server-only scaffolding.
|
||||
6. **MAUI.Core** targets Android (API 33+), iOS (15.0+), Windows (10.0.19041+) via platform folders.
|
||||
7. **Controllers** project is scaffolding — do not add business logic here.
|
||||
|
||||
## Serialization in UI
|
||||
8. SignalR uses **AcBinaryHubProtocol** (custom binary) — not the default JSON protocol.
|
||||
9. Grid filters use **AcExpressionNode** serialization — LINQ expressions are serialized and sent to server.
|
||||
|
||||
## Conventions
|
||||
10. Do not suggest removal/rollback as a solution — find a fix for the problem.
|
||||
11. All DLL references to AyCode.Core projects are via `DllReference` (not ProjectReference) — this is intentional.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# AyCode.Blazor — Claude Code Instructions
|
||||
|
||||
Before writing any code, read these files:
|
||||
1. `.github/copilot-instructions.md` — Domain rules and UI pitfalls (single source of truth)
|
||||
2. `docs/GLOSSARY.md` — Blazor/MAUI terminology and DevExpress conventions
|
||||
3. The relevant project's `README.md` for folder-specific context
|
||||
|
||||
This solution depends on **AyCode.Core** — for core framework rules see `../AyCode.Core/CLAUDE.md`.
|
||||
|
||||
When modifying code, update the corresponding README.md if it becomes out of sync with the code.
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
# AyCode.Blazor Solution
|
||||
|
||||
Blazor Server + MAUI Hybrid UI framework built on DevExpress 25.1.3 components. Provides reusable grids, card views, authentication, and SignalR-powered real-time data. Depends on AyCode.Core for serialization, entities, and services.
|
||||
|
||||
## LLM Context
|
||||
|
||||
Domain rules and UI pitfalls live in a single file: [`.github/copilot-instructions.md`](.github/copilot-instructions.md)
|
||||
|
||||
| Tool | Auto-loaded | Action needed |
|
||||
|------|------------|---------------|
|
||||
| GitHub Copilot | ✅ `copilot-instructions.md` | None |
|
||||
| Claude Code | ✅ `CLAUDE.md` → references above | None |
|
||||
| Cursor / Windsurf | ✅ `README.md` | Read `copilot-instructions.md` via @file |
|
||||
|
||||
Detailed docs: [`docs/`](docs/) — GLOSSARY.md, ARCHITECTURE.md
|
||||
|
||||
Core framework rules: [`../AyCode.Core/.github/copilot-instructions.md`](../AyCode.Core/.github/copilot-instructions.md)
|
||||
|
||||
## Solution Structure
|
||||
|
||||
| Project | Purpose | README |
|
||||
|---|---|---|
|
||||
| [`AyCode.Blazor.Components`](AyCode.Blazor.Components/README.md) | DevExpress UI components, grids, SignalR data sources, expression helpers | [README](AyCode.Blazor.Components/README.md) |
|
||||
| [`AyCode.Blazor.Models`](AyCode.Blazor.Models/README.md) | Shared view models for Blazor components | [README](AyCode.Blazor.Models/README.md) |
|
||||
| [`AyCode.Blazor.Models.Server`](AyCode.Blazor.Models.Server/README.md) | Server-side model scaffolding | [README](AyCode.Blazor.Models.Server/README.md) |
|
||||
| [`AyCode.Blazor.Controllers`](AyCode.Blazor.Controllers/README.md) | Controller scaffolding (minimal) | [README](AyCode.Blazor.Controllers/README.md) |
|
||||
| [`AyCode.Maui.Core`](AyCode.Maui.Core/README.md) | MAUI cross-platform: Android, iOS, Windows | [README](AyCode.Maui.Core/README.md) |
|
||||
|
||||
### Test Projects
|
||||
|
||||
| Project | Purpose | README |
|
||||
|---|---|---|
|
||||
| [`AyCode.Blazor.Components.Tests`](AyCode.Blazor.Components.Tests/README.md) | Grid and component tests | [README](AyCode.Blazor.Components.Tests/README.md) |
|
||||
|
||||
---
|
||||
|
||||
> **LLM Maintenance:** If you modify this solution's structure, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
# Architecture
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
```
|
||||
AyCode.Core Solution (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.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
> **LLM Maintenance:** If you modify the architecture, update this document.
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
# 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**.
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
|
||||
> **LLM Maintenance:** If you establish new UI conventions or patterns, document them here.
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
# Glossary
|
||||
|
||||
Blazor/MAUI UI terminology. For core framework terms see [`../../AyCode.Core/docs/GLOSSARY.md`](../../AyCode.Core/docs/GLOSSARY.md).
|
||||
|
||||
## UI Components
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **DxGrid** | DevExpress Blazor data grid. Used with `AcSignalRDataSource` for real-time SignalR data. |
|
||||
| **CardView** | Card-style layout wrapping DxGrid. Mobile-friendly alternative to table grids. |
|
||||
| **AcSignalRDataSource** | Grid data source backed by SignalR. Handles load, CRUD, filtering, and change tracking. |
|
||||
| **AcExpressionNode** | Serializable LINQ expression tree. Grid filters are serialized as expression nodes and sent to server. |
|
||||
|
||||
## Architecture
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **Blazor Hybrid** | MAUI app hosting Blazor components via WebView. Shares UI code between web and native. |
|
||||
| **DLL Reference** | AyCode.Core projects are referenced as DLLs (not ProjectReference). This is intentional — separates solution build graphs. |
|
||||
| **AcBinaryHubProtocol** | Custom SignalR hub protocol using AcBinary serializer instead of default JSON. Used for performance. |
|
||||
|
||||
## Authentication
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **AcBlazorLoginServiceBase** | Client-side login service managing JWT tokens, SecureStorage, and auto-refresh. |
|
||||
| **AcAuthenticationStateProvider** | Custom Blazor auth state provider backed by JWT claims. |
|
||||
|
||||
## MAUI Platforms
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **Platforms/** | Per-platform code folders: Android, iOS, Windows. MAUI SDK auto-includes based on target. |
|
||||
| **API 33+** | Minimum Android API level (Android 13). |
|
||||
|
||||
---
|
||||
|
||||
> **LLM Maintenance:** If you modify code that changes terminology, update this glossary.
|
||||
Loading…
Reference in New Issue