Home

FinanceOS

Personal finance intelligence, entirely on your device.

FinanceOS is a macOS personal finance application built in Swift. It imports bank statements from Indian banks, deduplicates transactions deterministically, and enriches them with an on-device ML intelligence platform — categorization, merchant resolution, recurring detection, relationship inference, and behavior analysis — without sending any data to a server.

The codebase is organized as a multi-package Swift workspace with strict package boundaries, MVVM presentation architecture, and a single SQLite database managed by GRDB.

---

Packages

Package	Owns	Depends On	Status
FinanceParsers	Parser protocol, bank-specific parsers (HDFC, ICICI, Amex, Scapia), format detection, FinanceParserCLI	Nothing	✅ Complete
FinanceCore	Domain models, GRDB repositories, DatabaseManager, AppContainer, import pipeline, spending service, logging	FinanceParsers, GRDB	✅ Complete
FinanceUI	FDS design system, adaptive tokens (light/dark, screen-scaling), FDS components, view modifiers	FinanceCore	✅ Complete
FinanceIntelligence	11-model ML platform, categorization, behavior analysis, knowledge graph, entity resolution, embeddings, feedback	FinanceCore, GRDB, swift-transformers, MLX, ZIPFoundation	🚧 In Progress
FinanceCLI	Headless parse/import/analyze/pipeline commands	FinanceCore, FinanceParsers, FinanceIntelligence, ArgumentParser	📋 Planned (FINOS-56)
FinanceTesting	Shared test helpers, fixtures, golden JSON, mocks	FinanceCore, FinanceParsers	✅ Complete

App target: FinanceOSMac — SwiftUI Views, ViewModels, navigation, EnvironmentKey definitions, app entry point.

---

Package Dependency Graph

graph TD
    Parsers[FinanceParsers\nzero deps]
    Core[FinanceCore]
    UI[FinanceUI]
    Intel[FinanceIntelligence]
    CLI[FinanceCLI]
    App[FinanceOSMac\nApp Target]
    DB[(SQLite / GRDB)]

    Core --> Parsers
    Core --> DB
    UI --> Core
    Intel --> Core
    Intel --> DB
    CLI --> Core
    CLI --> Parsers
    CLI --> Intel
    App --> Core
    App --> UI
    App --> Intel

Loading

---

Architecture Principles

Principle	Rule
Package isolation	No import SwiftUI in FinanceCore, FinanceParsers, FinanceIntelligence, or FinanceCLI
MVVM	SwiftUI View → ViewModel (@Observable @MainActor) → Repository Protocol → GRDB Repository → SQLite
Single database	DatabaseManager.shared owns the DatabaseQueue; all repositories receive it via injection
Offline-first	All ML inference runs on-device; no transaction data leaves the device
Deterministic before ML	Rule engine + entity resolution + graph analysis targets 90%+ accuracy; CoreML handles the tail
Auditable	Every intelligence decision has traceable provenance (rule ID, model version, confidence)

---

Active Work

Package Segregation Initiative

Enforcing clean package contracts — eliminating SwiftUI contamination from non-UI packages, introducing a headless CLI, adding light/dark mode + screen-adaptive scaling to the design system.

Epic	Title	Status
FINOS-55	Phase 1: Eliminate UI Contamination + Adaptive Token System	📋 To Do
FINOS-56	Phase 2: Create FinanceCLI Package	📋 To Do
FINOS-57	Phase 3: FinanceIntelligence API Boundary + Persistence Consolidation	📋 To Do

Financial Intelligence Platform

Building 11 ML models for transaction enrichment across 7 phases (~30 weeks).

Phase	Name	Duration
1	Foundation (evaluation harness, golden dataset)	4 weeks
2	Category + Merchant ML	4 weeks
3	Behavioral Intelligence (intent, recurring, income)	4 weeks
4	Embeddings + Personalization	4 weeks
5	Generative + Agent (MLX, FinanceAgent)	6 weeks
6	Link Prediction + Anomaly Detection	4 weeks
7	Hardening + CI	4 weeks

---

Wiki Navigation

Section	Contents
Product Requirements	Vision, PRDs for package segregation and intelligence platform
Architecture	System HLD, package boundaries, data model, intelligence platform HLD, MVVM
Technical Design	LLDs for package segregation, intelligence pipeline, knowledge graph, CoreML, DB schema
Features	Transaction ingestion, intelligence features, design system, CLI tools
Developer Guide	Setup, coding standards, design standards, build & test
Roadmap	Intelligence platform (7 phases) and package segregation (3 phases)