Forward/ballistic-builder-spring
2
0
Fork 0
mirror of https://gitea.gofwd.group/Forward_Group/ballistic-builder-spring.git synced 2026-01-20 16:51:03 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
develop
ballistic-builder-spring/ai-context.md

4.4 KiB
Raw Permalink Blame History

🤖 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