# Agent Public Profile Page — Complete Implementation Guide

**Last Updated:** April 11, 2026  
**Status:** 📋 Exploration Complete — Ready for Implementation  
**Scope:** `/agents/[id]` public profile page for GoodGo platform

---

## 📚 Documentation Index

This exploration package contains 3 comprehensive documents:

### 1. **AGENT_PROFILE_EXPLORATION.md** (21 KB)
**Comprehensive technical analysis of the entire codebase**

Contains:
- ✅ Web app structure & routing analysis
- ✅ Existing agent-related code inventory
- ✅ API endpoint design proposals
- ✅ UI component library overview
- ✅ Styling patterns & Tailwind setup
- ✅ State management & data fetching patterns
- ✅ SEO & structured data patterns
- ✅ Type definitions & interfaces
- ✅ Implementation checklist
- ✅ Key files reference guide

**Read this first** to understand the full architecture.

---

### 2. **AGENT_PROFILE_QUICK_REFERENCE.md** (10 KB)
**Quick-start guide for developers**

Contains:
- ✅ URL patterns & routing
- ✅ Backend API specification
- ✅ Frontend architecture diagram
- ✅ Data flow visualization
- ✅ Component composition guide
- ✅ API endpoints reference
- ✅ UI mockups & layouts
- ✅ Copy-paste code templates
- ✅ SEO & schema references
- ✅ 5-phase implementation timeline
- ✅ Example response structures
- ✅ Key files checklist

**Use this during development** as a handy reference.

---

### 3. **AGENT_PROFILE_CODE_EXAMPLES.md** (20 KB)
**Ready-to-use code templates for all components**

Contains:
- ✅ Backend query handler (CQRS pattern)
- ✅ Backend DTO definitions
- ✅ Backend controller endpoint
- ✅ Repository interface updates
- ✅ Prisma implementation
- ✅ Frontend API client (agents-api.ts)
- ✅ Frontend server fetch (agents-server.ts)
- ✅ Server component (page.tsx)
- ✅ Agent header component
- ✅ Agent listings section component
- ✅ Agent reviews section component
- ✅ Tailwind styling patterns
- ✅ Testing checklist

**Copy & paste these** into your actual files and customize.

---

## 🎯 Quick Start (5 Minutes)

1. **Read** `AGENT_PROFILE_QUICK_REFERENCE.md` sections:
   - 🎯 Implementation Overview
   - 📦 Backend Setup
   - 🎨 Frontend Architecture

2. **Review** `AGENT_PROFILE_CODE_EXAMPLES.md`:
   - Backend files structure
   - Frontend files structure

3. **Plan** implementation in 5 phases (see quick reference)

---

## 🏗️ Architecture Summary

### Backend (NestJS)
```
New Endpoint: GET /api/v1/agents/:agentId/profile
  │
  ├── Query: GetAgentProfileQuery
  ├── Handler: GetAgentProfileHandler
  ├── DTO: AgentPublicProfileDto
  ├── Repository: IAgentRepository.getPublicProfile()
  └── Implementation: PrismaAgentRepository
```

### Frontend (Next.js 15)
```
Route: /agents/[id]
  │
  ├── Page Component: [id]/page.tsx (Server)
  │   ├── Metadata generation (SEO)
  │   └── JSON-LD structured data
  │
  └── Client Component: AgentDetailClient
      ├── AgentHeader (profile info)
      ├── AgentReviewsSection (reviews & ratings)
      └── AgentListingsSection (properties)
```

### Data Flow
```
1. GET /agents/[id]
2. Server fetches agent profile (ISR: 1 hour cache)
3. Generates SEO metadata
4. Renders with JSON-LD structured data
5. Client component fetches:
   - Agent's listings (parallel)
   - Agent's reviews (parallel)
6. Display agent profile with interactive sections
```

---

## 📋 Implementation Phases

### Phase 1: Backend (1-2 hours)
- [ ] Create `get-agent-profile/` query handler
- [ ] Create `agent-public-profile.dto.ts`
- [ ] Update `agent.repository.ts` interface
- [ ] Implement `prisma-agent.repository.ts`
- [ ] Add endpoint to `agents.controller.ts`
- [ ] Test with Postman/curl

### Phase 2: Frontend Setup (1 hour)
- [ ] Create `lib/agents-api.ts`
- [ ] Create `lib/agents-server.ts`
- [ ] Create `/agents/[id]/` directory
- [ ] Create `/agents/[id]/page.tsx` (stub)

### Phase 3: UI Components (2-3 hours)
- [ ] Create `components/agents/` directory
- [ ] Create `agent-detail-client.tsx`
- [ ] Create `agent-header.tsx`
- [ ] Create `agent-reviews-section.tsx`
- [ ] Create `agent-listings-section.tsx`

