# chamakov/krona-vault architecture

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

- Interactive diagram: https://gitdiagram.com/chamakov/krona-vault
- Repository: https://github.com/chamakov/krona-vault

## Overview

KRONA VAULT is a self-hosted TCG-store credit, POS and custody platform with browser PWA portals and Node/edge API deployments. Its central workflow is a player-authorized POS redemption: the API routes the request to the ledger engine, which validates authorization, applies credit and produces a sealed voucher; the PWA supports offline access. Tournament pools, custody escrow, multi-store policy and forensic audit are distinct product branches. The source excerpts show API-to-engine/parser calls and PWA networking; unsampled subsystem links are included only where README documents them.

Main entry points: [`apps/api/src/server.ts`](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/server.ts) (Node API), [`apps/api/src/ledger-engine.ts`](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/ledger-engine.ts) (Credit ledger engine), [`apps/api/src/worker.ts`](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/worker.ts) (Edge API), [`apps/web-pwa/public/js/krona-core.js`](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/js/krona-core.js) (Portal client core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["PWA Portals"]
  node_portals["Store and player portals"]
  node_webcore["Portal client core<br/>[krona-core.js]"]
  node_offline["Offline PWA cache<br/>[sw.js]"]
end

subgraph group_api["API Runtime"]
  node_api_server["Node API<br/>[server.ts]"]
  node_api_worker["Edge API<br/>[worker.ts]"]
end

subgraph group_finance["Credit &amp; Accounting"]
  node_ledger["Credit ledger engine<br/>[ledger-engine.ts]"]
  node_crypto["TOTP and seals<br/>[index.ts]"]
  node_ledger_store[("Ledger database<br/>[init.sql]")]
  node_shared["Domain data types<br/>[index.ts]"]
end

subgraph group_operations["Store Operations"]
  node_pos["POS vouchers<br/>[pos.html]"]
  node_wallet["Player wallet<br/>[wallet.html]"]
  node_tournament["Tournament prizes"]
  node_custody["Custody escrow<br/>[custody.html]"]
  node_audit["Forensic audit<br/>[audit.html]"]
  node_stores["Store network<br/>[stores.html]"]
end

node_operator(("Store operator"))
node_player(("Player"))
node_d1[("Cloudflare D1")]

node_player -->|"uses"| node_wallet
node_operator -->|"checks out"| node_pos
node_pos -->|"served within"| node_portals
node_wallet -->|"served within"| node_portals
node_portals -->|"uses"| node_webcore
node_webcore -->|"requests"| node_api_server
node_webcore -->|"registers"| node_offline
node_api_server -->|"invokes"| node_ledger
node_api_worker -->|"invokes"| node_ledger
node_api_server -->|"parses standings"| node_tournament
node_api_worker -->|"parses standings"| node_tournament
node_ledger -->|"generates seals"| node_crypto
node_api_server -->|"generates PIN"| node_crypto
node_api_worker -->|"loads and saves"| node_d1
node_ledger -.->|"records entries"| node_ledger_store
node_operator -->|"imports standings"| node_tournament
node_operator -->|"manages escrow"| node_custody
node_operator -->|"reviews activity"| node_audit
node_operator -->|"configures branches"| node_stores

click node_portals "https://github.com/chamakov/krona-vault/tree/main/apps/web-pwa/public"
click node_webcore "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/js/krona-core.js"
click node_offline "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/sw.js"
click node_api_server "https://github.com/chamakov/krona-vault/blob/main/apps/api/src/server.ts"
click node_api_worker "https://github.com/chamakov/krona-vault/blob/main/apps/api/src/worker.ts"
click node_ledger "https://github.com/chamakov/krona-vault/blob/main/apps/api/src/ledger-engine.ts"
click node_crypto "https://github.com/chamakov/krona-vault/blob/main/packages/crypto-totp/src/index.ts"
click node_ledger_store "https://github.com/chamakov/krona-vault/blob/main/infra/postgres/init.sql"
click node_shared "https://github.com/chamakov/krona-vault/blob/main/packages/shared-types/src/index.ts"
click node_pos "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/pos.html"
click node_wallet "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/wallet.html"
click node_tournament "https://github.com/chamakov/krona-vault/blob/main/apps/api/src/pokemon-standings-parser.ts"
click node_custody "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/custody.html"
click node_audit "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/audit.html"
click node_stores "https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/stores.html"

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_portals,node_webcore,node_offline toneBlue
class node_api_server,node_api_worker,node_d1 toneAmber
class node_ledger,node_crypto,node_ledger_store,node_shared toneMint
class node_pos,node_wallet,node_tournament,node_custody,node_audit,node_stores toneRose
class node_operator,node_player toneIndigo
```

## Components

### PWA Portals

- [Store and player portals](https://github.com/chamakov/krona-vault/tree/main/apps/web-pwa/public): `apps/web-pwa/public`
- [Portal client core](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/js/krona-core.js): `apps/web-pwa/public/js/krona-core.js`
- [Offline PWA cache](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/sw.js): `apps/web-pwa/public/sw.js`

### API Runtime

- [Node API](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Edge API](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/worker.ts): `apps/api/src/worker.ts`

### Credit & Accounting

- [Credit ledger engine](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/ledger-engine.ts): `apps/api/src/ledger-engine.ts`
- [TOTP and seals](https://github.com/chamakov/krona-vault/blob/main/packages/crypto-totp/src/index.ts): `packages/crypto-totp/src/index.ts`
- [Ledger database](https://github.com/chamakov/krona-vault/blob/main/infra/postgres/init.sql): `infra/postgres/init.sql`
- [Domain data types](https://github.com/chamakov/krona-vault/blob/main/packages/shared-types/src/index.ts): `packages/shared-types/src/index.ts`

### Store Operations

- [POS vouchers](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/pos.html): `apps/web-pwa/public/pos.html`
- [Player wallet](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/wallet.html): `apps/web-pwa/public/wallet.html`
- [Tournament prizes](https://github.com/chamakov/krona-vault/blob/main/apps/api/src/pokemon-standings-parser.ts): `apps/api/src/pokemon-standings-parser.ts`
- [Custody escrow](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/custody.html): `apps/web-pwa/public/custody.html`
- [Forensic audit](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/audit.html): `apps/web-pwa/public/audit.html`
- [Store network](https://github.com/chamakov/krona-vault/blob/main/apps/web-pwa/public/stores.html): `apps/web-pwa/public/stores.html`

### Other components

- **Store operator**
- **Player**
- **Cloudflare D1**

## Connections

- Player → Player wallet: uses (evidence: `README.md`)
- Store operator → POS vouchers: checks out (evidence: `README.md`)
- POS vouchers → Store and player portals: served within (evidence: `README.md`)
- Player wallet → Store and player portals: served within (evidence: `README.md`)
- Store and player portals → Portal client core: uses (evidence: `apps/web-pwa/public/js/krona-core.js`)
- Portal client core → Node API: requests (evidence: `apps/web-pwa/public/js/krona-core.js`)
- Portal client core → Offline PWA cache: registers (evidence: `apps/web-pwa/public/js/krona-core.js`)
- Node API → Credit ledger engine: invokes (evidence: `apps/api/src/server.ts`)
- Edge API → Credit ledger engine: invokes (evidence: `apps/api/src/worker.ts`)
- Node API → Tournament prizes: parses standings (evidence: `apps/api/src/server.ts`)
- Edge API → Tournament prizes: parses standings (evidence: `apps/api/src/worker.ts`)
- Credit ledger engine → TOTP and seals: generates seals (evidence: `apps/api/src/ledger-engine.ts`)
- Node API → TOTP and seals: generates PIN (evidence: `apps/api/src/server.ts`)
- Edge API → Cloudflare D1: loads and saves (evidence: `apps/api/src/worker.ts`)
- Credit ledger engine → Ledger database: records entries (evidence: `README.md`)
- Store operator → Tournament prizes: imports standings (evidence: `README.md`)
- Store operator → Custody escrow: manages escrow (evidence: `README.md`)
- Store operator → Forensic audit: reviews activity (evidence: `README.md`)
- Store operator → Store network: configures branches (evidence: `README.md`)