goodgo-platform/docs/audits/README_INQUIRIES_EXPLORATION.md

# 📚 Inquiries Module - Complete Exploration Documentation

**Generated:** April 11, 2026  
**Module:** `apps/api/src/modules/inquiries/`  
**Status:** ✅ Complete & Thorough Analysis

---

## 📖 DOCUMENTATION FILES

This exploration includes **3 comprehensive documentation files** designed for different use cases:

### 1. **INQUIRIES_MODULE_EXPLORATION.md** (23 KB)
**Purpose:** In-depth reference guide  
**Best for:** Understanding architecture, patterns, and complete file descriptions

Contains:
- 📁 Complete directory structure
- 📄 Full file listing with descriptions
- 🏗️ Module architecture diagrams
- 🔑 Key classes & handlers breakdown
- 🎯 DDD layer analysis
- 📊 Test file summary
- 🛠️ Dependencies & security
- 📝 API contracts

**Read this when:** You need complete understanding of the module

---

### 2. **INQUIRIES_MODULE_QUICK_REFERENCE.md** (9.3 KB)
**Purpose:** Quick lookup guide  
**Best for:** Getting up to speed quickly, finding specific information

Contains:
- 📊 Module at a glance
- 📁 Files by layer overview
- 🔄 Request flow diagrams
- 🔑 Key classes table
- 📝 Key interfaces
- 🧪 Test statistics
- 🔐 Authorization matrix
- 🎯 DDD principles
- 📌 Common patterns
- 🔍 Where to look for X guide

**Read this when:** You need quick answers or are new to the module

---

### 3. **INQUIRIES_COMPLETE_FILE_INDEX.md** (23 KB)
**Purpose:** Exhaustive file reference  
**Best for:** Finding specific files, understanding dependencies, planning modifications

Contains:
- 📋 Complete file listing by path
- 📊 File statistics tables
- 🔍 File discovery guide
- 🔗 Dependency graph
- 📝 File cross-references
- 🎯 Entry points for modifications
- Line count for each file
- Detailed method descriptions

**Read this when:** You need file-by-file details or planning changes

---

## 🎯 QUICK START BY USE CASE

### I want to understand the overall architecture
→ Start with **Quick Reference** → Dive into **Exploration**

### I'm new to this module
→ Start with **Quick Reference** → Browse **File Index** as needed

### I need to add a new endpoint
→ Check **File Index** → Entry Points section → Follow the guide

### I need to understand a specific layer
→ Search **Quick Reference** for layer → Read full details in **Exploration**

### I'm looking for a specific class or method
→ Use **File Index** → File Discovery Guide section

### I need to understand data flow
→ **Quick Reference** → Request Flows section

### I'm fixing a bug or refactoring
→ **File Index** → Dependency Graph & Cross-References

---

## 📊 MODULE SNAPSHOT

```
Location:    apps/api/src/modules/inquiries/
Files:       25 total (19 source + 6 test files)
LOC:         1,212 lines of code
Pattern:     CQRS + DDD (Clean Architecture)
Tests:       24 test cases across 6 suites
Endpoints:   4 HTTP endpoints
```

### Layer Breakdown

| Layer | Files | Purpose |
|-------|-------|---------|
| **Presentation** | 5 | HTTP endpoints + validation |
| **Application** | 8 | Commands/Queries + orchestration |
| **Domain** | 6 | Business logic + contracts |
| **Infrastructure** | 1 | Prisma persistence |
| **Module** | 2 | Configuration + exports |

---

## 🗂️ FILE TREE

