Add Galaxy repository API and clients

2026-04-29 07:27:00 -04:00
parent 047d875fe6
commit 133c83029b
103 changed files with 22788 additions and 39 deletions
@@ -23,6 +23,9 @@
                    <li class="nav-item">
                        <NavLink class="nav-link" href="events">Events</NavLink>
                    </li>
+                    <li class="nav-item">
+                        <NavLink class="nav-link" href="galaxy">Galaxy</NavLink>
+                    </li>
                    <li class="nav-item">
                        <NavLink class="nav-link" href="settings">Settings</NavLink>
                    </li>
@@ -29,6 +29,26 @@ else
        <MetricCard Label="Queue Overflows" Value="@DashboardDisplay.Count(DashboardDisplay.MetricValue(Snapshot, "mxgateway.queues.overflows"))" />
    </section>

+    <section class="dashboard-section">
+        <div class="section-heading d-flex align-items-center gap-2">
+            <h2>Galaxy Repository</h2>
+            <StatusBadge Text="@Snapshot.Galaxy.Status.ToString()" />
+            <NavLink class="ms-auto small" href="galaxy">View browse details &rarr;</NavLink>
+        </div>
+        <div class="metric-grid compact">
+            <MetricCard Label="Last Deploy" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastDeployTime)" />
+            <MetricCard Label="Objects" Value="@DashboardDisplay.Count(Snapshot.Galaxy.ObjectCount)" Detail="@($"{Snapshot.Galaxy.AreaCount:N0} areas")" />
+            <MetricCard Label="Attributes" Value="@DashboardDisplay.Count(Snapshot.Galaxy.AttributeCount)" />
+            <MetricCard Label="Historized" Value="@DashboardDisplay.Count(Snapshot.Galaxy.HistorizedAttributeCount)" />
+            <MetricCard Label="Alarms" Value="@DashboardDisplay.Count(Snapshot.Galaxy.AlarmAttributeCount)" />
+            <MetricCard Label="Last Refresh" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastSuccessAt)" Detail="@GalaxyRefreshDetail()" />
+        </div>
+        @if (!string.IsNullOrWhiteSpace(Snapshot.Galaxy.LastError))
+        {
+            <div class="empty-state mt-2">@Snapshot.Galaxy.LastError</div>
+        }
+    </section>
+
    <section class="dashboard-section">
        <div class="section-heading">
            <h2>Recent Faults</h2>
@@ -36,3 +56,23 @@ else
        <FaultList Faults="@Snapshot.Faults" />
    </section>
 }
+
+@code {
+    private string? GalaxyRefreshDetail()
+    {
+        DashboardGalaxySummary galaxy = Snapshot!.Galaxy;
+        if (galaxy.LastQueriedAt is null)
+        {
+            return "never queried";
+        }
+
+        if (galaxy.LastSuccessAt is null)
+        {
+            return "no successful refresh yet";
+        }
+
+        return galaxy.LastQueriedAt > galaxy.LastSuccessAt
+            ? $"last attempt {DashboardDisplay.DateTime(galaxy.LastQueriedAt)}"
+            : null;
+    }
+}
@@ -0,0 +1,195 @@
+@page "/galaxy"
+@page "/dashboard/galaxy"
+@inherits DashboardPageBase
+
+<PageTitle>Dashboard Galaxy</PageTitle>
+
+@if (Snapshot is null)
+{
+    <div class="empty-state">Loading Galaxy summary.</div>
+}
+else
+{
+    <div class="dashboard-page-header">
+        <div>
+            <h1>Galaxy Repository</h1>
+            <div class="text-secondary">@RefreshHeading()</div>
+        </div>
+        <StatusBadge Text="@Snapshot.Galaxy.Status.ToString()" />
+    </div>
+
+    <section class="metric-grid">
+        <MetricCard Label="Last Deploy" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastDeployTime)" Detail="@DeployAge()" />
+        <MetricCard Label="Objects" Value="@DashboardDisplay.Count(Snapshot.Galaxy.ObjectCount)" Detail="@($"{Snapshot.Galaxy.AreaCount:N0} areas")" />
+        <MetricCard Label="Attributes" Value="@DashboardDisplay.Count(Snapshot.Galaxy.AttributeCount)" Detail="dynamic, deployed" />
+        <MetricCard Label="Historized" Value="@DashboardDisplay.Count(Snapshot.Galaxy.HistorizedAttributeCount)" />
+        <MetricCard Label="Alarms" Value="@DashboardDisplay.Count(Snapshot.Galaxy.AlarmAttributeCount)" />
+        <MetricCard Label="Last Refresh" Value="@DashboardDisplay.DateTime(Snapshot.Galaxy.LastSuccessAt)" Detail="@LastAttemptDetail()" />
+    </section>
+
+    @if (Snapshot.Galaxy.Status == DashboardGalaxyStatus.Unknown)
+    {
+        <section class="dashboard-section">
+            <div class="empty-state">
+                Galaxy summary has not been collected yet. The dashboard refreshes the
+                summary every @RefreshIntervalSeconds() seconds via the
+                <code>GalaxyRepository</code> service.
+            </div>
+        </section>
+    }
+
+    @if (!string.IsNullOrWhiteSpace(Snapshot.Galaxy.LastError))
+    {
+        <section class="dashboard-section">
+            <div class="section-heading">
+                <h2>Last Error</h2>
+            </div>
+            <div class="empty-state">@Snapshot.Galaxy.LastError</div>
+        </section>
+    }
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Object Categories</h2>
+        </div>
+        @if (Snapshot.Galaxy.ObjectCategories.Count == 0)
+        {
+            <div class="empty-state">No deployed objects observed.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Category</th>
+                            <th scope="col">Category ID</th>
+                            <th scope="col">Objects</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardGalaxyCategoryCount row in Snapshot.Galaxy.ObjectCategories)
+                        {
+                            <tr>
+                                <td>@row.CategoryName</td>
+                                <td><code>@row.CategoryId</code></td>
+                                <td>@DashboardDisplay.Count(row.ObjectCount)</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Top Templates</h2>
+        </div>
+        @if (Snapshot.Galaxy.TopTemplates.Count == 0)
+        {
+            <div class="empty-state">No template usage observed.</div>
+        }
+        else
+        {
+            <div class="table-responsive">
+                <table class="table table-sm dashboard-table">
+                    <thead>
+                        <tr>
+                            <th scope="col">Template</th>
+                            <th scope="col">Instances</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (DashboardGalaxyTemplateUsage row in Snapshot.Galaxy.TopTemplates)
+                        {
+                            <tr>
+                                <td><code>@row.TemplateName</code></td>
+                                <td>@DashboardDisplay.Count(row.InstanceCount)</td>
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+            </div>
+        }
+    </section>
+
+    <section class="dashboard-section">
+        <div class="section-heading">
+            <h2>Sync Info</h2>
+        </div>
+        <div class="table-responsive">
+            <table class="table table-sm dashboard-table details-table">
+                <tbody>
+                    <tr><th scope="row">Status</th><td><StatusBadge Text="@Snapshot.Galaxy.Status.ToString()" /></td></tr>
+                    <tr><th scope="row">Last successful refresh</th><td>@DashboardDisplay.DateTime(Snapshot.Galaxy.LastSuccessAt)</td></tr>
+                    <tr><th scope="row">Last attempt</th><td>@DashboardDisplay.DateTime(Snapshot.Galaxy.LastQueriedAt)</td></tr>
+                    <tr><th scope="row">Galaxy <code>time_of_last_deploy</code></th><td>@DashboardDisplay.DateTime(Snapshot.Galaxy.LastDeployTime)</td></tr>
+                    <tr><th scope="row">Refresh interval</th><td>@RefreshIntervalSeconds() seconds</td></tr>
+                    <tr><th scope="row">Connection string</th><td><code>@DashboardDisplay.Text(GalaxyConnectionStringDisplay())</code></td></tr>
+                    <tr><th scope="row">Command timeout</th><td>@CommandTimeoutSeconds() seconds</td></tr>
+                </tbody>
+            </table>
+        </div>
+        <div class="text-secondary small mt-2">
+            Browse data is served by the <code>galaxy_repository.v1.GalaxyRepository</code> gRPC
+            service. Clients call <code>DiscoverHierarchy</code> for the full tree and
+            <code>GetLastDeployTime</code> to detect redeployments.
+        </div>
+    </section>
+}
+
+@code {
+    [Inject]
+    private IOptions<MxGateway.Server.Galaxy.GalaxyRepositoryOptions> GalaxyOptions { get; set; } = null!;
+
+    private string RefreshHeading()
+    {
+        DashboardGalaxySummary galaxy = Snapshot!.Galaxy;
+        return galaxy.LastSuccessAt is null
+            ? "Awaiting first successful refresh"
+            : $"Refreshed {DashboardDisplay.DateTime(galaxy.LastSuccessAt)}";
+    }
+
+    private string? DeployAge()
+    {
+        DashboardGalaxySummary galaxy = Snapshot!.Galaxy;
+        if (galaxy.LastDeployTime is null || galaxy.LastSuccessAt is null)
+        {
+            return null;
+        }
+
+        TimeSpan age = galaxy.LastSuccessAt.Value - galaxy.LastDeployTime.Value;
+        if (age < TimeSpan.Zero)
+        {
+            return null;
+        }
+
+        return $"{DashboardDisplay.Duration(age)} ago";
+    }
+
+    private string? LastAttemptDetail()
+    {
+        DashboardGalaxySummary galaxy = Snapshot!.Galaxy;
+        if (galaxy.LastQueriedAt is null)
+        {
+            return "never queried";
+        }
+
+        if (galaxy.LastSuccessAt is null)
+        {
+            return "no successful refresh yet";
+        }
+
+        return galaxy.LastQueriedAt > galaxy.LastSuccessAt
+            ? $"last attempt {DashboardDisplay.DateTime(galaxy.LastQueriedAt)}"
+            : null;
+    }
+
+    private int RefreshIntervalSeconds() => Math.Max(1, GalaxyOptions.Value.DashboardRefreshIntervalSeconds);
+
+    private int CommandTimeoutSeconds() => GalaxyOptions.Value.CommandTimeoutSeconds;
+
+    private string? GalaxyConnectionStringDisplay() =>
+        DashboardRedactor.Redact(GalaxyOptions.Value.ConnectionString);
+}
@@ -9,7 +9,9 @@
        "Ready" or "Healthy" => "text-bg-success",
        "Creating" or "StartingWorker" or "WaitingForPipe" or "InitializingWorker" or "Closing" => "text-bg-info",
        "Closed" => "text-bg-secondary",
-        "Faulted" => "text-bg-danger",
+        "Stale" => "text-bg-warning",
+        "Faulted" or "Unavailable" => "text-bg-danger",
+        "Unknown" => "text-bg-light text-dark border",
        _ => "text-bg-light text-dark border"
    };
 }
