goodgo-platform/docs/explorations/README_ANALYTICS_DOCS.md

Analytics Module Documentation Index

This directory contains comprehensive documentation about the GoodGo Platform Analytics Module. Start here to understand the architecture and implementation patterns.

---

📚 Documentation Files

1. 🎯 EXPLORATION_SUMMARY.md - START HERE

Purpose: High-level overview and quick findings Length: ~12 KB | Read Time: 10 minutes Contains:

• Key findings summary
• Quick statistics (2 controllers, 14+ queries, 3 commands)
• File path quick map
• Implementation templates for new handlers
• Next steps for implementation

👉 Best for: Getting oriented quickly, understanding what was discovered

---

2. 📖 ANALYTICS_ARCHITECTURE.md - COMPREHENSIVE REFERENCE

Purpose: Deep-dive technical documentation Length: ~25 KB | Read Time: 30-40 minutes Contains (10 detailed sections):

1. Module structure (DDD layers)
2. Controller & endpoint structure
3. Query/Handler pattern (CQRS implementation)
4. Redis caching patterns (cache-aside, Lua scripts)
5. Prisma schema for all models
6. Shared guards & decorators
7. DTO patterns
8. Dependency injection & module setup
9. Key patterns & conventions
10. Quick reference paths

👉 Best for: Deep understanding, implementation reference, code review

---

3. ⚡ ANALYTICS_QUICK_REFERENCE.md - DEVELOPER CHEAT SHEET

Purpose: Quick lookup guide for developers Length: ~11 KB | Read Time: 5-10 minutes (reference) Contains:

• Architecture stack overview
• All file paths organized by layer
• Guard & decorator stack explanation
• Cache patterns (TTLs, prefixes, code examples)
• Prisma models summary
• Complete handler pattern code example
• Common endpoints list
• Error handling pattern
• Conventions table

👉 Best for: Developers implementing features, quick syntax lookup, copy-paste templates

---

4. 🔄 ANALYTICS_ARCHITECTURE_DIAGRAM.txt - VISUAL OVERVIEW

Purpose: Visual representation of system architecture Length: ~19 KB | Read Time: 15 minutes Contains:

• Complete system architecture ASCII diagram
• All layers: HTTP → Database
• Data flow walkthrough for example request
• Component relationships
• External service integrations
• Shared utilities & exports

👉 Best for: Understanding system flow, presentations, documentation

---

🎓 Suggested Reading Order

For New Team Members

1. EXPLORATION_SUMMARY.md (overview)
2. ANALYTICS_ARCHITECTURE_DIAGRAM.txt (visual)
3. ANALYTICS_QUICK_REFERENCE.md (reference)

For Implementation

1. ANALYTICS_QUICK_REFERENCE.md (templates)
2. ANALYTICS_ARCHITECTURE.md (section 3-8 for patterns)
3. Look at existing handlers: apps/api/src/modules/analytics/application/queries/

For Code Review

1. ANALYTICS_ARCHITECTURE.md (full reference)
2. ANALYTICS_QUICK_REFERENCE.md (conventions table)
3. Check against existing patterns

For Architecture Understanding

1. ANALYTICS_ARCHITECTURE_DIAGRAM.txt
2. ANALYTICS_ARCHITECTURE.md (sections 1-3, 8)
3. Look at: analytics.module.ts, analytics.controller.ts

---

🔍 Quick Lookup Guide

"How do I create a new query handler?"

→ ANALYTICS_QUICK_REFERENCE.md → "CQRS Handler Pattern" section → ANALYTICS_ARCHITECTURE.md → Section 3

"What cache TTLs should I use?"

→ ANALYTICS_QUICK_REFERENCE.md → "Cache Patterns" section → ANALYTICS_ARCHITECTURE.md → Section 4 (Cache Configuration)

"How does rate limiting work?"

→ ANALYTICS_QUICK_REFERENCE.md → "Guards & Decorators Stack" → ANALYTICS_ARCHITECTURE.md → Section 4 (Rate Limiting with Redis)

"What are the Prisma models for analytics?"

→ ANALYTICS_QUICK_REFERENCE.md → "Prisma Models" section → ANALYTICS_ARCHITECTURE.md → Section 5

"How should I handle errors?"

→ ANALYTICS_QUICK_REFERENCE.md → "Error Handling Pattern" → ANALYTICS_ARCHITECTURE.md → Section 6

"What endpoints exist?"

→ ANALYTICS_QUICK_REFERENCE.md → "Common Endpoints" section → ANALYTICS_ARCHITECTURE.md → Section 2

"How do I understand the full data flow?"

→ ANALYTICS_ARCHITECTURE_DIAGRAM.txt → "Data Flow Example" section

---

📊 Key Takeaways

Architecture Pattern

DDD + CQRS with clear layer separation:

• Presentation (controllers, DTOs)
• Application (query/command handlers)
• Domain (interfaces, entities)
• Infrastructure (Prisma, external services)

Caching Strategy

Cache-aside pattern with Redis:

• cache.getOrSet(key, loader, TTL, metric)
• Graceful degradation if Redis unavailable
• Prometheus metrics for cache hit/miss/degradation

Rate Limiting

Sliding-window with Redis sorted sets:

