# kenoplug/keno-vault architecture

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

- Interactive diagram: https://gitdiagram.com/kenoplug/keno-vault
- Repository: https://github.com/kenoplug/keno-vault

## Overview

#### Purpose and Entry Points
Keno Vault is a static, browser-based personal net-worth tracker with free/pro feature gating. The primary user entry is `index.html`; authenticated dashboard and settings views are under `pages/dashboard.html` and `pages/settings.html`. Vercel serves the frontend and routes serverless endpoints via `vercel.json` and `server.js`.

#### Frontend Application Shell
The vanilla JavaScript client owns UI rendering, authentication state, asset CRUD, dashboard KPIs, charts, history, exports, and plan-aware feature access. `js/app.js` is the central application coordinator, with finance computations separated into `js/calculators.js`. Shared deployment, Supabase, admin, and site constants are configured in `js/config.js`.

Paths:
- `index.html`
- `js/app.js`
- `js/config.js`

#### Dashboard and Financial Intelligence
Dashboard presentation is split from the core client behavior: `pages/dashboard.html` supplies the dashboard view and `css/dashboard.css` provides dedicated styling. Financial modeling—including retirement, debt, allocation, depreciation, tax, and net-worth-related calculations—is concentrated in `js/calculators.js`, allowing UI flows to consume computed results rather than embed formulas.

Paths:
- `pages/dashboard.html`
- `css/dashboard.css`
- `js/calculators.js`

#### Identity, Data, and Authorization Boundary
Supabase provides Google authentication, PostgreSQL persistence, synchronization, and row-level security. `supabase-migration.sql` defines the backend schema/policies, while the browser uses the configured public Supabase credentials. The frontend should remain limited to user-scoped operations protected by RLS; privileged subscription updates and account deletion run in Edge Functions.

Paths:
- `supabase-migration.sql`
- `js/config.js`
- `supabase/functions/delete-account/index.ts`

#### Security and Local Privacy Controls
Sensitive client-side controls—session auto-lock, PIN/privacy behavior, and encrypted backup mechanisms—are organized in `js/security.js`. Encryption uses the browser Web Crypto API, keeping encryption/decryption in the client boundary rather than requiring a separate cryptographic service.

Paths:
- `js/security.js`
- `js/app.js`
- `pages/settings.html`

#### Subscription and Payment Flow
A user initiates Pro purchase through a Supabase Edge Function that creates a Bachs checkout. Bachs asynchronously calls the webhook function after payment; that trusted server-side path activates or updates the subscription record. The client then reads subscription state to enforce free limits and unlock Pro modules. Bachs supports cards, bank transfers, mobile money, and crypto.

Paths:
- `supabase/functions/create-checkout/index.ts`
- `supabase/functions/bachs-webhook/index.ts`
- `supabase-migration.sql`

#### Server-Side Automation and Integrations
Supabase Edge Functions isolate external integrations and privileged actions from the static frontend. `ai-advisor` provides an AI-backed advisory boundary, while `send-notification` supports outbound notification workflows. The frontend additionally obtains foreign-exchange data from `open.er-api.com`; Chart.js renders client-side visualizations.

Paths:
- `supabase/functions/ai-advisor/index.ts`
- `supabase/functions/send-notification/index.ts`
- `supabase/functions/bachs-webhook/index.ts`

#### Runtime and Deployment
The product is primarily a static HTML/CSS/JavaScript application deployed on Vercel. Supabase hosts auth, database, and Deno/TypeScript Edge Functions; Vercel configuration and the Node server file define deployment/runtime integration points. Tailwind is loaded from CDN, with custom CSS retained for dashboard-specific behavior.

Paths:
- `vercel.json`
- `server.js`
- `css/dashboard.css`

