# benjiewheeler/gift.star architecture

> Architecture diagram of the GitHub repository benjiewheeler/gift.star, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benjiewheeler/gift.star
- Repository: https://github.com/benjiewheeler/gift.star

## Overview

gift.star combines a Svelte web app for creating and managing token claim links with a WAX smart contract that creates, cancels, and claims them. The main journey is a creator preparing a link, the contract securing its token and claim data, and a claimant using the corresponding private key to claim it; the frontend also exposes link views and transaction-derived link lookup. Edges reflect README statements or shown client calls; connections from individual pages to the contract are unverified because their source was not excerpted.

Main entry points: [`frontend/src/lib/index.ts`](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/index.ts) (Link and balance queries), [`contract/contract/src/gift_star.cpp`](https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/src/gift_star.cpp) (Gift link actions), [`frontend/src/routes/trading/link/[id]/+page.svelte`](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/link/%5Bid%5D/%2Bpage.svelte) (Claim link view), [`frontend/src/routes/trading/create/+page.svelte`](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/create/%2Bpage.svelte) (Create link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Gift web app"]
  node_home["Home page<br/>[+page.svelte]"]
  node_create["Create link<br/>[+page.svelte]"]
  node_linkview["Claim link view<br/>[+page.svelte]"]
  node_linklist["Creator links<br/>[+page.svelte]"]
  node_session["Wallet session<br/>[store.ts]"]
  node_ui["Interface components"]
end

subgraph group_client["Chain client"]
  node_contractclient["Contract client<br/>[contract.ts]"]
  node_chainqueries["Link and balance queries<br/>[index.ts]"]
end

subgraph group_contract["Contract lifecycle"]
  node_giftcontract["Gift link actions<br/>[gift_star.cpp]"]
  node_contracttypes["Contract declarations<br/>[gift_star.hpp]"]
  node_linkstate[("Link records<br/>[gift_star.cpp]")]
end

subgraph group_external["External services"]
  node_wax["WAX API"]
  node_history["Transaction history APIs"]
  node_balanceapi["Light API"]
  node_tokencontract["eosio.token-compatible token"]
end

node_creator(("Gift creator"))
node_claimant(("Link claimant"))

node_creator -->|"prepares gift"| node_create
node_claimant -->|"opens link"| node_linkview
node_creator -->|"creates or cancels"| node_giftcontract
node_claimant -->|"claims with key"| node_giftcontract
node_create -.->|"submits actions"| node_giftcontract
node_linkview -.->|"submits claim"| node_giftcontract
node_linklist -.->|"loads links"| node_chainqueries
node_linkview -.->|"loads link"| node_chainqueries
node_chainqueries -->|"loads contract"| node_contractclient
node_chainqueries -->|"reads tables"| node_wax
node_chainqueries -->|"looks up transaction"| node_history
node_chainqueries -->|"fetches balances"| node_balanceapi
node_giftcontract -->|"supports token standard"| node_tokencontract

click node_home "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/%2Bpage.svelte"
click node_create "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/create/%2Bpage.svelte"
click node_linkview "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/link/%5Bid%5D/%2Bpage.svelte"
click node_linklist "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/links/%2Bpage.svelte"
click node_session "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/store.ts"
click node_ui "https://github.com/benjiewheeler/gift.star/tree/master/frontend/src/lib/components/ui"
click node_contractclient "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/contract.ts"
click node_chainqueries "https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/index.ts"
click node_giftcontract "https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/src/gift_star.cpp"
click node_contracttypes "https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/include/gift_star.hpp"
click node_linkstate "https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/src/gift_star.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_create,node_linkview,node_linklist,node_session,node_ui toneBlue
class node_contractclient,node_chainqueries toneAmber
class node_giftcontract,node_contracttypes,node_linkstate toneMint
class node_wax,node_history,node_balanceapi,node_tokencontract toneRose
class node_creator,node_claimant toneIndigo
```

## Components

### Gift web app

- [Home page](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Create link](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/create/%2Bpage.svelte): `frontend/src/routes/trading/create/+page.svelte`
- [Claim link view](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/link/%5Bid%5D/%2Bpage.svelte): `frontend/src/routes/trading/link/[id]/+page.svelte`
- [Creator links](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/routes/trading/links/%2Bpage.svelte): `frontend/src/routes/trading/links/+page.svelte`
- [Wallet session](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/store.ts): `frontend/src/lib/store.ts`
- [Interface components](https://github.com/benjiewheeler/gift.star/tree/master/frontend/src/lib/components/ui): `frontend/src/lib/components/ui`

### Chain client

- [Contract client](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/contract.ts): `frontend/src/lib/contract.ts`
- [Link and balance queries](https://github.com/benjiewheeler/gift.star/blob/master/frontend/src/lib/index.ts): `frontend/src/lib/index.ts`

### Contract lifecycle

- [Gift link actions](https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/src/gift_star.cpp): `contract/contract/src/gift_star.cpp`
- [Contract declarations](https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/include/gift_star.hpp): `contract/contract/include/gift_star.hpp`
- [Link records](https://github.com/benjiewheeler/gift.star/blob/master/contract/contract/src/gift_star.cpp): `contract/contract/src/gift_star.cpp`

### External services

- **WAX API**
- **Transaction history APIs**
- **Light API**
- **eosio.token-compatible token**

### Other components

- **Gift creator**
- **Link claimant**

## Connections

- Gift creator → Create link: prepares gift
- Link claimant → Claim link view: opens link
- Gift creator → Gift link actions: creates or cancels
- Link claimant → Gift link actions: claims with key
- Create link → Gift link actions: submits actions
- Claim link view → Gift link actions: submits claim
- Creator links → Link and balance queries: loads links
- Claim link view → Link and balance queries: loads link
- Link and balance queries → Contract client: loads contract (evidence: `frontend/src/lib/index.ts`)
- Link and balance queries → WAX API: reads tables (evidence: `frontend/src/lib/index.ts`)
- Link and balance queries → Transaction history APIs: looks up transaction (evidence: `frontend/src/lib/index.ts`)
- Link and balance queries → Light API: fetches balances (evidence: `frontend/src/lib/index.ts`)
- Gift link actions → eosio.token-compatible token: supports token standard
