# skyfire-xyz/kyapay architecture

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

- Interactive diagram: https://gitdiagram.com/skyfire-xyz/kyapay
- Repository: https://github.com/skyfire-xyz/kyapay

## Overview

1. **Repository purpose**
   - This repo is primarily a **protocol specification and reference example** repository for **KYAPay**, an identity-linked payment protocol based on **JWT tokens**.
   - It is not a single application or service; the architecture is split between **specification documents** and **example verification code**.

2. **Top-level structure**
   - The root contains mostly **governance, licensing, and specification process documents**: community license, scope, notices, license, governance, contributing, code of conduct, maintainer info.
   - This makes the repo’s first boundary clear: **spec/content governance** vs **code examples**.

3. **Specification and model layer**
   - `docs/data-model.md` defines the **core JWT data model** for KYAPay.
   - `docs/example-api.md` defines the **example API surface** and expected protocol interactions.
   - These docs are the canonical source for how tokens and API exchanges are structured.

4. **Example implementation layer**
   - `code-examples/verifyToken` contains the executable references for token validation.
   - The examples are duplicated in **Python** and **TypeScript**, showing the same protocol logic in two runtimes rather than serving different product features.

5. **Protocol flow: token verification**
   - The main runtime use case is: **receive a KYAPay JWT token → parse/configure protocol inputs → verify token semantics/signature/claims → determine whether the token is valid for a target party**.
   - The repo’s examples are centered on verifying tokens in two common contexts:
     - `verifyKyaTokenToExternalSeller`
     - `verifyKyaPayTokenToOnboardedService`

6. **Two verification scenarios**
   - `verifyKyaTokenToExternalSeller` suggests validation for a token presented to an **external seller**.
   - `verifyKyaPayTokenToOnboardedService` suggests validation for a token used with a **pre-onboarded service**.
   - Architecturally, this implies the protocol supports at least two trust boundaries: **external counterparties** and **registered/onboarded services**.

7. **Shared helper boundary**
   - Each language implementation has a `helpers` folder with:
     - `common` utilities
     - `kya`-specific logic
     - `pay`-specific logic
   - This indicates a clean split between **shared token plumbing** and **token-type-specific verification rules**.

8. **Configuration and utility layer**
   - `config` and `utils` modules exist in both Python and TypeScript examples.
   - These likely hold environment-specific values, constants, and helper routines needed to run the reference verification flow without embedding protocol details directly in the main scripts.

9. **Language/runtime split**
   - The examples are implemented in **Python** and **TypeScript/Node.js**, each with its own dependency manifest (`requirements.txt`, `package.json`, `tsconfig.json`).
   - This matters architecturally because the repo demonstrates the protocol as **language-agnostic**, while keeping each runtime’s implementation isolated.

10. **External dependencies and integration points**
   - The practical integration boundary is the **JWT ecosystem**: whatever libraries are used, the core architecture expects token parsing and verification support from the runtime.
   - No server, database, or deployment infrastructure is defined in the repo; the code examples appear to be **offline/reference verification flows** rather than a hosted application.

11. **Documentation-driven architecture**
   - The repo’s intended architecture is document-first: the **data model** and **example API** define the contract, and the sample code demonstrates how clients enforce it.
   - For diagramming, place the docs/specs as the authoritative source feeding the two reference implementations.

12. **Overall mental model**
   - The system is best drawn as:
     - **Governance/licensing layer**
     - **Protocol specification layer**
     - **Reference token-verification implementations**
     - **Two target trust contexts**: external seller vs onboarded service
   - There is no single backend; the repo is a **protocol standard plus sample validators**.

