Code Standards¶

Coding conventions for the Consystence codebase.

.NET conventions¶

Target framework¶

All services target .NET 10. Use the latest C# language features (C# 13).

Data transfer¶

Use records for DTOs and grain state:

[GenerateSerializer]
public record DeviceStatus
{
    [Id(0)] public string DeviceId { get; init; } = "";
    [Id(1)] public bool IsOnline { get; init; }
    [Id(2)] public DateTime LastSeen { get; init; }
}

Orleans serialization¶

All types that cross grain boundaries must have [GenerateSerializer] with [Id(n)] on each property. Do not use Newtonsoft.Json or System.Text.Json for grain communication.

Async rendering¶

Use ValueTask for rendering methods that often return synchronously (cached HTML fragments):

public ValueTask<string> RenderAsync(ComponentNode node, RenderContext context)
{
    if (_cache.TryGetValue(node, out var html))
        return ValueTask.FromResult(html);

    return new ValueTask<string>(RenderSlowPathAsync(node, context));
}

HTML in C¶

Use raw string literals for HTML templates:

var html = $$"""
    <div class="p-4 bg-slate-800 rounded-lg">
        <h3 class="text-sm text-slate-400">{{label}}</h3>
        <span class="text-2xl text-white">{{value}} {{unit}}</span>
    </div>
    """;

Naming conventions¶

IDs and keys¶

C# naming¶

Follow the standard .NET conventions:

Theming¶

Tailwind CSS palette¶

The dark theme uses these colour tokens:

Brand colours¶

YAML conventions¶

Device type definitions, alarm configs, and command configs use YAML:

• 2-space indentation
• No trailing whitespace
• Strings quoted only when necessary (e.g. containing : or #)
• Lists use - with a space

Architectural boundaries¶

Orleans services¶

The site server (consystence-server) uses Orleans for all stateful operations: device instances, page sessions, alarm evaluation, and audit logging.

Plain ASP.NET Core services¶

Platform services that do not need distributed state use plain ASP.NET Core without Orleans: