chore(docs): consolidate 22 audit files from root into docs/audits/
Root directory had accumulated audit/exploration markdown files cluttering the project root. Moved all audit-related files to docs/audits/ with a README.md index, and updated cross-references in K6_LOAD_TESTING_GUIDE.md and README_FRONTEND_DOCS.md. Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
439
docs/audits/ADMIN_AUDIT_INDEX.md
Normal file
439
docs/audits/ADMIN_AUDIT_INDEX.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# GoodGo Platform Admin Module Audit Logging - Complete Documentation Index
|
||||
|
||||
## 📋 Quick Navigation
|
||||
|
||||
This comprehensive exploration includes **3 detailed documents** totaling ~61KB of analysis.
|
||||
|
||||
### Document 1: **ADMIN_AUDIT_EXPLORATION.md** (24KB)
|
||||
**Purpose**: Complete codebase analysis and current state assessment
|
||||
|
||||
**Contains:**
|
||||
- Full directory structure of admin module
|
||||
- Prisma schema analysis (User, Listing models - no audit model found)
|
||||
- All 8 admin controller endpoints with exact details
|
||||
- Existing event/logging infrastructure analysis
|
||||
- Logger service documentation with PII redaction
|
||||
- Exception handling and error filter patterns
|
||||
- Security & RBAC implementation
|
||||
- Complete DDD layer structure explanation
|
||||
- Module bootstrap configuration
|
||||
- Summary of what's already in place vs what needs building
|
||||
|
||||
**Key Takeaways:**
|
||||
- 13+ admin action endpoints already capture admin ID from JWT
|
||||
- 7 domain events already published by command handlers
|
||||
- Event-driven architecture already in place (NestJS CQRS)
|
||||
- Pino logger with PII redaction available
|
||||
- Repository pattern established and documented
|
||||
- No audit logging exists yet - greenfield opportunity
|
||||
|
||||
**Read Time:** 15-20 minutes
|
||||
|
||||
---
|
||||
|
||||
### Document 2: **ADMIN_AUDIT_QUICK_FILES.md** (9KB)
|
||||
**Purpose**: Quick reference guide to critical files and implementation checklist
|
||||
|
||||
**Contains:**
|
||||
- Prioritized file reading order (must-read first)
|
||||
- Exact line numbers for key locations
|
||||
- Main controller endpoint list
|
||||
- Command handler flow diagrams
|
||||
- Domain events list
|
||||
- Existing listener pattern as template
|
||||
- Logger service quick reference
|
||||
- Architecture references (repository pattern, module bootstrap, app setup)
|
||||
- Prisma schema locations
|
||||
- Complete endpoint audit list
|
||||
- Dependencies already available in module
|
||||
- Step-by-step implementation checklist (5 phases)
|
||||
- Critical patterns to follow
|
||||
- File structure for new code additions
|
||||
- Events to listen to list
|
||||
|
||||
**Read Time:** 5-10 minutes
|
||||
|
||||
**Best For:** Quick lookups during implementation
|
||||
|
||||
---
|
||||
|
||||
### Document 3: **ADMIN_AUDIT_ARCHITECTURE.md** (28KB)
|
||||
**Purpose**: Complete architecture design and implementation guide
|
||||
|
||||
**Contains:**
|
||||
- System design overview with ASCII diagram
|
||||
- Data flow sequence with state transitions
|
||||
- **Complete Prisma schema addition** (enums + AuditLog model)
|
||||
- Full repository pattern implementation
|
||||
- Domain interface definition
|
||||
- Prisma implementation with queries
|
||||
- Event listener implementation with handlers for all 7 events
|
||||
- Query handler for retrieving audit logs
|
||||
- Controller endpoint code
|
||||
- Dependency injection registration in module
|
||||
- Unit test examples
|
||||
- Integration test examples
|
||||
- Testing strategy
|
||||
|
||||
**Key Sections:**
|
||||
1. Visual ASCII diagrams of data flow
|
||||
2. Exact Prisma model code (copy-paste ready)
|
||||
3. Repository interfaces and implementations
|
||||
4. Listener handlers for all admin events
|
||||
5. Query and controller additions
|
||||
6. Module registration code
|
||||
7. Complete test examples
|
||||
|
||||
**Read Time:** 20-30 minutes
|
||||
|
||||
**Best For:** Implementation reference and testing
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Recommended Reading Order
|
||||
|
||||
### For Initial Understanding (30 minutes)
|
||||
1. **ADMIN_AUDIT_QUICK_FILES.md** - Get overview and file locations (5 min)
|
||||
2. **ADMIN_AUDIT_EXPLORATION.md** Sections 1-4 - Understand structure and patterns (15 min)
|
||||
3. **ADMIN_AUDIT_ARCHITECTURE.md** - See data flow and design (10 min)
|
||||
|
||||
### For Implementation (2-3 hours)
|
||||
1. Read **ADMIN_AUDIT_ARCHITECTURE.md** completely
|
||||
2. Reference **ADMIN_AUDIT_QUICK_FILES.md** checklist
|
||||
3. Use **ADMIN_AUDIT_EXPLORATION.md** for pattern details when needed
|
||||
|
||||
### For Debugging (As needed)
|
||||
- Use **ADMIN_AUDIT_QUICK_FILES.md** to find exact file locations
|
||||
- Use **ADMIN_AUDIT_EXPLORATION.md** to understand existing patterns
|
||||
- Use **ADMIN_AUDIT_ARCHITECTURE.md** to verify implementation patterns
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Project Structure at a Glance
|
||||
|
||||
```
|
||||
GoodGo Admin Module (modules/admin/)
|
||||
├── Domain Layer (domain/)
|
||||
│ ├── Events (7 existing events - user/listing/kyc/subscription)
|
||||
│ └── Repositories (query interfaces)
|
||||
│
|
||||
├── Application Layer (application/)
|
||||
│ ├── Commands (8 handlers - ban, approve, reject, adjust)
|
||||
│ ├── Queries (6 handlers - stats, queues, users, revenue)
|
||||
│ └── Listeners (2 existing + 1 to add for audit)
|
||||
│
|
||||
├── Infrastructure Layer (infrastructure/)
|
||||
│ └── Repositories (Prisma implementations)
|
||||
│
|
||||
└── Presentation Layer (presentation/)
|
||||
├── Controllers (2 controllers with 12 endpoints)
|
||||
└── DTOs (input validation)
|
||||
|
||||
Database (PostgreSQL 16 + PostGIS)
|
||||
├── User model (has isActive, kycStatus, role)
|
||||
├── Listing model (has status, moderationScore)
|
||||
└── [TO ADD] AuditLog model
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Critical Findings
|
||||
|
||||
### ✅ Already Implemented
|
||||
1. **Admin Identity Capture** - All actions have @CurrentUser() to get admin ID
|
||||
2. **Event Publishing** - Commands publish domain events
|
||||
3. **Event Listener Pattern** - UserBannedListener shows template
|
||||
4. **Logger Service** - Pino with PII redaction
|
||||
5. **Exception Handling** - Global filter + domain exceptions
|
||||
6. **Repository Pattern** - Admin module shows clear interface/implementation separation
|
||||
7. **CQRS Module** - CqrsModule.forRoot() in app.module.ts
|
||||
8. **DI System** - Clear Symbol-based token pattern
|
||||
|
||||
### ❌ Not Yet Implemented
|
||||
1. **AuditLog Prisma Model** - Database table needed
|
||||
2. **Audit Repository** - Interface + Prisma implementation
|
||||
3. **Audit Event Listener** - To capture and persist events
|
||||
4. **Query Handler** - To retrieve audit logs
|
||||
5. **Controller Endpoint** - GET /admin/audit-logs
|
||||
6. **HTTP Context Capture** - IP address, user agent (optional enhancement)
|
||||
|
||||
### 📊 Implementation Scope
|
||||
- **New Files to Create**: 6-8 files
|
||||
- **Files to Modify**: 3-4 files (schema.prisma, admin.module.ts, controllers)
|
||||
- **Estimated Time**: 4-8 hours implementation + 2 hours testing
|
||||
- **Complexity**: Medium (straightforward pattern, follows existing conventions)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 What Each Document Provides
|
||||
|
||||
### ADMIN_AUDIT_EXPLORATION.md
|
||||
|
||||
**Use for:**
|
||||
- Understanding project architecture
|
||||
- Learning existing patterns
|
||||
- Understanding DDD layer structure
|
||||
- Understanding module bootstrap
|
||||
|
||||
**Key Sections:**
|
||||
1. Admin Module Structure - Full directory breakdown
|
||||
2. Prisma Schema Analysis - Current models and what's missing
|
||||
3. Admin Controller Actions & Flow - All 12 endpoints detailed
|
||||
4. Existing Event/Logging Infrastructure - Events and listeners
|
||||
5. Logger Service - Pino configuration and usage
|
||||
6. Exception Handling & Filters - Error handling patterns
|
||||
7. Security & Guards - RBAC implementation
|
||||
8. DDD Layer Structure - Command/Query handlers explained
|
||||
9. Module Bootstrap - How admin.module.ts works
|
||||
10. Existing Interceptor Patterns - HttpMetricsInterceptor, CSRF middleware
|
||||
11. Summary for Audit Logging Implementation - What's in place vs needed
|
||||
|
||||
---
|
||||
|
||||
### ADMIN_AUDIT_QUICK_FILES.md
|
||||
|
||||
**Use for:**
|
||||
- Quick file location lookups
|
||||
- Command handler flow understanding
|
||||
- Event listener template reference
|
||||
- Implementation phase checklist
|
||||
- File structure for new code
|
||||
|
||||
**Key Sections:**
|
||||
1. Must Read First - Top 6 critical files
|
||||
2. Architecture References - Patterns to follow
|
||||
3. Prisma Schema - Where things are
|
||||
4. Exact Endpoints to Audit - All 8 endpoints listed
|
||||
5. Dependencies Already Imported - What's available
|
||||
6. Implementation Checklist - 5 phases with tasks
|
||||
7. Critical Patterns to Follow - 4 key patterns
|
||||
8. Where to Add Code - File structure
|
||||
9. Events to Listen To - All 8 events
|
||||
|
||||
---
|
||||
|
||||
### ADMIN_AUDIT_ARCHITECTURE.md
|
||||
|
||||
**Use for:**
|
||||
- Detailed architecture understanding
|
||||
- Exact implementation code
|
||||
- Database schema design
|
||||
- Testing examples
|
||||
|
||||
**Key Sections:**
|
||||
1. System Design Overview - Large ASCII diagram of full flow
|
||||
2. Data Flow Sequence - Event flow from request to database
|
||||
3. Prisma Schema Addition - **Copy-paste ready**
|
||||
4. Repository Layer - Interface and implementation code
|
||||
5. Event Listener Implementation - Handlers for all events
|
||||
6. Query Handler for Retrieval - Getting audit logs
|
||||
7. Controller Endpoint - GET /admin/audit-logs
|
||||
8. DI Registration - Module setup code
|
||||
9. Testing Strategy - Unit and integration tests
|
||||
|
||||
---
|
||||
|
||||
## 📝 Key Code Examples Available
|
||||
|
||||
### In ADMIN_AUDIT_ARCHITECTURE.md
|
||||
|
||||
**Ready to Use:**
|
||||
|
||||
1. **Prisma Schema** (lines ~100-150)
|
||||
- AuditLog model with all fields
|
||||
- AdminAction, AuditResourceType, AuditStatus enums
|
||||
- Indexes for performance
|
||||
|
||||
2. **Repository Interface** (lines ~160-200)
|
||||
- IAuditLogRepository interface
|
||||
- CreateAuditLogDto interface
|
||||
- FindAuditLogsParams interface
|
||||
|
||||
3. **Repository Implementation** (lines ~210-260)
|
||||
- PrismaAuditLogRepository class
|
||||
- create() method
|
||||
- findMany() with filtering
|
||||
- Date range queries
|
||||
|
||||
4. **Event Listener** (lines ~270-330)
|
||||
- AuditLoggingListener class
|
||||
- @OnEvent() handlers for all 7 events
|
||||
- Error handling
|
||||
|
||||
5. **Query Handler** (lines ~340-360)
|
||||
- GetAuditLogsQuery class
|
||||
- GetAuditLogsHandler implementation
|
||||
|
||||
6. **Controller Endpoint** (lines ~370-395)
|
||||
- @Get('audit-logs') endpoint
|
||||
- Query parameters with Swagger docs
|
||||
|
||||
7. **DI Registration** (lines ~400-430)
|
||||
- AdminModule provider setup
|
||||
|
||||
8. **Test Examples** (lines ~440-500)
|
||||
- Unit test example
|
||||
- Integration test example
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Cross-References Between Documents
|
||||
|
||||
### EXPLORATION → QUICK FILES
|
||||
- EXPLORATION Section 1 (Admin Module Structure) is summarized in QUICK FILES "MUST READ FIRST"
|
||||
- EXPLORATION Section 3 (Controller Actions) is detailed in QUICK FILES "EXACT ENDPOINTS TO AUDIT"
|
||||
|
||||
### QUICK FILES → ARCHITECTURE
|
||||
- QUICK FILES file locations referenced in ARCHITECTURE "WHERE TO ADD CODE"
|
||||
- QUICK FILES events list matched in ARCHITECTURE listener handlers
|
||||
|
||||
### ARCHITECTURE → EXPLORATION
|
||||
- ARCHITECTURE patterns follow conventions from EXPLORATION Section 8 (DDD Layer Structure)
|
||||
- ARCHITECTURE DI setup matches pattern from EXPLORATION Section 9 (Module Bootstrap)
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
1. **Start with QUICK_FILES** - 5 minute overview before diving deep
|
||||
2. **Use EXPLORATION as reference** - Bookmark Section 3 (Controllers) and Section 8 (DDD)
|
||||
3. **Copy from ARCHITECTURE** - Most code is ready to paste with minimal adjustments
|
||||
4. **Follow the checklist** - QUICK_FILES has 5-phase checklist that matches ARCHITECTURE sections
|
||||
5. **Pattern matching** - ARCHITECTURE AuditLoggingListener mirrors existing UserBannedListener
|
||||
6. **Testing template** - ARCHITECTURE has unit and integration test examples
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Path
|
||||
|
||||
### Beginner (Just want overview)
|
||||
1. QUICK_FILES section "MUST READ FIRST" (5 min)
|
||||
2. ARCHITECTURE "System Design Overview" (10 min)
|
||||
3. Total: 15 minutes
|
||||
|
||||
### Intermediate (Want to understand structure)
|
||||
1. QUICK_FILES (10 min)
|
||||
2. EXPLORATION Sections 1, 2, 3 (20 min)
|
||||
3. ARCHITECTURE "Data Flow Sequence" (10 min)
|
||||
4. Total: 40 minutes
|
||||
|
||||
### Advanced (Ready to implement)
|
||||
1. All three documents in sequence (60 min)
|
||||
2. QUICK_FILES implementation checklist (5 min)
|
||||
3. Start coding following ARCHITECTURE code sections
|
||||
|
||||
---
|
||||
|
||||
## 📞 Reference Quick Links
|
||||
|
||||
### Event Names to Listen To
|
||||
- 'user.banned' ← UserBannedEvent
|
||||
- 'user.unbanned' ← UserUnbannedEvent
|
||||
- 'listing.approved' ← ListingApprovedEvent
|
||||
- 'listing.rejected' ← ListingRejectedEvent
|
||||
- 'kyc.approved' ← KycApprovedEvent
|
||||
- 'kyc.rejected' ← KycRejectedEvent
|
||||
- 'subscription.adjusted' ← SubscriptionAdjustedEvent
|
||||
|
||||
### Admin Endpoints to Audit
|
||||
1. PATCH /admin/users/status (UpdateUserStatusCommand)
|
||||
2. POST /admin/users/ban (BanUserCommand)
|
||||
3. POST /admin/subscriptions/adjust (AdjustSubscriptionCommand)
|
||||
4. POST /admin/moderation/approve (ApproveListingCommand)
|
||||
5. POST /admin/moderation/reject (RejectListingCommand)
|
||||
6. POST /admin/moderation/bulk (BulkModerateListingsCommand)
|
||||
7. POST /admin/kyc/approve (ApproveKycCommand)
|
||||
8. POST /admin/kyc/reject (RejectKycCommand)
|
||||
|
||||
### Key Files
|
||||
- Controllers: `presentation/controllers/admin*.controller.ts`
|
||||
- Events: `domain/events/*.event.ts`
|
||||
- Listeners: `application/listeners/*.listener.ts`
|
||||
- Handlers: `application/commands/*/handler.ts`
|
||||
- Schema: `prisma/schema.prisma`
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Summary
|
||||
|
||||
```
|
||||
HTTP Request
|
||||
↓
|
||||
Controller (validate, extract admin ID from JWT)
|
||||
↓
|
||||
CommandBus.execute(Command)
|
||||
↓
|
||||
CommandHandler (business logic + publish event)
|
||||
↓
|
||||
EventBus.publish(Event)
|
||||
↓ branches to:
|
||||
├─ UserBannedListener (existing - side effects)
|
||||
└─ AuditLoggingListener (NEW - persist to database)
|
||||
↓
|
||||
AuditLogRepository.create(AuditLog)
|
||||
↓
|
||||
Prisma.auditLog.create()
|
||||
↓
|
||||
PostgreSQL AuditLog table
|
||||
|
||||
Later:
|
||||
GET /admin/audit-logs
|
||||
↓
|
||||
QueryHandler
|
||||
↓
|
||||
AuditLogRepository.findMany()
|
||||
↓
|
||||
Return paginated results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verification Checklist
|
||||
|
||||
Use this to verify you've read and understood everything:
|
||||
|
||||
- [ ] Read ADMIN_AUDIT_QUICK_FILES.md "MUST READ FIRST" section
|
||||
- [ ] Read ADMIN_AUDIT_EXPLORATION.md Sections 1-4
|
||||
- [ ] Reviewed ADMIN_AUDIT_ARCHITECTURE.md "System Design Overview" diagram
|
||||
- [ ] Understood admin action endpoints (12 endpoints listed)
|
||||
- [ ] Identified domain events (7 events to listen to)
|
||||
- [ ] Located existing listener pattern (UserBannedListener)
|
||||
- [ ] Found Prisma schema location (prisma/schema.prisma)
|
||||
- [ ] Understood repository pattern (interface + Prisma implementation)
|
||||
- [ ] Saw DI registration pattern (Symbol-based tokens)
|
||||
- [ ] Reviewed controller endpoint patterns (@Get, @Post decorators)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Total Documentation Provided
|
||||
|
||||
- **3 Markdown files** (~61KB total)
|
||||
- **11+ major sections** with detailed explanations
|
||||
- **ASCII diagrams** for visual understanding
|
||||
- **Ready-to-use code** for immediate implementation
|
||||
- **Test examples** for unit and integration testing
|
||||
- **5-phase implementation checklist**
|
||||
- **Events mapping** to handler names
|
||||
- **File locations** with line numbers where applicable
|
||||
- **DDD pattern explanations** with examples
|
||||
- **Patterns to follow** with code templates
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. **Read ADMIN_AUDIT_QUICK_FILES.md** (5 min)
|
||||
2. **Review ADMIN_AUDIT_EXPLORATION.md** (20 min)
|
||||
3. **Study ADMIN_AUDIT_ARCHITECTURE.md** (30 min)
|
||||
4. **Follow implementation checklist** from QUICK_FILES
|
||||
5. **Copy code examples** from ARCHITECTURE
|
||||
6. **Run tests** using examples from ARCHITECTURE
|
||||
7. **Deploy with confidence** - patterns are proven in codebase
|
||||
|
||||
---
|
||||
|
||||
Generated: 2026-04-10
|
||||
Total Exploration Time: ~3 hours
|
||||
Documentation Quality: Comprehensive with examples
|
||||
Implementation Confidence: Very High (follows existing patterns)
|
||||
|
||||
Reference in New Issue
Block a user