@@ -0,0 +1,98 @@
+using MxGateway.Server.Galaxy;
+
+namespace MxGateway.Server.Dashboard;
+
+/// <summary>
+///     Projects a <see cref="GalaxyHierarchyCacheEntry"/> into a
+///     <see cref="DashboardGalaxySummary"/> for the Blazor pages. Top-templates and
+///     per-category breakdowns are computed here rather than stored on the cache so the
+///     Galaxy namespace stays free of dashboard-presentation concepts.
+/// </summary>
+internal static class DashboardGalaxyProjector
+{
+    private const int TopTemplatesLimit = 10;
+
+    private static readonly IReadOnlyDictionary<int, string> CategoryNamesById = new Dictionary<int, string>
+    {
+        [1] = "WinPlatform",
+        [3] = "AppEngine",
+        [4] = "InTouchViewApp",
+        [10] = "UserDefined",
+        [11] = "FieldReference",
+        [13] = "Area",
+        [17] = "DIObject",
+        [24] = "DDESuiteLinkClient",
+        [26] = "OPCClient",
+    };
+
+    public static DashboardGalaxySummary Project(GalaxyHierarchyCacheEntry entry)
+    {
+        DashboardGalaxyStatus status = entry.Status switch
+        {
+            GalaxyCacheStatus.Healthy => DashboardGalaxyStatus.Healthy,
+            GalaxyCacheStatus.Stale => DashboardGalaxyStatus.Stale,
+            GalaxyCacheStatus.Unavailable => DashboardGalaxyStatus.Unavailable,
+            _ => DashboardGalaxyStatus.Unknown,
+        };
+
+        IReadOnlyList<DashboardGalaxyTemplateUsage> topTemplates;
+        IReadOnlyList<DashboardGalaxyCategoryCount> objectCategories;
+
+        if (entry.Hierarchy.Count == 0)
+        {
+            topTemplates = Array.Empty<DashboardGalaxyTemplateUsage>();
+            objectCategories = Array.Empty<DashboardGalaxyCategoryCount>();
+        }
+        else
+        {
+            Dictionary<int, int> objectsByCategory = new();
+            Dictionary<string, int> templateUsage = new(StringComparer.OrdinalIgnoreCase);
+
+            foreach (GalaxyHierarchyRow row in entry.Hierarchy)
+            {
+                objectsByCategory.TryGetValue(row.CategoryId, out int categoryCount);
+                objectsByCategory[row.CategoryId] = categoryCount + 1;
+
+                if (row.TemplateChain.Count > 0)
+                {
+                    string immediate = row.TemplateChain[0];
+                    if (!string.IsNullOrWhiteSpace(immediate))
+                    {
+                        templateUsage.TryGetValue(immediate, out int templateCount);
+                        templateUsage[immediate] = templateCount + 1;
+                    }
+                }
+            }
+
+            topTemplates = templateUsage
+                .OrderByDescending(entry => entry.Value)
+                .ThenBy(entry => entry.Key, StringComparer.OrdinalIgnoreCase)
+                .Take(TopTemplatesLimit)
+                .Select(entry => new DashboardGalaxyTemplateUsage(entry.Key, entry.Value))
+                .ToArray();
+
+            objectCategories = objectsByCategory
+                .OrderByDescending(entry => entry.Value)
+                .ThenBy(entry => entry.Key)
+                .Select(entry => new DashboardGalaxyCategoryCount(
+                    entry.Key,
+                    CategoryNamesById.TryGetValue(entry.Key, out string? name) ? name : $"Category {entry.Key}",
+                    entry.Value))
+                .ToArray();
+        }
+
+        return new DashboardGalaxySummary(
+            Status: status,
+            LastQueriedAt: entry.LastQueriedAt,
+            LastSuccessAt: entry.LastSuccessAt,
+            LastDeployTime: entry.LastDeployTime,
+            LastError: entry.LastError,
+            ObjectCount: entry.ObjectCount,
+            AreaCount: entry.AreaCount,
+            AttributeCount: entry.AttributeCount,
+            HistorizedAttributeCount: entry.HistorizedAttributeCount,
+            AlarmAttributeCount: entry.AlarmAttributeCount,
+            TopTemplates: topTemplates,
+            ObjectCategories: objectCategories);
+    }
+}
@@ -0,0 +1,47 @@
+namespace MxGateway.Server.Dashboard;
+
+/// <summary>
+///     Snapshot of the Galaxy Repository (ZB) browse state surfaced on the dashboard.
+///     Populated by <see cref="GalaxySummaryCache"/> on a background refresh cadence so
+///     the dashboard never blocks on SQL.
+/// </summary>
+public sealed record DashboardGalaxySummary(
+    DashboardGalaxyStatus Status,
+    DateTimeOffset? LastQueriedAt,
+    DateTimeOffset? LastSuccessAt,
+    DateTimeOffset? LastDeployTime,
+    string? LastError,
+    int ObjectCount,
+    int AreaCount,
+    int AttributeCount,
+    int HistorizedAttributeCount,
+    int AlarmAttributeCount,
+    IReadOnlyList<DashboardGalaxyTemplateUsage> TopTemplates,
+    IReadOnlyList<DashboardGalaxyCategoryCount> ObjectCategories)
+{
+    public static DashboardGalaxySummary Unknown { get; } = new(
+        DashboardGalaxyStatus.Unknown,
+        LastQueriedAt: null,
+        LastSuccessAt: null,
+        LastDeployTime: null,
+        LastError: null,
+        ObjectCount: 0,
+        AreaCount: 0,
+        AttributeCount: 0,
+        HistorizedAttributeCount: 0,
+        AlarmAttributeCount: 0,
+        TopTemplates: Array.Empty<DashboardGalaxyTemplateUsage>(),
+        ObjectCategories: Array.Empty<DashboardGalaxyCategoryCount>());
+}
+
+public enum DashboardGalaxyStatus
+{
+    Unknown = 0,
+    Healthy = 1,
+    Stale = 2,
+    Unavailable = 3,
+}
+
+public sealed record DashboardGalaxyTemplateUsage(string TemplateName, int InstanceCount);
+
+public sealed record DashboardGalaxyCategoryCount(int CategoryId, string CategoryName, int ObjectCount);
@@ -12,4 +12,5 @@ public sealed record DashboardSnapshot(
    IReadOnlyList<DashboardWorkerSummary> Workers,
    IReadOnlyList<DashboardMetricSummary> Metrics,
    IReadOnlyList<DashboardFaultSummary> Faults,
-    EffectiveGatewayConfiguration Configuration);
+    EffectiveGatewayConfiguration Configuration,
+    DashboardGalaxySummary Galaxy);
@@ -1,6 +1,7 @@
 using System.Runtime.CompilerServices;
 using Microsoft.Extensions.Options;
 using MxGateway.Server.Configuration;
