# 🤖 Battl Builder — AI Context & Guardrails

> **Purpose:**  
> This document provides persistent context for AI assistants working on the **Battl Builder** project.  
> It defines the product vision, architecture, constraints, and expectations so AI outputs remain aligned, safe, and useful.

---

## 1. Project Overview

**Battl Builder** is a PCPartPicker-style platform for firearms, starting with the **AR-15 ecosystem**.

Users can:
- Browse firearm parts by role (upper, lower, barrel, etc.)
- Compare prices across multiple merchants
- Assemble builds using a visual Builder UI
- Share builds publicly

Battl Builder:
- **Does not sell products**
- **Does not process payments**
- Is **affiliate-driven** (AvantLink)
- Focuses on **clarity, accuracy, and trust**

Think: *“Build smarter rifles, not spreadsheets.”*

---

## 2. Product Philosophy

### Core Principles
- **Accuracy > Completeness**
- **Idempotency > Speed**
- **Explicit data > heuristics**
- **Long-term maintainability > cleverness**

### Non-Goals
AI should NOT assume this project is:
- An e-commerce checkout platform
- A firearm marketplace
- A forum-first community
- A content or media brand (for now)

Avoid suggestions that introduce:
- Real-time inventory guarantees
- Payment processing
- Legal/compliance risk
- Over-engineered abstractions

---

## 3. Current State (Beta)

### What Exists
- User authentication
- Functional Builder UI
- Dedicated part pages
- Basic builds community
- 2 merchants (AvantLink)
- Production Spring Boot backend

### What’s Intentionally Light
- Compatibility logic (rule-based, evolving)
- Social features
- Price history & analytics
- Public build discovery

This is a **real beta**, not a mock project.

---

## 4. Backend Architecture

### Tech Stack
- **Java 17**
- **Spring Boot 3.x**
- **PostgreSQL**
- **Hibernate / JPA**
- **Maven**
- **REST APIs**
- **Docker (local + infra)**

### Core Responsibilities
- Merchant feed ingestion (CSV / TSV)
- Product normalization & deduplication
- Offer upserts (price, stock, URLs)
- Category → Part Role mapping
- Platform inference (AR-15 today)
- Supplying clean data to the Builder UI

---

## 5. Import Pipeline (Critical Context)

The import system is the **heart of the platform**.

### Key Characteristics
- Idempotent by design
- Safe to re-run repeatedly
- Handles dirty, malformed feeds
- Never duplicates products or offers

### Import Modes
- **Full Import:** products + offers
- **Offer-Only Sync:** price/stock refresh

### Deduplication Rules
- Products deduped by **Brand + MPN** (UPC fallback later)
- Offers are **merchant-specific**
- Offers track:
    - `firstSeenAt`
    - `lastSeenAt`

⚠️ **Never introduce logic that breaks idempotency.**  
⚠️ **Never assume merchant data is clean or complete.**

---

## 6. Frontend Expectations

- Next.js / React
- Backend owns business logic
- Frontend consumes normalized APIs
- No hardcoded compatibility rules
- No duplication of backend logic

The Builder UI assumes:
- Part roles are authoritative
- Compatibility is backend-driven
- Data is already normalized

---

## 7. Infrastructure & Dev Environment

- PostgreSQL (Docker or local)
- Spring Boot runs on `:8080`
- CI builds on push / PR
- Local dev favors simplicity over cleverness

---

## 8. Constraints You Must Respect

AI suggestions must account for:
- Small team
- Incremental delivery
- Clear migration paths
- Code readability 6–12 months out

Avoid:
- “Rewrite everything” answers
- Premature abstractions
- Magical inference engines
- Hidden or implicit behavior

---

## 9. How AI Should Respond

When assisting on this project:

- **Feature requests** → propose phased, minimal solutions
- **Refactors** → explain tradeoffs and migration steps
- **Debugging** → reason from architecture first
- **Design** → follow PCPartPicker mental models
- **Scaling** → assume success, move incrementally

If something is unclear:
- Ask **one focused question**
- Otherwise state assumptions and proceed

---

## 10. Mental Model Summary

Battl Builder is:

- A **builder, not a store**
- A **data normalization engine disguised as a UI**
- Opinionated where it matters
- Flexible where it counts
- Built for **credibility and longevity**

AI assistance should help the project grow **cleanly, safely, and intelligently**.

---

### ✅ Recommended Usage
Paste this file into:
- Cursor / Copilot project context
- ChatGPT system prompt
- Claude project memory
- `/docs/ai-context.md`
-