> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcm.game/llms.txt
> Use this file to discover all available pages before exploring further.

# Walkthrough

# Walkthrough - Sprint 15: The Global Market & Gacha System

We have successfully designed, built, integrated, and verified the complete feature set for **Sprint 15 (The Global Market & Gacha System)** within the `pcmtg-core` monorepo. This implementation guarantees full compliance with the macroeconomic rules, zero-trust transactional mechanics, and Cloud Run scaling constraints defined in the PCMTG Project Bible.

***

## 🧱 Architectural System Sequence Flow

The following sequence diagram illustrates the Zero-Trust execution path of a player's transaction under horizontal container scaling. Memorystore (Redis) gates ingress rate limits, and Postgres row-level locks protect balance ledger mutability.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Client as Player Client (Next.js)
    participant LB as Cloud Run Load Balancer
    participant Redis as Memorystore (Redis)
    participant DB as Neon Postgres (Row Lock)

    Client->>LB: Request POST /market/buy-item { cardId }
    LB->>Redis: Evaluate Rate Limit (MULTI/EXEC Sliding Window)
    alt Request Count > 5 per 10s
        Redis-->>LB: Limit Exceeded (Count > 5)
        LB-->>Client: HTTP 429 Too Many Requests
    else Limit Under Bound
        Redis-->>LB: Rate Limit OK (Count <= 5)
        LB->>DB: SELECT FOR UPDATE on player_wallets (Pessimistic exclusive row lock)
        Note over DB: Lock acquired. Concurrent race requests wait.
        LB->>DB: Query declared quadrant directly from player_accounts
        LB->>DB: Query card costs and verify balances
        alt Insufficient funds OR duplicate modifier detected
            LB-->>Client: HTTP 400 Bad Request (Transaction Aborted & Rolled Back)
        else Balance and Duplicates Validated
            LB->>DB: Update player_wallets balance
            LB->>DB: Create OwnedCard connection
            LB->>DB: Insert TransactionLog receipt
            DB-->>LB: Commit Interactive Transaction (Row Lock Released)
            LB-->>Client: HTTP 201 Created (Returned Minted Card & New Wallet)
        end
    end
