ballistic-builder-spring/README.md

# Ballistic Backend  
### Internal Engine for the Builder Ecosystem

The Ballistic Backend is the operational backbone behind the Shadown System Armory and its admin tools. It ingests merchant feeds, normalizes product data, manages categories, synchronizes prices, and powers the compatibility, pricing, and product logic behind the consumer-facing Builder.

It’s built for reliability, longevity, and clean extensibility — the kind of foundation you want when scaling from a small beta to a fully public platform.

---

## What This Backend Does

### **Merchant Feed Ingestion**
- Pulls AvantLink feeds (CSV or TSV)
- Automatically detects delimiters
- Normalizes raw merchant fields
- Creates or updates product records
- Upserts price and stock offers
- Tracks first-seen / last-seen timestamps
- Safely handles malformed or incomplete rows  
- Ensures repeat imports never duplicate offers

### **Category Mapping Engine**
- Identifies every unique raw category coming from each merchant feed  
- Exposes *unmapped* categories in the admin UI  
- Allows you to assign:  
  - Part Role  
  - Product Configuration (Stripped, Complete, Kit, etc.)
- Applies mappings automatically on future imports  
- Respects manual overrides such as `platform_locked`

### **Builder Support**
The frontend Builder depends on this backend for:

- Loading parts grouped by role  
- Offering compatible options  
- Calculating build cost  
- Comparing offers across merchants  
- Providing product metadata, imagery, and offer data  

**Future expansions include:** price history, compatibility engine, build exports, public build pages, multi-merchant aggregation, and automated anomaly detection.

---

## Tech Stack

- **Spring Boot 3.x**  
- **Java 17**  
- **PostgreSQL**  
- **Hibernate (JPA)**  
- **HikariCP**  
- **Apache Commons CSV**  
- **Maven**  
- **REST API**

---

## Local Development

### Requirements
- Java 17 or newer  
- PostgreSQL running locally  
- Port 8080 open (default backend port)

### Run Development Server

```bash
./mvnw spring-boot:run