Architecture and Data Flow

Architecture and Data Flow

Finance Guru is a local, CLI-first environment. It has no required long-running server for analysis commands. Code lives in the repository checkout; private data lives in a separate instance directory.

Instance boundary

The InstancePaths model in src/config/instance_paths.py resolves every private path from one instance root. The root comes from FIN_GURU_DATA_ROOT when set, and otherwise from the current working directory. The instance layout is flat. The root holds .env, user-profile.yaml, config.yaml, system-context.md, family_office.db, snaptrade-accounts.yaml, and dividend-schedules.yaml, plus the directories imports/, analysis/, tickets/, strategies/, hedging/, reports/, auto-tickets/, and notes/. The SnapTrade account-routing file is snaptrade-accounts.yaml directly under the instance root.

Data boundary

Instance root (FIN_GURU_DATA_ROOT or current working directory)
  .env with SnapTrade or SimpleFIN credentials (local configuration)
                  |
                  v
Provider sync modules -> family_office.db (local SQLite under the instance root)
                  |
                  v
Python analysis and strategy CLIs -> local terminal output or instance artifacts

The public repository must not contain database files, access URLs, account numbers, balances, positions, or credentials. Google Sheets/DataHub and Google Drive are not part of the current data path.

Verified implementation seams

• src/config/instance_paths.py resolves every private path from the instance root.
• src/cli/instance_init.py scaffolds a local-only instance directory.
• src/integrations/refresh_all.py coordinates the configured refreshes.
• src/integrations/snaptrade/ contains account, position, balance, and activity synchronization surfaces.
• src/integrations/simplefin/sync_expenses_db.py imports configured bank and card transaction data into local SQLite.
• src/models/, src/analysis/, and CLI entrypoints form the checked-in validation, business-logic, and command layers.

For source-path evidence and the status of uncertain claims, see the evidence ledger.

Continue with Privacy or CLI Reference.