+using MxGateway.Server.Galaxy;
 using MxGateway.Server.Metrics;
 using MxGateway.Server.Sessions;
 using MxGateway.Server.Workers;
@@ -14,6 +15,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
    private readonly ISessionRegistry _sessionRegistry;
    private readonly GatewayMetrics _metrics;
    private readonly IGatewayConfigurationProvider _configurationProvider;
+    private readonly IGalaxyHierarchyCache _galaxyHierarchyCache;
    private readonly TimeProvider _timeProvider;
    private readonly DateTimeOffset _gatewayStartedAt;
    private readonly TimeSpan _snapshotInterval;
@@ -24,12 +26,14 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
        ISessionRegistry sessionRegistry,
        GatewayMetrics metrics,
        IGatewayConfigurationProvider configurationProvider,
+        IGalaxyHierarchyCache galaxyHierarchyCache,
        IOptions<GatewayOptions> options,
        TimeProvider? timeProvider = null)
    {
        _sessionRegistry = sessionRegistry ?? throw new ArgumentNullException(nameof(sessionRegistry));
        _metrics = metrics ?? throw new ArgumentNullException(nameof(metrics));
        _configurationProvider = configurationProvider ?? throw new ArgumentNullException(nameof(configurationProvider));
+        _galaxyHierarchyCache = galaxyHierarchyCache ?? throw new ArgumentNullException(nameof(galaxyHierarchyCache));
        ArgumentNullException.ThrowIfNull(options);

        _timeProvider = timeProvider ?? TimeProvider.System;
@@ -65,7 +69,8 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
            Workers: workerSummaries,
            Metrics: CreateMetricSummaries(metricsSnapshot),
            Faults: CreateFaultSummaries(sessions, generatedAt),
-            Configuration: _configurationProvider.GetEffectiveConfiguration());
+            Configuration: _configurationProvider.GetEffectiveConfiguration(),
+            Galaxy: DashboardGalaxyProjector.Project(_galaxyHierarchyCache.Current));
    }

    public async IAsyncEnumerable<DashboardSnapshot> WatchSnapshotsAsync(
@@ -0,0 +1,17 @@
+namespace MxGateway.Server.Galaxy;
+
+public enum GalaxyCacheStatus
+{
+    /// <summary>Cache has never completed a refresh.</summary>
+    Unknown = 0,
+
+    /// <summary>Cache holds data from a recent successful refresh.</summary>
+    Healthy = 1,
+
+    /// <summary>Cache holds data, but the most recent refresh attempt failed
+    /// or no successful refresh has happened within the staleness threshold.</summary>
+    Stale = 2,
+
+    /// <summary>Latest refresh failed and no prior data is available.</summary>
+    Unavailable = 3,
+}
@@ -0,0 +1,14 @@
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     A single Galaxy deploy notification. Published by <see cref="GalaxyHierarchyCache"/>
+///     whenever a refresh detects that <c>galaxy.time_of_last_deploy</c> has changed (or on
+///     the first successful refresh). Consumed by <see cref="IGalaxyDeployNotifier"/>
+///     subscribers (the streaming gRPC RPC).
+/// </summary>
+public sealed record GalaxyDeployEventInfo(
+    long Sequence,
+    DateTimeOffset ObservedAt,
+    DateTimeOffset? TimeOfLastDeploy,
+    int ObjectCount,
+    int AttributeCount);
@@ -0,0 +1,74 @@
+using System.Collections.Concurrent;
+using System.Runtime.CompilerServices;
+using System.Threading.Channels;
+
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     Channel-based fan-out of Galaxy deploy events to streaming gRPC subscribers. Each
+///     subscriber gets a private bounded channel so a slow client cannot back-pressure
+///     other subscribers or the publisher. When a subscriber's channel is full the oldest
+///     event is dropped — clients use the sequence field to detect gaps.
+/// </summary>
+public sealed class GalaxyDeployNotifier : IGalaxyDeployNotifier
+{
+    private const int SubscriberQueueCapacity = 16;
+
+    private readonly ConcurrentDictionary<Guid, Channel<GalaxyDeployEventInfo>> _subscribers = new();
+    private GalaxyDeployEventInfo? _latest;
+
+    public GalaxyDeployEventInfo? Latest => Volatile.Read(ref _latest);
+
+    public void Publish(GalaxyDeployEventInfo info)
+    {
+        ArgumentNullException.ThrowIfNull(info);
+
+        Volatile.Write(ref _latest, info);
+
+        foreach (Channel<GalaxyDeployEventInfo> channel in _subscribers.Values)
+        {
+            // BoundedChannelFullMode.DropOldest -> writes never wait; we only fail if the
+            // channel was completed by the subscriber side, which we ignore.
+            channel.Writer.TryWrite(info);
+        }
+    }
+
+    public async IAsyncEnumerable<GalaxyDeployEventInfo> SubscribeAsync(
+        [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        Guid subscriberId = Guid.NewGuid();
+        Channel<GalaxyDeployEventInfo> channel = Channel.CreateBounded<GalaxyDeployEventInfo>(
+            new BoundedChannelOptions(SubscriberQueueCapacity)
+            {
+                FullMode = BoundedChannelFullMode.DropOldest,
+                SingleReader = true,
+                SingleWriter = false,
+            });
+
+        _subscribers[subscriberId] = channel;
+
+        // Bootstrap: emit the latest known event so subscribers don't need to wait for
+        // the next deploy to know current state.
+        GalaxyDeployEventInfo? bootstrap = Volatile.Read(ref _latest);
+        if (bootstrap is not null)
+        {
+            channel.Writer.TryWrite(bootstrap);
+        }
+
+        try
+        {
+            while (await channel.Reader.WaitToReadAsync(cancellationToken).ConfigureAwait(false))
+            {
+                while (channel.Reader.TryRead(out GalaxyDeployEventInfo? next))
+                {
+                    yield return next;
+                }
+            }
+        }
+        finally
+        {
+            _subscribers.TryRemove(subscriberId, out _);
+            channel.Writer.TryComplete();
+        }
+    }
+}
@@ -0,0 +1,186 @@
+using Google.Protobuf.WellKnownTypes;
+using Microsoft.Data.SqlClient;
+using Microsoft.Extensions.Logging;
+using MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Server.Grpc;
+
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     Server-side cache of Galaxy Repository browse data. All gRPC clients share the same
+///     entry — the materialized <see cref="DiscoverHierarchyReply"/> is produced once per
+///     refresh and reused across requests. Refreshes are deploy-time gated: every tick
+///     queries <c>galaxy.time_of_last_deploy</c> (cheap), and the heavy hierarchy +
+///     attributes rowsets are pulled only when that timestamp has advanced.
+/// </summary>
+public sealed class GalaxyHierarchyCache : IGalaxyHierarchyCache
+{
+    private static readonly TimeSpan StaleThreshold = TimeSpan.FromMinutes(5);
+
+    private readonly GalaxyRepository _repository;
+    private readonly IGalaxyDeployNotifier _notifier;
+    private readonly TimeProvider _timeProvider;
+    private readonly ILogger<GalaxyHierarchyCache>? _logger;
+    private readonly TaskCompletionSource _firstLoad = new(TaskCreationOptions.RunContinuationsAsynchronously);
+    private readonly SemaphoreSlim _refreshGate = new(1, 1);
+    private GalaxyHierarchyCacheEntry _current = GalaxyHierarchyCacheEntry.Empty;
+
+    public GalaxyHierarchyCache(
+        GalaxyRepository repository,
+        IGalaxyDeployNotifier notifier,
+        TimeProvider? timeProvider = null,
+        ILogger<GalaxyHierarchyCache>? logger = null)
+    {
+        _repository = repository;
+        _notifier = notifier;
+        _timeProvider = timeProvider ?? TimeProvider.System;
+        _logger = logger;
+    }
+
+    public GalaxyHierarchyCacheEntry Current
+    {
+        get
+        {
+            GalaxyHierarchyCacheEntry snapshot = Volatile.Read(ref _current);
+            GalaxyCacheStatus projected = ProjectStatus(snapshot);
+            return projected == snapshot.Status ? snapshot : snapshot with { Status = projected };
+        }
+    }
+
+    public async Task RefreshAsync(CancellationToken cancellationToken)
+    {
+        await _refreshGate.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await RefreshCoreAsync(cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            _refreshGate.Release();
+        }
+    }
+
+    public Task WaitForFirstLoadAsync(CancellationToken cancellationToken)
+    {
+        return _firstLoad.Task.WaitAsync(cancellationToken);
+    }
+
+    private async Task RefreshCoreAsync(CancellationToken cancellationToken)
+    {
+        GalaxyHierarchyCacheEntry previous = Volatile.Read(ref _current);
+        DateTimeOffset queriedAt = _timeProvider.GetUtcNow();
+
+        try
+        {
+            DateTime? deployRaw = await _repository.GetLastDeployTimeAsync(cancellationToken).ConfigureAwait(false);
+            DateTimeOffset? deployTime = deployRaw.HasValue
+                ? new DateTimeOffset(DateTime.SpecifyKind(deployRaw.Value, DateTimeKind.Utc))
+                : null;
+
+            bool hasPriorData = previous.HasData;
+            bool deployChanged = !hasPriorData || deployTime != previous.LastDeployTime;
+
+            if (!deployChanged)
+            {
+                // No deploy change — skip heavy queries; just bump LastSuccessAt.
+                GalaxyHierarchyCacheEntry refreshed = previous with
+                {
+                    Status = GalaxyCacheStatus.Healthy,
+                    LastQueriedAt = queriedAt,
+                    LastSuccessAt = queriedAt,
+                    LastError = null,
+                };
+                Volatile.Write(ref _current, refreshed);
+                _firstLoad.TrySetResult();
+                return;
+            }
+
+            Task<List<GalaxyHierarchyRow>> hierarchyTask = _repository.GetHierarchyAsync(cancellationToken);
+            Task<List<GalaxyAttributeRow>> attributesTask = _repository.GetAttributesAsync(cancellationToken);
+            await Task.WhenAll(hierarchyTask, attributesTask).ConfigureAwait(false);
+
+            List<GalaxyHierarchyRow> hierarchy = hierarchyTask.Result;
+            List<GalaxyAttributeRow> attributes = attributesTask.Result;
+            DiscoverHierarchyReply reply = BuildReply(hierarchy, attributes);
+
+            int areaCount = hierarchy.Count(row => row.IsArea);
+            int historized = attributes.Count(row => row.IsHistorized);
+            int alarms = attributes.Count(row => row.IsAlarm);
+
+            long nextSequence = previous.Sequence + 1;
+            GalaxyHierarchyCacheEntry next = new(
+                Status: GalaxyCacheStatus.Healthy,
+                Sequence: nextSequence,
+                LastQueriedAt: queriedAt,
+                LastSuccessAt: queriedAt,
+                LastDeployTime: deployTime,
+                LastError: null,
+                Hierarchy: hierarchy,
+                Attributes: attributes,
+                Reply: reply,
+                ObjectCount: hierarchy.Count,
+                AreaCount: areaCount,
+                AttributeCount: attributes.Count,
+                HistorizedAttributeCount: historized,
+                AlarmAttributeCount: alarms);
+
+            Volatile.Write(ref _current, next);
+            _firstLoad.TrySetResult();
+
+            _notifier.Publish(new GalaxyDeployEventInfo(
+                Sequence: nextSequence,
+                ObservedAt: queriedAt,
+                TimeOfLastDeploy: deployTime,
+                ObjectCount: hierarchy.Count,
+                AttributeCount: attributes.Count));
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (Exception exception) when (exception is SqlException or InvalidOperationException)
+        {
+            _logger?.LogWarning(exception, "Galaxy hierarchy cache refresh failed.");
+            GalaxyHierarchyCacheEntry failed = previous with
+            {
+                Status = previous.HasData ? GalaxyCacheStatus.Stale : GalaxyCacheStatus.Unavailable,
+                LastQueriedAt = queriedAt,
+                LastError = exception.Message,
+            };
+            Volatile.Write(ref _current, failed);
+            _firstLoad.TrySetResult();
+        }
+    }
+
+    private static DiscoverHierarchyReply BuildReply(
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes)
+    {
+        Dictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId = attributes
+            .GroupBy(a => a.GobjectId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        DiscoverHierarchyReply reply = new();
+        foreach (GalaxyHierarchyRow row in hierarchy)
+        {
+            reply.Objects.Add(GalaxyProtoMapper.MapObject(row, attributesByGobjectId));
+        }
+        return reply;
+    }
+
+    private GalaxyCacheStatus ProjectStatus(GalaxyHierarchyCacheEntry snapshot)
+    {
+        if (snapshot.Status is GalaxyCacheStatus.Unknown or GalaxyCacheStatus.Unavailable)
+        {
+            return snapshot.Status;
+        }
+
+        if (snapshot.LastSuccessAt is { } success
+            && _timeProvider.GetUtcNow() - success > StaleThreshold)
+        {
+            return GalaxyCacheStatus.Stale;
+        }
+
+        return snapshot.Status;
+    }
+}
@@ -0,0 +1,43 @@
+using MxGateway.Contracts.Proto.Galaxy;
+
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     Immutable snapshot of the Galaxy Repository browse data held by
+///     <see cref="GalaxyHierarchyCache"/>. Multiple gRPC clients share the same instance —
+///     the materialized <see cref="Reply"/> is produced once per refresh and reused.
+/// </summary>
+public sealed record GalaxyHierarchyCacheEntry(
+    GalaxyCacheStatus Status,
+    long Sequence,
+    DateTimeOffset? LastQueriedAt,
+    DateTimeOffset? LastSuccessAt,
+    DateTimeOffset? LastDeployTime,
+    string? LastError,
+    IReadOnlyList<GalaxyHierarchyRow> Hierarchy,
+    IReadOnlyList<GalaxyAttributeRow> Attributes,
+    DiscoverHierarchyReply? Reply,
+    int ObjectCount,
+    int AreaCount,
+    int AttributeCount,
+    int HistorizedAttributeCount,
+    int AlarmAttributeCount)
+{
+    public static GalaxyHierarchyCacheEntry Empty { get; } = new(
+        Status: GalaxyCacheStatus.Unknown,
+        Sequence: 0,
+        LastQueriedAt: null,
+        LastSuccessAt: null,
+        LastDeployTime: null,
+        LastError: null,
+        Hierarchy: Array.Empty<GalaxyHierarchyRow>(),
+        Attributes: Array.Empty<GalaxyAttributeRow>(),
+        Reply: null,
+        ObjectCount: 0,
+        AreaCount: 0,
+        AttributeCount: 0,
+        HistorizedAttributeCount: 0,
+        AlarmAttributeCount: 0);
+
+    public bool HasData => Status is GalaxyCacheStatus.Healthy or GalaxyCacheStatus.Stale;
+}
@@ -0,0 +1,56 @@
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     Periodically refreshes <see cref="IGalaxyHierarchyCache"/> off the request path. The
+///     interval comes from <see cref="GalaxyRepositoryOptions.DashboardRefreshIntervalSeconds"/>;
+///     each tick is cheap when the deploy timestamp is unchanged.
+/// </summary>
+public sealed class GalaxyHierarchyRefreshService(
+    IGalaxyHierarchyCache cache,
+    IOptions<GalaxyRepositoryOptions> options,
+    ILogger<GalaxyHierarchyRefreshService> logger,
+    TimeProvider? timeProvider = null) : BackgroundService
+{
+    private readonly TimeProvider _timeProvider = timeProvider ?? TimeProvider.System;
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        TimeSpan interval = TimeSpan.FromSeconds(Math.Max(1, options.Value.DashboardRefreshIntervalSeconds));
+
+        try
+        {
+            await cache.RefreshAsync(stoppingToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+            return;
+        }
+
+        using PeriodicTimer timer = new(interval, _timeProvider);
+        try
+        {
+            while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
+            {
+                try
+                {
+                    await cache.RefreshAsync(stoppingToken).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+                {
+                    return;
+                }
+                catch (Exception exception)
+                {
+                    logger.LogWarning(exception, "Galaxy hierarchy cache refresh tick failed.");
+                }
+            }
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+        }
+    }
+}
@@ -0,0 +1,35 @@
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     One row from <see cref="GalaxyRepository.GetHierarchyAsync"/>: a deployed Galaxy
+///     <c>gobject</c> with its hierarchy parent and template-derivation chain.
+/// </summary>
+public sealed class GalaxyHierarchyRow
+{
+    public int GobjectId { get; init; }
+    public string TagName { get; init; } = string.Empty;
+    public string ContainedName { get; init; } = string.Empty;
+    public string BrowseName { get; init; } = string.Empty;
+    public int ParentGobjectId { get; init; }
+    public bool IsArea { get; init; }
+    public int CategoryId { get; init; }
+    public int HostedByGobjectId { get; init; }
+    public IReadOnlyList<string> TemplateChain { get; init; } = Array.Empty<string>();
+}
+
+/// <summary>One row from <see cref="GalaxyRepository.GetAttributesAsync"/>.</summary>
+public sealed class GalaxyAttributeRow
+{
+    public int GobjectId { get; init; }
+    public string TagName { get; init; } = string.Empty;
+    public string AttributeName { get; init; } = string.Empty;
+    public string FullTagReference { get; init; } = string.Empty;
+    public int MxDataType { get; init; }
+    public string? DataTypeName { get; init; }
+    public bool IsArray { get; init; }
+    public int? ArrayDimension { get; init; }
+    public int MxAttributeCategory { get; init; }
+    public int SecurityClassification { get; init; }
+    public bool IsHistorized { get; init; }
+    public bool IsAlarm { get; init; }
+}
@@ -0,0 +1,218 @@
+using Microsoft.Data.SqlClient;
+
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     SQL access to the AVEVA System Platform Galaxy Repository (ZB) database. Ported from
+///     the OtOpcUa project so the row sets stay byte-for-byte identical between the two
+///     consumers — the same SQL drives the OPC UA server's address space and this gateway's
+///     gRPC browse surface.
+/// </summary>
+public sealed class GalaxyRepository(GalaxyRepositoryOptions options)
+{
+    public async Task<bool> TestConnectionAsync(CancellationToken ct = default)
+    {
+        try
+        {
+            using SqlConnection conn = new(options.ConnectionString);
+            await conn.OpenAsync(ct).ConfigureAwait(false);
+            using SqlCommand cmd = new("SELECT 1", conn) { CommandTimeout = options.CommandTimeoutSeconds };
+            object? result = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false);
+            return result is int i && i == 1;
+        }
+        catch (SqlException) { return false; }
+        catch (InvalidOperationException) { return false; }
+    }
+
+    public async Task<DateTime?> GetLastDeployTimeAsync(CancellationToken ct = default)
+    {
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+        using SqlCommand cmd = new("SELECT time_of_last_deploy FROM galaxy", conn)
+        { CommandTimeout = options.CommandTimeoutSeconds };
+        object? result = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false);
+        return result is DateTime dt ? dt : null;
+    }
+
+    public async Task<List<GalaxyHierarchyRow>> GetHierarchyAsync(CancellationToken ct = default)
+    {
+        List<GalaxyHierarchyRow> rows = new();
+
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+
+        using SqlCommand cmd = new(HierarchySql, conn) { CommandTimeout = options.CommandTimeoutSeconds };
+        using SqlDataReader reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            string templateChainRaw = reader.IsDBNull(8) ? string.Empty : reader.GetString(8);
+            string[] templateChain = templateChainRaw.Length == 0
+                ? Array.Empty<string>()
+                : templateChainRaw.Split(['|'], StringSplitOptions.RemoveEmptyEntries)
+                    .Select(s => s.Trim())
+                    .Where(s => s.Length > 0)
+                    .ToArray();
+
+            rows.Add(new GalaxyHierarchyRow
+            {
+                GobjectId = Convert.ToInt32(reader.GetValue(0)),
+                TagName = reader.GetString(1),
+                ContainedName = reader.IsDBNull(2) ? string.Empty : reader.GetString(2),
+                BrowseName = reader.GetString(3),
+                ParentGobjectId = Convert.ToInt32(reader.GetValue(4)),
+                IsArea = Convert.ToInt32(reader.GetValue(5)) == 1,
+                CategoryId = Convert.ToInt32(reader.GetValue(6)),
+                HostedByGobjectId = Convert.ToInt32(reader.GetValue(7)),
+                TemplateChain = templateChain,
+            });
+        }
+        return rows;
+    }
+
+    public async Task<List<GalaxyAttributeRow>> GetAttributesAsync(CancellationToken ct = default)
+    {
+        List<GalaxyAttributeRow> rows = new();
+
+        using SqlConnection conn = new(options.ConnectionString);
+        await conn.OpenAsync(ct).ConfigureAwait(false);
+
+        using SqlCommand cmd = new(AttributesSql, conn) { CommandTimeout = options.CommandTimeoutSeconds };
+        using SqlDataReader reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(ct).ConfigureAwait(false))
+        {
+            rows.Add(new GalaxyAttributeRow
+            {
+                GobjectId = Convert.ToInt32(reader.GetValue(0)),
+                TagName = reader.GetString(1),
+                AttributeName = reader.GetString(2),
+                FullTagReference = reader.GetString(3),
+                MxDataType = Convert.ToInt32(reader.GetValue(4)),
+                DataTypeName = reader.IsDBNull(5) ? null : reader.GetString(5),
+                IsArray = Convert.ToInt32(reader.GetValue(6)) == 1,
+                ArrayDimension = reader.IsDBNull(7) ? null : Convert.ToInt32(reader.GetValue(7)),
+                MxAttributeCategory = Convert.ToInt32(reader.GetValue(8)),
+                SecurityClassification = Convert.ToInt32(reader.GetValue(9)),
+                IsHistorized = Convert.ToInt32(reader.GetValue(10)) == 1,
+                IsAlarm = Convert.ToInt32(reader.GetValue(11)) == 1,
+            });
+        }
+        return rows;
+    }
+
+    private const string HierarchySql = @"
+;WITH template_chain AS (
+    SELECT g.gobject_id AS instance_gobject_id, t.gobject_id AS template_gobject_id,
+           t.tag_name AS template_tag_name, t.derived_from_gobject_id, 0 AS depth
+    FROM gobject g
+    INNER JOIN gobject t ON t.gobject_id = g.derived_from_gobject_id
+    WHERE g.is_template = 0 AND g.deployed_package_id <> 0 AND g.derived_from_gobject_id <> 0
+    UNION ALL
+    SELECT tc.instance_gobject_id, t.gobject_id, t.tag_name, t.derived_from_gobject_id, tc.depth + 1
+    FROM template_chain tc
+    INNER JOIN gobject t ON t.gobject_id = tc.derived_from_gobject_id
+    WHERE tc.derived_from_gobject_id <> 0 AND tc.depth < 10
+)
+SELECT DISTINCT
+    g.gobject_id,
+    g.tag_name,
+    g.contained_name,
+    CASE WHEN g.contained_name IS NULL OR g.contained_name = ''
+         THEN g.tag_name
+         ELSE g.contained_name
+    END AS browse_name,
+    CASE WHEN g.contained_by_gobject_id = 0
+         THEN g.area_gobject_id
+         ELSE g.contained_by_gobject_id
+    END AS parent_gobject_id,
+    CASE WHEN td.category_id = 13
+         THEN 1
+         ELSE 0
+    END AS is_area,
+    td.category_id AS category_id,
+    g.hosted_by_gobject_id AS hosted_by_gobject_id,
+    ISNULL(
+        STUFF((
+            SELECT '|' + tc.template_tag_name
+            FROM template_chain tc
+            WHERE tc.instance_gobject_id = g.gobject_id
+            ORDER BY tc.depth
+            FOR XML PATH('')
+        ), 1, 1, ''),
+        ''
+    ) AS template_chain
+FROM gobject g
+INNER JOIN template_definition td
+    ON g.template_definition_id = td.template_definition_id
+WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+    AND g.is_template = 0
+    AND g.deployed_package_id <> 0
+ORDER BY parent_gobject_id, g.tag_name";
+
+    private const string AttributesSql = @"
+;WITH deployed_package_chain AS (
+    SELECT g.gobject_id, p.package_id, p.derived_from_package_id, 0 AS depth
+    FROM gobject g
+    INNER JOIN package p ON p.package_id = g.deployed_package_id
+    WHERE g.is_template = 0 AND g.deployed_package_id <> 0
+    UNION ALL
+    SELECT dpc.gobject_id, p.package_id, p.derived_from_package_id, dpc.depth + 1
+    FROM deployed_package_chain dpc
+    INNER JOIN package p ON p.package_id = dpc.derived_from_package_id
+    WHERE dpc.derived_from_package_id <> 0 AND dpc.depth < 10
+)
+SELECT gobject_id, tag_name, attribute_name, full_tag_reference,
+    mx_data_type, data_type_name, is_array, array_dimension,
+    mx_attribute_category, security_classification, is_historized, is_alarm
+FROM (
+    SELECT
+        dpc.gobject_id,
+        g.tag_name,
+        da.attribute_name,
+        g.tag_name + '.' + da.attribute_name
+            + CASE WHEN da.is_array = 1 THEN '[]' ELSE '' END
+            AS full_tag_reference,
+        da.mx_data_type,
+        dt.description AS data_type_name,
+        da.is_array,
+        CASE WHEN da.is_array = 1
+             THEN CONVERT(int, CONVERT(varbinary(2),
+                  SUBSTRING(da.mx_value, 15, 2) + SUBSTRING(da.mx_value, 13, 2), 2))
+             ELSE NULL
+        END AS array_dimension,
+        da.mx_attribute_category,
+        da.security_classification,
+        CASE WHEN EXISTS (
+            SELECT 1 FROM deployed_package_chain dpc2
+            INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = da.attribute_name
+            INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'HistoryExtension'
+            WHERE dpc2.gobject_id = dpc.gobject_id
+        ) THEN 1 ELSE 0 END AS is_historized,
+        CASE WHEN EXISTS (
+            SELECT 1 FROM deployed_package_chain dpc2
+            INNER JOIN primitive_instance pi ON pi.package_id = dpc2.package_id AND pi.primitive_name = da.attribute_name
+            INNER JOIN primitive_definition pd ON pd.primitive_definition_id = pi.primitive_definition_id AND pd.primitive_name = 'AlarmExtension'
+            WHERE dpc2.gobject_id = dpc.gobject_id
+        ) THEN 1 ELSE 0 END AS is_alarm,
+        ROW_NUMBER() OVER (
+            PARTITION BY dpc.gobject_id, da.attribute_name
+            ORDER BY dpc.depth
+        ) AS rn
+    FROM deployed_package_chain dpc
+    INNER JOIN dynamic_attribute da
+        ON da.package_id = dpc.package_id
+    INNER JOIN gobject g
+        ON g.gobject_id = dpc.gobject_id
+    INNER JOIN template_definition td
+        ON td.template_definition_id = g.template_definition_id
+    LEFT JOIN data_type dt
+        ON dt.mx_data_type = da.mx_data_type
+    WHERE td.category_id IN (1, 3, 4, 10, 11, 13, 17, 24, 26)
+        AND da.attribute_name NOT LIKE '[_]%'
+        AND da.attribute_name NOT LIKE '%.Description'
+        AND da.mx_attribute_category IN (2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 24)
+) ranked
+WHERE rn = 1
+ORDER BY tag_name, attribute_name";
+}
@@ -0,0 +1,21 @@
+namespace MxGateway.Server.Galaxy;
+
+/// <summary>
+///     Connection settings for the AVEVA System Platform Galaxy Repository (ZB) database.
+///     Bound to the <c>MxGateway:Galaxy</c> configuration section.
+/// </summary>
+public sealed class GalaxyRepositoryOptions
+{
+    public const string SectionName = "MxGateway:Galaxy";
+
+    public string ConnectionString { get; init; } =
+        "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;";
+
+    public int CommandTimeoutSeconds { get; init; } = 60;
+
+    /// <summary>
+    ///     Interval (seconds) between background refreshes of the dashboard Galaxy summary
+    ///     cache. SQL is hit at most once per interval regardless of dashboard render rate.
+    /// </summary>
+    public int DashboardRefreshIntervalSeconds { get; init; } = 30;
+}
@@ -0,0 +1,23 @@
+using Microsoft.Extensions.Options;
+
+namespace MxGateway.Server.Galaxy;
+
+public static class GalaxyRepositoryServiceCollectionExtensions
+{
+    public static IServiceCollection AddGalaxyRepository(this IServiceCollection services)
+    {
+        services
+            .AddOptions<GalaxyRepositoryOptions>()
+            .BindConfiguration(GalaxyRepositoryOptions.SectionName)
+            .ValidateOnStart();
+
+        services.AddSingleton(sp =>
+            new GalaxyRepository(sp.GetRequiredService<IOptions<GalaxyRepositoryOptions>>().Value));
+
+        services.AddSingleton<IGalaxyDeployNotifier, GalaxyDeployNotifier>();
+        services.AddSingleton<IGalaxyHierarchyCache, GalaxyHierarchyCache>();
+        services.AddHostedService<GalaxyHierarchyRefreshService>();
+
+        return services;
+    }
+}
@@ -0,0 +1,18 @@
+namespace MxGateway.Server.Galaxy;
+
+public interface IGalaxyDeployNotifier
+{
+    /// <summary>The most recently published event, or <c>null</c> if no event has fired yet.</summary>
+    GalaxyDeployEventInfo? Latest { get; }
+
+    /// <summary>Publishes a deploy event to all current subscribers and stores it as <see cref="Latest"/>.</summary>
+    void Publish(GalaxyDeployEventInfo info);
+
+    /// <summary>
+    ///     Subscribe to deploy events. The async sequence yields events as they fire. If
+    ///     <see cref="Latest"/> is set, it is yielded first so subscribers can bootstrap their
+    ///     local cache without waiting for the next deploy. Pass a cancellation token to
+    ///     unsubscribe.
+    /// </summary>
+    IAsyncEnumerable<GalaxyDeployEventInfo> SubscribeAsync(CancellationToken cancellationToken);
+}
@@ -0,0 +1,22 @@
+namespace MxGateway.Server.Galaxy;
+
+public interface IGalaxyHierarchyCache
+{
+    /// <summary>The latest cache entry. Status freshness is recomputed against the clock.</summary>
+    GalaxyHierarchyCacheEntry Current { get; }
+
+    /// <summary>
+    ///     Forces a refresh against the Galaxy Repository. Performs a cheap
+    ///     <c>time_of_last_deploy</c> probe first and only re-queries the heavy hierarchy +
+    ///     attributes rowsets when the deploy time has changed since the last successful
+    ///     refresh.
+    /// </summary>
+    Task RefreshAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Awaits the first completed refresh attempt (success or failure). Useful for
+    ///     gRPC handlers that want to serve from cache without returning Unavailable on the
+    ///     very first request after gateway start.
+    /// </summary>
+    Task WaitForFirstLoadAsync(CancellationToken cancellationToken);
+}
@@ -3,6 +3,7 @@ using MxGateway.Contracts;
 using MxGateway.Server.Configuration;
 using MxGateway.Server.Dashboard;
 using MxGateway.Server.Diagnostics;
+using MxGateway.Server.Galaxy;
 using MxGateway.Server.Grpc;
 using MxGateway.Server.Metrics;
 using MxGateway.Server.Security.Authentication;
@@ -51,6 +52,7 @@ public static class GatewayApplication
        builder.Services.AddWorkerProcessLauncher();
        builder.Services.AddGatewaySessions();
        builder.Services.AddGatewayDashboard();
+        builder.Services.AddGalaxyRepository();

        return builder;
    }
