Touli Gift Economy Flowcharts

How points become gifts, how gifts are matched and claimed, and how the loop closes back into better matching.

Sources: AI Engine Build Instructions v1.3, Gift Catalogue v4.2, How It Works (users).

---

1. End-to-end gift economy (citizen view)

flowchart TD
  subgraph earn [Earn Impact]
    A[Do a good deed] --> B[Submit evidence]
    B --> C[Verification pipeline]
    C --> D{Approved?}
    D -->|No| E[Rejected or manual review]
    D -->|Yes| F[Points credited to wallet]
  end

  subgraph discover [Discover Gifts]
    F --> G[Nightly gift feed refresh]
    G --> H{Feed state}
    H -->|Balance >= cost| I[Available now]
    H -->|>= 75% of cost| J[Almost there]
    H -->|Below threshold| K[On the horizon]
  end

  subgraph claim [Claim and Collect]
    I --> L[User taps Claim]
    L --> M[Points escrowed]
    M --> N{Gift type}
    N -->|Physical| O[Collect in person within 7 days]
    N -->|Digital or voucher| P[Instant delivery]
    N -->|Group experience| Q[Join slot and show up at venue]
    O --> R[Show QR at counter]
    R --> S[Vendor validates]
    P --> S
    Q --> S
  end

  subgraph close [Close the Loop]
    S --> T[Rate gift and heart vendor or product]
    T --> U[Profile and matching signals updated]
    U --> G
    S --> V[Ledger entry plus optional chain anchor]
  end

  E --> B

---

2. Points to tier ladder

Points are non-transferable and have no cash value. Gift cost is fixed by catalogue tier (One-Cost engine: roughly retail EUR x 33.3).

flowchart LR
  P[Verified impact hours] --> E[55 pts per hour base rate]
  E --> M[Multipliers: verify, group, trust, streak, challenge, diversity]
  M --> W[Wallet balance]

  W --> T1G[Tier I-G Group 100-499]
  W --> T1L[Tier I-L Local 100-499]
  W --> T2[Tier II Standard 500-1499]
  W --> T3[Tier III Premium 1500-2999]
  W --> T4[Tier IV Select 3000-4999]
  W --> T5[Tier V Prestige 5000+]

  T1G --> G1[Group experiences always open]
  T1L --> G2[Coffee, museum, local items]
  T2 --> G3[Dining, books, culture]
  T3 --> G4[Workshops, spa]
  T4 --> G5[Fine dining, VIP]
  T5 --> G6[Getaways, prestige]

Pricing anchor: 1 hour verified impact ≈ EUR 3 retail ≈ 100 catalogue points at baseline verification.

---

3. Gift matchmaking pipeline (system view)

Matching is deterministic — no LLM in the ranking path.

flowchart TD
  A[Nightly batch: build user profile] --> B[Hard filter SQL]
  B --> C{Eligible gifts remain?}
  C -->|No| D[On the horizon only]
  C -->|Yes| E[Weighted score ranker]

  B1[Balance >= cost] --> B
  B2[Account age and tier gates] --> B
  B3[Geo and cultural tags] --> B
  B4[Stock > 0] --> B
  B5[Cadence headroom soft] --> B
  B6[Same-gift repeat rules] --> B

  E --> F[Top 20 cache per user]
  F --> G[Surface feed states]

  W1[Revealed deeds and redemptions 40%] --> E
  W2[Stated hearts x1.5 boost 15%] --> E
  W3[Context geo language season 15%] --> E
  W4[Catalogue health 10%] --> E
  W5[Fairness score 10%] --> E
  W6[Novelty and morale 10%] --> E

---

4. Wave release and fairness (stock allocation)

Popular gifts are limited. Allocation is FCFS inside a fairness-ranked batch, not a raw speed race.

flowchart TD
  A[Weekly stock release from partners] --> B[Compute fairness batch ~2x stock size]
  B --> C[Notify eligible users in batch]
  C --> D[First-come-first-served within batch]
  D --> E{Claim within 48-72h TTL?}
  E -->|Yes| F[Gift reserved plus points escrow]
  E -->|No| G[Unclaimed unit rolls to next batch]
  F --> H[User completes collection window]
  G --> A

  FS[Fairness inputs: first reward, time since last gift, consistency, verification quality, community impact] --> B

---

5. Claim and collect (four-step user flow)

flowchart LR
  S1[1 Claim] --> S2[2 Go in person or instant]
  S2 --> S3[3 Show Touli code or QR]
  S3 --> S4[4 Rate and heart]

  S1 --> E1[Unit reserved]
  S1 --> E2[Points moved to escrow]

  S3 --> V1[Vendor dashboard updated]

  S4 --> L1[Better future matches]

  S2 --> N1{No-show on physical?}
  N1 -->|Yes| N2[Unit released]
  N2 --> N3[Points returned from escrow]

---

6. When a gift is gone (fallback paths)

flowchart TD
  A[Gift out of stock or missed wave] --> B{User choice}
  B --> C[Join waitlist]
  B --> D[Pick same-tier alternative]
  B --> E[Claim group experience I-G floor]
  C --> F[Notified when stock returns]
  D --> G[Claim flow continues]
  E --> G
  G --> H[New gifts drop weekly from local partners]

---

7. Generosity loop (send points as gifts)

Planned product path: earn points, then gift onward for a small bonus on send (not on self-redemption).

flowchart TD
  A[User has redeemable points] --> B{Gift route}
  B -->|Friend| C[Send to connection]
  B -->|AI-matched stranger| D[Anonymous match adult-only policy]
  B -->|Self redemption| E[No generosity bonus]

  C --> F[+10% of gift cost back to sender cap applies]
  D --> G[+15% back cap applies]
  F --> H[Recipient receives gift allocation]
  G --> H
  E --> H

  H --> I[Ledger: gift debit plus optional gift credit]
  I --> J[Chain anchor leaf optional]

Policy: Random stranger gifting is disabled for all users under 18 by default.

---

8. Supply side (where gifts come from)

flowchart LR
  subgraph sources [Three source model]
    S1[Civic and group venues 100-400 slots per month]
    S2[Cafe and bar partners 15-30+ per month]
    S3[Individual human donors 20-40+ per month]
  end

  sources --> P[Gift pool inventory]
  P --> R[Weekly wave release]
  R --> M[Matchmaking and claim]

---

Key rules (quick reference)

Rule	Value
Base earn rate	55 pts / verified hour
Catalogue anchor	~100 pts ≈ EUR 3 retail
Points expiry	12 months account inactivity
Group experience floor	Tier I-G always available
Physical claim window	7 days to collect
Claim reservation TTL	48-72 hours
Matching refresh	Nightly top-20 cache
Generosity bonus	+10% friend, +15% AI-matched stranger (capped)

---

Related architecture docs

• touli-points-dld.md — deterministic scoring and ledger
• touli-api-event-contracts.md — claim and ledger events
• touli-compliance-controls.md — minor gifting restrictions