# huyphamngoc98nb/taixiucanhan architecture

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

- Interactive diagram: https://gitdiagram.com/huyphamngoc98nb/taixiucanhan
- Repository: https://github.com/huyphamngoc98nb/taixiucanhan

## Overview

1. **What this repository is**
   - A **local-first expense tracker** built with **React + Vite + TypeScript**, then packaged for **Android via Capacitor**.
   - The app is designed to work **offline**, with **SQLite as the source of truth** rather than a remote backend.

2. **Runtime boundaries**
   - The primary runtime is the **frontend app** bundled into `dist/` and hosted inside the Capacitor Android shell under `android/`.
   - SQLite is accessed through the Capacitor SQLite stack, with **`jeep-sqlite` / `sql.js`** used for web development.
   - A separate `server/` TypeScript package exists, but the README and folder layout position the app as **device-local first**, not server-driven.

3. **Application shell**
   - `src/app/` contains the top-level composition: **layouts, routing, providers, and bootstrap flow**.
   - `AppBootstrap`, `AppProvider`, `AppUnlock`, and `GlobalErrorBoundary` establish the startup pipeline: initialize environment/security/DB, handle loading and failure states, and then render the app shell.
   - `MainLayout` provides the app’s **bottom navigation** and route framing.

4. **Domain-driven module structure**
   - Business logic is split by feature under `src/modules/`: **transactions, wallets, budgets, recurring bills, reports, backup, export, settings, auth, categories**.
   - Each module generally owns its **pages, components, hooks, services, repositories, and domain models**.
   - This keeps UI, state, and data access aligned around feature boundaries instead of a single global store.

5. **Data flow pattern**
   - The common path is: **page/component → hook → service → repository → SQLite**.
   - Hooks such as `useTransactions`, `useBudgets`, `useRecurringBills`, and `useWallets` manage async view state for the UI.
   - Services perform business rules and orchestration; repositories isolate persistence and SQL-specific details.

6. **Persistence layer**
   - `src/core/db/` is the main infrastructure layer for **SQLite connections, migrations, transactions, pragmas, health checks, and encryption**.
   - Migrations are stored as ordered SQL files (`001_init.sql` through later schema changes), with a `migration-runner.ts` coordinating schema upgrades.
   - The repository layer includes both **SQLite-backed implementations** and abstractions used by tests and feature code.

7. **Security and app unlock**
   - The app is configured for **SQLCipher-encrypted SQLite** and gates database access behind **PIN/biometric-style unlock** before initialization.
   - This makes security part of the startup boundary rather than a feature-level concern.
   - `src/core/auth/auth.service.ts` and `src/app/providers/AppUnlock.tsx` are the main visible pieces of that gate.

8. **Key domain flows**
   - **Transactions** drive the core financial ledger and feed derived features like dashboard summaries, budgets, and reports.
   - **Wallets** represent accounts and are used for balance calculations and transaction scoping.
   - **Budgets** are category- and scope-aware, with logic for progress, alerts, and status classification.
   - **Recurring bills** compute next due dates and reminder visibility, then surface reminders on the dashboard.

9. **Derived analytics and reporting**
   - Reports are not a separate data source; they are computed from transaction and wallet data.
   - `reports` includes services for **cashflow summaries, category summaries, and period summaries**, which feed chart components and summary cards.
   - The dashboard is also a derived view model built from core ledger data, not a duplicated dataset.

10. **Backup and export**
   - The app has two distinct portability paths:
     - **Backup/restore**: JSON-based full-database portability, including app data and metadata.
     - **Export**: human-readable outputs such as **PDF** and **Excel/CSV** for analysis and sharing.
   - Backup restore is explicitly **destructive** and follows a wipe-and-reload model.
   - Receipt files are treated specially: backups preserve **paths/metadata**, not the binary images themselves.

11. **File and device integration**
   - `src/core/files/receipt-storage.ts` indicates device-local file handling for receipt images.
   - `src/modules/export/services/share-file.ts` suggests exports are handed off to the host device for sharing.
   - These are important boundaries because they separate **database state** from **native file storage** and OS-level sharing.

