# nnovida/verakey architecture

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

- Interactive diagram: https://gitdiagram.com/nnovida/verakey
- Repository: https://github.com/nnovida/verakey

## Overview

VeraKey is a passkey-authorized wallet system for creating app-specific, unlinkable USDG accounts and signing in to websites. A user enters through the web app, creates or selects an account, and authorizes payments or account changes with a browser-generated proof; the server relays eligible transactions to Arbitrum. The product also supports popup sign-in, recovery, consent-based account-link disclosures, and a validator for modular accounts. The graph preserves those documented capabilities, but several page and SDK implementations were not sampled, so some documented subsystem links are dashed and unverified.

Main entry points: [`client/src/App.tsx`](https://github.com/nnovida/verakey/blob/main/client/src/App.tsx) (Web routes), [`packages/sdk/src/client.ts`](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/client.ts) (Wallet client), [`contracts/stylus/account/src/lib.rs`](https://github.com/nnovida/verakey/blob/main/contracts/stylus/account/src/lib.rs) (Wallet account), [`server/index.ts`](https://github.com/nnovida/verakey/blob/main/server/index.ts) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web routes<br/>[App.tsx]"]
  node_home["Product home<br/>[Home.tsx]"]
  node_accounts["Accounts UI<br/>[Accounts.tsx]"]
  node_policy["Policy controls<br/>[Policy.tsx]"]
  node_recovery["Recovery UI<br/>[Recovery.tsx]"]
  node_pay["Payment flow<br/>[Pay.tsx]"]
  node_disclose["Link disclosure<br/>[Disclose.tsx]"]
  node_verify["Sign-in verifier<br/>[Verify.tsx]"]
  node_provider["Wallet state"]
  node_actionui["Action timeline"]
end

subgraph group_sdk["Passkey SDK"]
  node_sdkclient["Wallet client<br/>[client.ts]"]
  node_webauthn["Passkey operations<br/>[webauthn.ts]"]
  node_proof["Proof generation<br/>[prover.ts]"]
  node_abi["Contract ABI<br/>[abi.ts]"]
end

subgraph group_service["Relaying service"]
  node_config["Network configuration<br/>[config.ts]"]
  node_api["HTTP API<br/>[index.ts]"]
  node_limits["Request limits<br/>[rate-limit.ts]"]
  node_relayer["Transaction relayer<br/>[relayer.ts]"]
  node_shared["API contracts<br/>[api.ts]"]
end

subgraph group_chain["On-chain accounts"]
  node_factory["Account factory<br/>[lib.rs]"]
  node_account["Wallet account<br/>[lib.rs]"]
  node_contractcore["Action rules<br/>[action.rs]"]
end

subgraph group_integrations["Identity integrations"]
  node_sdkconnect["Connect protocol<br/>[connect.ts]"]
  node_signin["Sign-in proofs<br/>[signin.ts]"]
  node_sdkserver["Website verification<br/>[server.ts]"]
  node_validator["ERC-7579 validator<br/>[validator.ts]"]
end

node_user(("Wallet user"))
node_site(("Relying website"))
node_chainrpc{{"Arbitrum network"}}
node_browser{{"Passkey browser"}}

node_user -->|"opens"| node_webapp
node_webapp -->|"routes to"| node_home
node_webapp -->|"routes to"| node_accounts
node_webapp -->|"routes to"| node_pay
node_webapp -->|"routes to"| node_policy
node_webapp -->|"routes to"| node_recovery
node_webapp -->|"routes to"| node_disclose
node_webapp -->|"routes to"| node_verify
node_webapp -->|"provides state"| node_provider
node_accounts -->|"uses"| node_sdkclient
node_actionui -->|"reports proof state"| node_sdkclient
node_provider -.->|"uses"| node_sdkclient
node_sdkclient -->|"requests assertions"| node_webauthn
node_sdkclient -->|"generates proofs"| node_proof
node_sdkclient -->|"encodes contract calls"| node_abi
node_browser -.->|"performs passkey"| node_webauthn
node_sdkclient -->|"submits actions"| node_relayer
node_sdkconnect -.->|"supports sign-in"| node_signin
node_site -.->|"verifies sign-in"| node_sdkserver
node_sdkserver -->|"verifies proofs"| node_signin
node_api -->|"loads settings"| node_config
node_api -->|"throttles requests"| node_limits
node_api -->|"handles relay"| node_relayer
node_api -->|"uses API types"| node_shared
node_relayer -->|"validates calls"| node_abi
node_relayer -.->|"submits transactions"| node_chainrpc
node_user -.->|"authorizes actions"| node_account
node_factory -->|"clones implementation"| node_account
node_account -.->|"applies action rules"| node_contractcore
node_account -.->|"records account state"| node_chainrpc
node_disclose -.->|"proves consent"| node_sdkclient
node_validator -.->|"validates proofs"| node_account

click node_webapp "https://github.com/nnovida/verakey/blob/main/client/src/App.tsx"
click node_home "https://github.com/nnovida/verakey/blob/main/client/src/pages/Home.tsx"
click node_accounts "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Accounts.tsx"
click node_policy "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Policy.tsx"
click node_recovery "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Recovery.tsx"
click node_pay "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Pay.tsx"
click node_disclose "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Disclose.tsx"
click node_verify "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Verify.tsx"
click node_provider "https://github.com/nnovida/verakey/blob/main/client/src/state/VeraKeyProvider.tsx"
click node_actionui "https://github.com/nnovida/verakey/blob/main/client/src/pages/app/useAuthorizedAction.ts"
click node_sdkclient "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/client.ts"
click node_webauthn "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/webauthn.ts"
click node_proof "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/prover.ts"
click node_abi "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/abi.ts"
click node_sdkconnect "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/connect.ts"
click node_signin "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/signin.ts"
click node_sdkserver "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/server.ts"
click node_config "https://github.com/nnovida/verakey/blob/main/server/config.ts"
click node_api "https://github.com/nnovida/verakey/blob/main/server/index.ts"
click node_limits "https://github.com/nnovida/verakey/blob/main/server/rate-limit.ts"
click node_relayer "https://github.com/nnovida/verakey/blob/main/server/relayer.ts"
click node_shared "https://github.com/nnovida/verakey/blob/main/shared/api.ts"
click node_factory "https://github.com/nnovida/verakey/blob/main/contracts/stylus/factory/src/lib.rs"
click node_account "https://github.com/nnovida/verakey/blob/main/contracts/stylus/account/src/lib.rs"
click node_contractcore "https://github.com/nnovida/verakey/blob/main/contracts/stylus/core/src/action.rs"
click node_validator "https://github.com/nnovida/verakey/blob/main/packages/sdk/src/validator.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_webapp,node_home,node_accounts,node_policy,node_recovery,node_pay,node_disclose,node_verify,node_provider,node_actionui,node_user,node_browser toneBlue
class node_sdkclient,node_webauthn,node_proof,node_abi toneAmber
class node_config,node_api,node_limits,node_relayer,node_shared toneMint
class node_factory,node_account,node_contractcore toneRose
class node_sdkconnect,node_signin,node_sdkserver,node_validator,node_site,node_chainrpc toneIndigo
```

## Components

### Web application

- [Web routes](https://github.com/nnovida/verakey/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Product home](https://github.com/nnovida/verakey/blob/main/client/src/pages/Home.tsx): `client/src/pages/Home.tsx`
- [Accounts UI](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Accounts.tsx): `client/src/pages/app/Accounts.tsx`
- [Policy controls](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Policy.tsx): `client/src/pages/app/Policy.tsx`
- [Recovery UI](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Recovery.tsx): `client/src/pages/app/Recovery.tsx`
- [Payment flow](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Pay.tsx): `client/src/pages/app/Pay.tsx`
- [Link disclosure](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Disclose.tsx): `client/src/pages/app/Disclose.tsx`
- [Sign-in verifier](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/Verify.tsx): `client/src/pages/app/Verify.tsx`
- [Wallet state](https://github.com/nnovida/verakey/blob/main/client/src/state/VeraKeyProvider.tsx): `client/src/state/VeraKeyProvider.tsx`
- [Action timeline](https://github.com/nnovida/verakey/blob/main/client/src/pages/app/useAuthorizedAction.ts): `client/src/pages/app/useAuthorizedAction.ts`

### Passkey SDK

- [Wallet client](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/client.ts): `packages/sdk/src/client.ts`
- [Passkey operations](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/webauthn.ts): `packages/sdk/src/webauthn.ts`
- [Proof generation](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/prover.ts): `packages/sdk/src/prover.ts`
- [Contract ABI](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/abi.ts): `packages/sdk/src/abi.ts`

### Relaying service

- [Network configuration](https://github.com/nnovida/verakey/blob/main/server/config.ts): `server/config.ts`
- [HTTP API](https://github.com/nnovida/verakey/blob/main/server/index.ts): `server/index.ts`
- [Request limits](https://github.com/nnovida/verakey/blob/main/server/rate-limit.ts): `server/rate-limit.ts`
- [Transaction relayer](https://github.com/nnovida/verakey/blob/main/server/relayer.ts): `server/relayer.ts`
- [API contracts](https://github.com/nnovida/verakey/blob/main/shared/api.ts): `shared/api.ts`

### On-chain accounts

- [Account factory](https://github.com/nnovida/verakey/blob/main/contracts/stylus/factory/src/lib.rs): `contracts/stylus/factory/src/lib.rs`
- [Wallet account](https://github.com/nnovida/verakey/blob/main/contracts/stylus/account/src/lib.rs): `contracts/stylus/account/src/lib.rs`
- [Action rules](https://github.com/nnovida/verakey/blob/main/contracts/stylus/core/src/action.rs): `contracts/stylus/core/src/action.rs`

### Identity integrations

- [Connect protocol](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/connect.ts): `packages/sdk/src/connect.ts`
- [Sign-in proofs](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/signin.ts): `packages/sdk/src/signin.ts`
- [Website verification](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/server.ts): `packages/sdk/src/server.ts`
- [ERC-7579 validator](https://github.com/nnovida/verakey/blob/main/packages/sdk/src/validator.ts): `packages/sdk/src/validator.ts`

### Other components

- **Wallet user**
- **Relying website**
- **Arbitrum network**
- **Passkey browser**

## Connections

- Wallet user → Web routes: opens (evidence: `client/src/App.tsx`)
- Web routes → Product home: routes to (evidence: `client/src/App.tsx`)
- Web routes → Accounts UI: routes to (evidence: `client/src/App.tsx`)
- Web routes → Payment flow: routes to (evidence: `client/src/App.tsx`)
- Web routes → Policy controls: routes to (evidence: `client/src/App.tsx`)
- Web routes → Recovery UI: routes to (evidence: `client/src/App.tsx`)
- Web routes → Link disclosure: routes to (evidence: `client/src/App.tsx`)
- Web routes → Sign-in verifier: routes to (evidence: `client/src/App.tsx`)
- Web routes → Wallet state: provides state (evidence: `client/src/App.tsx`)
- Accounts UI → Wallet client: uses (evidence: `client/src/pages/app/Accounts.tsx`)
- Action timeline → Wallet client: reports proof state (evidence: `client/src/pages/app/useAuthorizedAction.ts`)
- Wallet state → Wallet client: uses
- Wallet client → Passkey operations: requests assertions (evidence: `packages/sdk/src/client.ts`)
- Wallet client → Proof generation: generates proofs (evidence: `packages/sdk/src/client.ts`)
- Wallet client → Contract ABI: encodes contract calls (evidence: `packages/sdk/src/client.ts`)
- Passkey browser → Passkey operations: performs passkey
- Wallet client → Transaction relayer: submits actions (evidence: `packages/sdk/src/client.ts`)
- Connect protocol → Sign-in proofs: supports sign-in
- Relying website → Website verification: verifies sign-in
- Website verification → Sign-in proofs: verifies proofs (evidence: `packages/sdk/src/server.ts`)
- HTTP API → Network configuration: loads settings (evidence: `server/index.ts`)
- HTTP API → Request limits: throttles requests (evidence: `server/index.ts`)
- HTTP API → Transaction relayer: handles relay (evidence: `server/index.ts`)
- HTTP API → API contracts: uses API types (evidence: `server/index.ts`)
- Transaction relayer → Contract ABI: validates calls (evidence: `server/relayer.ts`)
- Transaction relayer → Arbitrum network: submits transactions
- Wallet user → Wallet account: authorizes actions
- Account factory → Wallet account: clones implementation
- Wallet account → Action rules: applies action rules
- Wallet account → Arbitrum network: records account state
- Link disclosure → Wallet client: proves consent
- ERC-7579 validator → Wallet account: validates proofs
