# 🧨 Ballistic Admin UI  
### Internal Tools for the Builder Ecosystem

The Ballistic Admin UI is the control board behind the Builder.  
It’s where feeds get shaped, categories get normalized, and the catalog stays sharp.

This is an internal tool built for speed, clarity, and capability.

---

# 🚀 What This Admin UI Does

## Merchant Feeds  
Path: `//admin/merchants`

A clean dashboard for all merchants feeding the system.

- View and edit feed URLs  
- Monitor activity and sync timestamps  
- Trigger:
  - Full Imports — pull and process a complete catalog  
  - Offers-Only Syncs — refresh price and stock without re-ingesting products

Purpose: keep the catalog alive, current, and trustworthy.

---

## Category Mapping  
Path: `/builder/admin/category-mapping`

This is where raw merchant chaos gets cleaned up.

- See every unique category discovered during import  
- Filter by merchant or unmapped categories  
- Assign internal standards:
  - Part Role (LOWER_RECEIVER, BARREL, etc.)
  - Configuration (STRIPPED, COMPLETE, KIT)

Once mapped, future imports classify parts automatically.

---

## Builder Integration

The admin UI powers the consumer-facing Builder at `/builder`.

Today:
- Load compatible parts  
- Assemble full builds  
- Pull lowest prices across merchants  

Tomorrow:
- Full compatibility engine  
- Price history  
- Build exports / public build pages  
- Merchant health monitoring  
- Deal surfacing and anomaly detection  

---

# 🧱 Tech Stack

- Next.js (App Router)  
- TypeScript  
- TailwindCSS  
- Fetch API client  
- Spring Boot backend

---

# 🔧 Local Development

## Install Dependencies
npm install  
yarn install  
pnpm install  

## Environment Variables

Create `.env.local`:

NEXT_PUBLIC_API_BASE_URL=http://localhost:8080  
NEXT_PUBLIC_ADMIN_BASE_PATH=/builder/admin  

## Start Dev Server
npm run dev  

Then visit:  
http://localhost:3000/builder/admin

---

# 🌐 Backend Requirements (CORS)

Your Spring Boot backend must allow:

Origin: http://localhost:3000

If CORS fails, the admin cannot communicate with the API.

---

# 🧭 Project Structure

app/  
  builder/  
    admin/  
      merchants/  
      category-mapping/  
components/  
  admin/  
lib/  
  api/  

---

# 📘 Admin API

Full API reference lives in:  
docs/BALLISTIC_ADMIN_API.md

Covers:
- Merchant endpoints  
- Import triggers  
- Offers-only sync  
- Category mapping  

---

# 🧪 Working With Imports

1. Open Merchant Admin  
2. Update feed URLs  
3. Run Full Import  
4. Go to Category Mapping  
5. Filter → Only Unmapped  
6. Map the new categories  
7. Re-run import to verify  

---

# 🔒 Security

Local: no auth, unrestricted.  
Production: lock everything down.

Admin tools should never be publicly exposed.

---

# 🛣 Roadmap

- Product browser  
- Offer browser  
- Merchant health checks  
- Compatibility intelligence  
- Price tracking  
- Build sharing  
- Category heuristics  
- Deal surfacing  

---

# 🤝 Contributing

- Use feature branches  
- Keep backend calls in `lib/api`  
- Update docs when adding endpoints  
- Test everything with the live backend  

---