goodgo-platform/docs/explorations/FRONTEND_DOCUMENTATION_INDEX.md

GoodGo Platform - Frontend Documentation Index

📋 Documentation Files

You now have 3 comprehensive guides to help you understand and build on the GoodGo frontend:

1. NEXTJS_FRONTEND_STRUCTURE.md ← START HERE

Most comprehensive, detailed reference

• ✅ Complete app router structure
• ✅ Page patterns (public, detail, admin CRUD)
• ✅ UI components organization
• ✅ Mapbox integration details
• ✅ Tailwind/styling system
• ✅ API client & data fetching patterns
• ✅ Prisma schema (ProjectDevelopment model)
• ✅ Existing du-an routes
• ✅ Summary checklist for building

When to use: Understanding the overall architecture, setting up new features, learning patterns

2. NEXTJS_QUICK_REFERENCE.md ← FOR QUICK LOOKUPS

Fast reference with code examples

• ✅ File organization overview
• ✅ 3 common patterns with code
• ✅ Key files table (which file to edit for what)
• ✅ API integration checklist
• ✅ UI & styling checklist
• ✅ Mapbox setup
• ✅ Authentication pattern
• ✅ React Query patterns
• ✅ Testing structure
• ✅ Common mistakes & how to avoid
• ✅ Pro tips

When to use: You know what you want to do, need a quick code snippet

3. NEXTJS_VISUAL_FLOWCHART.md ← FOR VISUALIZATION

Diagrams and visual flows

• ✅ Data flow architecture
• ✅ Page rendering flows (browse, detail, CRUD)
• ✅ Component hierarchy tree
• ✅ Data fetching timeline
• ✅ API layer organization
• ✅ Route group strategy
• ✅ Type flow (raw → normalized → component)
• ✅ Mapbox integration flow
• ✅ Styling cascade

When to use: Understanding how data flows, how pages render, system organization

---

🚀 Quick Start Guide

For Building a New Public Browse Page

1. Read: NEXTJS_FRONTEND_STRUCTURE.md → Section 2 (Page Patterns) → Pattern A
2. Reference: NEXTJS_QUICK_REFERENCE.md → Common Patterns → Pattern 1
3. Visualize: NEXTJS_VISUAL_FLOWCHART.md → Page Rendering Flow → Pattern 1
4. Copy: Existing /du-an/page.tsx as template
5. Checklist: NEXTJS_FRONTEND_STRUCTURE.md → Section 8 (Summary Checklist)

For Building a New Detail Page

1. Read: NEXTJS_FRONTEND_STRUCTURE.md → Section 2 (Page Patterns) → Pattern C
2. Reference: NEXTJS_QUICK_REFERENCE.md → Common Patterns → Pattern 2
3. Visualize: NEXTJS_VISUAL_FLOWCHART.md → Page Rendering Flow → Pattern 2
4. Copy: Existing /du-an/[slug]/page.tsx as template
5. Check: Server-side fetching setup in du-an-server.ts

For Building a New Admin/CRUD Page

1. Read: NEXTJS_FRONTEND_STRUCTURE.md → Section 2 (Page Patterns) → Pattern B
2. Reference: NEXTJS_QUICK_REFERENCE.md → Common Patterns → Pattern 3
3. Visualize: NEXTJS_VISUAL_FLOWCHART.md → Page Rendering Flow → Pattern 3
4. Copy: Existing /projects/page.tsx as template
5. Setup: Create API methods, React Query hooks, mutations

For Adding Mapbox Integration

1. Read: NEXTJS_FRONTEND_STRUCTURE.md → Section 4 (Mapbox Integration)
2. Reference: NEXTJS_QUICK_REFERENCE.md → Mapbox Setup
3. Visualize: NEXTJS_VISUAL_FLOWCHART.md → Mapbox Integration Flow
4. Copy: Existing components/du-an/project-map.tsx as template

For Adding API Integration

1. Read: NEXTJS_FRONTEND_STRUCTURE.md → Section 6 (API Client & Data Fetching)
2. Reference: NEXTJS_QUICK_REFERENCE.md → API Integration Checklist
3. Visualize: NEXTJS_VISUAL_FLOWCHART.md → API Layer Organization
4. Steps:
   • Define types in lib/[domain]-api.ts
   • Create API methods
   • Create React Query hooks in lib/hooks/use-[domain].ts
   • Use in components

For Styling Components

1. Read: NEXTJS_FRONTEND_STRUCTURE.md → Section 5 (Tailwind/Styling)
2. Reference: NEXTJS_QUICK_REFERENCE.md → UI & Styling Checklist
3. Visualize: NEXTJS_VISUAL_FLOWCHART.md → Styling Cascade
4. Use: Design tokens from tailwind.config.ts

---

📚 File Locations to Know

Key Files for Each Feature

App Router & Pages:
  apps/web/app/[locale]/(public)/du-an/
  apps/web/app/[locale]/(dashboard)/projects/
  
Components:
  apps/web/components/du-an/
  apps/web/components/ui/
  apps/web/components/map/
  
