goodgo-platform/docs/audits/AGENT_PROFILE_README.md

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 14)

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)

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

Backend (Existing, Reused)

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

{
  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.