# Capital Forge League — Online Auction + Donor Driving System

**Built with PHP / Laravel** | AI-assisted starting bids | Region/School progress tracking | Givebutter-inspired CRM & Live Display

This package contains high-fidelity PNG mockups of the proposed software interfaces and a complete architectural blueprint + starter code for implementing the system in Laravel.

## Features (Mapped to Requirements)

### 1. Online Auction (Sports Memorabilia & Trading Cards)
- Silent / timed auctions with real-time bidding (Laravel Reverb / Echo + WebSockets)
- Categories, search, favorites, auto-bid (proxy), outbid notifications
- Individual lot start/end times, buy-now option, bid increments
- Mobile-first bidding experience
- Automatic winner declaration + payment collection
- **AI Starting Bid Engine**: Upload/scan item photo → Vision model identifies card/player/set → market comps lookup → suggests starting bid (40-60% of estimated value) stored as JSON metadata

### 2. Donor Driving Backend (CRM)
- Import donor lists (CSV/JSON)
- Assign donors to interns by **Region** or **School**
- Status pipeline: New → Contacted → Pledged → Donated
- Activity timeline, notes, last contact
- Bulk actions, filters, saved segments
- Full integration with auction winners (bids auto-link to donor profiles)

### 3. Public Progress Visibility
- Live dashboard showing raised totals
- Breakdown **by Region** (map visualization) and **by School** (leaderboards with intern leaders)
- Real-time supporter feed (donations + bids)
- Perfect for interns, partners, and public transparency

### 4. Live Display (Event Big Screen)
- Goal thermometer + progress bar
- Live supporter feed with confetti
- Scan-to-Donate QR + Text-to-Donate
- Rotating auction highlight
- Inspired by Givebutter Live Display

### 5. Embeddable Widgets
- Fundraising thermometers
- Donate buttons
- Progress by school/region snippets

## Tech Stack Recommendation
- **Backend**: Laravel 11+ (PHP 8.3)
- **Auth & Roles**: Laravel Breeze / Jetstream + Spatie Permission (Admin, Intern, Bidder, Public)
- **Real-time**: Laravel Reverb (or Pusher/Ably)
- **Queues**: Laravel Horizon + Redis (bid processing, notifications, AI analysis)
- **Media**: Spatie Media Library
- **Frontend**: Blade + Livewire 3 + Alpine.js + Tailwind CSS (dark neon theme) **or** Inertia.js + Vue/React
- **AI**: xAI Grok Vision / OpenAI GPT-4o Vision API (or local alternative) + JSON market data store or external comps API
- **Payments**: Stripe / PayPal (or Laravel Cashier)
- **JSON**: Heavy use for bid history snapshots, AI analysis results, widget configs, import payloads

## Database Models (Core)

```php
// Key models
- User (with roles)
- Auction
- Lot (belongsTo Auction; hasMany Bids; json: ai_analysis, images_meta)
- Bid
- Campaign (fundraising drive)
- Donor (or Contact; region_id, school_id, assigned_intern_id, status, custom_fields json)
- Donation
- Region
- School
- Assignment (intern ↔ donors)
```

## Sample Code Structure

See the `/code` folder (to be expanded) or the snippets below.

### Example: Lot Model with AI JSON
```php
// app/Models/Lot.php
class Lot extends Model
{
    use HasFactory, SoftDeletes, InteractsWithMedia;

    protected $fillable = [
        'auction_id', 'title', 'description', 'starting_bid', 
        'current_bid', 'buy_now_price', 'reserve_price',
        'starts_at', 'ends_at', 'status', 'ai_analysis', // JSON
        'category_id', 'condition', 'serial_number'
    ];

    protected $casts = [
        'ai_analysis' => 'array',
        'starts_at' => 'datetime',
        'ends_at' => 'datetime',
    ];

    public function bids() { return $this->hasMany(Bid::class)->latest(); }
    public function auction() { return $this->belongsTo(Auction::class); }
    public function highestBid() { return $this->bids()->orderByDesc('amount')->first(); }
}
```

