# darwintjoe/fazai architecture

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

- Interactive diagram: https://gitdiagram.com/darwintjoe/fazai
- Repository: https://github.com/darwintjoe/fazai

## Overview

FAZAI is an offline-capable, browser-based accounting PWA. Users unlock with a PIN, record or import transactions, and review balances and reports; the double-entry ledger and IndexedDB provide its core accounting layer. AI-assisted entry and receipt/statement parsing, contacts, POS imports, and administration are supporting workflows. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README documentation; unsampled components are represented at their existing directory paths where needed.

Main entry points: [`src/app/page.tsx`](https://github.com/darwintjoe/fazai/blob/main/src/app/page.tsx) (App shell), [`src/lib/fazai-db.ts`](https://github.com/darwintjoe/fazai/blob/main/src/lib/fazai-db.ts) (Local accounting data), [`src/components/fazai/report-viewer.tsx`](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/report-viewer.tsx) (Report viewer), [`src/app/api/ai`](https://github.com/darwintjoe/fazai/tree/main/src/app/api/ai) (AI API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_shell["App shell<br/>[page.tsx]"]
  node_pin["PIN login<br/>[pin-login.tsx]"]
  node_dashboard["Dashboard<br/>[dashboard.tsx]"]
end

subgraph group_accounting["Accounting and reports"]
  node_transactions["Transaction entry and history"]
  node_history["Transaction history<br/>[history.tsx]"]
  node_contacts["Contacts<br/>[contacts.tsx]"]
  node_reports["Report viewer<br/>[report-viewer.tsx]"]
  node_ledger["Double-entry ledger<br/>[ledger-engine.ts]"]
end

subgraph group_assistance["AI and imports"]
  node_aiui["AI assistant<br/>[ai-chat.tsx]"]
  node_airoutes["AI API routes"]
  node_provider["AI provider adapters<br/>[ai-provider.ts]"]
  node_receipt["Receipt capture and OCR<br/>[receipt-ocr.tsx]"]
  node_statement["Statement import"]
  node_keywords["Account keyword mapping<br/>[keyword-map.ts]"]
end

subgraph group_operations["Administration and integrations"]
  node_admin["Administration<br/>[admin-panel.tsx]"]
  node_pos["POS import and tracking<br/>[pos-import.ts]"]
  node_backup["Backup and restore<br/>[admin-backup.tsx]"]
end

subgraph group_platform["Local platform"]
  node_db[("Local accounting data<br/>[fazai-db.ts]")]
  node_appstate["App state<br/>[app-store.ts]"]
  node_authstate["Authentication state<br/>[auth-store.ts]"]
  node_sw["Offline service worker<br/>[sw.js]"]
  node_format["Date and number formatting<br/>[format.ts]"]
  node_i18n["Translations<br/>[i18n.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_shell
node_shell -->|"shows"| node_pin
node_shell -->|"renders"| node_dashboard
node_shell -->|"renders"| node_transactions
node_shell -->|"renders"| node_history
node_shell -->|"renders"| node_reports
node_shell -->|"renders"| node_aiui
node_shell -->|"renders"| node_admin
node_pin -->|"authenticates"| node_authstate
node_transactions -.->|"records entries"| node_ledger
node_aiui -->|"creates transactions"| node_ledger
node_ledger -->|"reads and writes"| node_db
node_reports -->|"generates reports"| node_ledger
node_reports -->|"formats values"| node_format
node_reports -->|"renders statement"| node_contacts
node_history -->|"reads transactions"| node_db
node_aiui -.->|"requests assistance"| node_airoutes
node_airoutes -->|"calls provider"| node_provider
node_airoutes -->|"uses mappings"| node_keywords
node_receipt -.->|"requests parsing"| node_airoutes
node_receipt -->|"uses mappings"| node_keywords
node_statement -->|"uses AI provider"| node_provider
node_statement -->|"imports records"| node_db
node_admin -.->|"manages data"| node_db
node_backup -.->|"exports and restores"| node_db
node_pos -.->|"imports sales"| node_db
node_user -->|"uses offline app"| node_sw

click node_shell "https://github.com/darwintjoe/fazai/blob/main/src/app/page.tsx"
click node_pin "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/pin-login.tsx"
click node_dashboard "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/dashboard.tsx"
click node_transactions "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/transaction-form.tsx"
click node_history "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/history.tsx"
click node_contacts "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/contacts.tsx"
click node_reports "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/report-viewer.tsx"
click node_ledger "https://github.com/darwintjoe/fazai/blob/main/src/lib/ledger-engine.ts"
click node_db "https://github.com/darwintjoe/fazai/blob/main/src/lib/fazai-db.ts"
click node_appstate "https://github.com/darwintjoe/fazai/blob/main/src/lib/app-store.ts"
click node_authstate "https://github.com/darwintjoe/fazai/blob/main/src/lib/auth-store.ts"
click node_aiui "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/ai-chat.tsx"
click node_airoutes "https://github.com/darwintjoe/fazai/tree/main/src/app/api/ai"
click node_provider "https://github.com/darwintjoe/fazai/blob/main/src/lib/ai-provider.ts"
click node_receipt "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/receipt-ocr.tsx"
click node_statement "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/statement-import.tsx"
click node_admin "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/admin-panel.tsx"
click node_pos "https://github.com/darwintjoe/fazai/blob/main/src/lib/pos-import.ts"
click node_backup "https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/admin-backup.tsx"
click node_sw "https://github.com/darwintjoe/fazai/blob/main/public/sw.js"
click node_format "https://github.com/darwintjoe/fazai/blob/main/src/lib/format.ts"
click node_i18n "https://github.com/darwintjoe/fazai/blob/main/src/lib/i18n.ts"
click node_keywords "https://github.com/darwintjoe/fazai/blob/main/src/lib/keyword-map.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_shell,node_pin,node_dashboard,node_user toneBlue
class node_transactions,node_history,node_contacts,node_reports,node_ledger toneAmber
class node_aiui,node_airoutes,node_provider,node_receipt,node_statement,node_keywords toneMint
class node_admin,node_pos,node_backup toneRose
class node_db,node_appstate,node_authstate,node_sw,node_format,node_i18n toneIndigo
```

## Components

### App experience

- [App shell](https://github.com/darwintjoe/fazai/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [PIN login](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/pin-login.tsx): `src/components/fazai/pin-login.tsx`
- [Dashboard](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/dashboard.tsx): `src/components/fazai/dashboard.tsx`

### Accounting and reports

- [Transaction entry and history](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/transaction-form.tsx): `src/components/fazai/transaction-form.tsx`
- [Transaction history](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/history.tsx): `src/components/fazai/history.tsx`
- [Contacts](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/contacts.tsx): `src/components/fazai/contacts.tsx`
- [Report viewer](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/report-viewer.tsx): `src/components/fazai/report-viewer.tsx`
- [Double-entry ledger](https://github.com/darwintjoe/fazai/blob/main/src/lib/ledger-engine.ts): `src/lib/ledger-engine.ts`

### AI and imports

- [AI assistant](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/ai-chat.tsx): `src/components/fazai/ai-chat.tsx`
- [AI API routes](https://github.com/darwintjoe/fazai/tree/main/src/app/api/ai): `src/app/api/ai`
- [AI provider adapters](https://github.com/darwintjoe/fazai/blob/main/src/lib/ai-provider.ts): `src/lib/ai-provider.ts`
- [Receipt capture and OCR](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/receipt-ocr.tsx): `src/components/fazai/receipt-ocr.tsx`
- [Statement import](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/statement-import.tsx): `src/components/fazai/statement-import.tsx`
- [Account keyword mapping](https://github.com/darwintjoe/fazai/blob/main/src/lib/keyword-map.ts): `src/lib/keyword-map.ts`

### Administration and integrations

- [Administration](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/admin-panel.tsx): `src/components/fazai/admin-panel.tsx`
- [POS import and tracking](https://github.com/darwintjoe/fazai/blob/main/src/lib/pos-import.ts): `src/lib/pos-import.ts`
- [Backup and restore](https://github.com/darwintjoe/fazai/blob/main/src/components/fazai/admin-backup.tsx): `src/components/fazai/admin-backup.tsx`

### Local platform

- [Local accounting data](https://github.com/darwintjoe/fazai/blob/main/src/lib/fazai-db.ts): `src/lib/fazai-db.ts`
- [App state](https://github.com/darwintjoe/fazai/blob/main/src/lib/app-store.ts): `src/lib/app-store.ts`
- [Authentication state](https://github.com/darwintjoe/fazai/blob/main/src/lib/auth-store.ts): `src/lib/auth-store.ts`
- [Offline service worker](https://github.com/darwintjoe/fazai/blob/main/public/sw.js): `public/sw.js`
- [Date and number formatting](https://github.com/darwintjoe/fazai/blob/main/src/lib/format.ts): `src/lib/format.ts`
- [Translations](https://github.com/darwintjoe/fazai/blob/main/src/lib/i18n.ts): `src/lib/i18n.ts`

### Other components

- **User**

## Connections

- User → App shell: uses
- App shell → PIN login: shows (evidence: `src/app/page.tsx`)
- App shell → Dashboard: renders (evidence: `src/app/page.tsx`)
- App shell → Transaction entry and history: renders (evidence: `src/app/page.tsx`)
- App shell → Transaction history: renders (evidence: `src/app/page.tsx`)
- App shell → Report viewer: renders (evidence: `src/app/page.tsx`)
- App shell → AI assistant: renders (evidence: `src/app/page.tsx`)
- App shell → Administration: renders (evidence: `src/app/page.tsx`)
- PIN login → Authentication state: authenticates (evidence: `src/app/page.tsx`)
- Transaction entry and history → Double-entry ledger: records entries
- AI assistant → Double-entry ledger: creates transactions (evidence: `src/components/fazai/ai-chat.tsx`)
- Double-entry ledger → Local accounting data: reads and writes (evidence: `src/lib/ledger-engine.ts`)
- Report viewer → Double-entry ledger: generates reports (evidence: `src/components/fazai/report-viewer.tsx`)
- Report viewer → Date and number formatting: formats values (evidence: `src/components/fazai/report-viewer.tsx`)
- Report viewer → Contacts: renders statement (evidence: `src/components/fazai/report-viewer.tsx`)
- Transaction history → Local accounting data: reads transactions (evidence: `src/components/fazai/history.tsx`)
- AI assistant → AI API routes: requests assistance
- AI API routes → AI provider adapters: calls provider (evidence: `src/app/api/ai/chat/route.ts`)
- AI API routes → Account keyword mapping: uses mappings (evidence: `src/app/api/ai/chat/route.ts`)
- Receipt capture and OCR → AI API routes: requests parsing
- Receipt capture and OCR → Account keyword mapping: uses mappings (evidence: `src/components/fazai/receipt-ocr.tsx`)
- Statement import → AI provider adapters: uses AI provider (evidence: `src/components/fazai/statement-import.tsx`)
- Statement import → Local accounting data: imports records (evidence: `src/components/fazai/statement-import.tsx`)
- Administration → Local accounting data: manages data
- Backup and restore → Local accounting data: exports and restores
- POS import and tracking → Local accounting data: imports sales
- User → Offline service worker: uses offline app
