docs: consolidate exploration & audit reports under docs/ (TEC-3094)
- Move 8 stray .md (+5 .txt) from ~/Desktop into docs/explorations/from-desktop/ - Reorganize 27 .md/.txt at workspace root: - audit reports -> docs/audits/ - exploration reports -> docs/explorations/ - design system -> docs/design-system/ - Keep only README/CHANGELOG/CONTRIBUTING/CLAUDE at repo root - Refresh docs/README.md as canonical index with links to all groups - Note: pre-existing docs/audits/AUDIT_INDEX.md and AUDIT_SUMMARY.md were overwritten by the newer root-level versions during the move Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
304
docs/explorations/README_ANALYTICS_DOCS.md
Normal file
304
docs/explorations/README_ANALYTICS_DOCS.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user