mirror of
https://gitea.gofwd.group/Forward_Group/ballistic-builder-spring.git
synced 2026-01-20 16:51:03 -05:00
195 lines
4.4 KiB
Markdown
195 lines
4.4 KiB
Markdown
# 🤖 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`
|
||
- |