Main entry points: [`docs/example-api.md`](https://github.com/skyfire-xyz/kyapay/blob/main/docs/example-api.md) (Example API), [`code-examples/verifyToken/python/verifyKyaTokenToExternalSeller.py`](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/verifyKyaTokenToExternalSeller.py) (External seller), [`code-examples/verifyToken/python/verifyKyaPayTokenToOnboardedService.py`](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/verifyKyaPayTokenToOnboardedService.py) (Onboarded service), [`code-examples/verifyToken/typescript/src/verifyKyaTokenToExternalSeller.ts`](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/verifyKyaTokenToExternalSeller.ts) (External seller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_governance["Governance"]
  node_license_agreement["Contributor license<br/>governance doc"]
  node_community_license["Community license<br/>governance doc"]
  node_scope["Scope<br/>governance doc<br/>[2._Scope.md]"]
  node_notices["Notices<br/>governance doc<br/>[3._Notices.md]"]
  node_license["License<br/>governance doc<br/>[4._License.md]"]
  node_governance_doc["Governance<br/>[5._Governance.md]"]
  node_contributing["Contributing<br/>process doc<br/>[6._Contributing.md]"]
  node_code_of_conduct["Code of conduct<br/>policy doc"]
  node_maintainers["Maintainers<br/>project doc<br/>[MAINTAINERS.md]"]
end

subgraph group_specs["Specifications"]
  node_data_model["Data model<br/>protocol spec<br/>[data-model.md]"]
  node_example_api["Example API<br/>protocol spec<br/>[example-api.md]"]
end

subgraph group_python["Python examples"]
  node_python_cfg["Config<br/>python module<br/>[config.py]"]
  node_python_utils["Utils<br/>python module<br/>[utils.py]"]
  node_python_common["Common<br/>python helpers<br/>[common.py]"]
  node_python_kya["KYA helpers<br/>python helpers<br/>[kya.py]"]
  node_python_pay["PAY helpers<br/>python helpers<br/>[pay.py]"]
  node_python_external["External seller<br/>python verifier"]
  node_python_onboarded["Onboarded service<br/>python verifier"]
end

subgraph group_typescript["TypeScript examples"]
  node_ts_cfg["Config<br/>ts module<br/>[config.ts]"]
  node_ts_utils["Utils<br/>ts module<br/>[utils.ts]"]
  node_ts_common["Common<br/>ts helpers<br/>[common.ts]"]
  node_ts_kya["KYA helpers<br/>ts helpers<br/>[kya.ts]"]
  node_ts_pay["PAY helpers<br/>ts helpers<br/>[pay.ts]"]
  node_ts_external["External seller<br/>ts verifier"]
  node_ts_onboarded["Onboarded service<br/>ts verifier"]
end

node_repo{{"KYAPay<br/>protocol repo"}}
node_jwt_ecosystem(("JWT libs<br/>runtime dependency"))

node_repo -->|"governed by"| node_license_agreement
node_repo -->|"governed by"| node_community_license
node_repo -->|"defines"| node_scope
node_repo -->|"defines"| node_notices
node_repo -->|"defines"| node_license
node_repo -->|"defines"| node_governance_doc
node_repo -->|"defines"| node_contributing
node_repo -->|"defines"| node_code_of_conduct
node_repo -->|"defines"| node_maintainers
node_repo -->|"specifies"| node_data_model
node_repo -->|"specifies"| node_example_api
node_data_model -->|"informs"| node_python_common
node_data_model -->|"informs"| node_ts_common
node_example_api -->|"drives"| node_python_external
node_example_api -->|"drives"| node_python_onboarded
node_example_api -->|"drives"| node_ts_external
node_example_api -->|"drives"| node_ts_onboarded
node_jwt_ecosystem -->|"supports"| node_python_external
node_jwt_ecosystem -->|"supports"| node_python_onboarded
node_jwt_ecosystem -->|"supports"| node_ts_external
node_jwt_ecosystem -->|"supports"| node_ts_onboarded
node_python_cfg -->|"configures"| node_python_external
node_python_cfg -->|"configures"| node_python_onboarded
node_python_utils -->|"supports"| node_python_external
node_python_utils -->|"supports"| node_python_onboarded
node_python_common -->|"shared by"| node_python_kya
node_python_common -->|"shared by"| node_python_pay
node_python_kya -->|"used by"| node_python_external
node_python_pay -->|"used by"| node_python_onboarded
node_ts_cfg -->|"configures"| node_ts_external
node_ts_cfg -->|"configures"| node_ts_onboarded
node_ts_utils -->|"supports"| node_ts_external
node_ts_utils -->|"supports"| node_ts_onboarded
node_ts_common -->|"shared by"| node_ts_kya
node_ts_common -->|"shared by"| node_ts_pay
node_ts_kya -->|"used by"| node_ts_external
node_ts_pay -->|"used by"| node_ts_onboarded

click node_license_agreement "https://github.com/skyfire-xyz/kyapay/blob/main/.0_CS_Contributor_License_Agreement.md"
click node_community_license "https://github.com/skyfire-xyz/kyapay/blob/main/1._Community_Specification_License-v1.md"
click node_scope "https://github.com/skyfire-xyz/kyapay/blob/main/2._Scope.md"
click node_notices "https://github.com/skyfire-xyz/kyapay/blob/main/3._Notices.md"
click node_license "https://github.com/skyfire-xyz/kyapay/blob/main/4._License.md"
click node_governance_doc "https://github.com/skyfire-xyz/kyapay/blob/main/5._Governance.md"
click node_contributing "https://github.com/skyfire-xyz/kyapay/blob/main/6._Contributing.md"
click node_code_of_conduct "https://github.com/skyfire-xyz/kyapay/blob/main/8._Code_of_Conduct.md"
click node_maintainers "https://github.com/skyfire-xyz/kyapay/blob/main/MAINTAINERS.md"
click node_data_model "https://github.com/skyfire-xyz/kyapay/blob/main/docs/data-model.md"
click node_example_api "https://github.com/skyfire-xyz/kyapay/blob/main/docs/example-api.md"
click node_python_cfg "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/config.py"
click node_python_utils "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/utils.py"
click node_python_common "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/helpers/common.py"
click node_python_kya "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/helpers/kya.py"
click node_python_pay "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/helpers/pay.py"
click node_python_external "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/verifyKyaTokenToExternalSeller.py"
click node_python_onboarded "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/verifyKyaPayTokenToOnboardedService.py"
click node_ts_cfg "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/config.ts"
click node_ts_utils "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/utils.ts"
click node_ts_common "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/helpers/common.ts"
click node_ts_kya "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/helpers/kya.ts"
click node_ts_pay "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/helpers/pay.ts"
click node_ts_external "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/verifyKyaTokenToExternalSeller.ts"
click node_ts_onboarded "https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/verifyKyaPayTokenToOnboardedService.ts"

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_license_agreement,node_community_license,node_scope,node_notices,node_license,node_governance_doc,node_contributing,node_code_of_conduct,node_maintainers toneBlue
class node_data_model,node_example_api toneAmber
class node_python_cfg,node_python_utils,node_python_common,node_python_kya,node_python_pay,node_python_external,node_python_onboarded toneMint
class node_ts_cfg,node_ts_utils,node_ts_common,node_ts_kya,node_ts_pay,node_ts_external,node_ts_onboarded toneRose
class node_repo,node_jwt_ecosystem toneNeutral
```

## Components

### Governance

Repository policy, licensing, and maintenance documents

- [Contributor license](https://github.com/skyfire-xyz/kyapay/blob/main/.0_CS_Contributor_License_Agreement.md): governance doc · Contributor agreement and licensing terms · `.0_CS_Contributor_License_Agreement.md`
- [Community license](https://github.com/skyfire-xyz/kyapay/blob/main/1._Community_Specification_License-v1.md): governance doc · Specification license for community use · `1._Community_Specification_License-v1.md`
- [Scope](https://github.com/skyfire-xyz/kyapay/blob/main/2._Scope.md): governance doc · Repository scope and boundaries · `2._Scope.md`
- [Notices](https://github.com/skyfire-xyz/kyapay/blob/main/3._Notices.md): governance doc · Legal notices and attribution · `3._Notices.md`
- [License](https://github.com/skyfire-xyz/kyapay/blob/main/4._License.md): governance doc · Primary project license · `4._License.md`
- [Governance](https://github.com/skyfire-xyz/kyapay/blob/main/5._Governance.md): governance doc · Governance and process rules · `5._Governance.md`
- [Contributing](https://github.com/skyfire-xyz/kyapay/blob/main/6._Contributing.md): process doc · Contribution workflow and expectations · `6._Contributing.md`
- [Code of conduct](https://github.com/skyfire-xyz/kyapay/blob/main/8._Code_of_Conduct.md): policy doc · Community conduct policy · `8._Code_of_Conduct.md`
- [Maintainers](https://github.com/skyfire-xyz/kyapay/blob/main/MAINTAINERS.md): project doc · Maintainer roles and contacts · `MAINTAINERS.md`

### Specifications

Protocol model and example API definitions

- [Data model](https://github.com/skyfire-xyz/kyapay/blob/main/docs/data-model.md): protocol spec · Core KYAPay JWT data model · `docs/data-model.md`
- [Example API](https://github.com/skyfire-xyz/kyapay/blob/main/docs/example-api.md): protocol spec · Example API surface and interaction model · `docs/example-api.md`

### Python examples

Reference verification flow in Python

- [Config](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/config.py): python module · Python runtime configuration · `code-examples/verifyToken/python/config.py`
- [Utils](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/utils.py): python module · Shared Python utility routines · `code-examples/verifyToken/python/utils.py`
- [Common](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/helpers/common.py): python helpers · Shared token plumbing and reusable helpers · `code-examples/verifyToken/python/helpers/common.py`
- [KYA helpers](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/helpers/kya.py): python helpers · KYA-specific verification logic · `code-examples/verifyToken/python/helpers/kya.py`
- [PAY helpers](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/helpers/pay.py): python helpers · PAY-specific verification logic · `code-examples/verifyToken/python/helpers/pay.py`
- [External seller](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/verifyKyaTokenToExternalSeller.py): python verifier · Verifies a KYA token for an external seller trust boundary · `code-examples/verifyToken/python/verifyKyaTokenToExternalSeller.py`
- [Onboarded service](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/python/verifyKyaPayTokenToOnboardedService.py): python verifier · Verifies a KYA Pay token for a pre-onboarded service · `code-examples/verifyToken/python/verifyKyaPayTokenToOnboardedService.py`

### TypeScript examples

Reference verification flow in TypeScript

- [Config](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/config.ts): ts module · TypeScript runtime configuration · `code-examples/verifyToken/typescript/src/config.ts`
- [Utils](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/utils.ts): ts module · Shared TypeScript utility routines · `code-examples/verifyToken/typescript/src/utils.ts`
- [Common](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/helpers/common.ts): ts helpers · Shared token plumbing and reusable helpers · `code-examples/verifyToken/typescript/src/helpers/common.ts`
- [KYA helpers](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/helpers/kya.ts): ts helpers · KYA-specific verification logic · `code-examples/verifyToken/typescript/src/helpers/kya.ts`
- [PAY helpers](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/helpers/pay.ts): ts helpers · PAY-specific verification logic · `code-examples/verifyToken/typescript/src/helpers/pay.ts`
- [External seller](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/verifyKyaTokenToExternalSeller.ts): ts verifier · Verifies a KYA token for an external seller trust boundary · `code-examples/verifyToken/typescript/src/verifyKyaTokenToExternalSeller.ts`
- [Onboarded service](https://github.com/skyfire-xyz/kyapay/blob/main/code-examples/verifyToken/typescript/src/verifyKyaPayTokenToOnboardedService.ts): ts verifier · Verifies a KYA Pay token for a pre-onboarded service · `code-examples/verifyToken/typescript/src/verifyKyaPayTokenToOnboardedService.ts`

### Other components

- **KYAPay**: protocol repo · Identity-linked payment protocol specification and reference examples
- **JWT libs**: runtime dependency · Token parsing and verification support from the host runtime

## Connections

- KYAPay → Contributor license: governed by · Repository governance and legal terms
- KYAPay → Community license: governed by · Repository governance and legal terms
- KYAPay → Scope: defines · Repository governance and legal terms
- KYAPay → Notices: defines · Repository governance and legal terms
- KYAPay → License: defines · Repository governance and legal terms
- KYAPay → Governance: defines · Repository governance and legal terms
- KYAPay → Contributing: defines · Repository governance and legal terms
- KYAPay → Code of conduct: defines · Repository governance and legal terms
- KYAPay → Maintainers: defines · Repository governance and legal terms
- KYAPay → Data model: specifies · Authoritative protocol model
- KYAPay → Example API: specifies · Authoritative protocol model
- Data model → Common: informs · Protocol model shapes validation helpers
- Data model → Common: informs · Protocol model shapes validation helpers
- Example API → External seller: drives · Example API is exercised by reference verifiers
- Example API → Onboarded service: drives · Example API is exercised by reference verifiers
- Example API → External seller: drives · Example API is exercised by reference verifiers
- Example API → Onboarded service: drives · Example API is exercised by reference verifiers
- JWT libs → External seller: supports · JWT parsing and verification library support
- JWT libs → Onboarded service: supports · JWT parsing and verification library support
- JWT libs → External seller: supports · JWT parsing and verification library support
- JWT libs → Onboarded service: supports · JWT parsing and verification library support
- Config → External seller: configures · Runtime settings for the verification flow
- Config → Onboarded service: configures · Runtime settings for the verification flow
- Utils → External seller: supports · Reusable runtime utilities
- Utils → Onboarded service: supports · Reusable runtime utilities
- Common → KYA helpers: shared by · Common helper layer used by token-specific logic
- Common → PAY helpers: shared by · Common helper layer used by token-specific logic
- KYA helpers → External seller: used by · KYA-specific validation path
- PAY helpers → Onboarded service: used by · PAY-specific validation path
- Config → External seller: configures · Runtime settings for the verification flow
- Config → Onboarded service: configures · Runtime settings for the verification flow
- Utils → External seller: supports · Reusable runtime utilities
- Utils → Onboarded service: supports · Reusable runtime utilities
- Common → KYA helpers: shared by · Common helper layer used by token-specific logic
- Common → PAY helpers: shared by · Common helper layer used by token-specific logic
- KYA helpers → External seller: used by · KYA-specific validation path
- PAY helpers → Onboarded service: used by · PAY-specific validation path