```
inquiries/
├── 📄 index.ts                              [Barrel export]
├── 📄 inquiries.module.ts                   [NestJS Module]
│
├── 📁 presentation/
│   ├── controllers/
│   │   └── inquiries.controller.ts          [4 endpoints]
│   ├── dto/
│   │   ├── create-inquiry.dto.ts            [Input validation]
│   │   └── list-inquiries.dto.ts            [Pagination]
│   └── __tests__/
│       └── inquiries.controller.spec.ts     [6 tests]
│
├── 📁 application/
│   ├── commands/
│   │   ├── create-inquiry/
│   │   │   ├── create-inquiry.command.ts
│   │   │   └── create-inquiry.handler.ts
│   │   └── mark-inquiry-read/
│   │       ├── mark-inquiry-read.command.ts
│   │       └── mark-inquiry-read.handler.ts
│   ├── queries/
│   │   ├── get-inquiries-by-agent/
│   │   │   ├── get-inquiries-by-agent.query.ts
│   │   │   └── get-inquiries-by-agent.handler.ts
│   │   └── get-inquiries-by-listing/
│   │       ├── get-inquiries-by-listing.query.ts
│   │       └── get-inquiries-by-listing.handler.ts
│   └── __tests__/
│       ├── create-inquiry.handler.spec.ts
│       ├── mark-inquiry-read.handler.spec.ts
│       ├── get-inquiries-by-listing.handler.spec.ts
│       └── get-inquiries-by-agent.handler.spec.ts
│
├── 📁 domain/
│   ├── entities/
│   │   └── inquiry.entity.ts                [Aggregate Root]
│   ├── events/
│   │   ├── inquiry-created.event.ts
│   │   └── inquiry-read.event.ts
│   ├── repositories/
│   │   ├── inquiry.repository.ts            [Interface]
│   │   └── inquiry-read.dto.ts              [Read DTO]
│   └── __tests__/
│       └── inquiry-domain.spec.ts           [5 tests]
│
└── 📁 infrastructure/
    └── repositories/
        └── prisma-inquiry.repository.ts     [Implementation]
```

---

## 🔄 REQUEST FLOWS

### Create Inquiry
```
POST /inquiries
→ Controller validates JWT
→ CreateInquiryCommand dispatched
→ CreateInquiryHandler executes:
  • Validate listing exists
  • Create InquiryEntity
  • Save to repository
  • Publish InquiryCreatedEvent
→ Response: { id, listingId, createdAt }
```

### Mark as Read
```
PATCH /inquiries/:id/read (AGENT only)
→ Controller validates JWT + AGENT role
→ MarkInquiryReadCommand dispatched
→ MarkInquiryReadHandler executes:
  • Load inquiry entity
  • Verify agent owns listing
  • Update entity state
  • Persist change
  • Publish InquiryReadEvent
→ Response: { success: true }
```

### List Inquiries
```
GET /inquiries/listing/:id or /agent/me
→ Controller validates JWT (+ AGENT for /agent/me)
→ Query dispatched
→ Handler resolves pagination
→ Repository executes paginated query
→ Response: PaginatedResult<InquiryReadDto>
```

---

## 🔑 KEY CONCEPTS

### DDD (Domain-Driven Design)
- **Domain Entity:** `InquiryEntity` encapsulates inquiry logic
- **Domain Events:** `InquiryCreatedEvent`, `InquiryReadEvent`
- **Repository Pattern:** Interface in domain, implementation in infrastructure
- **Aggregate Root:** InquiryEntity manages state transitions

### CQRS (Command Query Responsibility Segregation)
- **Commands:** CreateInquiryCommand, MarkInquiryReadCommand (write operations)
- **Queries:** GetInquiriesByListingQuery, GetInquiriesByAgentQuery (read operations)
- **Handlers:** Separate classes for each command/query

### Clean Architecture Layers
1. **Presentation:** HTTP endpoints, DTOs, decorators
2. **Application:** Commands/Queries, handlers, coordination
3. **Domain:** Business logic, entities, events, interfaces
4. **Infrastructure:** Database, persistence implementation

---

## 🧪 TEST COVERAGE

**Total:** 24 tests across 6 test suites

| Test Suite | Tests | Focus |
|-----------|-------|-------|
| Domain Entity | 5 | Aggregate behavior, events |
| CreateInquiryHandler | 4 | Happy path, validation, events |
| MarkInquiryReadHandler | 5 | Happy path, auth, errors |
| GetInquiriesByListingHandler | 2 | Pagination, empty results |
| GetInquiriesByAgentHandler | 2 | Results, agent lookup |
| InquiriesController | 6 | All endpoints, defaults |

---

## 🔐 Security

**Authentication:** All endpoints require JWT token  
**Authorization:** RBAC with AGENT role for certain endpoints

### Endpoint Security Matrix

| Endpoint | Auth | Role | Extra Checks |
|----------|------|------|--------------|
| POST /inquiries | JWT | Any | Listing exists |
| GET /listing/:id | JWT | Any | - |
| GET /agent/me | JWT | AGENT | - |
| PATCH /:id/read | JWT | AGENT | Agent owns listing |

---

## 📡 API CONTRACTS

### POST /inquiries
```
Request:  { listingId: string, message: string, phone?: string }
Response: { id: string, listingId: string, createdAt: string }
Status:   201 | 400 | 401 | 404
```