### AI Analysis Service (Starter)
```php
// app/Services/AiLotAnalyzer.php
namespace App\Services;

use OpenAI\Laravel\Facades\OpenAI; // or Grok equivalent
use Illuminate\Support\Facades\Http;

class AiLotAnalyzer
{
    public function analyze(string $imagePath): array
    {
        // 1. Vision call to identify item
        $response = OpenAI::chat()->create([
            'model' => 'gpt-4o',
            'messages' => [
                ['role' => 'system', 'content' => 'You are a sports memorabilia expert. Identify the exact item from the image. Return JSON only: player, year, set, card_number, grade_estimate, condition_notes.'],
                ['role' => 'user', 'content' => [
                    ['type' => 'text', 'text' => 'Analyze this sports card or memorabilia.'],
                    ['type' => 'image_url', 'image_url' => ['url' => 'data:image/jpeg;base64,' . base64_encode(file_get_contents($imagePath))]]
                ]]
            ],
            'response_format' => ['type' => 'json_object']
        ]);

        $id = json_decode($response->choices[0]->message->content, true);

        // 2. Lookup market comps (mock or real API / local JSON store)
        $comps = $this->getMarketComps($id);

        // 3. Calculate suggested start
        $market = $comps['market_value'] ?? 100;
        $suggested = [
            'conservative' => round($market * 0.40, 2),
            'recommended'  => round($market * 0.50, 2),
            'aggressive'   => round($market * 0.60, 2),
        ];

        return [
            'identification' => $id,
            'comps' => $comps,
            'suggested_starting_bids' => $suggested,
            'confidence' => 0.92,
            'analyzed_at' => now()->toIso8601String(),
        ];
    }

    protected function getMarketComps(array $id): array
    {
        // In production: query eBay sold, COMC, PWCC, or your own JSON/db of recent sales
        // For now return structured example matching the mockup
        return [
            'lowest_sale' => 10.90,
            'market_value' => 10.90,
            'highest_sale' => 10.90,
            'source' => 'internal_comps_json'
        ];
    }
}
```

### Real-time Bidding Controller Snippet
```php
// app/Http/Controllers/BidController.php
public function place(Request $request, Lot $lot)
{
    $request->validate(['amount' => 'required|numeric|min:' . ($lot->current_bid + $lot->increment)]);

    // Auth, anti-sniping extension logic, etc.

    $bid = $lot->bids()->create([
        'user_id' => auth()->id(),
        'amount' => $request->amount,
        'is_proxy' => $request->boolean('proxy'),
        'max_proxy' => $request->max_proxy,
    ]);

    $lot->update(['current_bid' => $request->amount]);

    // Broadcast
    broadcast(new BidPlaced($bid))->toOthers();

    // Notify previous high bidder
    // Queue job for outbid email/SMS

    return response()->json(['success' => true, 'bid' => $bid]);
}
```

### Progress Aggregation (by School / Region)
```php
// In CampaignController or dedicated service
public function progress(Campaign $campaign)
{
    $bySchool = Donation::where('campaign_id', $campaign->id)
        ->selectRaw('school_id, SUM(amount) as raised, COUNT(*) as donors')
        ->with('school')
        ->groupBy('school_id')
        ->get();

    $byRegion = // similar with region_id

    return view('progress', compact('campaign', 'bySchool', 'byRegion'));
}
```

## Mockup Images (PNG)

All images are production-ready UI mockups in the CFL dark navy + neon green/blue sports-tech aesthetic:

1. **01-auction-homepage.png** — Public auction landing with featured lots
2. **02-lot-detail-ai-bid.png** — Item page with AI market value + suggested start + live bid history (JSON style)
3. **03-donor-crm-dashboard.png** — Backend donor driving interface with region/school filters & intern assignment
4. **04-progress-by-school-region.png** — Public progress dashboard with map + school leaderboards
5. **05-live-display.png** — Event big-screen Live Display (thermometer, feed, QR, text-to-donate)
6. **06-ai-item-analysis.png** — Admin AI scan/analyze panel that feeds the starting bid

## Next Steps for Lavlesh / Dev Team
1. Scaffold Laravel project with Breeze + Spatie + Media Library + Reverb
2. Implement migrations for the models above
3. Build AI service (start with mock JSON responses, then wire vision API)
4. Real-time bid channel + Livewire components for live updates
5. CSV import for donors + assignment UI
6. Public progress page with Livewire polling or Echo
7. Live Display route (full-screen, no chrome)
8. Theme: Tailwind config with CFL colors (deep navy #0A1628, neon #00FF9D / #00D4FF)

## Branding Notes
- Dark navy / near-black backgrounds
- Neon green (#00FF9D or similar) + electric blue accents
- High visual hierarchy, dynamic cards
- Veteran / athlete / forge motifs
- Florida / Tampa Bay presence where appropriate
- "Greatness" standard — no average UI

Questions or refinements? Ready to generate more screens, full migrations, or Livewire components on request.