### Phase 4: SEO & Polish (1 hour)
- [ ] Implement `generateMetadata()`
- [ ] Add JSON-LD schemas
- [ ] Mobile responsive testing
- [ ] Dark mode testing

### Phase 5: Testing & QA (1 hour)
- [ ] Manual e2e testing
- [ ] 404 handling
- [ ] ISR revalidation
- [ ] Pagination (reviews/listings)
- [ ] SEO audit (Lighthouse)

**Total Estimated Time:** 6-8 hours

---

## 🔗 Key API Endpoints

### Backend (New)
```http
GET /agents/:agentId/profile
  # Returns: AgentPublicProfileDto
  # Status: 200 (success), 404 (not found)
```

### Backend (Existing, Reused)
```http
GET /listings?agentId=:id&status=ACTIVE
  # Get agent's active listings

GET /reviews?targetType=AGENT&targetId=:id
  # Get agent reviews with pagination

GET /reviews/stats?targetType=AGENT&targetId=:id
  # Get aggregate rating statistics
```

---

## 🎨 Frontend Routes

```
/                                    # Landing page
/agents/[id]                         # Agent profile (NEW)
/en/agents/[id]                      # English locale (NEW)
/vi/agents/[id]                      # Vietnamese locale (NEW)
/listings/[id]                       # Listing detail (EXISTING)
/search                              # Search page (EXISTING)
/pricing                             # Pricing page (EXISTING)
```

---

## 📦 Files to Create/Modify

### Backend
| File | Action | Lines |
|------|--------|-------|
| `agents/application/queries/get-agent-profile/get-agent-profile.query.ts` | CREATE | 5 |
| `agents/application/queries/get-agent-profile/get-agent-profile.handler.ts` | CREATE | 30 |
| `agents/presentation/dto/agent-public-profile.dto.ts` | CREATE | 30 |
| `agents/presentation/controllers/agents.controller.ts` | MODIFY | +20 |
| `agents/domain/repositories/agent.repository.ts` | MODIFY | +1 method |
| `agents/infrastructure/repositories/prisma-agent.repository.ts` | MODIFY | +35 |

### Frontend
| File | Action | Lines |
|------|--------|-------|
| `lib/agents-api.ts` | CREATE | 40 |
| `lib/agents-server.ts` | CREATE | 15 |
| `app/[locale]/(public)/agents/[id]/page.tsx` | CREATE | 120 |
| `components/agents/agent-detail-client.tsx` | CREATE | 30 |
| `components/agents/agent-header.tsx` | CREATE | 120 |
| `components/agents/agent-listings-section.tsx` | CREATE | 70 |
| `components/agents/agent-reviews-section.tsx` | CREATE | 100 |

**Total New Lines:** ~595  
**Files Created:** 10  
**Files Modified:** 3

---

## 🧪 Validation Checklist

### API Validation
- [ ] Endpoint returns 200 for valid agent
- [ ] Endpoint returns 404 for invalid agent
- [ ] Response includes all required fields
- [ ] Dates are ISO 8601 formatted
- [ ] Numbers have correct precision

### Frontend Validation
- [ ] Page loads without errors
- [ ] Metadata generates correctly
- [ ] JSON-LD validates on structured.data.org
- [ ] Mobile responsive (320px, 768px, 1024px)
- [ ] Dark mode works correctly
- [ ] ISR revalidation works

### SEO Validation
- [ ] Title tag is unique and descriptive
- [ ] Meta description is complete
- [ ] OG image displays correctly
- [ ] Canonical URL is correct
- [ ] Breadcrumb schema is valid
- [ ] LocalBusiness schema is valid

### Performance Validation
- [ ] First Contentful Paint < 2s
- [ ] Largest Contentful Paint < 2.5s
- [ ] Cumulative Layout Shift < 0.1
- [ ] Lighthouse score > 80

---

## 📊 Data Structure Reference

### Agent Public Profile Response
```typescript
{
  id: string;                      // "clu1x2y3z4a5b6c7d8e9f0"
  fullName: string;                // "Nguyễn Văn A"
  avatarUrl: string | null;        // "https://..."
  licenseNumber: string | null;    // "DA123456"
  agency: string | null;           // "GoodGo Agency"
  qualityScore: number;            // 4.8
  bio: string | null;              // Agent description
  serviceAreas: string[];          // ["quan-1", "quan-7"]
  isVerified: boolean;             // true
  totalListings: number;           // 45
  activeListings: number;          // 32
  avgReviewRating: number;         // 4.7
  totalReviews: number;            // 120
  createdAt: string;               // ISO 8601
  updatedAt: string;               // ISO 8601
}
```

