MoneyFlow

MoneyFlow is a Vietnamese personal-finance web product built around a trustworthy user-owned ledger. The released MVP is manual/import-assisted; the accepted long-term direction is to reduce maintenance by acquiring already-digital activity safely instead of requiring permanent retyping.

Bank/Open API sync, native mobile acquisition, wealth, household finance and AI mutation are not shipped unless merged implementation evidence proves them. Manual capture remains a first-class fallback for cash, corrections and missing/off-system events.

Current work and release status

MoneyFlow has a functional MVP but is not public-beta ready.

For non-trivial work, start with:

npm run agent:doctor -- --json

Repository responsibilities are deliberately separated:

• GitHub Issues/PRs — human backlog, current task status, review and owner decisions.
• Work packets — scoped specification, risks, permissions and evidence when the change class requires one; they are not a queue or authority selector.
• PR memory index — bounded per-PR provenance, loaded only when history is needed.
• Code, tests and migrations — implemented product truth.

Do not infer current work from a filename, date, newest document, open PR or chat summary.

What MoneyFlow does today

• Explicit demo mode with browser-local exploration data.
• Explicit authenticated mode on a pluggable backend: MF_BACKEND_PROVIDER selects Supabase Auth + PostgreSQL/RLS or managed Neon Auth + Neon Data API/RLS. Production currently runs neon.
• Multiple accounts such as cash, bank, e-wallet, credit and savings representations.
• Income, expense and balanced internal transfers.
• Edit, soft delete and recovery paths.
• Account balances, register/history and reconciliation paths.
• Category budgets, recurring commitments/income and savings goals.
• Weekly, monthly and yearly reporting.
• Controlled import/share capture and CSV export.
• Complete versioned account archive at /settings/backup, separate from scoped/report export.
• Responsive light/dark web UI.

The implementation and tests always outrank this summary.

Long-term acquisition direction

bank / provider / statement / share / device-assisted / manual source
  -> source evidence + provenance
  -> normalized candidate
  -> duplicate / transfer / rule decision
  -> review or bounded approved automation
  -> atomic ledger fact
  -> clearing / reconciliation / correction

Provider connectivity is read-only first and optional. MoneyFlow remains useful when a provider is unavailable, consent expires or a source cannot be connected.

Financial and trust invariants

• VND is stored as integer đồng; never floating-point money.
• Internal transfers are equal/opposite movements and never count as income or expense.
• Missing source coverage, planning data, balances, dates, commitments or income are never guessed.
• Destructive ledger actions use recoverable/soft-delete behavior where required.
• Authenticated user-owned data is tenant-isolated through PostgreSQL/RLS.
• Demo and authenticated stores are explicit and never presented as the same source of truth.
• Source/provider evidence is validated through the normal financial path; adapters do not silently create a second ledger.
• Full backup/restore is separate from scoped export.

Runtime modes

NEXT_PUBLIC_APP_MODE is explicit:

• authenticated — managed auth (Neon Auth in production; Supabase Auth when MF_BACKEND_PROVIDER=supabase) + PostgreSQL/RLS.
• demo — browser-local exploration data.

Missing credentials never silently switch the application into demo mode.

Run locally

npm install
cp .env.example .env.local
# Fill documented local values in .env.local
npm run dev

Configuration/provider requirements are owned by docs/configuration.md. Production values belong in provider settings, never committed source files.

Quality checks

Common checks include:

npm run check:knowledge
npm run test:ci-policy
npm run check:deployment-env
npm run check:architecture
npm run check:css-ownership
npm run lint
npm run typecheck
npm run test
npm run build

Boundary-specific verification includes database/RLS, browser/e2e and responsive UI audits when selected by policy. A build does not prove RLS, browser usability, provider configuration, production behavior or physical-device behavior.

Authority route

Start with AGENTS.md and docs/context/README.md.

Question	Authority
Current task scope/status	explicit owner request + GitHub issue/PR
Implemented product truth	current code, tests and migrations
Product identity and principles	docs/product/PRINCIPLES.md
Long-term product strategy	docs/product/PRODUCT_STRATEGY.md
Ecosystem structure/boundaries	docs/product/ECOSYSTEM_STRATEGY.md
Product metrics and stage gates	docs/product/PRODUCT_METRICS.md
Released MVP capability reference	docs/MVP_DEFINITION.md
Architecture	ARCHITECTURE.md
Change classes and gates	docs/engineering/RISK_PROPORTIONAL_DELIVERY.md
Permission/handoff rules	docs/engineering/AGENT_OPERATING_MODEL.md
Context/research routing	docs/context/README.md
Work-packet convention	docs/plans/README.md
App/deployment configuration	docs/configuration.md
External reference repositories	docs/research/MONEYFLOW_REFERENCE_REPO_ATLAS_2026.md

PRINCIPLES.md remains product law. Strategy, ecosystem and metrics documents interpret that law and do not grant implementation permission. Historical research, completed packets and old issues are evidence, not permission to restart work.

Change workflow

1. Read the explicit task/issue/PR, affected code/tests and docs/context/README.md.
2. Create/use a focused non-main branch.
3. Run npm run agent:doctor -- --json and follow the risk-selected gates.
4. Create a full work packet from docs/templates/FEATURE_WORK_PACKET.md when the change class requires it.
5. Implement the smallest coherent change; avoid drive-by refactors.
6. Update the spec before changing requirements.
7. Create the mandatory per-PR provenance record.
8. Require exact-head checks appropriate to the affected boundary.
9. Human owner decides merge, provider writes, deployment and public-beta acceptance.

Do not push feature/fix commits directly to main, force-push shared history, weaken required checks, or treat a long-term roadmap item as runtime authorization.