How huyphamngoc98nb/taixiucanhan works
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: DashboardPage.tsx Transactions · connection.ts SQLite core · AppBootstrap.tsx Bootstrap · app-repositories.ts Repo registry
Components 22
App shell
Bootstrap, routing, and layout composition for the device-local UI.
- Main entry · Vite/React startup into the app shell.
src/main.tsx - Router · Top-level navigation and route wiring.
src/app/router/index.tsx - Bootstrap · Initializes environment, database, and loading state.
src/app/providers/AppBootstrap.tsx - App unlock · Gates database access behind local unlock.
src/app/providers/AppUnlock.tsx - Main layout · Bottom navigation and routed app framing.
src/app/layouts/MainLayout.tsx
Core infra
Database, security, file, and telemetry foundations.
- SQLite core · Connection, pragmas, health, transaction, and encryption support.
src/core/db/sqlite/connection.ts - Migrations · Ordered SQL migrations and migration runner.
src/core/db/migrations/migration-runner.ts - Repo registry · Wires app repositories and persistence implementations together.
src/core/repositories/app-repositories.ts - Auth service · Local auth and unlock-related logic.
src/core/auth/auth.service.ts - Receipt storage · 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 · Core transaction entry, list, edit, and dashboard flow.
src/modules/transactions/pages/DashboardPage.tsx - Wallets · Wallet/account management and balances.
src/modules/wallets/pages/WalletsPage.tsx - Budgets · Budget setup, progress, status, and alerts.
src/modules/budgets/pages/BudgetSettingsPage.tsx - Recurring bills · Recurring bill schedules and due reminders.
src/modules/recurring-bills/pages/RecurringBillsPage.tsx - Reports · Derived summaries and charts from ledger data.
src/modules/reports/pages/ReportsPage.tsx - Backup · JSON backup, restore, and destructive reload flow.
src/modules/backup/pages/BackupPage.tsx - Export · PDF/Excel/CSV generation and device sharing.
src/modules/export/pages/ExportPage.tsx - Settings · Currency, language, and database diagnostics.
src/modules/settings/pages/SettingsPage.tsx
Shared UI
Reusable UI, contexts, and app-wide utilities.
- Shared UI · Reusable controls, dialogs, loading/error states, and contexts.
src/shared/components/EmptyState.tsx
Platform
Native shell, build outputs, and server-side package.
- Android shell · Capacitor Android wrapper around the web app.
android/app/src/main/java/com/taixiucanhan/app/MainActivity.java - Web bundle · Built static app and SQLite web assets.
dist/index.html - Server pkg · Separate TypeScript package present alongside the device-first app.
server/src/index.ts
Connections 23
- 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.