### GET /inquiries/listing/:listingId
```
Query:    { page?: number, limit?: number }
Response: PaginatedResult<InquiryReadDto>
Status:   200 | 401
```

### GET /inquiries/agent/me
```
Query:    { page?: number, limit?: number }
Response: PaginatedResult<InquiryReadDto>
Status:   200 | 401 | 403
```

### PATCH /inquiries/:id/read
```
Response: { success: boolean }
Status:   200 | 401 | 403 | 404
```

---

## 🚀 GETTING STARTED

### For Understanding the Code
1. Read **Quick Reference** (5 min)
2. Review **Request Flows** (5 min)
3. Explore specific layers in **Exploration** as needed

### For Adding Features
1. Check **File Index** → Entry Points (2 min)
2. Follow the modification guide (varies)
3. Check existing tests for patterns

### For Debugging
1. Identify the layer (presentation/application/domain/infrastructure)
2. Find the file in **File Index**
3. Check tests for expected behavior

---

## 📋 COMMON PATTERNS

### Adding a Command
1. Create `application/commands/[name]/[name].command.ts`
2. Create `application/commands/[name]/[name].handler.ts`
3. Implement `ICommandHandler<YourCommand>`
4. Register in `inquiries.module.ts` CommandHandlers array
5. Add tests in `application/__tests__/`

### Adding a Query
1. Create `application/queries/[name]/[name].query.ts`
2. Create `application/queries/[name]/[name].handler.ts`
3. Implement `IQueryHandler<YourQuery>`
4. Register in `inquiries.module.ts` QueryHandlers array
5. Add tests in `application/__tests__/`

### Adding an Endpoint
1. Add method to `InquiriesController`
2. Add DTOs if needed to `presentation/dto/`
3. Dispatch command/query via bus
4. Add tests to `presentation/__tests__/`

---

## 🔗 EXTERNAL DEPENDENCIES

**Core:**
- `@nestjs/common` - Framework
- `@nestjs/cqrs` - CQRS bus
- `@prisma/client` - ORM

**Validation:**
- `class-validator` - DTO validation
- `class-transformer` - Type transformation

**Documentation:**
- `@nestjs/swagger` - OpenAPI docs

**Internal:**
- `@modules/shared` - AggregateRoot, exceptions
- `@modules/auth` - JWT guards, decorators

---

## 📈 QUALITY METRICS

| Aspect | Rating | Notes |
|--------|--------|-------|
| Architecture | ⭐⭐⭐⭐⭐ | Clean DDD + CQRS |
| Organization | ⭐⭐⭐⭐⭐ | Clear layer separation |
| Type Safety | ⭐⭐⭐⭐⭐ | Full TypeScript |
| Tests | ⭐⭐⭐⭐☆ | 24 tests, good depth |
| Auth | ⭐⭐⭐⭐⭐ | Proper RBAC |
| Maintainability | ⭐⭐⭐⭐⭐ | Easy to extend |

---

## 💡 ARCHITECTURAL HIGHLIGHTS

✅ **Separation of Concerns** - Each layer has single responsibility  
✅ **Dependency Inversion** - Depend on abstractions, not concrete implementations  
✅ **Event-Driven** - Domain events for business significance  
✅ **CQRS** - Read/write paths separate and optimizable  
✅ **Type Safety** - Full TypeScript with no any types  
✅ **Testability** - All layers independently testable  
✅ **Extensibility** - Easy to add new commands/queries  

---

## 🎓 LEARNING PATH

**Beginner:** Read Quick Reference → Understand layers → Look at controller  
**Intermediate:** Study handlers → Review entities → Examine tests  
**Advanced:** Deep dive into event sourcing → Pagination → Optimization patterns  

---

## 📞 REFERENCE QUICK LINKS

Within documentation files:

**Quick Reference:**
- Files by layer
- Request flows
- Authorization matrix
- Entry points for changes

**File Index:**
- Complete file descriptions
- Dependency graph
- Cross-references
- Modification guide

**Exploration:**
- Architecture diagrams
- Design patterns
- Security details
- Test coverage analysis

---

## ✨ Next Steps

1. **Read the Quick Reference** to get oriented
2. **Pick a documentation file** based on your need
3. **Use the discovery guides** to find specific information
4. **Follow the modification guides** when making changes
5. **Check tests** for expected behavior

---

**Happy exploring! 🚀**

Generated: April 11, 2026  
Documentation Status: ✅ Complete