mirror of
https://github.com/Dvorinka/Trackeep.git
synced 2026-06-03 20:12:58 +00:00
Tomas Dvorak
083373a24f
- Add Redis architecture implementation - Update browser extension functionality - Clean up deprecated files and documentation - Enhance backend handlers for auth, messages, search - Add new configuration options and settings - Update Docker and deployment configurations
44 KiB
44 KiB
Redis Architecture Diagram for Trackeep
System Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Web App │ │ Browser Ext │ │ Mobile │ │ API Keys │ │
│ │ (React) │ │ │ │ (Future) │ │ │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼─────────────────┼────────────┘
│ │ │ │
└─────────────────┴─────────────────┴─────────────────┘
│
HTTP/WebSocket
│
┌───────────────────────────────────┼─────────────────────────────────────────┐
│ LOAD BALANCER / REVERSE PROXY │
│ (Nginx / Traefik - Future) │
└───────────────────────────────────┼─────────────────────────────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
┌─────────▼─────────┐ ┌──────────▼──────────┐ ┌─────────▼─────────┐
│ Trackeep Backend │ │ Trackeep Backend │ │ Trackeep Backend │
│ Instance 1 │◄──►│ Instance 2 │◄─►│ Instance N │
│ (Go/Gin) │ │ (Go/Gin) │ │ (Go/Gin) │
└─────────┬─────────┘ └──────────┬──────────┘ └─────────┬─────────┘
│ │ │
└─────────────────────────┼─────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
┌─────────▼──────────┐ ┌─────────────▼──────────────┐
│ REDIS │ │ PostgreSQL │
│ (Cache Layer) │ │ (Primary Database) │
│ │ │ │
│ ┌───────────────┐ │ │ ┌──────────────────────┐ │
│ │ Sessions │ │ │ │ users │ │
│ │ (Hash) │ │ │ │ bookmarks │ │
│ ├───────────────┤ │ │ │ tasks │ │
│ │ Cache │ │ │ │ notes │ │
│ │ (String) │ │ │ │ files │ │
│ ├───────────────┤ │ │ │ messages │ │
│ │ Rate Limiting │ │ │ │ analytics │ │
│ │ (Sorted Set) │ │ │ │ marketplace │ │
│ ├───────────────┤ │ │ │ ... │ │
│ │ Leaderboards │ │ │ └──────────────────────┘ │
│ │ (Sorted Set) │ │ └────────────────────────────┘
│ ├───────────────┤ │
│ │ Pub/Sub │ │ ┌──────────────────────────────┐
│ │ Channels │◄─┼──────┤ YouTube Scraper Service │
│ └───────────────┘ │ │ (Python) │
└────────────────────┘ └──────────────────────────────┘
Data Flow Patterns
1. Session Management Flow
┌──────────┐ Login Request ┌──────────────┐
│ Client │ ─────────────────────► │ Backend │
└──────────┘ └──────┬───────┘
│
│ Create Session
▼
┌──────────────┐
│ Redis │
│ tk:session │
│ :{sessionID}│
└──────┬───────┘
│
│ Store Session Data
│ (TTL: 24h)
▼
┌──────────┐ Session Cookie ┌──────────────┐
│ Client │ ◄───────────────────── │ Backend │
└────┬─────┘ └──────────────┘
│
│ Subsequent Requests
│ with Session Cookie
▼
┌──────────┐ Validate Session ┌──────────────┐
│ Client │ ─────────────────────► │ Backend │
└──────────┘ └──────┬───────┘
│
│ Lookup Session
▼
┌──────────────┐
│ Redis │
│ (O(1) get) │
└──────┬───────┘
│
│ Session Valid
▼
┌──────────────┐
│ Response │
└──────────────┘
2. Caching Flow (Search Results)
┌──────────┐ Search Request ┌──────────────┐
│ Client │ ────────────────────► │ Backend │
└──────────┘ └──────┬───────┘
│
│ Check Cache
▼
┌──────────────┐
│ Redis │
│ tk:search │
│ :{hash} │
└──────┬───────┘
│
┌───────────┴───────────┐
│ │
Cache Hit Cache Miss
│ │
▼ ▼
┌────────────┐ ┌────────────────┐
│ Return │ │ Query │
│ Cached │ │ PostgreSQL │
│ Results │ │ (Multiple │
│ (Fast) │ │ Tables) │
└────────────┘ └───────┬────────┘
│
│ Results
▼
┌──────────────┐
│ Cache │
│ Results │
│ (TTL: 5min) │
└──────┬───────┘
│
▼
┌──────────────┐
│ Return │
│ Results │
└──────────────┘
3. Rate Limiting Flow
┌──────────┐ API Request ┌──────────────┐
│ Client │ ─────────────────────► │ Backend │
│ (IP: x) │ └──────┬───────┘
└──────────┘ │
│ Check Rate Limit
▼
┌──────────────┐
│ Redis │
│ tk:rl:{IP} │
│ (Sorted Set)│
└──────┬───────┘
│
┌────────────┴────────────┐
│ │
Within Limit Limit Exceeded
│ │
▼ ▼
┌────────────┐ ┌──────────────┐
│ Update │ │ Return 429 │
│ Counter │ │ Too Many │
│ (ZADD) │ │ Requests │
└─────┬──────┘ └──────────────┘
│
▼
┌────────────┐
│ Process │
│ Request │
└────────────┘
Time Window Visualization (Sliding Window):
T-60s T-30s NOW
│ │ │
▼ ▼ ▼
[req1] [req2] [req3] <-- Current window
│ │ │
Expired │ │
Valid requests counted
4. Real-Time Pub/Sub Flow (Multi-Instance)
┌─────────────────────────────────────────────────────────────────┐
│ WEBSOCKET CONNECTIONS │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Client 1 │ │ Client 2 │ │ Client 3 │ │ Client 4 │ │
│ │(User A) │ │(User B) │ │(User A) │ │(User C) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ │ ┌────────┴────────┐ │ │ │
│ └─────►│ Backend 1 │◄─────┘ │ │
│ │ (Go/Gin) │ │ │
│ │ │ │ │
│ │ In-Memory Hub │ │ │
│ │ (Local Users) │ │ │
│ └────────┬────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ │ │
│ └───────►│ Redis │◄───────┘ │
│ │ Pub/Sub │ │
│ ┌────────┤ Channel ├────────┐ │
│ │ └──────────────┘ │ │
│ │ │ │ │
│ ┌────────┴────────┐ │ ┌────────┴────────┐│
│ │ Backend 2 │◄─────┘ │ Backend 3 ││
│ │ (Go/Gin) │ │ (Go/Gin) ││
│ │ │ │ ││
│ │ In-Memory Hub │ │ In-Memory Hub ││
│ │ (Local Users) │ │ (Local Users) ││
│ └────────┬────────┘ └────────┬────────┘│
│ │ │ │
│ ┌────────┴────────┐ ┌────────┴────────┐│
│ │ Client 5 │ │ Client 6 ││
│ │ (User B) │ │ (User A) ││
│ └─────────────────┘ └─────────────────┘│
└─────────────────────────────────────────────────────────────────┘
Message Flow:
1. Client 1 (Backend 1) sends message
2. Backend 1 stores in PostgreSQL
3. Backend 1 publishes to Redis channel
4. All backends receive message via subscription
5. Each backend forwards to connected local clients
6. All participants receive real-time update
5. Leaderboard Update Flow
┌──────────┐ Challenge Action ┌──────────────┐
│ Client │ ────────────────────► │ Backend │
└──────────┘ └──────┬───────┘
│
│ Record Score
▼
┌──────────────┐
│ Redis │
│ tk:challenge│
│ :{id}:lb │
│ (ZADD score)│
└──────┬───────┘
│
│ Update Rank
▼
┌──────────┐ Get Leaderboard ┌──────────────┐
│ Client │ ────────────────────► │ Backend │
└──────────┘ └──────┬───────┘
│
│ ZREVRANGE
▼
┌──────────────┐
│ Redis │
│ Top N Ranks │
│ (O(log N)) │
└──────┬───────┘
│
▼
┌──────────────┐
│ Leaderboard │
│ Response │
└──────────────┘
Data Structure:
┌─────────────────────────────────────────────────────┐
│ Redis Sorted Set: tk:challenge:123:leaderboard │
├─────────────────────────────────────────────────────┤
│ Member (UserID) │ Score │ Rank │
├─────────────────────┼────────────┼────────────────┤
│ 42 │ 1500 │ 1 │
│ 17 │ 1200 │ 2 │
│ 89 │ 980 │ 3 │
│ 23 │ 750 │ 4 │
│ ... │ ... │ ... │
└─────────────────────┴────────────┴────────────────┘
Component Interactions
Backend Integration Points
┌─────────────────────────────────────────────────────────────────────┐
│ TRACKEEP BACKEND (Go/Gin) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Session │ │ Cache │ │ Rate │ │
│ │ Store │ │ Middleware │ │ Limiter │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────────────┼─────────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Redis Client │ │
│ │ (go-redis) │ │
│ └───────┬────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │
│ │ String │ │ Hash │ │ Sorted Set │ │
│ │ (Cache) │ │ (Session) │ │ (Ranking) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Pub/Sub │ │ Set │ │
│ │ (Real-time) │ │ (Tracking) │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Fallback Strategy:
┌─────────────────────────────────────────────────────────────────────┐
│ if Redis unavailable: │
│ ├─► Sessions → Fallback to in-memory map │
│ ├─► Cache → Skip cache, query DB directly │
│ ├─► Rate Limit→ Skip rate limiting (log warning) │
│ └─► Pub/Sub → Local-only WebSocket (limited functionality) │
└─────────────────────────────────────────────────────────────────────┘
Deployment Scenarios
Scenario 1: Single Node (Development)
┌─────────────────────────────────────────────────────┐
│ Docker Host │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Frontend │ │ Backend │ │
│ │ (Nginx) │ │ (Go/Gin) │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ │ │ │
│ │ ┌────────┴────────┐ │
│ │ │ Redis │ │
│ │ │ (Single Node) │ │
│ │ └────────┬────────┘ │
│ │ │ │
│ │ ┌────────┴────────┐ │
│ └───────►│ PostgreSQL │ │
│ │ (Single Node) │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
Scenario 2: High Availability (Production)
┌─────────────────────────────────────────────────────────────────────────────┐
│ Docker Swarm / Kubernetes │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Load Balancer │ │
│ └───────────────────────────────┬─────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────┼────────────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌────────▼────────┐ ┌───────▼───────┐ │
│ │ Backend 1 │◄──────►│ Backend 2 │◄────►│ Backend 3 │ │
│ └──────┬──────┘ └────────┬────────┘ └───────┬───────┘ │
│ │ │ │ │
│ └────────────────────────┼────────────────────────┘ │
│ │ │
│ ┌─────────────▼─────────────┐ │
│ │ Redis Sentinel │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │
│ │ │ M1 │◄►│ R1 │◄►│ R2 │ │ │
│ │ └──┬──┘ └──┬──┘ └──┬──┘ │ │
│ │ └───────┴───────┘ │ │
│ │ S1 S2 S3 │ │
│ └───────────────────────────┘ │
│ │ │
│ ┌─────────────▼─────────────┐ │
│ │ PostgreSQL Cluster │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │
│ │ │ P1 │◄►│ S1 │◄►│ S2 │ │ │
│ │ └─────┘ └─────┘ └─────┘ │ │
│ └───────────────────────────┘ │
│ │
│ Legend: M=Master, R=Replica, S=Sentinel, P=Primary │
└─────────────────────────────────────────────────────────────────────────────┘
Memory Allocation Strategy
Redis Memory Budget (256MB Example):
┌────────────────────────────────────────────────────────────────┐
│ Total: 256MB │
├────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Sessions (30%) 77 MB │ │
│ │ ├── Active user sessions (TTL: 24h) │ │
│ │ └── User session index sets │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Cache (50%) 128 MB │ │
│ │ ├── Search results (TTL: 5m) │ │
│ │ ├── Analytics dashboards (TTL: 15m) │ │
│ │ ├── API responses (TTL: varies) │ │
│ │ └── AI recommendations (TTL: 1h) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Rate Limiting (10%) 26 MB │ │
│ │ ├── Per-IP tracking windows │ │
│ │ └── Token bucket state │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Real-time / Other (10%) 25 MB │ │
│ │ ├── Leaderboards │ │
│ │ ├── Pub/Sub buffers │ │
│ │ └── Miscellaneous │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
Eviction Policy: allkeys-lru
- Least Recently Used keys evicted first when memory limit reached
- Sessions have longer TTL to prevent premature eviction
- Cache entries have shorter TTL for frequent refresh
Key Naming Convention
Hierarchical Key Structure:
┌────────────────────────────────────────────────────────────────────┐
│ Format: tk:{resource}:{id}:{attribute}:{context} │
├────────────────────────────────────────────────────────────────────┤
│ │
│ SESSIONS │
│ ├── tk:session:{session_id} → SessionData (JSON) │
│ └── tk:user:sessions:{user_id} → Set of session IDs │
│ │
│ CACHE │
│ ├── tk:cache:search:{user_id}:{hash} → SearchResponse │
│ ├── tk:cache:analytics:{user_id}:{type} → AnalyticsData │
│ ├── tk:cache:user:{id}:profile → UserProfile │
│ └── tk:cache:marketplace:trending → TrendingItems │
│ │
│ RATE LIMITING │
│ ├── tk:rl:{ip}:general → SortedSet (timestamps)│
│ ├── tk:rl:{ip}:search → SortedSet │
│ ├── tk:rl:{ip}:ai → Token bucket state │
│ └── tk:rl:{ip}:upload → Token bucket state │
│ │
│ LEADERBOARDS │
│ ├── tk:challenge:{id}:leaderboard → SortedSet (scores) │
│ └── tk:marketplace:trending:{period} → SortedSet (views) │
│ │
│ REAL-TIME │
│ ├── tk:messages:{conversation_id} → Pub/Sub channel │
│ ├── tk:notifications:{user_id} → Pub/Sub channel │
│ └── tk:events:system → Pub/Sub channel │
│ │
│ COUNTERS │
│ ├── tk:counter:views:{content_type}:{id} → Integer │
│ └── tk:counter:downloads:{item_id} → Integer │
│ │
└────────────────────────────────────────────────────────────────────┘
Hash Function for Long Keys:
- MD5 or SHA1 for query parameters
- First 8-12 chars of hash usually sufficient
- Example: tk:cache:search:1234:a7f3d2c9b1e8
Performance Characteristics
Operation Complexities:
┌────────────────────┬─────────────┬─────────────┬─────────────────────┐
│ Operation │ Time (Big O)│ Memory │ Use Case │
├────────────────────┼─────────────┼─────────────┼─────────────────────┤
│ GET │ O(1) │ O(1) │ Session retrieval │
│ SET │ O(1) │ O(1) │ Cache storage │
│ DEL │ O(1) │ O(1) │ Cache invalidation │
│ EXPIRE │ O(1) │ O(1) │ TTL management │
├────────────────────┼─────────────┼─────────────┼─────────────────────┤
│ HGET │ O(1) │ O(1) │ Session field get │
│ HSET │ O(1) │ O(1) │ Session field set │
│ HGETALL │ O(N) │ O(N) │ Full session read │
├────────────────────┼─────────────┼─────────────┼─────────────────────┤
│ ZADD │ O(log N) │ O(1) │ Add score │
│ ZREVRANGE │ O(log N + M)│ O(M) │ Get top N ranks │
│ ZRANK │ O(log N) │ O(1) │ Get user rank │
│ ZSCORE │ O(1) │ O(1) │ Get user score │
├────────────────────┼─────────────┼─────────────┼─────────────────────┤
│ PUBLISH │ O(N+M) │ O(1) │ Send message │
│ SUBSCRIBE │ O(1) │ O(1) │ Listen channel │
├────────────────────┼─────────────┼─────────────┼─────────────────────┤
│ KEYS * │ O(N) │ O(N) │ DEBUG ONLY │
│ SCAN │ O(1) │ O(1) │ Iteration │
└────────────────────┴─────────────┴─────────────┴─────────────────────┘
N = Number of elements
M = Number of returned elements
Performance Targets:
┌────────────────────┬──────────────┬────────────────┐
│ Metric │ Target │ Measurement │
├────────────────────┼──────────────┼────────────────┤
│ Cache hit latency │ < 1ms │ p99 │
│ Cache miss latency │ < 5ms │ p99 │
│ Session read │ < 2ms │ p99 │
│ Session write │ < 3ms │ p99 │
│ Rate limit check │ < 1ms │ p99 │
│ Pub/Sub latency │ < 5ms │ p99 │
│ Leaderboard query │ < 10ms │ p99 (top 100) │
└────────────────────┴──────────────┴────────────────┘
Monitoring Points
Key Metrics to Track:
┌──────────────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE │
│ ├── Memory Usage % Alert: > 80% │
│ ├── Connected Clients Alert: > 80% of max │
│ ├── Blocked Clients Alert: > 0 (indicates slow ops) │
│ └── Uptime Alert: < 99.9% │
│ │
│ PERFORMANCE │
│ ├── Commands/sec Track: Trending │
│ ├── Hit Rate % Alert: < 80% │
│ ├── Miss Rate % Track: Trending │
│ ├── Evicted Keys/sec Alert: > 100/min │
│ └── Expired Keys/sec Track: Trending │
│ │
│ ERRORS │
│ ├── Rejected Connections Alert: > 0 │
│ ├── Keyspace Misses Track: vs Hits │
│ ├── Slow Queries (>10ms) Alert: > 10/min │
│ └── Replication Lag Alert: > 1s │
│ │
│ APPLICATION │
│ ├── Session Store Latency Alert: > 5ms p99 │
│ ├── Cache Hit Ratio Alert: < 75% │
│ ├── Rate Limit Accuracy Track: vs Expected │
│ └── Pub/Sub Delivery Time Alert: > 10ms p99 │
└──────────────────────────────────────────────────────────────────┘