12. **Shared UI and cross-cutting state**
   - `src/shared/` holds reusable UI controls, dialogs, toasts, empty/loading/error states, and global context.
   - `CurrencyContext` and `LanguageContext` are the main shared-state mechanisms called out in the README; they are meant for **UI concerns**, not database row replication.
   - The design explicitly prefers SQLite for durable state and keeps React context narrow.

13. **Settings and diagnostics**
   - The settings area is both user-facing and operational.
   - It includes **currency, language, and database diagnostics**, which are used to verify initialization, schema version, and seed/data integrity.
   - This makes diagnostics part of the product’s runtime architecture, not just development tooling.

14. **Testing and quality**
   - `src/tests/` contains unit and integration-style tests for **auth, DB, backup, budgets, reports, translations, logger, transactions, and UI behavior**.
   - The presence of in-memory repository fakes shows a clear separation between **domain logic** and **SQLite implementation**, enabling testable boundaries.

15. **Platform/tooling footprint**
   - The app is built with **TypeScript, React, Vite, and Capacitor**, with Android-specific sources under `android/`.
   - ESLint/Prettier and Vitest are part of the repo’s development toolchain.
   - `public/assets/sql-wasm.wasm` and `dist/` are important because the web build must include SQLite WebAssembly support for local development and Capacitor packaging.

