171 lines
3.1 KiB
Markdown
171 lines
3.1 KiB
Markdown
# 🧨 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
|
||
|
||
--- |