• Per-endpoint configuration
• Key by user ID or IP
• 429 response with Retry-After header

CQRS Pattern

Separation of commands and queries:

• Queries: read operations, cached with getOrSet()
• Commands: write operations, tracked
• Event handlers: listen to domain events

Repository Pattern

Dependency inversion:

• Domain: interface definition (Symbol)
• Infrastructure: Prisma implementation
• Handlers: inject repository abstraction

Error Handling

Consistent pattern:

1. Catch DomainException → rethrow
2. Log unexpected errors
3. Return user-friendly message via InternalServerErrorException

---

🚀 Implementation Checklist

When adding a new analytics query:

• Create Query class in application/queries/your-feature/
• Create Handler with cache-aside pattern
• Define DTO interface as handler return type
• Create Request DTO for controller parameters
• Add endpoint to appropriate controller
• Apply guard stack: EndpointRateLimitGuard → JwtAuthGuard → QuotaGuard
• Add @RequireQuota('analytics_queries')
• Register handler in analytics.module.ts QueryHandlers array
• Follow naming convention: Query → Handler → Dto
• Use CacheService.buildKey() for cache keys
• Use CacheTTL.* constants for TTLs
• Catch DomainException separately
• Add comprehensive error handling
• Test with Swagger/Postman
• Add unit tests in __tests__/ directory

---

📋 File Statistics

File	Size	Sections	Key Purpose
EXPLORATION_SUMMARY.md	12 KB	11 + templates	Overview & quick reference
ANALYTICS_ARCHITECTURE.md	25 KB	10 detailed	Deep technical reference
ANALYTICS_QUICK_REFERENCE.md	11 KB	Reference	Developer cheat sheet
ANALYTICS_ARCHITECTURE_DIAGRAM.txt	19 KB	ASCII diagrams	Visual architecture

Total Documentation: ~67 KB of comprehensive guides

---

🔗 Key File Paths Mentioned

Analytics Module Root

apps/api/src/modules/analytics/

Controllers

presentation/controllers/analytics.controller.ts      (13+ endpoints)
presentation/controllers/avm.controller.ts            (5 endpoints)

Query Handlers (14+)

application/queries/{query-name}/{query-name}.query.ts
application/queries/{query-name}/{query-name}.handler.ts

Shared Module

apps/api/src/modules/shared/
├── infrastructure/cache.service.ts               (cache-aside)
├── infrastructure/redis.service.ts               (Redis connection)
├── infrastructure/guards/endpoint-rate-limit.guard.ts
├── domain/domain-exception.ts
└── ...

---

💡 Tips for Using These Docs

1. Keep ANALYTICS_QUICK_REFERENCE.md open while coding
2. Use Ctrl+F to search for specific concepts
3. Read ANALYTICS_ARCHITECTURE.md sections sequentially for learning
4. Reference ANALYTICS_ARCHITECTURE_DIAGRAM.txt when explaining to others
5. Copy code templates from ANALYTICS_QUICK_REFERENCE.md
6. Check conventions table before naming new classes/files

---

🎯 Common Scenarios

I need to add a market analytics endpoint

→ See ANALYTICS_QUICK_REFERENCE.md: "CQRS Handler Pattern" → Use CachePrefix.MARKET_REPORT or MARKET_TREND → Check existing handlers: get-price-trend, get-heatmap, get-market-report

I need to add a valuation endpoint

→ See ANALYTICS_QUICK_REFERENCE.md: "Common Endpoints" → Use CachePrefix.VALUATION → Check existing: predict-valuation, batch-valuation, valuation-history

I need to understand the cache strategy

→ See ANALYTICS_QUICK_REFERENCE.md: "Cache Patterns" → See ANALYTICS_ARCHITECTURE.md: Section 4 (full details)

I need to add rate limiting

→ Already applied via @EndpointRateLimit decorator → See ANALYTICS_QUICK_REFERENCE.md: "Guards & Decorators Stack" → Modify limit/windowSeconds/keyStrategy as needed

I need to understand error handling

→ See ANALYTICS_QUICK_REFERENCE.md: "Error Handling Pattern" → See ANALYTICS_ARCHITECTURE.md: Section 6

---

✅ Documentation Quality Checklist

• ✅ Complete layer documentation (presentation → infrastructure)
• ✅ All 14+ query handlers covered
• ✅ Redis caching with Lua scripts explained
• ✅ Rate limiting architecture explained
• ✅ Prisma schema for analytics models
• ✅ Shared module exports documented
• ✅ Guard & decorator stack explained
• ✅ Error handling patterns shown
• ✅ Implementation templates provided
• ✅ Visual architecture diagram included
• ✅ Quick reference for developers
• ✅ File paths organized by layer

---

📞 Questions?

Refer to the specific documentation file for your scenario:

• What? → EXPLORATION_SUMMARY.md (quick findings)
• How? → ANALYTICS_QUICK_REFERENCE.md (templates & patterns)
• Why? → ANALYTICS_ARCHITECTURE.md (detailed explanations)
• Where? → ANALYTICS_ARCHITECTURE_DIAGRAM.txt (visual flow)

---

Last Updated: April 2026 Scope: Analytics Module (apps/api/src/modules/analytics/) Coverage: DDD, CQRS, Caching, Rate Limiting, Prisma, Shared Utilities