# Lakshmi Domain - Features > Personal Finance Intelligence Platform (TODO Phase 61) Lakshmi is the Oshun bounded context for personal and household finance. It gives users a single, consent-driven view of every account they hold — banks, brokerages, loans, credit cards, crypto wallets, real estate, insurance policies, and more — and turns that aggregated picture into actionable planning: budgets, goals, debt payoff, tax optimization, retirement projections, and AI-powered recommendations. The platform is designed for individuals and households at every financial sophistication level. A first-time budgeter can link a checking account and track spending; an advanced investor can analyze portfolio attribution, harvest tax losses, run Monte Carlo retirement simulations, and manage equity compensation. A financial advisor can be granted time-limited, scoped read access to a client's full financial picture. Lakshmi spans accounts, transactions, budgeting, investments, tax, debt, credit, retirement, insurance, estate, real-estate finance, crypto, income, goals, behavioral finance, household sharing, and self-employed/small-business finance. ## Implementation Status Lakshmi is **implemented**. The domain ships as **24 TypeScript libraries** under `libs/lakshmi/*` and **6 service applications** under `apps/lakshmi/*`, covering the full Phase 61 capability surface — every layer and every capability module below exists in source. `@lakshmi/transactions`, `@lakshmi/budgeting`, and `@lakshmi/behavioral` together back the V2 responsible-play spend-insight integration. Cross-domain contracts will be published under `@contracts/lakshmi` (planned; not yet present in source). ## Architecture: Five-Layer Model Lakshmi is organized into five layers. Every feature below belongs to one layer, and the layering is a hard dependency rule — higher layers depend on lower ones, never the reverse. This constraint prevents circular dependencies and keeps the core primitives stable. - **Core** — money, account, institution, household, user, advisor-access, financial-profile, and calculation primitives, plus the Drizzle ORM data layer. `@lakshmi/core`, `@lakshmi/db`. - **Integration** — bank, card, brokerage, crypto, tax, payroll, payment, and document ingestion adapters. `@lakshmi/accounts`, `@lakshmi/integrations`. - **Intelligence** — categorization, forecasting, risk analysis, optimization, planning, and behavioral insight. `@lakshmi/transactions`, `@lakshmi/budgeting`, `@lakshmi/behavioral`, `@lakshmi/investments`, `@lakshmi/ai-engine`, and the tax/debt/credit/retirement/insurance/estate/ real-estate/crypto/income/goals/household/business modules. - **Security** — consent, encryption, PII minimization, fraud detection, audit logging, and regulatory controls. `@lakshmi/security`. - **Experience** — dashboards, alerts, reports, and guided planning flows. `@lakshmi/reporting`, `@lakshmi/alerts`, surfaced through the `apps/lakshmi/*` services (`api-gateway`, `sync-engine`, `ai-agents`, `worker`, `scheduler`, `browser-extension`). ## Core Domain Objects `@lakshmi/core` defines the primitives every other layer builds on. Understanding these types is the starting point for working on any Lakshmi library: branded IDs, the `FinancialAccount` model, the user/household/advisor model, the `Money` value object, and a financial calculation engine. Branded ID types (`UserId`, `HouseholdId`, `AdvisorId`, `AdvisorAccessTokenId`, `AccountId`, `ConnectionId`, `InstitutionId`, `ManualAssetId`) prevent accidental cross-entity reference at compile time — the TypeScript compiler will reject code that accidentally passes an `AccountId` where a `UserId` is expected. Every monetary field is stored as **integer cents** to avoid floating-point drift. - **`FinancialAccount`** — a discriminated union over a `type` field with **32 account variants** across eight `AccountCategory` groups: `depository` (checking, savings, CD, money market), `credit` (credit card), `loan` (mortgage, auto, student, personal, HELOC), `investment` (brokerage, traditional/Roth/SEP/SIMPLE IRA, 401k/403b/457b, HSA, FSA, 529, UTMA/UGMA, trust, pension, annuity), `crypto` (exchange, wallet, DeFi position), `real_estate`, `business`, and `manual` (manual asset, manual liability). Each variant carries an `AccountSign` (`asset` or `liability`) that drives its net-worth contribution. Every account shares an `AccountBase` (`AccountId`, `userId`, optional `householdId`, `institutionId`, optional `connectionId`, currency, net-worth/sharing flags, and a `status` of `active`, `inactive`, `closed`, `frozen`, or `pending`). - **`AccountConnection`** — the consent-bearing link to an aggregation provider, identified by a branded `ConnectionId`. Its `ConnectionStatus` begins `active` and may move to `degraded` (partial data), `pending_mfa` / `pending_oauth` (awaiting authentication), `disconnected` (re-authentication required), `error` (unrecoverable), or `revoked` (token revoked by the institution or user). Only an `active` connection refreshes balances; a `disconnected` or `pending_mfa` connection surfaces a reconnect prompt and is driven back to `active` by a successful re-authentication. - **`LakshmiUser`, `Household`, `FinancialProfile`** — `LakshmiUser` carries auth metadata, residence, subscription `tier` (`free` / `premium` / `family`), onboarding state, notification and privacy settings, and a soft-delete field for GDPR right-to-erasure. `Household` groups members under role-based access (`owner`, `admin`, `member`, `viewer`, `child`) with per-account designations and shared goals. `FinancialProfile` holds the risk-tolerance score, income bracket, tax filing status, employment type, and retirement assumptions used by the intelligence layer. - **`AdvisorAccess`** — a time-limited, scoped grant letting a financial advisor read a client's data. Its `expiresAt` is mandatory — advisor access is never indefinite — and every access is recorded in an audit `accessLog`. - **`Institution`** — a financial-institution record with per-provider coverage, regulator identifiers (FDIC / NCUA), and a reliability score. - **`Money`** — an immutable value object holding integer minor units plus an ISO 4217 currency. Arithmetic preserves currency and rejects cross-currency operations; division and `fromDecimal` use banker's rounding. `@lakshmi/core` also ships a calculation engine (compound interest, amortization, time-value-of-money, Monte Carlo, federal/state tax brackets, risk metrics, Social Security). Transactions and financial goals are **not** core entities — they are owned by `@lakshmi/transactions` and `@lakshmi/goals` respectively, and persisted by `@lakshmi/db`. ## Integration Layer ### Account Aggregation (`@lakshmi/accounts`, `@lakshmi/integrations`) The integration layer is the bridge between external financial institutions and Lakshmi's internal domain model. It normalizes wildly different provider APIs into uniform `FinancialAccount` records so that every higher layer can work with a single model regardless of whether the data came from Plaid, Yodlee, or a manual entry. `@lakshmi/accounts` connects bank, brokerage, card, payroll, tax, crypto, and payment institutions through aggregation-provider adapters (Plaid, Yodlee, MX, Finicity, Tink) and turns them into `FinancialAccount` records. `@lakshmi/integrations` adds FDX/PSD2/CDR open-banking adapters and document storage. Balance refresh pulls current balances and new transactions for `active` connections only. Account-health checks surface stale syncs, low balances, and institution outages. The MFA / re-authentication flow drives a `pending_mfa` or `disconnected` connection back to `active`. Sync-failure handling distinguishes a transient institution error (retry) from a credential failure (move to `disconnected`, prompt reconnect). Data lineage records which adapter and sync run produced each record; duplicate detection prevents the same posted transaction from being ingested twice across overlapping sync windows. All integrations are consent-first and revocable (see Privacy and Compliance). ## Intelligence Layer The intelligence layer is where raw financial data becomes insight. Each module below owns a specific reasoning domain; they share core primitives but are otherwise independent so they can be tested and evolved separately. ### Transaction Intelligence (`@lakshmi/transactions`) Every transaction that enters Lakshmi flows through this module before it appears in any budget or report. `@lakshmi/transactions` normalizes and categorizes ingested transactions, organized into four module groups: categorization, merchants, receipts, and analysis. Categorization assigns each transaction a spending category from a Plaid-style taxonomy, with a confidence tier; low-confidence results route to a manual-review queue, and a personalization engine learns from user corrections. A user-supplied correction is recorded as a `user_override` categorization and pins the category against future automated re-categorization. Merchant enrichment resolves a raw descriptor to a canonical merchant, logo, and category hint. Receipt OCR extracts amounts, dates, and line items and matches receipts to transactions. Recurring-transaction detection identifies subscriptions and regular bills from amount and cadence regularity. Anomaly detection flags a transaction that deviates from the account's established pattern — an unusual amount, a new merchant, an out-of-pattern location, time, or frequency — for user review. Refund matching, pending-settlement prediction, splits, fee disaggregation, and international/travel FX handling refine a transaction further. ### Budgeting and Cash Flow (`@lakshmi/budgeting`) Budgeting is the most common entry point for new users. `@lakshmi/budgeting` builds envelope budgets and tracks spending against them so users always know how much they have left in each category before the period ends. An envelope is a named, periodic spending allocation; zero-based plans assign every dollar of projected income to an envelope or a goal. Spending velocity tracks the rate of spend within an envelope against the elapsed fraction of the period — a velocity above 1.0 means the envelope is on pace to overspend. Variance tracking reports actual-versus-planned per envelope at period close. Rollover carries an envelope's unspent balance into the next period when configured. Bills, savings rate, and runway (months of expenses covered by liquid balances) are derived cash-flow metrics. Shared budgets and household permissions let multiple household members view or edit envelopes under a permission policy. Budget overage is **warning-only** by default — it never blocks a transaction — unless a self-imposed cap or guardian control explicitly escalates it. ### Behavioral Finance (`@lakshmi/behavioral`) Most financial apps tell users what happened; behavioral finance helps them understand why and nudges them toward their goals. `@lakshmi/behavioral` owns impulse detection, nudges, and weekly reflection. Impulse detection flags a likely impulse purchase from signals such as an out-of-pattern discretionary spend, time of day, and merchant category, and can surface an at-checkout or post-transaction prompt. Nudges are short, opt-in behavioral prompts toward a user's stated goals — for example, a reminder when discretionary spending outpaces a savings goal. Weekly reflection assembles a summary of the week's spending, envelope variance, and goal progress into a reflective recap. All behavioral interventions require explicit user opt-in before they are applied; habit-formation tracking measures streaks against user-set financial habits. ### Investment Management (`@lakshmi/investments`) `@lakshmi/investments` gives investors a complete picture of their portfolios across all custodians. It tracks holdings, asset allocation, and portfolio performance. It maintains holdings with cost basis and tax lots, computes performance attribution and risk, tallies fees, and proposes rebalancing trades to restore a target allocation. Dividend tracking and retirement-account holdings are included; portfolio scenario modeling projects outcomes under varied return assumptions. ### Tax Planning (`@lakshmi/tax`) Tax is one of the largest controllable costs in a financial plan. `@lakshmi/tax` estimates and optimizes tax throughout the year rather than just at filing time. It tracks deductions, credits, and withholding, computes estimated quarterly taxes, identifies capital-gains harvesting opportunities from tax lots, and handles crypto and self-employment tax. Document collection assembles the records a filing needs; filing is a handoff — Lakshmi prepares and explains, it does not file. Tax outputs are clearly separated into information versus regulated advice (see Privacy and Compliance). ### Debt and Credit (`@lakshmi/debt`, `@lakshmi/credit`) Debt management and credit health are closely related but distinct concerns. `@lakshmi/debt` and `@lakshmi/credit` address them separately. `@lakshmi/debt` computes amortization schedules, compares payoff strategies (avalanche by interest rate, snowball by balance), evaluates refinancing, and optimizes interest cost across multiple debts. `@lakshmi/credit` tracks the credit profile, utilization, and score drivers, supports credit disputes, and produces credit-building recommendations and alerts. ### Retirement, Insurance, and Estate (`@lakshmi/retirement`, `@lakshmi/insurance`, `@lakshmi/estate`) These three modules handle long-horizon planning where the stakes are highest. `@lakshmi/retirement` projects retirement readiness from contributions, models drawdown, and applies Social Security and pension assumptions across scenarios. `@lakshmi/insurance` maintains a coverage inventory across policy types, runs gap analysis against household risk, tracks premiums and claims, and recommends coverage changes. `@lakshmi/estate` tracks beneficiary designations, wealth-transfer plans, and estate documents; it is the source of truth for the V2 per-account vault asset-transfer surface (see V2 Surfaces). ### Real Estate and Crypto (`@lakshmi/real-estate`, `@lakshmi/crypto`) Both modules illustrate Lakshmi's boundary discipline: each relies on an adjacent domain for raw facts while owning the personal-finance decision. `@lakshmi/real-estate` computes home affordability, mortgage analysis, rental economics, and per-property cash flow. It consumes real-estate asset facts from Cybele while retaining ownership of the financial decision. `@lakshmi/crypto` does digital-asset accounting: wallet tracking, exchange and on-chain imports, DeFi position tracking, cost basis, tax, and risk scoring. On-chain infrastructure is supplied by Aje; Lakshmi owns the finance view of those assets. ### Income, Goals, Household, and Business (`@lakshmi/income`, `@lakshmi/goals`, `@lakshmi/household`, `@lakshmi/business`) These four modules handle the remaining planning domains. `@lakshmi/income` models salary, contractor, creator, gig, rental, and business income, including irregular and recurring streams. `@lakshmi/goals` plans financial goals and life events with milestone tracking and probability scoring, ordering goals by priority when they compete for surplus cash. `@lakshmi/household` manages family budgets, member permissions, shared goals, and dependent planning. `@lakshmi/business` covers self-employment and small-business finance: P&L, invoices, business tax, and cash reserves. ### AI Reasoning (`@lakshmi/ai-engine`) `@lakshmi/ai-engine` sits above the other intelligence modules and provides financial reasoning, recommendation, and planning simulation across all of them. Every recommendation must preserve its inputs, assumptions, model version, and explanation metadata (see Privacy and Compliance) so any output is reproducible and auditable. ## Security Layer ### Privacy and Compliance (`@lakshmi/security`) Privacy is not an afterthought in Lakshmi — it is a layer in the architecture. `@lakshmi/security` owns consent, encryption, PII minimization, fraud detection, audit logs, and regulatory controls. The four binding requirements are: 1. **Consent-first and revocable** — every integration requires explicit user consent before connection and can be revoked at any time, moving the affected `AccountConnection` to `revoked`. 2. **Encryption and least privilege** — sensitive financial data is encrypted at rest and protected by least-privilege, role-based access. 3. **Explainable recommendations** — every recommendation preserves inputs, assumptions, model version, and explanation metadata. 4. **Information versus advice** — tax, investment, credit, and insurance outputs clearly separate general information from regulated advice; regulated advice is surfaced only where the product has the required compliance workflow. Every financial calculation, recommendation, aggregation, and alert path must carry deterministic tests plus privacy, consent, audit, and contract tests. Integration tests use sandbox fixtures and never require live credentials in CI. ## Experience Layer ### Reporting (`@lakshmi/reporting`) `@lakshmi/reporting` produces dashboards, statements, exports, analytics, and visualizations across every capability module, and supports data portability so a user can export their financial data in full. ### Alerts (`@lakshmi/alerts`) `@lakshmi/alerts` sends notifications and proactive financial alerts on configurable thresholds — low balance, envelope overage, large transaction, bill due, goal milestone — and drives threshold-based automation. ## V2 Surfaces Lakshmi exposes two adapter services to the V2 platform. Both are off-rollback — they must never feed deterministic match simulation or competitive game outcomes. ### V2 Responsible-Play Spend Insight `@v2/lakshmi-responsible-play-spend-insight` is the V2 adapter for responsible-play store confirmation. It composes `@lakshmi/behavioral`, `@lakshmi/budgeting`, and `@lakshmi/transactions` to surface spending context during in-app purchases. (The historical `@lakshmi/spend-insight` reference is not implemented.) The contract requires explicit player opt-in before any behavioral nudge, impulse-detection prompt, weekly summary reflection, or self-imposed cap is applied. Parental controls are guardian policy and apply independently of the player's own opt-in. Budget overages remain warning-only unless a self-imposed cap or a parental control explicitly blocks the action or requires guardian approval. The adapter is off rollback: spend insight can affect store confirmation, guardian approval, player education, and weekly summary copy, but it must **never** feed deterministic match simulation or competitive outcomes. ### V2 Per-Account Vault Asset Transfer `@v2/per-account-vault-estate-bridge` is the V2 adapter for per-account vault estate planning. It bridges Lakshmi's estate data to two other domains: `@oshun/identity` validates account ownership and sensitive-action gates, and `@themis/transparency` provides an immutable audit record for the transfer. The boundary exists because estate transfers are legal events requiring a trustworthy audit chain — neither Lakshmi nor identity can provide that alone. The reciprocal Lakshmi schema is `v2.per-account-vault-asset-transfer`, which requires nine fields: `vaultPlanId`, `householdId`, `ownerOshunAccountId`, `assetId`, `beneficiaryId`, `delegationId`, `evidenceDocumentId`, `transferInstructions`, and `themisAuditRecordId`. Lakshmi remains the source of truth for asset-inventory readiness, encrypted estate-document-vault completeness, beneficiary designations, digital-legacy action items, emergency-access readiness, and executor/trustee runbooks. V2 may publish an estate-transfer manifest only when **all** of the following hold: each required asset transfer is marked ready by Lakshmi; the beneficiary tracker has no missing or conflicting designations; the delegation evidence document exists in the encrypted estate-document vault; `@oshun/identity` validates the canonical owner account and sensitive-action gates; and `@themis/transparency` records the delegation plus transfer execution in a valid hash chain with an anchored checkpoint. This schema is an estate-administration control plane only. It is off rollback, server-authoritative, account/companion-only, and rejects live gameplay-frame RPCs. It must never feed deterministic match simulation, competitive frame outcomes, damage, AI, or rollback inputs. ## Cross-Domain Integrations Lakshmi's boundaries are drawn around ownership of the financial decision, not raw data. Each adjacent domain owns its own data and exposes it to Lakshmi through a defined contract. - **Maat** consumes aggregate business intelligence and risk where permitted. Maat owns enterprise and organizational finance, Lakshmi owns personal and household finance. The boundary prevents Lakshmi from needing to understand organizational accounting and prevents Maat from needing to understand personal budgeting. - **Aje** supplies Web3 and on-chain asset/provenance infrastructure consumed by `@lakshmi/crypto`. Aje owns the chain integrations; Lakshmi owns how those assets appear in a user's net worth and tax picture. - **Themis** supplies governance and compliance policy primitives, and the immutable transfer audit records used by the V2 vault surface. Any operation that constitutes a legal transfer of ownership routes through Themis for audit-chain integrity. - **Cybele** supplies real-estate asset and mortgage context consumed by `@lakshmi/real-estate`; Lakshmi owns the personal-finance decision. This boundary avoids duplicating property records and AVM data. - **Freya, Asase, Brigid, Saraswati**, and other commercial domains may expose user-permitted income, expense, asset, and business data through explicit contracts. ### Gaia Energy and Climate Integration Phase 175 adds Gaia renewable-energy-potential and climate-risk products as inputs to Lakshmi. Lakshmi consumes solar GHI, wind at 100m, hydro-inflow, heating/cooling degree days, storm risk, and climate-scenario outputs for energy-trading support, household capacity planning, insurance context, property-risk analysis, and financial-scenario modeling. Gaia owns forecast generation and uncertainty; Lakshmi owns financial-advice boundaries and the user-facing finance decision.