`MEMBERSHIP_PLATFORM_README.md`

406 lines
# Tokenized Wine Membership Platform

A complete blockchain-style membership system for rare wine bottles with governance voting, sample unlocking, and marketplace trading.

## 🚀 Live Application

**Main Dashboard:** http://45.61.58.125:7250/membership
**API Base URL:** http://45.61.58.125:7250/api/membership

---

## ✨ Features

### 1. **Tokenized Bottle Ownership**
- Each rare bottle is divided into membership units (tokens)
- Members own fractional rights to the bottle
- Complete provenance and authenticity tracking
- Digital records with cryptographic hashing

### 2. **Governance Voting System**
- Token holders vote on bottle decisions
- Proposals include: unlocking bottles, creating samples, hosting events
- Customizable quorum requirements (default: 50%)
- Approval thresholds (default: 66%)
- Real-time vote tracking and results

### 3. **Sample Unit Generation**
- When bottles are "unlocked" via governance, they become sample units
- Professional fulfillment partners handle all physical aspects
- Sample units remain tradable before redemption
- Complete digital provenance chain

### 4. **Marketplace Trading**
- Trade membership units before redemption
- Transfer sample rights peer-to-peer
- Price discovery through open market
- Platform handles ownership transfers atomically

### 5. **Legal Compliance**
- No direct alcohol handling by platform
- Licensed fulfillment partners in multiple states
- Age verification (21+)
- State-specific shipping restrictions
- Audit trail for all transactions

---

## 📊 Current System Data

### Bottles in System
1. **Château Margaux 1996**
   - 100 total membership units
   - 75 available
   - Estimated value: $15,000
   - Status: Active (voting in progress)

2. **DRC La Tâche 2005**
   - 50 total membership units
   - 50 available
   - Estimated value: $25,000
   - Status: Active

### Active Governance Vote
- **Proposal:** Unlock Château Margaux for sampling event
- **Status:** Active (ends in 5 days)
- **Current tally:** 18 For, 3 Against, 1 Abstain
- **Quorum:** 44% (need 50%)

---

## 🔌 API Endpoints

### Bottles
```bash
# Get all bottles
GET /api/membership/bottles

# Get bottle details with members and votes
GET /api/membership/bottles/:id

# Create new bottle (admin)
POST /api/membership/bottles
{
  "name": "Wine Name",
  "vintage": 2005,
  "producer": "Producer Name",
  "region": "Region",
  "size": "750ml",
  "totalMembershipUnits": 100,
  "availableMembershipUnits": 100,
  "estimatedValue": 10000,
  "provenance": "Provenance details...",
  "status": "active"
}
```

### Governance Voting
```bash
# Get all votes (or filter by bottle/active status)
GET /api/membership/votes?bottleId=:id&active=true

# Create new vote proposal
POST /api/membership/votes
{
  "bottleId": "bottle_123",
  "proposal": "Unlock bottle for tasting",
  "proposalType": "unlock",
  "description": "Detailed description...",
  "startDate": "2025-01-01",
  "endDate": "2025-01-08",
  "quorumRequired": 50,
  "approvalThreshold": 66,
  "createdBy": "admin"
}

# Cast a vote
POST /api/membership/votes/:id/cast
{
  "userId": "user_123",
  "membershipUnitId": "unit_456",
  "choice": "for" | "against" | "abstain"
}

# Execute a vote (triggers sample creation if passed)
POST /api/membership/votes/:id/execute
```

### Marketplace
```bash
# Get marketplace listings
GET /api/membership/marketplace?active=true

# Create listing
POST /api/membership/marketplace
{
  "listingType": "membership" | "sample-right",
  "itemId": "unit_or_right_id",
  "bottleId": "bottle_123",
  "sellerId": "user_123",
  "sellerName": "Seller Name",
  "price": 200,
  "currency": "USD",
  "status": "active"
}

# Purchase listing
POST /api/membership/marketplace/:id/purchase
{
  "buyerId": "user_456",
  "buyerEmail": "buyer@example.com",
  "buyerName": "Buyer Name"
}
```

### Sample Units
```bash
# Get sample units
GET /api/membership/samples?bottleId=:id&available=true
```

### Fulfillment
```bash
# Create fulfillment request (redeem sample)
POST /api/membership/fulfillment
{
  "sampleRightId": "right_123",
  "userId": "user_123",
  "userEmail": "user@example.com",
  "shippingAddress": {
    "name": "John Doe",
    "addressLine1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zipCode": "90001",
    "country": "USA",
    "phone": "+1234567890"
  }
}

# Get fulfillment requests
GET /api/membership/fulfillment?userId=:id
```

---

## 💡 How It Works

### 1. **Bottle Listing**
Rare bottles are tokenized into membership units. Each unit represents fractional ownership and voting rights.

### 2. **Governance Process**
Members vote on proposals using their membership units. Each unit = 1 vote.

```
Proposal Created → Voting Period (7 days) → Quorum Check → Approval Check → Execution
```

