# paulinotech1/mindful-money architecture

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

- Interactive diagram: https://gitdiagram.com/paulinotech1/mindful-money
- Repository: https://github.com/paulinotech1/mindful-money

## Overview

Vault is a browser-first personal finance tracker: the user imports or enters transactions, the browser encrypts and stores ciphertext through the Flask API, then decrypts records locally for finance views. Passkeys protect server access but do not replace the local passphrase-derived vault key. The graph also preserves documented recovery, security management, and manual-expense proof capabilities. The excerpts show the database/session foundations and parts of the browser and ZKP clients; some API relationships below are supported by README statements rather than sampled route bodies.

Main entry points: [`static/app.js`](https://github.com/paulinotech1/mindful-money/blob/main/static/app.js) (Finance UI), [`app.py`](https://github.com/paulinotech1/mindful-money/blob/main/app.py) (Flask API), [`static/zkp/manual_expense_v4_client.js`](https://github.com/paulinotech1/mindful-money/blob/main/static/zkp/manual_expense_v4_client.js) (Manual expense proofs), [`db.py`](https://github.com/paulinotech1/mindful-money/blob/main/db.py) (Database lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser finance app"]
  node_ui["Finance UI<br/>[app.js]"]
  node_bank["Bank and CSV import"]
  node_local_crypto["Local encryption and analytics<br/>[app.js]"]
  node_recovery_words["Recovery words<br/>[recovery-words.js]"]
end

subgraph group_server["Vault API"]
  node_api["Flask API<br/>[app.py]"]
  node_auth["Passkey sessions<br/>[app.py]"]
  node_record_api["Ciphertext records<br/>[app.py]"]
  node_security["Security and recovery<br/>[app.py]"]
end

subgraph group_storage["Persistent state"]
  node_db["Database lifecycle<br/>[db.py]"]
  node_models["Tenant and vault data<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_proofs["Proof verification"]
  node_zkp_client["Manual expense proofs"]
  node_zkp_core["Proof cryptography"]
  node_zkp_verify["Proof verifier<br/>[zkp_verifier.py]"]
end

node_user(("Vault user"))

node_user -->|"uses"| node_ui
node_ui -->|"imports transactions"| node_bank
node_ui -->|"encrypts and analyzes"| node_local_crypto
node_local_crypto -->|"uploads ciphertext"| node_record_api
node_record_api -->|"returns ciphertext"| node_local_crypto
node_ui -->|"signs in"| node_auth
node_ui -->|"manages vault"| node_security
node_ui -.->|"uses recovery"| node_recovery_words
node_api -->|"uses database"| node_db
node_db -->|"seeds identity"| node_models
node_db -->|"opens sessions"| node_postgres
node_models -->|"defines persisted data"| node_postgres
node_api -->|"verifies proofs"| node_zkp_verify
node_zkp_client -->|"uses cryptographic helpers"| node_zkp_core
node_zkp_client -->|"requests challenges"| node_api
node_api -.->|"routes record operations"| node_record_api
node_api -.->|"enforces access"| node_auth
node_api -.->|"serves security operations"| node_security
node_zkp_client -.->|"submits proof"| node_zkp_verify

click node_ui "https://github.com/paulinotech1/mindful-money/blob/main/static/app.js"
click node_bank "https://github.com/paulinotech1/mindful-money/blob/main/static/simplefin-client.js"
click node_local_crypto "https://github.com/paulinotech1/mindful-money/blob/main/static/app.js"
click node_recovery_words "https://github.com/paulinotech1/mindful-money/blob/main/static/recovery-words.js"
click node_api "https://github.com/paulinotech1/mindful-money/blob/main/app.py"
click node_auth "https://github.com/paulinotech1/mindful-money/blob/main/app.py"
click node_record_api "https://github.com/paulinotech1/mindful-money/blob/main/app.py"
click node_security "https://github.com/paulinotech1/mindful-money/blob/main/app.py"
click node_db "https://github.com/paulinotech1/mindful-money/blob/main/db.py"
click node_models "https://github.com/paulinotech1/mindful-money/blob/main/models.py"
click node_zkp_client "https://github.com/paulinotech1/mindful-money/blob/main/static/zkp/manual_expense_v4_client.js"
click node_zkp_core "https://github.com/paulinotech1/mindful-money/blob/main/static/zkp/manual_expense_v4_core.js"
click node_zkp_verify "https://github.com/paulinotech1/mindful-money/blob/main/zkp_verifier.py"

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_ui,node_bank,node_local_crypto,node_recovery_words,node_user toneBlue
class node_api,node_auth,node_record_api,node_security toneAmber
class node_db,node_models,node_postgres toneMint
class node_zkp_client,node_zkp_core,node_zkp_verify toneRose
```

## Components

### Browser finance app

- [Finance UI](https://github.com/paulinotech1/mindful-money/blob/main/static/app.js): `static/app.js`
- [Bank and CSV import](https://github.com/paulinotech1/mindful-money/blob/main/static/simplefin-client.js): `static/simplefin-client.js`
- [Local encryption and analytics](https://github.com/paulinotech1/mindful-money/blob/main/static/app.js): `static/app.js`
- [Recovery words](https://github.com/paulinotech1/mindful-money/blob/main/static/recovery-words.js): `static/recovery-words.js`

### Vault API

- [Flask API](https://github.com/paulinotech1/mindful-money/blob/main/app.py): `app.py`
- [Passkey sessions](https://github.com/paulinotech1/mindful-money/blob/main/app.py): `app.py`
- [Ciphertext records](https://github.com/paulinotech1/mindful-money/blob/main/app.py): `app.py`
- [Security and recovery](https://github.com/paulinotech1/mindful-money/blob/main/app.py): `app.py`

### Persistent state

- [Database lifecycle](https://github.com/paulinotech1/mindful-money/blob/main/db.py): `db.py`
- [Tenant and vault data](https://github.com/paulinotech1/mindful-money/blob/main/models.py): `models.py`
- **PostgreSQL**

### Proof verification

- [Manual expense proofs](https://github.com/paulinotech1/mindful-money/blob/main/static/zkp/manual_expense_v4_client.js): `static/zkp/manual_expense_v4_client.js`
- [Proof cryptography](https://github.com/paulinotech1/mindful-money/blob/main/static/zkp/manual_expense_v4_core.js): `static/zkp/manual_expense_v4_core.js`
- [Proof verifier](https://github.com/paulinotech1/mindful-money/blob/main/zkp_verifier.py): `zkp_verifier.py`

### Other components

- **Vault user**

## Connections

- Vault user → Finance UI: uses (evidence: `README.md`)
- Finance UI → Bank and CSV import: imports transactions (evidence: `README.md`)
- Finance UI → Local encryption and analytics: encrypts and analyzes (evidence: `README.md`)
- Local encryption and analytics → Ciphertext records: uploads ciphertext (evidence: `README.md`)
- Ciphertext records → Local encryption and analytics: returns ciphertext (evidence: `README.md`)
- Finance UI → Passkey sessions: signs in (evidence: `README.md`)
- Finance UI → Security and recovery: manages vault (evidence: `README.md`)
- Finance UI → Recovery words: uses recovery
- Flask API → Database lifecycle: uses database (evidence: `app.py`)
- Database lifecycle → Tenant and vault data: seeds identity (evidence: `db.py`)
- Database lifecycle → PostgreSQL: opens sessions (evidence: `db.py`)
- Tenant and vault data → PostgreSQL: defines persisted data (evidence: `models.py`)
- Flask API → Proof verifier: verifies proofs (evidence: `app.py`)
- Manual expense proofs → Proof cryptography: uses cryptographic helpers (evidence: `static/zkp/manual_expense_v4_client.js`)
- Manual expense proofs → Flask API: requests challenges (evidence: `static/zkp/manual_expense_v4_client.js`)
- Flask API → Ciphertext records: routes record operations (evidence: `app.py`)
- Flask API → Passkey sessions: enforces access (evidence: `app.py`)
- Flask API → Security and recovery: serves security operations (evidence: `app.py`)
- Manual expense proofs → Proof verifier: submits proof
