# kinyabundi/payflip architecture

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

- Interactive diagram: https://gitdiagram.com/kinyabundi/payflip
- Repository: https://github.com/kinyabundi/payflip

## Overview

PayFlip is a role-based marketplace supporting merchant product management and buyer product discovery, with local-currency checkout intended to deliver stablecoins to merchants. The visible entry point authenticates users and looks up their on-chain role; merchant product creation submits a smart-account operation, while the payment modal calls Kotani’s fiat checkout and wallet-transfer APIs. The tree shows buyer and merchant routes and components, but their implementation excerpts are unavailable, so their internal wiring is not asserted. The README provides no additional product documentation.

Main entry points: [`src/app/page.tsx`](https://github.com/kinyabundi/payflip/blob/main/src/app/page.tsx) (Home and role lookup), [`src/app/app/_components/AddProduct.tsx`](https://github.com/kinyabundi/payflip/blob/main/src/app/app/_components/AddProduct.tsx) (Add product form), [`src/context/AuthContext.tsx`](https://github.com/kinyabundi/payflip/blob/main/src/context/AuthContext.tsx) (Authentication context), [`src/app/app/buyer/products/view/page.tsx`](https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/products/view/page.tsx) (Product browsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and roles"]
  node_home["Home and role lookup<br/>[page.tsx]"]
  node_auth["Authentication context<br/>[AuthContext.tsx]"]
  node_login["Login page<br/>[page.tsx]"]
  node_roles["Role selection<br/>[roles.tsx]"]
  node_buyer_onboarding["Buyer onboarding<br/>[page.tsx]"]
  node_merchant_onboarding["Merchant onboarding<br/>[page.tsx]"]
end

subgraph group_merchant["Merchant marketplace"]
  node_merchant_dashboard["Merchant dashboard<br/>[page.tsx]"]
  node_merchant_new["New product route<br/>[page.tsx]"]
  node_add_product["Add product form<br/>[AddProduct.tsx]"]
  node_merchant_products["Merchant product view<br/>[page.tsx]"]
  node_merchant_layout["Merchant product layout<br/>[layout.tsx]"]
end

subgraph group_buyer["Buyer marketplace"]
  node_buyer_products["Product browsing<br/>[page.tsx]"]
  node_buyer_layout["Buyer product layout<br/>[layout.tsx]"]
  node_pay_modal["Fiat-to-crypto payment<br/>[pay.tsx]"]
end

subgraph group_chain["Chain and payments"]
  node_contract_abi["Marketplace contract interface<br/>[contract.ts]"]
  node_rpc_proxy["Alchemy RPC proxy<br/>[route.ts]"]
  node_chain_rpc["Chain RPC route<br/>[route.ts]"]
  node_account_config["Account configuration<br/>[config.ts]"]
end

subgraph group_presentation["Application shell"]
  node_app_shell["Application providers<br/>[providers.tsx]"]
  node_app_layout["Root layout<br/>[layout.tsx]"]
end

node_visitor(("Visitor or user"))
node_alchemy(("Alchemy services"))
node_blockchain[("Marketplace blockchain")]
node_kotani(("Kotani Pay API"))

node_visitor -->|"opens"| node_home
node_visitor -->|"opens"| node_login
node_home -->|"reads session"| node_auth
node_login -->|"authenticates"| node_auth
node_auth -->|"uses auth hooks"| node_alchemy
node_home -->|"looks up role"| node_blockchain
node_home -->|"calls ABI method"| node_contract_abi
node_visitor -->|"selects role"| node_roles
node_visitor -->|"starts onboarding"| node_buyer_onboarding
node_visitor -->|"starts onboarding"| node_merchant_onboarding
node_visitor -->|"browses"| node_buyer_products
node_buyer_products -->|"initiates payment"| node_pay_modal
node_pay_modal -->|"submits checkout and transfer"| node_kotani
node_visitor -->|"manages products"| node_merchant_dashboard
node_visitor -->|"adds product"| node_merchant_new
node_merchant_new -->|"renders form"| node_add_product
node_add_product -->|"encodes addProduct"| node_contract_abi
node_add_product -->|"submits user operation"| node_alchemy
node_alchemy -->|"sends operation"| node_blockchain
node_visitor -->|"views products"| node_merchant_products
node_rpc_proxy -.->|"forwards RPC request"| node_alchemy
node_chain_rpc -.->|"forwards chain RPC"| node_alchemy
node_app_layout -->|"provides app"| node_app_shell
node_buyer_layout -->|"wraps route"| node_buyer_products
node_merchant_layout -->|"wraps merchant routes"| node_merchant_dashboard
node_account_config -->|"configures account client"| node_alchemy

click node_home "https://github.com/kinyabundi/payflip/blob/main/src/app/page.tsx"
click node_auth "https://github.com/kinyabundi/payflip/blob/main/src/context/AuthContext.tsx"
click node_login "https://github.com/kinyabundi/payflip/blob/main/src/app/app/login/page.tsx"
click node_roles "https://github.com/kinyabundi/payflip/blob/main/src/components/modal/roles.tsx"
click node_buyer_onboarding "https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/onboarding/page.tsx"
click node_merchant_onboarding "https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/onboarding/page.tsx"
click node_contract_abi "https://github.com/kinyabundi/payflip/blob/main/src/abi/contract.ts"
click node_buyer_products "https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/products/view/page.tsx"
click node_buyer_layout "https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/products/layout.tsx"
click node_pay_modal "https://github.com/kinyabundi/payflip/blob/main/src/components/modal/pay.tsx"
click node_merchant_dashboard "https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/dashboard/page.tsx"
click node_merchant_new "https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/new/page.tsx"
click node_add_product "https://github.com/kinyabundi/payflip/blob/main/src/app/app/_components/AddProduct.tsx"
click node_merchant_products "https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/view/page.tsx"
click node_merchant_layout "https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/layout.tsx"
click node_rpc_proxy "https://github.com/kinyabundi/payflip/blob/main/src/app/api/rpc/%5B...routes%5D/route.ts"
click node_chain_rpc "https://github.com/kinyabundi/payflip/blob/main/src/app/api/rpc/chain/%5Bid%5D/route.ts"
click node_account_config "https://github.com/kinyabundi/payflip/blob/main/src/lib/config.ts"
click node_app_shell "https://github.com/kinyabundi/payflip/blob/main/src/app/providers.tsx"
click node_app_layout "https://github.com/kinyabundi/payflip/blob/main/src/app/layout.tsx"

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_auth,node_login,node_roles,node_buyer_onboarding,node_merchant_onboarding,node_visitor toneBlue
class node_merchant_dashboard,node_merchant_new,node_add_product,node_merchant_products,node_merchant_layout,node_blockchain toneAmber
class node_buyer_products,node_buyer_layout,node_pay_modal,node_kotani toneMint
class node_contract_abi,node_rpc_proxy,node_chain_rpc,node_account_config toneRose
class node_app_shell,node_app_layout,node_alchemy toneIndigo
```

## Components

### Identity and roles

- [Home and role lookup](https://github.com/kinyabundi/payflip/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Authentication context](https://github.com/kinyabundi/payflip/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Login page](https://github.com/kinyabundi/payflip/blob/main/src/app/app/login/page.tsx): `src/app/app/login/page.tsx`
- [Role selection](https://github.com/kinyabundi/payflip/blob/main/src/components/modal/roles.tsx): `src/components/modal/roles.tsx`
- [Buyer onboarding](https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/onboarding/page.tsx): `src/app/app/buyer/onboarding/page.tsx`
- [Merchant onboarding](https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/onboarding/page.tsx): `src/app/app/merchant/onboarding/page.tsx`

### Merchant marketplace

- [Merchant dashboard](https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/dashboard/page.tsx): `src/app/app/merchant/product/dashboard/page.tsx`
- [New product route](https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/new/page.tsx): `src/app/app/merchant/product/new/page.tsx`
- [Add product form](https://github.com/kinyabundi/payflip/blob/main/src/app/app/_components/AddProduct.tsx): `src/app/app/_components/AddProduct.tsx`
- [Merchant product view](https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/view/page.tsx): `src/app/app/merchant/product/view/page.tsx`
- [Merchant product layout](https://github.com/kinyabundi/payflip/blob/main/src/app/app/merchant/product/layout.tsx): `src/app/app/merchant/product/layout.tsx`

### Buyer marketplace

- [Product browsing](https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/products/view/page.tsx): `src/app/app/buyer/products/view/page.tsx`
- [Buyer product layout](https://github.com/kinyabundi/payflip/blob/main/src/app/app/buyer/products/layout.tsx): `src/app/app/buyer/products/layout.tsx`
- [Fiat-to-crypto payment](https://github.com/kinyabundi/payflip/blob/main/src/components/modal/pay.tsx): `src/components/modal/pay.tsx`

### Chain and payments

- [Marketplace contract interface](https://github.com/kinyabundi/payflip/blob/main/src/abi/contract.ts): `src/abi/contract.ts`
- [Alchemy RPC proxy](https://github.com/kinyabundi/payflip/blob/main/src/app/api/rpc/%5B...routes%5D/route.ts): `src/app/api/rpc/[...routes]/route.ts`
- [Chain RPC route](https://github.com/kinyabundi/payflip/blob/main/src/app/api/rpc/chain/%5Bid%5D/route.ts): `src/app/api/rpc/chain/[id]/route.ts`
- [Account configuration](https://github.com/kinyabundi/payflip/blob/main/src/lib/config.ts): `src/lib/config.ts`

### Application shell

- [Application providers](https://github.com/kinyabundi/payflip/blob/main/src/app/providers.tsx): `src/app/providers.tsx`
- [Root layout](https://github.com/kinyabundi/payflip/blob/main/src/app/layout.tsx): `src/app/layout.tsx`

### Other components

- **Visitor or user**
- **Alchemy services**
- **Marketplace blockchain**
- **Kotani Pay API**

## Connections

- Visitor or user → Home and role lookup: opens
- Visitor or user → Login page: opens
- Home and role lookup → Authentication context: reads session
- Login page → Authentication context: authenticates
- Authentication context → Alchemy services: uses auth hooks
- Home and role lookup → Marketplace blockchain: looks up role
- Home and role lookup → Marketplace contract interface: calls ABI method
- Visitor or user → Role selection: selects role
- Visitor or user → Buyer onboarding: starts onboarding
- Visitor or user → Merchant onboarding: starts onboarding
- Visitor or user → Product browsing: browses
- Product browsing → Fiat-to-crypto payment: initiates payment
- Fiat-to-crypto payment → Kotani Pay API: submits checkout and transfer
- Visitor or user → Merchant dashboard: manages products
- Visitor or user → New product route: adds product
- New product route → Add product form: renders form
- Add product form → Marketplace contract interface: encodes addProduct
- Add product form → Alchemy services: submits user operation
- Alchemy services → Marketplace blockchain: sends operation
- Visitor or user → Merchant product view: views products
- Alchemy RPC proxy → Alchemy services: forwards RPC request
- Chain RPC route → Alchemy services: forwards chain RPC
- Root layout → Application providers: provides app
- Buyer product layout → Product browsing: wraps route
- Merchant product layout → Merchant dashboard: wraps merchant routes
- Account configuration → Alchemy services: configures account client