# igorbnd/kept architecture

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

- Interactive diagram: https://gitdiagram.com/igorbnd/kept
- Repository: https://github.com/igorbnd/kept

## Overview

Kept turns merchant-authored guarantees into typed, reviewable rules, freezes approved promises into PayPal orders, monitors carrier or weather evidence, and automatically issues capped refunds when code determines a promise was broken. Merchants configure promises and review holds in the Studio; buyers shop and check out; merchants audit outcomes in the ledger. The graph includes documented suggestion, pricing, evidence review, narration, tracking, and budget capabilities. Some server internals were only sampled through the source index or README, so unsupported call details are omitted.

Main entry points: [`server/watcher.ts`](https://github.com/igorbnd/kept/blob/main/server/watcher.ts) (Rule watcher), [`server/index.ts`](https://github.com/igorbnd/kept/blob/main/server/index.ts) (HTTP API), [`server/ai/suggester.ts`](https://github.com/igorbnd/kept/blob/main/server/ai/suggester.ts) (Promise suggestions), [`web/src/api.ts`](https://github.com/igorbnd/kept/blob/main/web/src/api.ts) (Web API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_merchant_ui["Merchant and buyer UI"]
  node_app_router["App router<br/>[main.tsx]"]
  node_shop["Shop and checkout<br/>[Shop.tsx]"]
  node_order_page["Order details<br/>[OrderPage.tsx]"]
  node_studio["Promise Studio<br/>[Studio.tsx]"]
  node_ledger["Order ledger<br/>[Ledger.tsx]"]
  node_api_client["Web API client<br/>[api.ts]"]
end

subgraph group_promise_design["Promise design"]
  node_compiler["Promise compiler<br/>[compiler.ts]"]
  node_suggestions["Promise suggestions<br/>[suggester.ts]"]
  node_pricing["Expected-cost pricing<br/>[pricing.ts]"]
  node_context["Moment and climate context<br/>[context.ts]"]
end

subgraph group_monitoring["Monitoring and decisions"]
  node_watcher["Rule watcher<br/>[watcher.ts]"]
  node_assessor["Carrier evidence review<br/>[assessor.ts]"]
  node_narrator["Refund explanation<br/>[narrator.ts]"]
  node_carrier["Carrier tracking evidence<br/>[carrier.ts]"]
  node_weather["Weather evidence<br/>[weather.ts]"]
end

subgraph group_commerce["Orders and payments"]
  node_api_server["HTTP API<br/>[index.ts]"]
  node_paypal["PayPal commerce<br/>[paypal.ts]"]
end

subgraph group_persistence["State and contracts"]
  node_database[("SQLite document store<br/>[db.ts]")]
  node_contracts["Domain contracts<br/>[types.ts]"]
end

node_merchant(("Merchant"))
node_buyer(("Buyer"))
node_open_meteo["Open-Meteo"]
node_claude["Claude"]
node_paypal_service["PayPal services"]

node_app_router -->|"routes to"| node_shop
node_app_router -->|"routes to"| node_studio
node_app_router -->|"routes to"| node_ledger
node_app_router -->|"routes to"| node_order_page
node_merchant -->|"authors and approves"| node_studio
node_merchant -->|"reviews outcomes"| node_ledger
node_buyer -->|"shops and buys"| node_shop
node_shop -->|"requests data"| node_api_client
node_studio -->|"requests actions"| node_api_client
node_ledger -->|"loads ledger"| node_api_client
node_order_page -->|"loads order"| node_api_client
node_api_client -->|"sends API requests"| node_api_server
node_api_server -->|"compiles promises"| node_compiler
node_api_server -->|"requests ideas"| node_suggestions
node_api_server -->|"prices promises"| node_pricing
node_api_server -->|"handles checkout"| node_paypal
node_api_server -->|"starts monitoring"| node_watcher
node_api_server -->|"reads and writes"| node_database
node_suggestions -->|"uses context"| node_context
node_suggestions -->|"drafts ideas"| node_claude
node_suggestions -->|"compiles ideas"| node_compiler
node_suggestions -->|"prices ideas"| node_pricing
node_pricing -->|"uses climate history"| node_context
node_context -->|"fetches forecast and history"| node_open_meteo
node_compiler -->|"compiles with"| node_claude
node_watcher -->|"reads scans"| node_carrier
node_watcher -->|"reads observations"| node_weather
node_watcher -->|"reviews delivery evidence"| node_assessor
node_watcher -->|"writes refund note"| node_narrator
node_watcher -->|"logs decisions"| node_database
node_watcher -->|"issues refund"| node_paypal
node_watcher -->|"attaches tracking"| node_paypal
node_assessor -->|"assesses evidence"| node_claude
node_narrator -->|"drafts explanation"| node_claude
node_weather -->|"fetches observations"| node_open_meteo
node_paypal -->|"calls REST APIs"| node_paypal_service
node_carrier -->|"stores scans"| node_database
node_compiler -->|"validates rule"| node_contracts
node_api_server -->|"uses shared types"| node_contracts

click node_app_router "https://github.com/igorbnd/kept/blob/main/web/src/main.tsx"
click node_shop "https://github.com/igorbnd/kept/blob/main/web/src/pages/Shop.tsx"
click node_order_page "https://github.com/igorbnd/kept/blob/main/web/src/pages/OrderPage.tsx"
click node_studio "https://github.com/igorbnd/kept/blob/main/web/src/pages/Studio.tsx"
click node_ledger "https://github.com/igorbnd/kept/blob/main/web/src/pages/Ledger.tsx"
click node_api_client "https://github.com/igorbnd/kept/blob/main/web/src/api.ts"
click node_api_server "https://github.com/igorbnd/kept/blob/main/server/index.ts"
click node_compiler "https://github.com/igorbnd/kept/blob/main/server/ai/compiler.ts"
click node_suggestions "https://github.com/igorbnd/kept/blob/main/server/ai/suggester.ts"
click node_pricing "https://github.com/igorbnd/kept/blob/main/server/pricing.ts"
click node_context "https://github.com/igorbnd/kept/blob/main/server/sources/context.ts"
click node_watcher "https://github.com/igorbnd/kept/blob/main/server/watcher.ts"
click node_assessor "https://github.com/igorbnd/kept/blob/main/server/ai/assessor.ts"
click node_narrator "https://github.com/igorbnd/kept/blob/main/server/ai/narrator.ts"
click node_carrier "https://github.com/igorbnd/kept/blob/main/server/sources/carrier.ts"
click node_weather "https://github.com/igorbnd/kept/blob/main/server/sources/weather.ts"
click node_paypal "https://github.com/igorbnd/kept/blob/main/server/paypal.ts"
click node_database "https://github.com/igorbnd/kept/blob/main/server/db.ts"
click node_contracts "https://github.com/igorbnd/kept/blob/main/server/types.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_app_router,node_shop,node_order_page,node_studio,node_ledger,node_api_client toneBlue
class node_compiler,node_suggestions,node_pricing,node_context toneAmber
class node_watcher,node_assessor,node_narrator,node_carrier,node_weather toneMint
class node_api_server,node_paypal toneRose
class node_database,node_contracts,node_merchant,node_buyer,node_open_meteo,node_claude,node_paypal_service toneIndigo
```

## Components

### Merchant and buyer UI

- [App router](https://github.com/igorbnd/kept/blob/main/web/src/main.tsx): `web/src/main.tsx`
- [Shop and checkout](https://github.com/igorbnd/kept/blob/main/web/src/pages/Shop.tsx): `web/src/pages/Shop.tsx`
- [Order details](https://github.com/igorbnd/kept/blob/main/web/src/pages/OrderPage.tsx): `web/src/pages/OrderPage.tsx`
- [Promise Studio](https://github.com/igorbnd/kept/blob/main/web/src/pages/Studio.tsx): `web/src/pages/Studio.tsx`
- [Order ledger](https://github.com/igorbnd/kept/blob/main/web/src/pages/Ledger.tsx): `web/src/pages/Ledger.tsx`
- [Web API client](https://github.com/igorbnd/kept/blob/main/web/src/api.ts): `web/src/api.ts`

### Promise design

- [Promise compiler](https://github.com/igorbnd/kept/blob/main/server/ai/compiler.ts): `server/ai/compiler.ts`
- [Promise suggestions](https://github.com/igorbnd/kept/blob/main/server/ai/suggester.ts): `server/ai/suggester.ts`
- [Expected-cost pricing](https://github.com/igorbnd/kept/blob/main/server/pricing.ts): `server/pricing.ts`
- [Moment and climate context](https://github.com/igorbnd/kept/blob/main/server/sources/context.ts): `server/sources/context.ts`

### Monitoring and decisions

- [Rule watcher](https://github.com/igorbnd/kept/blob/main/server/watcher.ts): `server/watcher.ts`
- [Carrier evidence review](https://github.com/igorbnd/kept/blob/main/server/ai/assessor.ts): `server/ai/assessor.ts`
- [Refund explanation](https://github.com/igorbnd/kept/blob/main/server/ai/narrator.ts): `server/ai/narrator.ts`
- [Carrier tracking evidence](https://github.com/igorbnd/kept/blob/main/server/sources/carrier.ts): `server/sources/carrier.ts`
- [Weather evidence](https://github.com/igorbnd/kept/blob/main/server/sources/weather.ts): `server/sources/weather.ts`

### Orders and payments

- [HTTP API](https://github.com/igorbnd/kept/blob/main/server/index.ts): `server/index.ts`
- [PayPal commerce](https://github.com/igorbnd/kept/blob/main/server/paypal.ts): `server/paypal.ts`

### State and contracts

- [SQLite document store](https://github.com/igorbnd/kept/blob/main/server/db.ts): `server/db.ts`
- [Domain contracts](https://github.com/igorbnd/kept/blob/main/server/types.ts): `server/types.ts`

### Other components

- **Merchant**
- **Buyer**
- **Open-Meteo**
- **Claude**
- **PayPal services**

## Connections

- App router → Shop and checkout: routes to (evidence: `web/src/main.tsx`)
- App router → Promise Studio: routes to (evidence: `web/src/main.tsx`)
- App router → Order ledger: routes to (evidence: `web/src/main.tsx`)
- App router → Order details: routes to (evidence: `web/src/main.tsx`)
- Merchant → Promise Studio: authors and approves (evidence: `README.md`)
- Merchant → Order ledger: reviews outcomes (evidence: `README.md`)
- Buyer → Shop and checkout: shops and buys (evidence: `README.md`)
- Shop and checkout → Web API client: requests data (evidence: `web/src/pages/Shop.tsx`)
- Promise Studio → Web API client: requests actions (evidence: `web/src/pages/Studio.tsx`)
- Order ledger → Web API client: loads ledger (evidence: `web/src/pages/Ledger.tsx`)
- Order details → Web API client: loads order (evidence: `web/src/pages/OrderPage.tsx`)
- Web API client → HTTP API: sends API requests (evidence: `web/src/api.ts`)
- HTTP API → Promise compiler: compiles promises (evidence: `server/index.ts`)
- HTTP API → Promise suggestions: requests ideas (evidence: `server/index.ts`)
- HTTP API → Expected-cost pricing: prices promises (evidence: `server/index.ts`)
- HTTP API → PayPal commerce: handles checkout (evidence: `server/index.ts`)
- HTTP API → Rule watcher: starts monitoring (evidence: `server/index.ts`)
- HTTP API → SQLite document store: reads and writes (evidence: `server/index.ts`)
- Promise suggestions → Moment and climate context: uses context (evidence: `server/ai/suggester.ts`)
- Promise suggestions → Claude: drafts ideas (evidence: `README.md`)
- Promise suggestions → Promise compiler: compiles ideas (evidence: `README.md`)
- Promise suggestions → Expected-cost pricing: prices ideas (evidence: `README.md`)
- Expected-cost pricing → Moment and climate context: uses climate history (evidence: `server/pricing.ts`)
- Moment and climate context → Open-Meteo: fetches forecast and history (evidence: `server/sources/context.ts`)
- Promise compiler → Claude: compiles with (evidence: `server/ai/compiler.ts`)
- Rule watcher → Carrier tracking evidence: reads scans (evidence: `server/watcher.ts`)
- Rule watcher → Weather evidence: reads observations (evidence: `server/watcher.ts`)
- Rule watcher → Carrier evidence review: reviews delivery evidence (evidence: `server/watcher.ts`)
- Rule watcher → Refund explanation: writes refund note (evidence: `server/watcher.ts`)
- Rule watcher → SQLite document store: logs decisions (evidence: `server/watcher.ts`)
- Rule watcher → PayPal commerce: issues refund (evidence: `README.md`)
- Rule watcher → PayPal commerce: attaches tracking (evidence: `README.md`)
- Carrier evidence review → Claude: assesses evidence (evidence: `README.md`)
- Refund explanation → Claude: drafts explanation (evidence: `README.md`)
- Weather evidence → Open-Meteo: fetches observations (evidence: `server/sources/weather.ts`)
- PayPal commerce → PayPal services: calls REST APIs (evidence: `server/paypal.ts`)
- Carrier tracking evidence → SQLite document store: stores scans (evidence: `server/sources/carrier.ts`)
- Promise compiler → Domain contracts: validates rule (evidence: `server/ai/compiler.ts`)
- HTTP API → Domain contracts: uses shared types (evidence: `server/index.ts`)
