feat: GraphClient - POCO-based graph abstraction layer

[wendellmva]

Overview

Create a high-level GraphClient abstraction that allows users to work with POCOs while automatically translating them to graph entities (NodeTypes, Nodes, Edges, Properties).

User Experience

// 1. Define models with attributes
[GraphNode("app.task", Name = "Task", Icon = "task")]
public class TaskModel
{
    public Guid Id { get; set; }

    [GraphProperty(Required = true)]
    public string Title { get; set; }

    [GraphProperty(PropertyTypes.DateTime)]
    public DateTime DueDate { get; set; }

    [GraphEdge("assigned.to")]
    public UserModel? AssignedTo { get; set; }
}

// 2. Use GraphClient for CRUD
var client = new GraphClient("https://api.example.com");
var task = await client.CreateAsync(new TaskModel { Title = "My Task" });
var loaded = await client.GetAsync<TaskModel>(task.Id);

Implementation Tasks

Phase 1: Test Specifications (SPEC0230)

• Create src/test/SPEC0230.GraphClient/ directory structure
• Create GraphClientScenario.cs base class
• Create TestModels.cs with sample POCOs
• US01: Model Attributes scenarios
• US02: Type Registration scenarios
• US03: Node CRUD scenarios
• US04: Edge Navigation scenarios
• US05: Property Mapping scenarios

Phase 2: Attributes (src/abstractions/Attributes/)

• GraphNodeAttribute.cs - marks class as graph node
• GraphPropertyAttribute.cs - property metadata
• GraphEdgeAttribute.cs - navigation property as edge
• GraphIdAttribute.cs - marks ID property
• GraphIgnoreAttribute.cs - excludes from serialization

Phase 3: Client Implementation (src/abstractions/Client/)

• IGraphClient.cs - public interface
• GraphClient.cs - main implementation
• GraphClientOptions.cs - configuration
• Internal/ModelReflector.cs - reflection + caching
• Internal/ModelMetadata.cs - extracted type info
• Internal/TypeRegistry.cs - NodeType registration
• Internal/ModelMapper.cs - POCO ↔ Node conversion

Phase 4: Documentation

• src/abstractions/README.md - usage guide

Key Features

• Auto-registration: NodeTypes registered automatically on first use
• Version tracking: SHA256 hash detects model changes, updates NodeType
• Type inference: C# types mapped to PropertyTypes automatically
• Edge navigation: Navigation properties translated to graph edges
• Soft deletes: Default behavior matches existing patterns

User Stories

ID	Story	Description
US01	Model Attributes	Attribute decoration for graph metadata
US02	Type Registration	Auto-register NodeTypes on first use
US03	Node CRUD	Create, Read, Update, Delete operations
US04	Edge Navigation	Edge creation and traversal
US05	Property Mapping	Type conversion (C# ↔ PropertyTypes)

References

• Extends pattern from NodeTypeAttribute.cs
• Reuses hash logic from ModelShapeService.cs
• Follows test structure from SPEC0209.GraphSession