Main entry points: [`js/app.js`](https://github.com/kenoplug/keno-vault/blob/main/js/app.js) (App coordinator), [`vercel.json`](https://github.com/kenoplug/keno-vault/blob/main/vercel.json) (Vercel deployment), [`index.html`](https://github.com/kenoplug/keno-vault/blob/main/index.html) (Public entry), [`pages/dashboard.html`](https://github.com/kenoplug/keno-vault/blob/main/pages/dashboard.html) (Dashboard view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser App"]
  node_entry["Public entry<br/>HTML entry<br/>[index.html]"]
  node_app["App coordinator<br/>vanilla JS<br/>[app.js]"]
  node_config["Client configuration<br/>JS config<br/>[config.js]"]
  node_dashboard["Dashboard view<br/>HTML view<br/>[dashboard.html]"]
  node_dashboard_css["Dashboard styling<br/>CSS<br/>[dashboard.css]"]
  node_calculators["Financial calculators<br/>JS module<br/>[calculators.js]"]
  node_security["Local privacy controls<br/>JS security module<br/>[security.js]"]
  node_settings["Settings view<br/>HTML view<br/>[settings.html]"]
end

subgraph group_supabase["Supabase Backend"]
  node_supabase_db[("Auth, PostgreSQL &amp; RLS<br/>Supabase platform")]
  node_checkout{{"Create checkout<br/>Edge Function<br/>[index.ts]"}}
  node_webhook{{"Payment webhook<br/>Edge Function<br/>[index.ts]"}}
  node_delete_account{{"Delete account<br/>Edge Function<br/>[index.ts]"}}
  node_ai_advisor{{"AI advisor<br/>Edge Function<br/>[index.ts]"}}
  node_notifications{{"Notifications<br/>Edge Function<br/>[index.ts]"}}
end

subgraph group_external["External Services"]
  node_bachs["Bachs payments<br/>payment provider"]
  node_fx_api["Exchange-rate API<br/>FX data API"]
  node_chartjs["Chart.js<br/>chart library"]
end

subgraph group_hosting["Hosting"]
  node_vercel["Vercel deployment<br/>static hosting<br/>[vercel.json]"]
  node_server["Node server integration<br/>Node runtime<br/>[server.js]"]
end

node_entry -->|"loads"| node_app
node_app -->|"reads"| node_config
node_app -->|"renders"| node_dashboard
node_dashboard -->|"styled by"| node_dashboard_css
node_app -->|"uses"| node_calculators
node_app -->|"uses"| node_security
node_settings -->|"configures"| node_security
node_app -->|"user-scoped auth and data"| node_supabase_db
node_app -->|"starts Pro purchase"| node_checkout
node_checkout -->|"creates checkout"| node_bachs
node_bachs -->|"payment event"| node_webhook
node_webhook -->|"activates subscription"| node_supabase_db
node_app -->|"requests deletion"| node_delete_account
node_app -->|"requests advice"| node_ai_advisor
node_app -->|"triggers"| node_notifications
node_app -->|"fetches rates"| node_fx_api
node_app -->|"renders charts"| node_chartjs
node_vercel -->|"serves"| node_entry
node_vercel -->|"routes runtime"| node_server

click node_entry "https://github.com/kenoplug/keno-vault/blob/main/index.html"
click node_app "https://github.com/kenoplug/keno-vault/blob/main/js/app.js"
click node_config "https://github.com/kenoplug/keno-vault/blob/main/js/config.js"
click node_dashboard "https://github.com/kenoplug/keno-vault/blob/main/pages/dashboard.html"
click node_dashboard_css "https://github.com/kenoplug/keno-vault/blob/main/css/dashboard.css"
click node_calculators "https://github.com/kenoplug/keno-vault/blob/main/js/calculators.js"
click node_security "https://github.com/kenoplug/keno-vault/blob/main/js/security.js"
click node_settings "https://github.com/kenoplug/keno-vault/blob/main/pages/settings.html"
click node_supabase_db "https://github.com/kenoplug/keno-vault/blob/main/supabase-migration.sql"
click node_checkout "https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/create-checkout/index.ts"
click node_webhook "https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/bachs-webhook/index.ts"
click node_delete_account "https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/delete-account/index.ts"
click node_ai_advisor "https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/ai-advisor/index.ts"
click node_notifications "https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/send-notification/index.ts"
click node_vercel "https://github.com/kenoplug/keno-vault/blob/main/vercel.json"
click node_server "https://github.com/kenoplug/keno-vault/blob/main/server.js"

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_entry,node_app,node_config,node_dashboard,node_dashboard_css,node_calculators,node_security,node_settings toneBlue
class node_supabase_db,node_checkout,node_webhook,node_delete_account,node_ai_advisor,node_notifications toneAmber
class node_bachs,node_fx_api,node_chartjs toneMint
class node_vercel,node_server toneRose
```

## Components

### Browser App

Static vanilla JavaScript client.

- [Public entry](https://github.com/kenoplug/keno-vault/blob/main/index.html): HTML entry · `index.html`
- [App coordinator](https://github.com/kenoplug/keno-vault/blob/main/js/app.js): vanilla JS · Owns UI, auth state, assets, exports, and plan access. · `js/app.js`
- [Client configuration](https://github.com/kenoplug/keno-vault/blob/main/js/config.js): JS config · Supabase and deployment constants. · `js/config.js`
- [Dashboard view](https://github.com/kenoplug/keno-vault/blob/main/pages/dashboard.html): HTML view · `pages/dashboard.html`
- [Dashboard styling](https://github.com/kenoplug/keno-vault/blob/main/css/dashboard.css): CSS · `css/dashboard.css`
- [Financial calculators](https://github.com/kenoplug/keno-vault/blob/main/js/calculators.js): JS module · Net-worth, retirement, debt, allocation, tax, and depreciation models. · `js/calculators.js`
- [Local privacy controls](https://github.com/kenoplug/keno-vault/blob/main/js/security.js): JS security module · Auto-lock, PIN/privacy behavior, and encrypted backups via Web Crypto. · `js/security.js`
- [Settings view](https://github.com/kenoplug/keno-vault/blob/main/pages/settings.html): HTML view · `pages/settings.html`

### Supabase Backend

Identity, user-scoped data, and privileged functions.

- [Auth, PostgreSQL & RLS](https://github.com/kenoplug/keno-vault/blob/main/supabase-migration.sql): Supabase platform · Google identity and user-scoped persistence protected by row-level security. · `supabase-migration.sql`
- [Create checkout](https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/create-checkout/index.ts): Edge Function · Creates Bachs Pro checkout sessions. · `supabase/functions/create-checkout/index.ts`
- [Payment webhook](https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/bachs-webhook/index.ts): Edge Function · Trusted payment handler that updates subscriptions. · `supabase/functions/bachs-webhook/index.ts`
- [Delete account](https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/delete-account/index.ts): Edge Function · Privileged account deletion. · `supabase/functions/delete-account/index.ts`
- [AI advisor](https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/ai-advisor/index.ts): Edge Function · Server-side AI advisory boundary. · `supabase/functions/ai-advisor/index.ts`
- [Notifications](https://github.com/kenoplug/keno-vault/blob/main/supabase/functions/send-notification/index.ts): Edge Function · Outbound notification workflow. · `supabase/functions/send-notification/index.ts`

### External Services

- **Bachs payments**: payment provider · Supports cards, transfers, mobile money, and crypto.
- **Exchange-rate API**: FX data API
- **Chart.js**: chart library

### Hosting

- [Vercel deployment](https://github.com/kenoplug/keno-vault/blob/main/vercel.json): static hosting · Serves the frontend and serverless routes. · `vercel.json`
- [Node server integration](https://github.com/kenoplug/keno-vault/blob/main/server.js): Node runtime · `server.js`

## Connections

- Public entry → App coordinator: loads
- App coordinator → Client configuration: reads
- App coordinator → Dashboard view: renders
- Dashboard view → Dashboard styling: styled by
- App coordinator → Financial calculators: uses
- App coordinator → Local privacy controls: uses
- Settings view → Local privacy controls: configures
- App coordinator → Auth, PostgreSQL & RLS: user-scoped auth and data
- App coordinator → Create checkout: starts Pro purchase
- Create checkout → Bachs payments: creates checkout
- Bachs payments → Payment webhook: payment event
- Payment webhook → Auth, PostgreSQL & RLS: activates subscription
- App coordinator → Delete account: requests deletion
- App coordinator → AI advisor: requests advice
- App coordinator → Notifications: triggers
- App coordinator → Exchange-rate API: fetches rates
- App coordinator → Chart.js: renders charts
- Vercel deployment → Public entry: serves
- Vercel deployment → Node server integration: routes runtime