Main entry points: [`src/modules/transactions/pages/DashboardPage.tsx`](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/transactions/pages/DashboardPage.tsx) (Transactions), [`src/core/db/sqlite/connection.ts`](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/db/sqlite/connection.ts) (SQLite core), [`src/app/providers/AppBootstrap.tsx`](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/providers/AppBootstrap.tsx) (Bootstrap), [`src/core/repositories/app-repositories.ts`](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/repositories/app-repositories.ts) (Repo registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App shell"]
  node_node_main["Main entry<br/>react entry<br/>[main.tsx]"]
  node_node_router["Router<br/>route config<br/>[index.tsx]"]
  node_node_bootstrap["Bootstrap<br/>startup provider<br/>[AppBootstrap.tsx]"]
  node_node_unlock["App unlock<br/>security gate<br/>[AppUnlock.tsx]"]
  node_node_layout["Main layout<br/>shell layout<br/>[MainLayout.tsx]"]
end

subgraph group_group_core["Core infra"]
  node_node_db[("SQLite core<br/>db runtime<br/>[connection.ts]")]
  node_node_migrations["Migrations<br/>schema upgrades"]
  node_node_repos["Repo registry<br/>infrastructure"]
  node_node_auth["Auth service<br/>security service<br/>[auth.service.ts]"]
  node_node_receipts["Receipt storage<br/>device files<br/>[receipt-storage.ts]"]
end

subgraph group_group_domains["Domain modules"]
  node_node_tx["Transactions<br/>ledger module<br/>[DashboardPage.tsx]"]
  node_node_wallets["Wallets<br/>accounts module<br/>[WalletsPage.tsx]"]
  node_node_budgets["Budgets<br/>planning module"]
  node_node_bills["Recurring bills<br/>reminders module"]
  node_node_reports["Reports<br/>analytics module<br/>[ReportsPage.tsx]"]
  node_node_backup["Backup<br/>portability<br/>[BackupPage.tsx]"]
  node_node_export["Export<br/>output module<br/>[ExportPage.tsx]"]
  node_node_settings["Settings<br/>preferences<br/>[SettingsPage.tsx]"]
end

subgraph group_group_shared["Shared UI"]
  node_node_shared["Shared UI<br/>ui kit<br/>[EmptyState.tsx]"]
end

subgraph group_group_platform["Platform"]
  node_node_android["Android shell<br/>native host<br/>[MainActivity.java]"]
  node_node_web["Web bundle<br/>build output<br/>[index.html]"]
  node_node_server["Server pkg<br/>ts package<br/>[index.ts]"]
end

node_node_main -->|"starts"| node_node_bootstrap
node_node_bootstrap -->|"gates"| node_node_unlock
node_node_bootstrap -->|"opens"| node_node_db
node_node_unlock -->|"uses"| node_node_auth
node_node_bootstrap -->|"renders"| node_node_router
node_node_router -->|"frames"| node_node_layout
node_node_layout -->|"uses"| node_node_shared
node_node_db -->|"applies"| node_node_migrations
node_node_repos -->|"binds"| node_node_db
node_node_tx -->|"reads/writes"| node_node_repos
node_node_wallets -->|"reads/writes"| node_node_repos
node_node_budgets -->|"derives from"| node_node_tx
node_node_bills -->|"derives from"| node_node_tx
node_node_reports -->|"summarizes"| node_node_tx
node_node_reports -->|"summarizes"| node_node_wallets
node_node_backup -->|"exports/imports"| node_node_db
node_node_export -->|"builds from"| node_node_tx
node_node_export -->|"shares"| node_node_shared
node_node_tx -->|"attaches"| node_node_receipts
node_node_settings -->|"diagnoses"| node_node_db
node_node_android -->|"hosts"| node_node_web
node_node_web -->|"packages"| node_node_shared
node_node_server -.->|"separate"| node_node_db

click node_node_main "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/main.tsx"
click node_node_router "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/router/index.tsx"
click node_node_bootstrap "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/providers/AppBootstrap.tsx"
click node_node_unlock "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/providers/AppUnlock.tsx"
click node_node_layout "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/layouts/MainLayout.tsx"
click node_node_db "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/db/sqlite/connection.ts"
click node_node_migrations "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/db/migrations/migration-runner.ts"
click node_node_repos "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/repositories/app-repositories.ts"
click node_node_auth "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/auth/auth.service.ts"
click node_node_receipts "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/files/receipt-storage.ts"
click node_node_tx "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/transactions/pages/DashboardPage.tsx"
click node_node_wallets "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/wallets/pages/WalletsPage.tsx"
click node_node_budgets "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/budgets/pages/BudgetSettingsPage.tsx"
click node_node_bills "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/recurring-bills/pages/RecurringBillsPage.tsx"
click node_node_reports "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/reports/pages/ReportsPage.tsx"
click node_node_backup "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/backup/pages/BackupPage.tsx"
click node_node_export "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/export/pages/ExportPage.tsx"
click node_node_settings "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/settings/pages/SettingsPage.tsx"
click node_node_shared "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/shared/components/EmptyState.tsx"
click node_node_android "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/android/app/src/main/java/com/taixiucanhan/app/MainActivity.java"
click node_node_web "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/dist/index.html"
click node_node_server "https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/server/src/index.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_node_main,node_node_router,node_node_bootstrap,node_node_unlock,node_node_layout toneBlue
class node_node_db,node_node_migrations,node_node_repos,node_node_auth,node_node_receipts toneAmber
class node_node_tx,node_node_wallets,node_node_budgets,node_node_bills,node_node_reports,node_node_backup,node_node_export,node_node_settings toneMint
class node_node_shared toneRose
class node_node_android,node_node_web,node_node_server toneIndigo
```

## Components

### App shell

Bootstrap, routing, and layout composition for the device-local UI.

- [Main entry](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/main.tsx): react entry · Vite/React startup into the app shell. · `src/main.tsx`
- [Router](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/router/index.tsx): route config · Top-level navigation and route wiring. · `src/app/router/index.tsx`
- [Bootstrap](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/providers/AppBootstrap.tsx): startup provider · Initializes environment, database, and loading state. · `src/app/providers/AppBootstrap.tsx`
- [App unlock](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/providers/AppUnlock.tsx): security gate · Gates database access behind local unlock. · `src/app/providers/AppUnlock.tsx`
- [Main layout](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/app/layouts/MainLayout.tsx): shell layout · Bottom navigation and routed app framing. · `src/app/layouts/MainLayout.tsx`

### Core infra

Database, security, file, and telemetry foundations.

- [SQLite core](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/db/sqlite/connection.ts): db runtime · Connection, pragmas, health, transaction, and encryption support. · `src/core/db/sqlite/connection.ts`
- [Migrations](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/db/migrations/migration-runner.ts): schema upgrades · Ordered SQL migrations and migration runner. · `src/core/db/migrations/migration-runner.ts`
- [Repo registry](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/repositories/app-repositories.ts): infrastructure · Wires app repositories and persistence implementations together. · `src/core/repositories/app-repositories.ts`
- [Auth service](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/auth/auth.service.ts): security service · Local auth and unlock-related logic. · `src/core/auth/auth.service.ts`
- [Receipt storage](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/core/files/receipt-storage.ts): device files · Device-local receipt file handling and path metadata. · `src/core/files/receipt-storage.ts`

### Domain modules

Feature modules that own business logic and screens.

- [Transactions](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/transactions/pages/DashboardPage.tsx): ledger module · Core transaction entry, list, edit, and dashboard flow. · `src/modules/transactions/pages/DashboardPage.tsx`
- [Wallets](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/wallets/pages/WalletsPage.tsx): accounts module · Wallet/account management and balances. · `src/modules/wallets/pages/WalletsPage.tsx`
- [Budgets](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/budgets/pages/BudgetSettingsPage.tsx): planning module · Budget setup, progress, status, and alerts. · `src/modules/budgets/pages/BudgetSettingsPage.tsx`
- [Recurring bills](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/recurring-bills/pages/RecurringBillsPage.tsx): reminders module · Recurring bill schedules and due reminders. · `src/modules/recurring-bills/pages/RecurringBillsPage.tsx`
- [Reports](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/reports/pages/ReportsPage.tsx): analytics module · Derived summaries and charts from ledger data. · `src/modules/reports/pages/ReportsPage.tsx`
- [Backup](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/backup/pages/BackupPage.tsx): portability · JSON backup, restore, and destructive reload flow. · `src/modules/backup/pages/BackupPage.tsx`
- [Export](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/export/pages/ExportPage.tsx): output module · PDF/Excel/CSV generation and device sharing. · `src/modules/export/pages/ExportPage.tsx`
- [Settings](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/modules/settings/pages/SettingsPage.tsx): preferences · Currency, language, and database diagnostics. · `src/modules/settings/pages/SettingsPage.tsx`

### Shared UI

Reusable UI, contexts, and app-wide utilities.

- [Shared UI](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/src/shared/components/EmptyState.tsx): ui kit · Reusable controls, dialogs, loading/error states, and contexts. · `src/shared/components/EmptyState.tsx`

### Platform

Native shell, build outputs, and server-side package.

- [Android shell](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/android/app/src/main/java/com/taixiucanhan/app/MainActivity.java): native host · Capacitor Android wrapper around the web app. · `android/app/src/main/java/com/taixiucanhan/app/MainActivity.java`
- [Web bundle](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/dist/index.html): build output · Built static app and SQLite web assets. · `dist/index.html`
- [Server pkg](https://github.com/huyphamngoc98nb/taixiucanhan/blob/main/server/src/index.ts): ts package · Separate TypeScript package present alongside the device-first app. · `server/src/index.ts`

## Connections

- Main entry → Bootstrap: starts · App entry mounts the startup providers.
- Bootstrap → App unlock: gates · Unlock happens before database access and shell render.
- Bootstrap → SQLite core: opens · Initialization creates or verifies the SQLite runtime.
- App unlock → Auth service: uses · Unlock flow delegates to local auth logic.
- Bootstrap → Router: renders · Successful startup hands off to routing.
- Router → Main layout: frames · Routes are rendered inside the main shell layout.
- Main layout → Shared UI: uses · Layout depends on shared UI controls and global state.
- SQLite core → Migrations: applies · Schema changes are coordinated through the migration runner.
- Repo registry → SQLite core: binds · Repository implementations sit on top of SQLite.
- Transactions → Repo registry: reads/writes · Transactions use repositories for persistence.
- Wallets → Repo registry: reads/writes · Wallet state is persisted through repository bindings.
- Budgets → Transactions: derives from · Budget progress is computed from transaction activity.
- Recurring bills → Transactions: derives from · Reminder timing is based on ledger and schedule data.
- Reports → Transactions: summarizes · Reports aggregate transaction data.
- Reports → Wallets: summarizes · Reports also use wallet balances and scope.
- Backup → SQLite core: exports/imports · Backup restore and export operate on the local database.
- Export → Transactions: builds from · Exports are assembled from transactional datasets.
- Export → Shared UI: shares · Export flows reuse UI feedback and file sharing helpers.
- Transactions → Receipt storage: attaches · Transactions can reference device-local receipt files.
- Settings → SQLite core: diagnoses · Settings surface database health and schema status.
- Android shell → Web bundle: hosts · Android shell loads the built web bundle.
- Web bundle → Shared UI: packages · The web build contains the shared React UI.
- Server pkg → SQLite core: separate · A separate TypeScript package exists but is not the primary runtime.