@@ -125,6 +127,7 @@ public static class GatewayApplication
            .WithName("LiveHealth");

        endpoints.MapGrpcService<MxAccessGatewayService>();
+        endpoints.MapGrpcService<GalaxyRepositoryGrpcService>();
        endpoints.MapGatewayDashboard();

        return endpoints;
@@ -0,0 +1,69 @@
+using MxGateway.Contracts.Proto.Galaxy;
+using MxGateway.Server.Galaxy;
+
+namespace MxGateway.Server.Grpc;
+
+/// <summary>
+///     Maps <see cref="GalaxyHierarchyRow"/> + <see cref="GalaxyAttributeRow"/> rows produced
+///     by <see cref="GalaxyRepository"/> into <c>galaxy_repository.v1</c> proto messages.
+///     Pure function, separated so it can be unit-tested without a SQL connection.
+/// </summary>
+public static class GalaxyProtoMapper
+{
+    public static IEnumerable<GalaxyObject> MapHierarchy(
+        IReadOnlyList<GalaxyHierarchyRow> hierarchy,
+        IReadOnlyList<GalaxyAttributeRow> attributes)
+    {
+        Dictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId = attributes
+            .GroupBy(a => a.GobjectId)
+            .ToDictionary(g => g.Key, g => g.ToList());
+
+        foreach (GalaxyHierarchyRow row in hierarchy)
+        {
+            yield return MapObject(row, attributesByGobjectId);
+        }
+    }
+
+    public static GalaxyObject MapObject(
+        GalaxyHierarchyRow row,
+        IReadOnlyDictionary<int, List<GalaxyAttributeRow>> attributesByGobjectId)
+    {
+        GalaxyObject obj = new()
+        {
+            GobjectId = row.GobjectId,
+            TagName = row.TagName,
+            ContainedName = row.ContainedName,
+            BrowseName = row.BrowseName,
+            ParentGobjectId = row.ParentGobjectId,
+            IsArea = row.IsArea,
+            CategoryId = row.CategoryId,
+            HostedByGobjectId = row.HostedByGobjectId,
+        };
+        obj.TemplateChain.AddRange(row.TemplateChain);
+
+        if (attributesByGobjectId.TryGetValue(row.GobjectId, out List<GalaxyAttributeRow>? attrs))
+        {
+            foreach (GalaxyAttributeRow attr in attrs)
+            {
+                obj.Attributes.Add(MapAttribute(attr));
+            }
+        }
+
+        return obj;
+    }
+
+    public static GalaxyAttribute MapAttribute(GalaxyAttributeRow row) => new()
+    {
+        AttributeName = row.AttributeName,
+        FullTagReference = row.FullTagReference,
+        MxDataType = row.MxDataType,
+        DataTypeName = row.DataTypeName ?? string.Empty,
+        IsArray = row.IsArray,
+        ArrayDimension = row.ArrayDimension ?? 0,
+        ArrayDimensionPresent = row.ArrayDimension.HasValue,
+        MxAttributeCategory = row.MxAttributeCategory,
+        SecurityClassification = row.SecurityClassification,
+        IsHistorized = row.IsHistorized,
+        IsAlarm = row.IsAlarm,
+    };
+}
@@ -0,0 +1,158 @@
+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+using Microsoft.Data.SqlClient;
+using MxGateway.Contracts.Proto.Galaxy;
+using GalaxyDb = MxGateway.Server.Galaxy;
+using ProtoGalaxyRepository = MxGateway.Contracts.Proto.Galaxy.GalaxyRepository;
+
+namespace MxGateway.Server.Grpc;
+
+/// <summary>
+///     gRPC surface that exposes the Galaxy Repository to clients. <c>DiscoverHierarchy</c>
+///     and <c>GetLastDeployTime</c> serve from <see cref="GalaxyDb.IGalaxyHierarchyCache"/>
+///     so many clients share a single SQL pull. <c>WatchDeployEvents</c> streams events
+///     from <see cref="GalaxyDb.IGalaxyDeployNotifier"/>. <c>TestConnection</c> remains a
+///     direct SQL probe since callers use it as a health check.
+/// </summary>
+public sealed class GalaxyRepositoryGrpcService(
+    GalaxyDb.GalaxyRepository repository,
+    GalaxyDb.IGalaxyHierarchyCache cache,
+    GalaxyDb.IGalaxyDeployNotifier notifier,
+    ILogger<GalaxyRepositoryGrpcService> logger) : ProtoGalaxyRepository.GalaxyRepositoryBase
+{
+    private static readonly TimeSpan FirstLoadWaitBudget = TimeSpan.FromSeconds(5);
+
+    public override async Task<TestConnectionReply> TestConnection(
+        TestConnectionRequest request,
+        ServerCallContext context)
+    {
+        bool ok = await repository.TestConnectionAsync(context.CancellationToken).ConfigureAwait(false);
+        return new TestConnectionReply { Ok = ok };
+    }
+
+    public override async Task<GetLastDeployTimeReply> GetLastDeployTime(
+        GetLastDeployTimeRequest request,
+        ServerCallContext context)
+    {
+        await WaitForCacheBootstrap(context.CancellationToken).ConfigureAwait(false);
+        GalaxyDb.GalaxyHierarchyCacheEntry entry = cache.Current;
+
+        if (!entry.HasData)
+        {
+            throw new RpcException(new Status(
+                StatusCode.Unavailable,
+                ResolveUnavailableMessage(entry)));
+        }
+
+        GetLastDeployTimeReply reply = new() { Present = entry.LastDeployTime.HasValue };
+        if (entry.LastDeployTime.HasValue)
+        {
+            reply.TimeOfLastDeploy = Timestamp.FromDateTimeOffset(entry.LastDeployTime.Value);
+        }
+        return reply;
+    }
+
+    public override async Task<DiscoverHierarchyReply> DiscoverHierarchy(
+        DiscoverHierarchyRequest request,
+        ServerCallContext context)
+    {
+        await WaitForCacheBootstrap(context.CancellationToken).ConfigureAwait(false);
+        GalaxyDb.GalaxyHierarchyCacheEntry entry = cache.Current;
+
+        if (!entry.HasData || entry.Reply is null)
+        {
+            throw new RpcException(new Status(
+                StatusCode.Unavailable,
+                ResolveUnavailableMessage(entry)));
+        }
+
+        // Same materialized reply is shared across all clients — gRPC serialization is
+        // read-only and the entry is replaced atomically on the next refresh.
+        return entry.Reply;
+    }
+
+    public override async Task WatchDeployEvents(
+        WatchDeployEventsRequest request,
+        IServerStreamWriter<DeployEvent> responseStream,
+        ServerCallContext context)
+    {
+        DateTimeOffset? lastSeen = request.LastSeenDeployTime?.ToDateTimeOffset();
+
+        await foreach (GalaxyDb.GalaxyDeployEventInfo info in notifier
+            .SubscribeAsync(context.CancellationToken)
+            .ConfigureAwait(false))
+        {
+            // Suppress the initial bootstrap event when the client already knows about
+            // this deploy time. We only suppress the first one — subsequent events fire
+            // on actual changes, so they always pass.
+            if (lastSeen is { } seen && info.TimeOfLastDeploy == seen)
+            {
+                lastSeen = null;
+                continue;
+            }
+            lastSeen = null;
+
+            await responseStream.WriteAsync(MapDeployEvent(info), context.CancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    private async Task WaitForCacheBootstrap(CancellationToken cancellationToken)
+    {
+        if (cache.Current.HasData || cache.Current.Status == GalaxyDb.GalaxyCacheStatus.Unavailable)
+        {
+            return;
+        }
+
+        using CancellationTokenSource budget = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        budget.CancelAfter(FirstLoadWaitBudget);
+        try
+        {
+            await cache.WaitForFirstLoadAsync(budget.Token).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+        {
+            throw;
+        }
+        catch (OperationCanceledException)
+        {
+            // Budget elapsed; fall through and let the caller see the current
+            // (possibly Unknown/Unavailable) entry.
+        }
+    }
+
+    private static DeployEvent MapDeployEvent(GalaxyDb.GalaxyDeployEventInfo info)
+    {
+        DeployEvent ev = new()
+        {
+            Sequence = (ulong)info.Sequence,
+            ObservedAt = Timestamp.FromDateTimeOffset(info.ObservedAt),
+            ObjectCount = info.ObjectCount,
+            AttributeCount = info.AttributeCount,
+            TimeOfLastDeployPresent = info.TimeOfLastDeploy.HasValue,
+        };
+        if (info.TimeOfLastDeploy.HasValue)
+        {
+            ev.TimeOfLastDeploy = Timestamp.FromDateTimeOffset(info.TimeOfLastDeploy.Value);
+        }
+        return ev;
+    }
+
+    private static string ResolveUnavailableMessage(GalaxyDb.GalaxyHierarchyCacheEntry entry) => entry.Status switch
+    {
+        GalaxyDb.GalaxyCacheStatus.Unknown => "Galaxy cache has not completed its initial load yet.",
+        GalaxyDb.GalaxyCacheStatus.Unavailable => "Galaxy repository is unavailable.",
+        _ => "Galaxy cache has no data available.",
+    };
+
+    [System.Diagnostics.CodeAnalysis.SuppressMessage(
+        "Style",
+        "IDE0051:Remove unused private members",
+        Justification = "Kept for parity with prior SQL exception mapping; future direct-SQL paths reuse it.")]
+    private RpcException MapSqlException(SqlException exception)
+    {
+        logger.LogWarning(exception, "Galaxy repository query failed.");
+        return new RpcException(new Status(
+            StatusCode.Unavailable,
+            "Galaxy repository is unavailable."));
+    }
+}
@@ -1,6 +1,8 @@
+using System.Diagnostics;
 using Grpc.Core;
 using MxGateway.Contracts;
 using MxGateway.Contracts.Proto;
+using MxGateway.Server.Metrics;
 using MxGateway.Server.Security.Authorization;
 using MxGateway.Server.Sessions;
 using MxGateway.Server.Workers;
@@ -13,6 +15,7 @@ public sealed class MxAccessGatewayService(
    MxAccessGrpcRequestValidator requestValidator,
    MxAccessGrpcMapper mapper,
    IEventStreamService eventStreamService,
+    GatewayMetrics metrics,
    ILogger<MxAccessGatewayService> logger) : MxAccessGateway.MxAccessGatewayBase
 {
    public override async Task<OpenSessionReply> OpenSession(
@@ -110,7 +113,9 @@ public sealed class MxAccessGatewayService(
                .WithCancellation(context.CancellationToken)
                .ConfigureAwait(false))
            {
+                Stopwatch stopwatch = Stopwatch.StartNew();
                await responseStream.WriteAsync(publicEvent).ConfigureAwait(false);
+                metrics.RecordEventStreamSend(publicEvent.Family.ToString(), stopwatch.Elapsed);
            }
        }
        catch (Exception exception) when (exception is not RpcException)
@@ -219,19 +219,6 @@ public sealed class GatewayMetrics : IDisposable
        }
    }

-    public void SetGrpcEventStreamQueueDepth(int depth)
-    {
-        if (depth < 0)
-        {
-            throw new ArgumentOutOfRangeException(nameof(depth), depth, "Queue depth cannot be negative.");
-        }
-
-        lock (_syncRoot)
-        {
-            _grpcEventStreamQueueDepth = depth;
-        }
-    }
-
    public void AdjustGrpcEventStreamQueueDepth(int delta)
    {
        lock (_syncRoot)
@@ -7,6 +7,7 @@
  <ItemGroup>
    <PackageReference Include="Grpc.AspNetCore" Version="2.76.0" />
    <PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.7" />
+    <PackageReference Include="Microsoft.Data.SqlClient" Version="6.0.2" />
    <PackageReference Include="Polly.Core" Version="8.6.6" />
  </ItemGroup>

@@ -1,4 +1,5 @@
 using MxGateway.Contracts.Proto;
+using MxGateway.Contracts.Proto.Galaxy;

 namespace MxGateway.Server.Security.Authorization;

@@ -12,6 +13,10 @@ public sealed class GatewayGrpcScopeResolver
            CloseSessionRequest => GatewayScopes.SessionClose,
            StreamEventsRequest => GatewayScopes.EventsRead,
            MxCommandRequest commandRequest => ResolveCommandScope(commandRequest.Command?.Kind ?? MxCommandKind.Unspecified),
+            TestConnectionRequest or
+            GetLastDeployTimeRequest or
+            DiscoverHierarchyRequest or
+            WatchDeployEventsRequest => GatewayScopes.MetadataRead,
            _ => GatewayScopes.Admin
        };
    }
@@ -43,6 +43,11 @@
    },
    "Protocol": {
      "WorkerProtocolVersion": 1
+    },
+    "Galaxy": {
+      "ConnectionString": "Server=localhost;Database=ZB;Integrated Security=True;TrustServerCertificate=True;Encrypt=False;",
+      "CommandTimeoutSeconds": 60,
+      "DashboardRefreshIntervalSeconds": 30
    }
  }
 }