docs: consolidate exploration & audit reports under docs/ (TEC-3094)

- Move 8 stray .md (+5 .txt) from ~/Desktop into docs/explorations/from-desktop/ - Reorganize 27 .md/.txt at workspace root: - audit reports -> docs/audits/ - exploration reports -> docs/explorations/ - design system -> docs/design-system/ - Keep only README/CHANGELOG/CONTRIBUTING/CLAUDE at repo root - Refresh docs/README.md as canonical index with links to all groups - Note: pre-existing docs/audits/AUDIT_INDEX.md and AUDIT_SUMMARY.md were overwritten by the newer root-level versions during the move Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-21 16:29:24 +07:00
parent 912121cf09
commit 08b96f9c2d
39 changed files with 15129 additions and 562 deletions
--- a/docs/explorations/FRONTEND_DOCUMENTATION_INDEX.md
+++ b/docs/explorations/FRONTEND_DOCUMENTATION_INDEX.md
@@ -0,0 +1,284 @@
+# 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
+