The WiseInvest Wealth API is the core backend for the personal finance platform. It ingests financial documents, structures them into domain entities, and serves analytics and insights via a FastAPI application.
wealth/app.py defines the FastAPI app, includes routers from auth, core, analytics, and ingestion, and wires middleware and exception handlers.wealth/config.py loads environment variables (database URL, AWS credentials, n8n settings, feature flags) using Pydantic settings.Located under wealth/auth/:
router.py exposes login, register, and token refresh endpoints.service.py handles JWT generation and password hashing.dependencies.py provides get_current_user and related dependencies used across routers.The wealth/core/ package owns business logic and REST endpoints for the ledger and planning features:
router.py — primary FastAPI router that mounts sub-routes for assets, liabilities, income, expenses, goals, and value-refresh operations.schemas.py — Pydantic v2 request/response models for all core entities.assets.py — asset CRUD and net-worth delta updates.liabilities.py — liability CRUD, EMI schedule management, and credit-card helpers (including the mark-paid endpoint documented in docs/API.md).loan_closure.py — foreclosure & prepayment savings calculator powering the /liabilities/{id}/closure-savings endpoint.value_refresh.py — value refresh engine for loans and EPF/PPF accounts, exposed via /assets/refresh-values and /liabilities/refresh-values.goals.py, retirement.py, portfolio.py, cashflow.py — planning and portfolio analytics services.errors.py (error taxonomy), middleware.py (request ID + logging context), decorators.py and dependencies.py (request-scoped helpers), feature_gate.py (feature flag checks), and logging.py.Core entities are persisted via SQLAlchemy models under wealth/database/models/* with Alembic migrations in wealth/database/migrations/.
Recent changes add an insurance domain:
wealth/core/insurance.py defines the insurance service layer and API handlers.wealth/database/models/insurance.py and migration 036_add_insurance_policies.py add the insurance_policies table with fields for insurance_type, policy_status, sum_assured, premium, frequency, start_date, end_date, and linked_asset_id.services/wealth/docs/API.md under Insurance and include:
POST /insurance to create a policy.GET /insurance to list and filter policies.GET /insurance/summary for per-type coverage and expiring policies./insurance/{id} with update/delete and asset-linking support.Policies can be created manually or via the ingestion pipeline when users upload insurance policy documents.
Located under wealth/ingestion/:
router.py exposes document upload and processing endpoints.service.py orchestrates ingestion, including document registration, status tracking, and hand-off to processors.processing/ contains processors for different document types (bank statements, credit cards, loans, investments, retirement, and insurance):
dispatcher.py routes a document to the appropriate processor based on document_type.insurance_processor.py handles insurance_policy documents, upserting policies by (user, policy_number), auto-linking motor/home policies to assets, and persisting quick-reference details into meta_data.bank_statement_processor.py, credit_card_processor.py, loan_processor.py, investment_processor.py, retirement_processor.py, transaction_processor.py) parse and normalize tabular statement data.n8n_client.py and email/* integrate with n8n workflows and Gmail for automated document ingestion.Processing is resilient to retries, with metrics from wealth/ingestion/metrics.py and nightly scripts under wealth/scripts/ for stuck-document recovery and reconciliation.
The analytics engine lives under wealth/analytics/:
router.py defines endpoints such as /analytics/smart-insights, /analytics/net-worth, /analytics/assets/insights/by-category, and /analytics/liabilities/insights/by-type (see docs/API.md and docs/INSIGHTS_API.md).service.py provides aggregate calculations (net worth, surplus, liquidity ratios).insight_service.py, document_insight_service.py, category_insight_service.py, and entity_insight_service.py implement rule-based insights at portfolio, document, category, and entity levels.schemas.py defines the Insight and GroupedInsightsResponse models.Detailed rule catalogs and response examples appear in wealth/docs/INSIGHTS_API.md, wealth/docs/INSIGHTS_ARCHITECTURE.md, and wealth/docs/INSIGHTS_RULES.md.
Feature flags are implemented in wealth/core/feature_gate.py and used across routers to:
Gates are typically evaluated from request context (user, environment) and configuration loaded via wealth/config.py.
wealth/tests/integration/ validate concurrency behavior and financial calculations (e.g., test_cascade_outstanding.py, test_concurrency.py).wealth/tests/test_e2e_retirement.py cover critical retirement workflows.