Rental Platform

🗄️ DATABASE: PostgreSQL
│
├─ operators             Business owners (fleet managers)
├─ renters               Customers who book equipment
├─ equipment             Trailers, tools, vehicles in the fleet
├─ bookings              Rental reservations with status tracking
├─ stripe_accounts       Connect account links for operators
└─ payments              Charges, refunds, platform fees

🖥️ INTERFACE: Next.js 14 (App Router)
│
├─ /dashboard            Operator control panel (fleet, bookings, earnings)
├─ /equipment            Public equipment listings
├─ /booking              Multi-step booking flow
├─ /account              Renter profile, booking history
└─ /onboarding           Stripe Connect setup for operators

⚡ API LOGIC: Next.js API Routes + Service Layer
│
├─ /api/v1/equipment     CRUD for fleet management
├─ /api/v1/bookings      Booking creation, status updates
├─ /api/v1/payments      Stripe charge orchestration
├─ /api/v1/identity      Cross-app identity check (calls Platform API)
└─ src/services/         Business logic (booking.service, stripe.service)

1. Renter browses equipment (public, no login required)
   └─ /equipment → SSR page with all available trailers/tools

2. Renter selects dates & equipment
   └─ Multi-step form: dates → equipment → delivery address

3. Price calculation (server-side service layer)
   └─ booking.service.ts calculates:
       ├─ Rental fee (daily rate × days)
       ├─ Tax (8.6% Arizona TPT on rental only, not deposit)
       ├─ Deposit (configurable per equipment, max 5× daily rate)
       └─ Platform fee (10% of total, covers Stripe fees)

4. Payment via Stripe Connect
   └─ Charge goes to OPERATOR's Stripe account
   └─ Platform fee automatically deducted
   └─ Deposit held separately (not released to operator yet)

5. Booking created with status: pending_pickup
   └─ Operator sees booking in dashboard
   └─ Renter gets confirmation email

6. Status transitions:
   pending_pickup → active → returned → completed
   (or: pending_pickup → cancelled → deposit_refunded)

OPERATOR ONBOARDING:
1. Operator clicks "Enable Payments" in dashboard
2. System creates Stripe Connect account
3. Operator redirected to Stripe-hosted onboarding
4. Stripe collects bank info, tax IDs, etc.
5. Operator redirected back to platform
6. We save Stripe account ID → stripe_accounts table

BOOKING PAYMENT:
1. Renter enters card info (Stripe Checkout or Elements)
2. We create charge via Stripe API:
   stripe.charges.create({
     amount: totalCents,
     currency: 'usd',
     destination: operator.stripeAccountId,  // ← Money goes HERE
     application_fee_amount: platformFeeCents  // ← We keep this
   })
3. Money lands in operator's account (minus platform fee)
4. Deposit held as separate authorization (released later)

1. Check local database (renters.identity_verified)
   └─ ❌ Not verified locally

2. Call Platform API (3-second timeout):
   GET http://api.bened.works/api/identity/{keycloakId}
   └─ ✅ User verified on TradeCraft (for live trading)

3. Sync verification locally:
   UPDATE renters SET 
     identity_verified = true,
     legal_name = 'John Doe',
     verification_source = 'tradecraft'
   WHERE keycloak_id = '...'

4. Booking proceeds without re-verification

FILE: src/app/api/v1/bookings/route.ts
────────────────────────────────────────
export async function POST(request: Request) {
  const { user } = await getAuthenticatedUser();
  if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  
  const bookingData = await request.json();
  
  // ❌ NEVER DO THIS:
  // await sql`INSERT INTO bookings ...`
  
  // ✅ DO THIS:
  const booking = await bookingService.createBooking(user.sub, bookingData);
  
  return NextResponse.json({ data: booking });
}

FILE: src/services/booking.service.ts
──────────────────────────────────────
export async function createBooking(userId: string, data: BookingData) {
  // Business logic here:
  // - Validate dates
  // - Check equipment availability
  // - Calculate pricing
  // - Create Stripe charge
  // - Insert booking record
  // - Send confirmation email
  
  return booking;
}

CREATE TABLE bookings (
    id SERIAL PRIMARY KEY,
    renter_id INT REFERENCES renters(id),
    operator_id INT REFERENCES operators(id),
    equipment_id INT REFERENCES equipment(id),
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    status VARCHAR(50) DEFAULT 'pending_pickup',
    -- Financial breakdown (all in cents):
    rental_amount INT NOT NULL,
    tax_amount INT NOT NULL,
    deposit_amount INT NOT NULL,
    platform_fee INT NOT NULL,
    total_charged INT NOT NULL,
    stripe_charge_id VARCHAR(255),
    stripe_deposit_auth_id VARCHAR(255),
    created_at TIMESTAMP DEFAULT NOW()
);

STAGING DEPLOY (Hot Reload for Dev):
1. docker stop bened-trailers-staging
2. cd /opt/bened-rental && npm run dev
3. Nginx proxies to dev server
4. Changes reflect instantly (hot module replacement)

PRODUCTION DEPLOY (Docker Build):
1. cd /opt/bened-rental
2. docker build -t bened-trailers:latest \\
     --build-arg NEXT_PUBLIC_APP_URL=https://trailers.bened.works \\
     --no-cache .
3. docker stop bened-rental && docker rm bened-rental
4. docker run -d --name bened-rental \\
     --network bened-platform_bened-network \\
     --env-file .env \\
     bened-trailers:latest
5. Nginx at trailers.bened.works proxies to new container