APIs & Hooks:
  apps/web/lib/du-an-api.ts
  apps/web/lib/du-an-server.ts
  apps/web/lib/hooks/use-du-an.ts
  apps/web/lib/api-client.ts
  
Styling:
  apps/web/tailwind.config.ts
  apps/web/app/[locale]/layout.tsx
  
Prisma:
  prisma/schema.prisma (ProjectDevelopment model)

---

🔑 Key Concepts Summary

Server vs Client Components

• Server Component (default): No 'use client'

  • Can fetch data, access secrets, use databases
  • Used for layouts, metadata generation, static pages
  • Pass data to Client Components as props

• Client Component: Must have 'use client'

  • Can use hooks (useState, useEffect, useContext)
  • Can use React Query (useQuery, useMutation)
  • Can be interactive

Route Groups (Parentheses)

• (public) - No authentication required
• (auth) - Login/register pages
• (dashboard) - Protected pages (users)
• (admin) - Admin-only pages

Data Fetching Hierarchy

1. Server Component fetch() (for metadata, static generation)
2. useQuery hooks (for client-side data, caching)
3. useMutation hooks (for POST/PATCH/DELETE operations)

API Layer

1. apiClient - Raw fetch wrapper (CSRF, refresh)
2. Domain APIs - Typed API methods (duAnApi, listingsApi)
3. React Query Hooks - Prefilled query keys & options

Component Composition

Server Page → Server Wrapper → Client Component
                                   ↓
                            UI Components (shadcn/ui)
                                   ↓
                            Tailwind classes + Design tokens

---

🛠️ Development Workflow

Adding a New Feature

1. Design the API

   • Define request/response types
   • Create endpoint in backend
   • Test with curl/Postman

2. Create API Integration

   • Add types to lib/[domain]-api.ts
   • Add methods to API object
   • Create React Query hook in lib/hooks/use-[domain].ts

3. Build the Page

   • Create route in app/[locale]/[group]/[route]/
   • Choose: Server or Client Component
   • Add metadata for detail pages
   • Import components & hooks

4. Create Reusable Components

   • Extract repeated UI into components/[domain]/
   • Use TypeScript interfaces
   • Use shadcn/ui primitives

5. Style with Tailwind

   • Use design tokens (colors, spacing)
   • Responsive classes (sm:, md:, lg:)
   • Dark mode support

6. Test

   • Create __tests__/ folder in same directory
   • Write .spec.tsx tests
   • Test render, interaction, edge cases

7. Deploy

   • Push to branch
   • Create PR with description
   • CI/CD runs tests & builds
   • Merge to main

---

🎯 Common Tasks

"I want to list all projects"

→ Copy /du-an/page.tsx pattern → Use useProjectsSearch() hook → Add filters & pagination

"I want to show project details"

→ Copy /du-an/[slug]/page.tsx pattern → Use generateMetadata() for SEO → Use fetchProjectBySlug() for server fetching

"I want to add a form to create/edit projects"

→ Copy /projects/new/ pattern → Use useMutation() for submit → Create form component with validation

"I want to add a map"

→ Import ProjectMap from components/du-an/project-map.tsx → Pass projects array with lat/lng → Check NEXT_PUBLIC_MAPBOX_TOKEN env var

"I want to style a component"

→ Use Tailwind classes + design tokens → Copy classes from existing components → Use cn() utility for conditional classes

"I want to add authentication check"

→ Use useAuthStore() in client component → Check role field: BUYER, SELLER, AGENT, DEVELOPER, PARK_OPERATOR, ADMIN → Return unauthorized UI if role doesn't match

---

🆘 When You Get Stuck

Problem	Solution
"Server components can't use hooks"	Use 'use client' or move state to Client Component
"Type errors in API response"	Check normalizeProjectDetail() in du-an-server.ts
"Query not updating"	Use queryClient.invalidateQueries() in mutation onSuccess
"Component not rendering"	Check enabled prop on useQuery for conditional queries
"Images not loading"	Use next/image instead of <img>, add sizes prop
"Links not working with i18n"	Use Link from @/i18n/navigation, not next/link
"Mapbox token undefined"	Check NEXT_PUBLIC_MAPBOX_TOKEN in .env.local
"Tailwind classes not working"	Check file is in content array in tailwind.config.ts
"Dark mode not working"	Check darkMode: ['class'] in tailwind config
"Auth not working"	Check middleware, auth provider, cookies setup

---

📖 Further Reading

• Next.js Docs: https://nextjs.org/docs
• React Query Docs: https://tanstack.com/query
• Tailwind Docs: https://tailwindcss.com/docs
• Mapbox GL Docs: https://docs.mapbox.com/mapbox-gl-js
• shadcn/ui: https://ui.shadcn.com/

---

📝 Notes

• All guides are in the repo root
• Always follow existing patterns
• Use TypeScript strictly
• Write tests for new components
• Keep components small and focused
• Reuse UI components from components/ui/

Last Updated: April 21, 2026