PLAT-02: Distributed caching strategy and cache-invalidation semantics

backend/src/Taskdeck.Api/Extensions/ApplicationServiceRegistration.cs

@@ -12,7 +12,14 @@ public static class ApplicationServiceRegistration
 {
     public static IServiceCollection AddApplicationServices(this IServiceCollection services)
     {
-        services.AddScoped<BoardService>();
+        services.AddScoped<BoardService>(sp =>
+            new BoardService(
+                sp.GetRequiredService<IUnitOfWork>(),
+                sp.GetService<IAuthorizationService>(),
+                sp.GetService<IBoardRealtimeNotifier>(),
+                sp.GetService<IHistoryService>(),
+                sp.GetService<ICacheService>(),
+                sp.GetService<CacheSettings>()));
         services.AddScoped<ColumnService>();
         services.AddScoped<CardService>();
         services.AddScoped<CardCommentService>();

backend/src/Taskdeck.Application/Interfaces/ICacheService.cs

@@ -0,0 +1,45 @@
+namespace Taskdeck.Application.Interfaces;
+
+/// <summary>
+/// Generic cache abstraction for cache-aside pattern.
+/// Implementations must degrade safely: cache failures never throw exceptions
+/// to callers and do not affect data correctness.
+/// </summary>
+public interface ICacheService
+{
+    /// <summary>
+    /// Attempts to retrieve a cached value. Returns null on miss or error.
+    /// </summary>
+    /// <typeparam name="T">The cached value type (must be JSON-serializable).</typeparam>
+    /// <param name="key">The cache key (will be prefixed automatically).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The cached value, or null if not found or on error.</returns>
+    Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default) where T : class;
+
+    /// <summary>
+    /// Stores a value in the cache with the specified TTL.
+    /// Silently swallows errors — caller is never affected by cache write failures.
+    /// </summary>
+    /// <typeparam name="T">The value type (must be JSON-serializable).</typeparam>
+    /// <param name="key">The cache key (will be prefixed automatically).</param>
+    /// <param name="value">The value to cache.</param>
+    /// <param name="ttl">Time-to-live for the cached entry.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task SetAsync<T>(string key, T value, TimeSpan ttl, CancellationToken cancellationToken = default) where T : class;
+
+    /// <summary>
+    /// Removes a cached entry. Silently swallows errors.
+    /// </summary>
+    /// <param name="key">The cache key to invalidate.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task RemoveAsync(string key, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Removes all cached entries matching the specified prefix pattern.
+    /// Used for bulk invalidation (e.g., all board list caches for a user).
+    /// Silently swallows errors.
+    /// </summary>
+    /// <param name="keyPrefix">The key prefix to match for removal.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task RemoveByPrefixAsync(string keyPrefix, CancellationToken cancellationToken = default);
+}

backend/src/Taskdeck.Application/Services/BoardService.cs

@@ -13,6 +13,8 @@ public class BoardService
     private readonly IAuthorizationService? _authorizationService;
     private readonly IBoardRealtimeNotifier _realtimeNotifier;
     private readonly IHistoryService? _historyService;
+    private readonly ICacheService? _cacheService;
+    private readonly CacheSettings? _cacheSettings;
 
     public BoardService(IUnitOfWork unitOfWork)
         : this(unitOfWork, authorizationService: null, realtimeNotifier: null, historyService: null)
@@ -23,12 +25,16 @@ public BoardService(
         IUnitOfWork unitOfWork,
         IAuthorizationService? authorizationService,
         IBoardRealtimeNotifier? realtimeNotifier = null,
-        IHistoryService? historyService = null)
+        IHistoryService? historyService = null,
+        ICacheService? cacheService = null,
+        CacheSettings? cacheSettings = null)
     {
         _unitOfWork = unitOfWork;
         _authorizationService = authorizationService;
         _realtimeNotifier = realtimeNotifier ?? NoOpBoardRealtimeNotifier.Instance;
         _historyService = historyService;
+        _cacheService = cacheService;
+        _cacheSettings = cacheSettings ?? new CacheSettings();
     }
 
     private async Task SafeLogAsync(string entityType, Guid entityId, AuditAction action, Guid? userId = null, string? changes = null)
