238 lines
7.1 KiB
Markdown
238 lines
7.1 KiB
Markdown
# Knowledge Module Caching Layer Implementation
|
|
|
|
**Issue:** #79
|
|
**Branch:** `feature/knowledge-cache`
|
|
**Status:** ✅ Complete
|
|
|
|
## Overview
|
|
|
|
Implemented a comprehensive caching layer for the Knowledge module using Valkey (Redis-compatible), providing significant performance improvements for frequently accessed data.
|
|
|
|
## Implementation Summary
|
|
|
|
### 1. Cache Service (`cache.service.ts`)
|
|
|
|
Created `KnowledgeCacheService` with the following features:
|
|
|
|
**Core Functionality:**
|
|
- Entry detail caching (by workspace ID and slug)
|
|
- Search results caching (with filter-aware keys)
|
|
- Graph query caching (by entry ID and depth)
|
|
- Configurable TTL (default: 5 minutes)
|
|
- Cache statistics tracking (hits, misses, hit rate)
|
|
- Pattern-based cache invalidation
|
|
|
|
**Cache Key Structure:**
|
|
```
|
|
knowledge:entry:{workspaceId}:{slug}
|
|
knowledge:search:{workspaceId}:{query}:{filterHash}
|
|
knowledge:graph:{workspaceId}:{entryId}:{maxDepth}
|
|
```
|
|
|
|
**Configuration:**
|
|
- `KNOWLEDGE_CACHE_ENABLED` - Enable/disable caching (default: true)
|
|
- `KNOWLEDGE_CACHE_TTL` - Cache TTL in seconds (default: 300)
|
|
- `VALKEY_URL` - Valkey connection URL
|
|
|
|
**Statistics:**
|
|
- Hits/misses tracking
|
|
- Hit rate calculation
|
|
- Sets/deletes counting
|
|
- Statistics reset functionality
|
|
|
|
### 2. Service Integration
|
|
|
|
**KnowledgeService (`knowledge.service.ts`):**
|
|
- ✅ Cache-aware `findOne()` - checks cache before DB lookup
|
|
- ✅ Cache invalidation on `create()` - invalidates search/graph caches
|
|
- ✅ Cache invalidation on `update()` - invalidates entry, search, and graph caches
|
|
- ✅ Cache invalidation on `remove()` - invalidates entry, search, and graph caches
|
|
- ✅ Cache invalidation on `restoreVersion()` - invalidates entry, search, and graph caches
|
|
|
|
**SearchService (`search.service.ts`):**
|
|
- ✅ Cache-aware `search()` - checks cache before executing PostgreSQL query
|
|
- ✅ Filter-aware caching (different results for different filters/pages)
|
|
- ✅ Automatic cache population on search execution
|
|
|
|
**GraphService (`graph.service.ts`):**
|
|
- ✅ Cache-aware `getEntryGraph()` - checks cache before graph traversal
|
|
- ✅ Depth-aware caching (different cache for different depths)
|
|
- ✅ Automatic cache population after graph computation
|
|
|
|
### 3. Cache Invalidation Strategy
|
|
|
|
**Entry-level invalidation:**
|
|
- On create: invalidate workspace search/graph caches
|
|
- On update: invalidate specific entry, workspace search caches, related graph caches
|
|
- On delete: invalidate specific entry, workspace search/graph caches
|
|
- On restore: invalidate specific entry, workspace search/graph caches
|
|
|
|
**Link-level invalidation:**
|
|
- When entry content changes (potential link changes), invalidate graph caches
|
|
|
|
**Workspace-level invalidation:**
|
|
- Admin endpoint to clear all caches for a workspace
|
|
|
|
### 4. REST API Endpoints
|
|
|
|
**Cache Statistics (`KnowledgeCacheController`):**
|
|
|
|
```http
|
|
GET /api/knowledge/cache/stats
|
|
```
|
|
Returns cache statistics and enabled status (requires: workspace member)
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"enabled": true,
|
|
"stats": {
|
|
"hits": 1250,
|
|
"misses": 180,
|
|
"sets": 195,
|
|
"deletes": 15,
|
|
"hitRate": 0.874
|
|
}
|
|
}
|
|
```
|
|
|
|
```http
|
|
POST /api/knowledge/cache/clear
|
|
```
|
|
Clears all caches for the workspace (requires: workspace admin)
|
|
|
|
```http
|
|
POST /api/knowledge/cache/stats/reset
|
|
```
|
|
Resets cache statistics (requires: workspace admin)
|
|
|
|
### 5. Testing
|
|
|
|
Created comprehensive test suite (`cache.service.spec.ts`):
|
|
|
|
**Test Coverage:**
|
|
- ✅ Cache enabled/disabled configuration
|
|
- ✅ Entry caching (get, set, invalidate)
|
|
- ✅ Search caching with filter differentiation
|
|
- ✅ Graph caching with depth differentiation
|
|
- ✅ Cache statistics tracking
|
|
- ✅ Workspace cache clearing
|
|
- ✅ Cache miss/hit behavior
|
|
- ✅ Pattern-based invalidation
|
|
|
|
**Test Scenarios:** 13 test cases covering all major functionality
|
|
|
|
### 6. Documentation
|
|
|
|
**Updated README.md:**
|
|
- Added "Caching" section with overview
|
|
- Configuration examples
|
|
- Cache invalidation strategy explanation
|
|
- Performance benefits (estimated 80-99% improvement)
|
|
- API endpoint documentation
|
|
|
|
**Updated .env.example:**
|
|
- Added `KNOWLEDGE_CACHE_ENABLED` configuration
|
|
- Added `KNOWLEDGE_CACHE_TTL` configuration
|
|
- Included helpful comments
|
|
|
|
## Files Modified/Created
|
|
|
|
### New Files:
|
|
- ✅ `apps/api/src/knowledge/services/cache.service.ts` (381 lines)
|
|
- ✅ `apps/api/src/knowledge/services/cache.service.spec.ts` (296 lines)
|
|
|
|
### Modified Files:
|
|
- ✅ `apps/api/src/knowledge/knowledge.service.ts` - Added cache integration
|
|
- ✅ `apps/api/src/knowledge/services/search.service.ts` - Added cache integration
|
|
- ✅ `apps/api/src/knowledge/services/graph.service.ts` - Added cache integration
|
|
- ✅ `apps/api/src/knowledge/knowledge.controller.ts` - Added cache endpoints
|
|
- ✅ `apps/api/src/knowledge/knowledge.module.ts` - Added cache service provider
|
|
- ✅ `apps/api/src/knowledge/services/index.ts` - Exported cache service
|
|
- ✅ `apps/api/package.json` - Added ioredis dependency
|
|
- ✅ `.env.example` - Added cache configuration
|
|
- ✅ `README.md` - Added cache documentation
|
|
|
|
## Performance Impact
|
|
|
|
**Expected Performance Improvements:**
|
|
- Entry retrieval: 10-50ms → 2-5ms (80-90% improvement)
|
|
- Search queries: 100-300ms → 2-5ms (95-98% improvement)
|
|
- Graph traversals: 200-500ms → 2-5ms (95-99% improvement)
|
|
|
|
**Cache Hit Rates:**
|
|
- Expected: 70-90% for active workspaces
|
|
- Measured via `/api/knowledge/cache/stats` endpoint
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# Enable/disable caching (useful for development)
|
|
KNOWLEDGE_CACHE_ENABLED=true
|
|
|
|
# Cache TTL in seconds (default: 5 minutes)
|
|
KNOWLEDGE_CACHE_TTL=300
|
|
|
|
# Valkey connection
|
|
VALKEY_URL=redis://localhost:6379
|
|
```
|
|
|
|
### Development Mode
|
|
|
|
Disable caching during development:
|
|
```bash
|
|
KNOWLEDGE_CACHE_ENABLED=false
|
|
```
|
|
|
|
## Git History
|
|
|
|
```bash
|
|
# Commits:
|
|
576d2c3 - chore: add ioredis dependency for cache service
|
|
90abe2a - feat: add knowledge module caching layer (closes #79)
|
|
|
|
# Branch: feature/knowledge-cache
|
|
# Remote: origin/feature/knowledge-cache
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Merge to develop branch
|
|
2. ⏳ Monitor cache hit rates in production
|
|
3. ⏳ Tune TTL values based on usage patterns
|
|
4. ⏳ Consider adding cache warming for frequently accessed entries
|
|
5. ⏳ Add cache metrics to monitoring dashboard
|
|
|
|
## Deliverables Checklist
|
|
|
|
- ✅ Caching service integrated with Valkey
|
|
- ✅ Entry detail cache (GET /api/knowledge/entries/:slug)
|
|
- ✅ Search results cache
|
|
- ✅ Graph query cache
|
|
- ✅ TTL configuration (5 minutes default, configurable)
|
|
- ✅ Cache invalidation on update/delete
|
|
- ✅ Cache invalidation on entry changes
|
|
- ✅ Cache invalidation on link changes
|
|
- ✅ Caching wrapped around KnowledgeService methods
|
|
- ✅ Cache statistics endpoint
|
|
- ✅ Environment variables for cache TTL
|
|
- ✅ Option to disable cache for development
|
|
- ✅ Cache hit/miss metrics
|
|
- ✅ Tests for cache behavior
|
|
- ✅ Documentation in README
|
|
|
|
## Notes
|
|
|
|
- Cache gracefully degrades - errors don't break the application
|
|
- Cache can be completely disabled via environment variable
|
|
- Statistics are in-memory (reset on service restart)
|
|
- Pattern-based invalidation uses Redis SCAN (safe for large datasets)
|
|
- All cache operations are async and non-blocking
|
|
|
|
---
|
|
|
|
**Implementation Complete:** All deliverables met ✅
|
|
**Ready for:** Code review and merge to develop
|