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