@@ -67,6 +73,10 @@ public async Task<Result<BoardDto>> UpdateBoardAsync(Guid id, UpdateBoardDto dto
 
     public async Task<Result<BoardDetailDto>> GetBoardDetailAsync(Guid id, CancellationToken cancellationToken = default)
     {
+        // NOTE: Board detail is intentionally NOT cached because BoardDetailDto includes
+        // columns with card counts. ColumnService and CardService mutate this data without
+        // cache awareness, so caching here would serve stale column/card information.
+        // Board *list* caching is safe because BoardDto excludes columns and card counts.
         var board = await _unitOfWork.Boards.GetByIdWithDetailsAsync(id, cancellationToken);
         if (board == null)
             return Result.Failure<BoardDetailDto>(ErrorCodes.NotFound, $"Board with ID {id} not found");
@@ -88,6 +98,13 @@ public async Task<Result<BoardDetailDto>> GetBoardDetailAsync(Guid id, Guid acti
         return await GetBoardDetailAsync(id, cancellationToken);
     }
 
+    /// <summary>
+    /// Lists boards without user-scoped authorization. Not cached because this overload
+    /// has no user identity to scope the cache key, and caching an unscoped result could
+    /// serve stale data when user-specific caches are invalidated independently.
+    /// The user-scoped <see cref="ListBoardsAsync(Guid, string?, bool, CancellationToken)"/>
+    /// overload IS cached.
+    /// </summary>
     public async Task<Result<IEnumerable<BoardDto>>> ListBoardsAsync(string? searchText = null, bool includeArchived = false, CancellationToken cancellationToken = default)
     {
         var boards = await _unitOfWork.Boards.SearchAsync(searchText, includeArchived, cancellationToken);
@@ -99,12 +116,33 @@ public async Task<Result<IEnumerable<BoardDto>>> ListBoardsAsync(Guid actingUser
         if (actingUserId == Guid.Empty)
             return Result.Failure<IEnumerable<BoardDto>>(ErrorCodes.ValidationError, "Acting user ID cannot be empty");
 
+        // Only cache un-filtered, non-archived list (the most common request)
+        var canCache = _cacheService is not null && string.IsNullOrEmpty(searchText) && !includeArchived;
+
+        if (canCache)
+        {
+            var cacheKey = CacheKeys.BoardListForUser(actingUserId);
+            var cached = await _cacheService!.GetAsync<List<BoardDto>>(cacheKey, cancellationToken);
+            if (cached is not null)
+            {
+                return Result.Success<IEnumerable<BoardDto>>(cached);
+            }
+        }
+
         var candidateBoardIds = (await _unitOfWork.Boards.SearchIdsAsync(searchText, includeArchived, cancellationToken)).ToList();
 
         if (_authorizationService is null)
         {
             var boards = await _unitOfWork.Boards.GetByIdsAsync(candidateBoardIds, cancellationToken);
-            return Result.Success(boards.Select(MapToDto));
+            var dtos = boards.Select(MapToDto).ToList();
+
+            if (canCache)
+            {
+                var ttl = TimeSpan.FromSeconds(_cacheSettings!.BoardListTtlSeconds);
+                await _cacheService!.SetAsync(CacheKeys.BoardListForUser(actingUserId), dtos, ttl, cancellationToken);
+            }
+
+            return Result.Success<IEnumerable<BoardDto>>(dtos);
         }
 
         var visibleBoardIdsResult = await _authorizationService.GetReadableBoardIdsAsync(
@@ -117,8 +155,15 @@ public async Task<Result<IEnumerable<BoardDto>>> ListBoardsAsync(Guid actingUser
 
         var visibleBoardIds = visibleBoardIdsResult.Value.ToList();
         var visibleBoards = await _unitOfWork.Boards.GetByIdsAsync(visibleBoardIds, cancellationToken);
+        var result = visibleBoards.Select(MapToDto).ToList();
 
-        return Result.Success<IEnumerable<BoardDto>>(visibleBoards.Select(MapToDto));
+        if (canCache)
+        {
+            var ttl = TimeSpan.FromSeconds(_cacheSettings!.BoardListTtlSeconds);
+            await _cacheService!.SetAsync(CacheKeys.BoardListForUser(actingUserId), result, ttl, cancellationToken);
+        }
+
+        return Result.Success<IEnumerable<BoardDto>>(result);
     }
 
     public async Task<Result> DeleteBoardAsync(Guid id, CancellationToken cancellationToken = default)
@@ -152,6 +197,10 @@ await _realtimeNotifier.NotifyBoardMutationAsync(
                 cancellationToken);
             await SafeLogAsync("board", board.Id, AuditAction.Created, ownerId, $"name={board.Name}");
 
+            // Invalidate board list cache for the owner
+            if (ownerId.HasValue)
+                await InvalidateBoardListCacheAsync(ownerId.Value, cancellationToken);
+
             return Result.Success(MapToDto(board));
         }
         catch (DomainException ex)
@@ -197,6 +246,11 @@ await _realtimeNotifier.NotifyBoardMutationAsync(
                 await SafeLogAsync("board", board.Id, AuditAction.Unarchived, changes: changeSummary);
             else
                 await SafeLogAsync("board", board.Id, AuditAction.Updated, changes: changeSummary);
+
+            // Invalidate board list cache for the owner
+            if (board.OwnerId.HasValue)
+                await InvalidateBoardListCacheAsync(board.OwnerId.Value, cancellationToken);
+
             return Result.Success(MapToDto(board));
         }
         catch (DomainException ex)
@@ -238,6 +292,11 @@ await _realtimeNotifier.NotifyBoardMutationAsync(
             new BoardRealtimeEvent(board.Id, "board", "archived", board.Id, DateTimeOffset.UtcNow),
             cancellationToken);
         await SafeLogAsync("board", board.Id, AuditAction.Archived, changes: $"name={board.Name}");
+
+        // Invalidate board list cache for the owner
+        if (board.OwnerId.HasValue)
+            await InvalidateBoardListCacheAsync(board.OwnerId.Value, cancellationToken);
+
         return Result.Success();
     }
 
@@ -274,6 +333,12 @@ private static BoardDto MapToDto(Board board)
         );
     }
 
+    private async Task InvalidateBoardListCacheAsync(Guid userId, CancellationToken cancellationToken)
+    {
+        if (_cacheService is null) return;
+        await _cacheService.RemoveAsync(CacheKeys.BoardListForUser(userId), cancellationToken);
+    }
+
     private BoardDetailDto MapToDetailDto(Board board)
     {
         var columns = board.Columns

backend/src/Taskdeck.Application/Services/CacheKeys.cs

@@ -0,0 +1,19 @@
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Centralized cache key definitions for the cache-aside pattern.
+/// Keys are structured as "resource:scope:id" and prefixed by the
+/// cache service with the global key prefix (e.g., "td:").
+/// </summary>
+public static class CacheKeys
+{
+    // NOTE: BoardDetail is intentionally NOT cached. BoardDetailDto includes columns
+    // with card counts, and ColumnService/CardService mutate that data without cache
+    // awareness. Caching board detail would serve stale column/card information.
+
+    /// <summary>
+    /// Cache key for a user's board list (default, non-filtered, non-archived).
+    /// Format: boards:user:{userId}
+    /// </summary>
+    public static string BoardListForUser(Guid userId) => $"boards:user:{userId}";
+}

backend/src/Taskdeck.Application/Services/CacheSettings.cs

@@ -0,0 +1,29 @@
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Configuration for the distributed caching layer.
+/// Bound from appsettings.json "Cache" section.
+/// </summary>
+public sealed class CacheSettings
+{
+    /// <summary>
+    /// Cache provider: "Redis", "InMemory", or "None".
+    /// Defaults to "InMemory" for local-first usage.
+    /// </summary>
+    public string Provider { get; set; } = "InMemory";
+
+    /// <summary>
+    /// Redis connection string. Only used when Provider is "Redis".
+    /// </summary>
+    public string? RedisConnectionString { get; set; }
+
+    /// <summary>
+    /// Global key prefix to avoid collisions in shared Redis instances.
+    /// </summary>
+    public string KeyPrefix { get; set; } = "td";
+
+    /// <summary>
+    /// Default TTL in seconds for board list cache entries.
+    /// </summary>
+    public int BoardListTtlSeconds { get; set; } = 60;
+}

backend/src/Taskdeck.Infrastructure/DependencyInjection.cs

@@ -1,10 +1,12 @@
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
 using Taskdeck.Application.Interfaces;
 using Taskdeck.Application.Services;
 using Taskdeck.Infrastructure.Persistence;
 using Taskdeck.Infrastructure.Repositories;
+using Taskdeck.Infrastructure.Services;
 
 namespace Taskdeck.Infrastructure;
 
@@ -49,6 +51,62 @@ public static IServiceCollection AddInfrastructure(this IServiceCollection servi
         services.AddScoped<IKnowledgeSearchService, Taskdeck.Infrastructure.Services.KnowledgeFtsSearchService>();
         services.AddScoped<IUnitOfWork, UnitOfWork>();
 
+        // Cache service registration
+        services.AddCacheService(configuration);
+
         return services;
     }
+
+    private static void AddCacheService(this IServiceCollection services, IConfiguration configuration)
+    {
+        var cacheSettings = configuration.GetSection("Cache").Get<CacheSettings>() ?? new CacheSettings();
+
+        switch (cacheSettings.Provider.ToLowerInvariant())
+        {
+            case "redis":
+                if (string.IsNullOrWhiteSpace(cacheSettings.RedisConnectionString))
+                {
+                    // Fallback to in-memory if Redis is configured but no connection string
+                    services.AddSingleton<ICacheService>(sp =>
+                        new InMemoryCacheService(
+                            sp.GetRequiredService<ILogger<InMemoryCacheService>>(),
+                            cacheSettings.KeyPrefix));
+                }
+                else
+                {
+                    services.AddSingleton<ICacheService>(sp =>
+                        new RedisCacheService(
+                            cacheSettings.RedisConnectionString,
+                            sp.GetRequiredService<ILogger<RedisCacheService>>(),
+                            cacheSettings.KeyPrefix));
+                }
+                break;
+
+            case "none":
+                services.AddSingleton<ICacheService>(NoOpCacheService.Instance);
+                break;
+
+            case "inmemory":
+                services.AddSingleton<ICacheService>(sp =>
+                    new InMemoryCacheService(
+                        sp.GetRequiredService<ILogger<InMemoryCacheService>>(),
+                        cacheSettings.KeyPrefix));
+                break;
+
+            default:
+                // Log a warning so operators notice configuration typos (e.g., "Rediss" or "inmem")
+                // instead of silently falling back to InMemory.
+                services.AddSingleton<ICacheService>(sp =>
+                {
+                    var logger = sp.GetRequiredService<ILogger<InMemoryCacheService>>();
+                    logger.LogWarning(
+                        "Unknown cache provider '{Provider}', falling back to InMemory. Valid values: Redis, InMemory, None",
+                        cacheSettings.Provider);
+                    return new InMemoryCacheService(logger, cacheSettings.KeyPrefix);
+                });
+                break;
+        }
+
+        services.AddSingleton(cacheSettings);
+    }
 }