---

## 🔍 Key Design Decisions

1. **Routing:** Agent profiles under `(public)` group, same as listings
2. **Pattern:** Follow listing detail page pattern exactly (copy/paste approach)
3. **Data Fetching:** Server-side with ISR (1 hour revalidation)
4. **State:** Client-side useState for reviews/listings (no Zustand)
5. **Components:** Split into Page (server) + Client (interactive)
6. **SEO:** LocalBusiness JSON-LD schema for agent
7. **Styling:** Reuse existing UI components & Tailwind tokens
8. **Reviews:** Leverage existing /reviews endpoints (already public)

---

## 🚀 Getting Started

### Step 1: Read the Docs
- [ ] Read `AGENT_PROFILE_QUICK_REFERENCE.md` (10 min)
- [ ] Skim `AGENT_PROFILE_EXPLORATION.md` (20 min)

### Step 2: Backend Implementation
- [ ] Copy code from `AGENT_PROFILE_CODE_EXAMPLES.md` (Phase 1)
- [ ] Adapt to your codebase
- [ ] Test with Postman

### Step 3: Frontend Implementation
- [ ] Create directory structure
- [ ] Copy components from code examples (Phase 2-3)
- [ ] Wire up data fetching
- [ ] Add SEO metadata

### Step 4: Testing
- [ ] Manual testing
- [ ] Lighthouse audit
- [ ] E2E test (agent profile page)

---

## 💡 Implementation Tips

1. **Copy the listing detail page structure** — Agent page should be ~90% similar
2. **Reuse PropertyCard component** — For displaying agent's listings
3. **Use existing review endpoints** — Already public and don't need auth
4. **Follow i18n patterns** — Agent name/bio may need translation
5. **Test 404 handling** — When agent doesn't exist
6. **Cache agent profile** — 1 hour ISR matches listing pattern

---

## 📖 Reference Files in Codebase

### Pattern to Copy
- ✅ `app/[locale]/(public)/listings/[id]/page.tsx` — Page structure
- ✅ `components/search/property-card.tsx` — Card pattern
- ✅ `lib/listings-api.ts` — API client pattern
- ✅ `lib/listings-server.ts` — Server fetch pattern
- ✅ `components/seo/json-ld.tsx` — JSON-LD pattern

### Endpoints to Use
- ✅ `GET /listings?agentId=:id` — Existing
- ✅ `GET /reviews?targetType=AGENT` — Existing
- ✅ `GET /reviews/stats?targetType=AGENT` — Existing

### Components to Reuse
- ✅ `Card`, `CardContent` — Layout
- ✅ `Badge` — Status/stats display
- ✅ `Button` — CTAs
- ✅ `Image` — Avatar & property photos
- ✅ `PropertyCard` — Listings display

---

## ❓ FAQ

**Q: How long does this take to implement?**  
A: 6-8 hours total (1-2h backend, 1h setup, 2-3h UI, 1h SEO, 1h testing)

**Q: Do I need to create new backend endpoints?**  
A: Yes, 1 new endpoint: `GET /agents/:agentId/profile`. Reviews/listings endpoints already exist.

**Q: Can I reuse components from the listing page?**  
A: Yes! PropertyCard, metadata generation, JSON-LD structure can all be adapted.

**Q: How do I handle pagination for listings/reviews?**  
A: Use the same pagination as listing detail page (`limit`, `offset`, `page`)

**Q: What about internationalization?**  
A: Agent fullName/bio come from database; use existing i18n patterns in codebase

**Q: How is SEO handled?**  
A: Server-side metadata generation + LocalBusiness JSON-LD schema

---

## 📞 Support

If you have questions during implementation:

1. **Check the exploration document** — Most answers are there
2. **Review code examples** — All patterns are shown
3. **Look at existing pages** — Listing detail page is the best reference
4. **Follow the CQRS pattern** — Used throughout the API

---

## ✅ Completion Checklist

- [ ] Read all 3 documentation files
- [ ] Understand the data flow
- [ ] Plan your implementation (5 phases)
- [ ] Create directory structure
- [ ] Implement backend endpoint
- [ ] Implement frontend API client
- [ ] Create page component
- [ ] Create client components
- [ ] Add SEO metadata
- [ ] Add JSON-LD schemas
- [ ] Test manually
- [ ] Run Lighthouse audit
- [ ] Deploy & monitor

---

**Status:** 🟢 Ready to build!

Good luck with your implementation. Follow the patterns in the codebase, and you'll have a professional agent profile page up and running in a day.