Add Project Developer Guide

Project-Developer-Guide.md

@@ -0,0 +1,192 @@
+# Battl Builder – Next.js Developer Guide
+
+## 1. Project Overview
+This project is the front-end for **Battl Builder**, a PCPartPicker-style firearm builder.  
+It is built with:
+- Next.js 14 (App Router)
+- TypeScript
+- TailwindCSS + DaisyUI
+- Server & Client Components
+- API integration with the Spring Boot backend
+
+---
+
+## 2. Folder Structure
+
+```
+/app
+  /builder
+  /builds
+  /category/[categoryId]/[pageId]
+  layout.tsx
+  globals.css
+
+/components
+  /builder
+  /cards
+  /nav
+  /ui
+
+/lib
+  api.ts
+  utils.ts
+  types.ts
+
+/context
+  BuildContext.tsx
+```
+
+### Key Pages
+| Page | Purpose |
+|------|----------|
+| `/builder` | Main rifle builder UI |
+| `/builds` | Social builds feed (placeholder) |
+| `/category/[categoryId]/[pageId]` | Single category product listing |
+
+---
+
+## 3. Data Fetching
+
+### Loading products for builder UI
+Frontend calls:
+
+```ts
+GET /api/gunbuilder/products?platform=AR-15&partRoles=optic
+```
+
+Backend returns:
+- Product details
+- Offer data
+- Price ranges
+- Images
+- Part role
+- Slug
+
+Mapped into UI-facing structures via:
+
+```ts
+import { ProductSummary } from "@/lib/types";
+```
+
+---
+
+## 4. Category Mapping
+
+The builder UI groups parts by category slug (e.g., `"optic"`).
+
+Categories come from:
+- Hardcoded temporary map OR
+- API endpoint `/api/part-role-mappings/AR-15/map`
+
+Example:
+
+```ts
+{
+  partRole: "OPTIC_LPVO",
+  categorySlug: "optic"
+}
+```
+
+---
+
+## 5. Build State Management
+
+Stored in:
+
+```
+/context/BuildContext.tsx
+```
+
+Handles:
+- Selected parts
+- Total price calculation
+- Swapping parts
+- Clearing build
+
+---
+
+## 6. Styling
+
+### TailwindCSS utilities
+- `uppercase`
+- `tracking-wide`
+- `font-bold`
+- `text-primary`
+
+### DaisyUI components
+- Cards
+- Buttons
+- Badges
+- Alerts
+- Inputs
+
+---
+
+## 7. Running Locally
+
+### Install dependencies
+```
+npm install
+```
+
+### Run Dev Server
+```
+npm run dev
+```
+
+### Environment Variables
+```
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
+```
+
+---
+
+## 8. Adding New Builder Categories
+
+1. Add category slug to the backend (`part_categories` table)
+2. Add mapping in `part_role_mappings`
+3. Add frontend label in:
+```
+/lib/categories.ts
+```
+
+---
+
+## 9. Adding New Pages
+
+```
+/app/new-page/page.tsx
+```
+
+Use:
+
+```tsx
+export default function Page() {
+  return <div>My New Page</div>;
+}
+```
+
+---
+
+## 10. Recommended Improvements (Future)
+
+- SSR caching with `fetch({ next: { revalidate: 60 } })`
+- Replace hardcoded PART_ROLE → category mappings
+- Add OptimizedImage component wrapper
+- Client-side build validation (compatibility engine)
+
+---
+
+## 11. Deployment
+
+Recommended:
+- Vercel (first-class support)
+- Cloudflare Pages (optional)
+
+Environment variables must match backend deployment.
+
+---
+
+## 12. Summary
+
+This guide should allow a developer to quickly onboard, understand structure, modify categories, extend the builder, and integrate with the backend services powering Battl Builder.