Initial commit: BOM Local Service

Models/CacheUpdateStatus.cs

@@ -0,0 +1,56 @@
+namespace BomLocalService.Models;
+
+/// <summary>
+/// Status information about a cache update operation for a location.
+/// Returned when manually triggering a cache refresh via the refresh endpoint.
+/// </summary>
+public class CacheUpdateStatus
+{
+    /// <summary>
+    /// Indicates whether a background cache update was triggered.
+    /// True if the cache was missing or stale and an update was initiated.
+    /// False if the cache is valid and no update was needed.
+    /// </summary>
+    public bool UpdateTriggered { get; set; }
+
+    /// <summary>
+    /// Indicates whether cached screenshot files exist for this location.
+    /// True if PNG screenshot files are found in the cache directory.
+    /// False if no cached files exist for this location.
+    /// </summary>
+    public bool CacheExists { get; set; }
+
+    /// <summary>
+    /// Indicates whether the existing cache is still valid (not expired).
+    /// Cache is considered valid if the observation time plus expiration buffer (typically 15.5 minutes)
+    /// is still in the future. BOM updates observations every 15 minutes, so cache expiration
+    /// includes a small buffer to account for timing variations.
+    /// True if cache exists and is still valid, false if cache is missing or expired.
+    /// </summary>
+    public bool CacheIsValid { get; set; }
+
+    /// <summary>
+    /// The UTC timestamp when the current cache will expire and should be refreshed.
+    /// Calculated as: ObservationTime + CacheExpirationMinutes (typically observation time + 15.5 minutes).
+    /// Null if no cache exists or metadata is not available.
+    /// </summary>
+    public DateTime? CacheExpiresAt { get; set; }
+
+    /// <summary>
+    /// The UTC timestamp when the next cache update should occur.
+    /// If cache is valid: equals CacheExpiresAt (when current cache expires).
+    /// If cache is invalid/missing: equals current time + CacheExpirationMinutes (when background update will complete).
+    /// Null if cache is valid and CacheExpiresAt is null.
+    /// </summary>
+    public DateTime? NextUpdateTime { get; set; }
+
+    /// <summary>
+    /// Human-readable message describing the cache status and action taken.
+    /// Possible values:
+    /// - "Cache is valid, no update needed" - Cache exists and is still fresh
+    /// - "Cache is stale, update triggered" - Cache exists but expired, update initiated
+    /// - "No cache exists, update triggered" - No cache found, update initiated
+    /// </summary>
+    public string? Message { get; set; }
+}
+

Models/LastUpdatedInfo.cs

@@ -0,0 +1,39 @@
+namespace BomLocalService.Models;
+
+/// <summary>
+/// Metadata extracted from the BOM weather map page about observation and forecast times.
+/// This information is scraped from the weather metadata section on the BOM website.
+/// </summary>
+public class LastUpdatedInfo
+{
+    /// <summary>
+    /// The UTC timestamp when the weather observations were taken.
+    /// Extracted from the BOM website metadata section (e.g., "Observations: 11 minutes ago, 8:20 pm AEST").
+    /// BOM updates observations every 15 minutes (at :00, :15, :30, :45 past the hour).
+    /// </summary>
+    public DateTime ObservationTime { get; set; }
+
+    /// <summary>
+    /// The UTC timestamp when the weather forecast was generated.
+    /// Extracted from the BOM website metadata section (e.g., "Forecast: 41 minutes ago, 7:50 pm AEST").
+    /// Forecasts are typically updated less frequently than observations.
+    /// </summary>
+    public DateTime ForecastTime { get; set; }
+
+    /// <summary>
+    /// The name of the weather station providing the observations for this location.
+    /// Extracted from text like "at Gympie weather station" in the metadata section.
+    /// May be null if the station name cannot be parsed from the page.
+    /// Example: "Gympie", "Brisbane", "Sydney"
+    /// </summary>
+    public string? WeatherStation { get; set; }
+
+    /// <summary>
+    /// The distance from the requested location to the weather station.
+    /// Extracted from text like "30 km from Pomona, QLD" in the metadata section.
+    /// Format: "{number} km" (e.g., "30 km", "15 km").
+    /// May be null if the distance cannot be parsed from the page.
+    /// </summary>
+    public string? Distance { get; set; }
+}
+

Models/RadarScreenshotResponse.cs

@@ -0,0 +1,55 @@
+namespace BomLocalService.Models;
+
+/// <summary>
+/// Response model containing the radar screenshot image path and associated metadata.
+/// This is the primary response returned when requesting a radar screenshot for a location.
+/// </summary>
+public class RadarScreenshotResponse
+{
+    /// <summary>
+    /// The full file system path to the cached PNG screenshot image file.
+    /// This is the path on the server where the screenshot is stored.
+    /// Format: "{CacheDirectory}/{Suburb}_{State}_{Timestamp}.png"
+    /// Example: "/app/cache/Pomona_QLD_20251207_000906.png"
+    /// </summary>
+    public string ImagePath { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The UTC timestamp when the screenshot file was last written/modified on disk.
+    /// This is the file system modification time, which typically matches when the screenshot was captured.
+    /// Used as a fallback if metadata is not available.
+    /// </summary>
+    public DateTime LastUpdated { get; set; }
+
+    /// <summary>
+    /// The UTC timestamp when the weather observations were taken (from BOM website).
+    /// This comes from the LastUpdatedInfo metadata extracted from the BOM weather map page.
+    /// BOM updates observations every 15 minutes (at :00, :15, :30, :45 past the hour).
+    /// If metadata is not available, defaults to DateTime.UtcNow.
+    /// </summary>
+    public DateTime ObservationTime { get; set; }
+
+    /// <summary>
+    /// The UTC timestamp when the weather forecast was generated (from BOM website).
+    /// This comes from the LastUpdatedInfo metadata extracted from the BOM weather map page.
+    /// Forecasts are typically updated less frequently than observations.
+    /// If metadata is not available, defaults to DateTime.UtcNow.
+    /// </summary>
+    public DateTime ForecastTime { get; set; }
+
+    /// <summary>
+    /// The name of the weather station providing the observations for this location.
+    /// Extracted from the BOM website metadata (e.g., "Gympie", "Brisbane").
+    /// May be null if the station name cannot be parsed or if metadata is not available.
+    /// </summary>
+    public string? WeatherStation { get; set; }
+
+    /// <summary>
+    /// The distance from the requested location to the weather station.
+    /// Extracted from the BOM website metadata (e.g., "30 km", "15 km").
+    /// Format: "{number} km".
+    /// May be null if the distance cannot be parsed or if metadata is not available.
+    /// </summary>
+    public string? Distance { get; set; }
+}
+