```

***

## 🚀 Key Achievements

### 1. Zero-Trust Transaction Ledger (Atomic Economy)

* **File:** [market.js](file:///home/andrew/pcmtg-core/backend/src/routes/market.js)
* **Implementation:** To eliminate race conditions and double-spending, all market actions are handled inside secure `prisma.$transaction` blocks.
  * An exclusive, pessimistic row lock is obtained on the player's wallet using raw SQL `FOR UPDATE` prior to checking or validating any fund balances:
    ```javascript theme={null}
    await tx.$executeRaw`SELECT * FROM player_wallets WHERE player_id = ${playerId}::uuid FOR UPDATE;`;
    ```
  * The transaction block atomically deducts native funds, inserts a record into the `OwnedCard` table, logs the action into the ledger (`TransactionLog`), and commits or rolls back as a single atomic unit.

### 2. Identity & "Based Pill" Defection Protection

* **File:** [market.js](file:///home/andrew/pcmtg-core/backend/src/routes/market.js)
* **Implementation:** Rather than dynamically deriving a user's alignment from coordinate standings (which would break defection mechanics), we query the explicitly declared `quadrant` string field directly from `PlayerAccount`.
  * Currencies are securely mapped directly to native currencies as per **Project Bible §3.2.5**:
    * `AUTH_RIGHT` $\rightarrow$ `dinars`
    * `AUTH_LEFT` $\rightarrow$ `labor`
    * `LIB_LEFT` $\rightarrow$ `pronouns`
    * `LIB_RIGHT` $\rightarrow$ `monke`

### 3. Asymmetric Cross-Quadrant Gacha Mechanics

* **File:** [market.js](file:///home/andrew/pcmtg-core/backend/src/routes/market.js)
* **Implementation:** Refactored `POST /market/buy-pack` to accept `{ targetQuadrant }` in the payload.
  * **Pricing Model:** Native synthesis packs cost **20 units** of native currency, while defector synthesis (cross-quadrant) packs cost **50 units** representing the ideological defection tax.
  * **Gacha Candidates & Cryptographic Randomness:** Uses the cryptographically secure server-side Node.js `crypto.randomInt` module for rolling rarity categories and selecting candidate cards to prevent client-side prediction:
    * `COMMON`: 60%
    * `UNCOMMON`: 25%
    * `RARE`: 10%
    * `EPIC`: 4%
    * `LEGENDARY`: 1%
  * Queries are strictly filtered by `cardType = 'MEME'` and `affinity = targetQuadrant` with automatic fallback mapping if specific rarities are temporarily unavailable.

### 4. Serverless-Safe Sliding-Window Rate Limiter

* **File:** [rateLimiter.js](file:///home/andrew/pcmtg-core/backend/src/middleware/rateLimiter.js)
* **Implementation:** Implemented an active sliding-window rate limiter using a Google Cloud Memorystore (Redis) instance (via `ioredis`).
  * Utilizes atomic Redis pipeline transactions (`MULTI/EXEC`) with sorted sets (`ZSET`) to log and clear timestamps per player id:
    ```javascript theme={null}
    const multi = redis.multi();
    multi.zremrangebyscore(key, 0, clearBefore);
    multi.zadd(key, now, now);
    multi.zcard(key);
    multi.expire(key, 10);
    ```
  * Strictly limits all `/market/*` endpoints to **5 requests per 10 seconds** per player.
  * Designed with defensive fail-open parameters to preserve game playability if Redis encounters transient cloud network outages.

### 5. Premium Glassmorphic Frontend Page

* **File:** [page.tsx](file:///home/andrew/pcmtg-core/frontend/app/market/page.tsx)
* **Implementation:** Structured a responsive layout styled using pure CSS 3D perspectives, custom booster-pack flip animations, and glassmorphic micro-layouts.
  * **Interactive State Flows:** Toggles tabs seamlessly between `Spot Market` (individual items/policies) and `Meme Bazaar` (booster synthesis packs).
  * **Active State Syncing:** Syncs with the global layout `<WalletOverlay />` by triggering silent UI balance updates immediately on successful transaction receipts.
  * **Overlay Animations:** Provides immersive, high-fidelity card-opening animations: shaking booster packs, tearing wrappers, realistic card-flip perspective rotations, and rarity-colored radial glow drops (silver for `COMMON` up to celestial golden fire animations for `LEGENDARY`).

***

## 🧪 Verification Results

We executed the end-to-end integration test suite in [test-market.js](file:///home/andrew/pcmtg-core/backend/test-market.js) utilizing an in-memory `ioredis` mocking interceptor to validate functionality against the live Neon Postgres database.

### Test Execution Log Output

```text theme={null}
◇ injected env (3) from .env
🏁 STARTING SPRINT 15 GLOBAL MARKET & GACHA INTEGRATION TESTS...

👤 STEP 1: Finding or creating test user in Postgres...
✅ Reset existing player: MarketTester (ID: 978dfb6b-83c0-49e4-9a9a-18addb6231e6)

🃏 STEP 2: Seeding mock items, policies, and memes for Gacha rolling...
✅ Seeding mock card assets completed successfully.

🚀 STEP 3: Starting local test server on port 8082...
PCMTG Mechanical Room live on port 8082
[REDIS CONNECTED] Successfully connected to Redis instance.

🛑 STEP 4: Testing sliding-window rate-limiter protection on Memorystore...
- Request status codes: [200, 200, 200, 200, 200, 429, 429, 429, 429, 429]
- Throttled requests (429): 5
✅ Rate limiter throttled requests beautifully as expected.

⏳ Cooling down sliding window rate limiter (10 seconds)...

💸 STEP 5: Testing single item purchase with atomic balances...
- Server purchase response: {
  success: true,
  message: 'Item purchased successfully.',
  card: {
    id: '00000000-0000-0000-0000-000000000001',
    name: 'Automated Lobby Lobbyist',
    marketCostDinars: 15,
    ...
  },
  cost: 15,
  currency: 'dinars',
  wallet: { dinars: 85, labor: 100, pronouns: 100, monke: 100 }
}
- Wallet balance after item: Dinars = 85 (expected: 85)
✅ Spot market purchase test passed perfectly!

🚫 STEP 6: Testing duplicate unique modifier purchases...
[POST /market/buy-item ERROR]: DuplicateItemForbidden
- Server duplicate response: { error: 'You already own this unique modifier card.' }
✅ Duplicate unique modifier protection worked perfectly!

🎰 STEP 7: Testing Asymmetric Gacha Synthesis & Cross-Quadrant Economy...
- Action: Buying matching/native quadrant pack ("AUTH_RIGHT"). Expected cost: 20 Dinars.
- Native Gacha Result cards: [
  'The Bottomless Brainlet (AUTH_RIGHT)',
  'Caius Cosades Wojak (AUTH_RIGHT)',
  'Zoomer Wojak (AUTH_RIGHT)'
]
- Native Gacha reported cost: 20 (expected: 20)
- Wallet after native Gacha: 65 Dinars (expected: 65)

- Action: Buying defected/opposing quadrant pack ("AUTH_LEFT"). Expected cost: 50 Dinars.
- Opposing Gacha Result cards: [
  'Rainbow Wojak (AUTH_LEFT)',
  'Zoomer Girl (AUTH_LEFT)',
  'Crying Wojak Facepalm (AUTH_LEFT)'
]
- Opposing Gacha reported cost: 50 (expected: 50)
- Wallet after opposing Gacha: 15 Dinars (expected: 15)
✅ Asymmetric pricing and card affinity boundaries verified perfectly!

🎉 ALL SPRINT 15 MARKET & GACHA INTEGRATION TESTS PASSED PERFECTLY!
```

***

## 🔒 Security & Defensive Guardrails Met

1. **Race-Condition Elimination:** Exclusive locked updates protect the balance check and card-minting sequences.
2. **Duplicate Modifier Seal:** A single player cannot buy multiples of the same unique passive item or policy card.
3. **Sybil & DDoS Mitigation:** The horizontal Memorystore sliding window instantly isolates and blocks brute-force purchase attempts.
4. **Cryptographic Anti-Tampering:** Card rarity outcomes are computed strictly backend-side using random numbers derived from node's native secure entropy generator.