### 3. **Unlock Flow**
When an "unlock" vote passes:
1. Bottle status changes to "unlocked"
2. System creates sample units (e.g., 100 × 50ml samples)
3. Sample rights distributed to members proportionally
4. Members can trade or redeem their sample rights

### 4. **Trading Flow**
```
List Item → Buyer Purchases → Ownership Transferred → Digital Record Created
```

### 5. **Redemption Flow**
```
Request Redemption → Compliance Check → Partner Assignment → Processing → Shipped → Delivered
```

---

## 🏗️ Architecture

### Tech Stack
- **Frontend:** Next.js 16 + React 19 + TailwindCSS
- **Backend:** Next.js API Routes
- **Data Layer:** In-memory database (easily swappable for PostgreSQL/MongoDB)
- **Deployment:** PM2 process manager

### Data Models
```
Bottle
├── MembershipUnits (1:many)
├── GovernanceVotes (1:many)
└── SampleUnits (1:many)

MembershipUnit
├── Owner (UserProfile)
├── TransactionHistory
└── Votes

GovernanceVote
├── Votes (many)
└── SampleUnits (created when executed)

SampleUnit
└── SampleRight (1:1)
    ├── Owner
    ├── TransferHistory
    └── FulfillmentRequest
```

### Digital Records
Every significant action creates an immutable digital record with:
- Cryptographic hash
- Previous hash (blockchain-style chain)
- Timestamp
- Entity data snapshot

---

## 🎨 User Interface

### Dashboard Tabs

**1. Bottles Tab**
- Browse all available bottles
- View membership unit availability
- See estimated values and provenance
- Purchase membership units

**2. Governance Tab**
- View active proposals
- Cast votes with your membership units
- Track voting progress
- See quorum and approval metrics

**3. Marketplace Tab**
- Browse listings for membership units and sample rights
- Purchase from other members
- See price history

**4. My Holdings Tab**
- View your membership units
- Manage your sample rights
- List items for sale
- Request redemption

---

## 🔐 Legal Compliance Features

### Platform Never Handles Alcohol
- All physical handling by licensed partners
- Platform provides digital membership rights only
- Sample rights are entitlements, not physical goods

### Age Verification
- 21+ verification required
- Integration points for ID verification services

### State Restrictions
- Fulfillment partners mapped to legal states
- Automatic compliance checks before shipping
- Rejection if state not supported

### Licensed Distribution
- All shipments through licensed distributors
- Proper permits and documentation
- Audit trail for regulatory compliance

---

## 📱 Example Use Cases

### Use Case 1: Rare Bottle Investment
1. Investor buys 10 membership units in Château Margaux 1996
2. Holds units as bottle appreciates in value
3. Votes on governance decisions
4. Sells units at profit when value increases

### Use Case 2: Wine Collector Tasting
1. Collector owns 5 membership units
2. Votes "For" on unlock proposal
3. Receives 5 sample rights (50ml each)
4. Redeems 2 samples for personal tasting
5. Sells remaining 3 sample rights on marketplace

### Use Case 3: Group Tasting Event
1. Wine club votes to unlock bottle for event
2. Proposal passes with 80% approval
3. 100 samples created
4. Club coordinates redemption for event
5. Members attend exclusive tasting

---

## 🚀 Future Enhancements

### Blockchain Integration
- Ethereum or Polygon smart contracts
- NFT-based membership units
- On-chain governance voting
- Crypto payment integration

### Enhanced Features
- Dutch auction for initial unit sales
- Fractional reserve system
- Insurance integration
- Professional authentication services
- AR/VR bottle viewing
- Sommelier tasting notes
- Investment analytics dashboard

### Platform Expansion
- Support for spirits, rare whiskeys
- Wine futures/en primeur support
- Cellar management integration
- Social features (clubs, groups)
- Mobile apps (iOS/Android)

---

## 🧪 Testing the System

### Test Voting
```bash
# Cast a vote
curl -X POST http://45.61.58.125:7250/api/membership/votes/VOTE_ID/cast \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_1",
    "membershipUnitId": "unit_YOUR_ID",
    "choice": "for"
  }'
```

### Test Marketplace Purchase
```bash
curl -X POST http://45.61.58.125:7250/api/membership/marketplace/LISTING_ID/purchase \
  -H "Content-Type: application/json" \
  -d '{
    "buyerId": "user_1",
    "buyerEmail": "test@example.com",
    "buyerName": "Test Buyer"
  }'
```

---

## 📞 Support & Contact

For questions or issues:
- Check the API documentation above
- Review the codebase in `/root/Projects/wine-finder-next`
- Examine the type definitions in `/src/types/membership.ts`

---

## 📄 License & Legal

This platform facilitates membership rights and governance, not direct alcohol sales. All alcohol handling is performed by licensed third-party fulfillment partners in compliance with local, state, and federal regulations.

**Platform operates as:** Digital membership service
**Not operates as:** Alcohol retailer or distributor
**Physical fulfillment by:** Licensed partners with proper permits

---

**Built with ❤️ for rare wine enthusiasts**