# hammem/monarchmoney architecture

> Architecture diagram of the GitHub repository hammem/monarchmoney, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hammem/monarchmoney
- Repository: https://github.com/hammem/monarchmoney

## Overview

Monarch Money is an asynchronous Python client for accessing and modifying personal-finance data through Monarch Money’s API. The principal workflow is to create a client, authenticate (optionally using MFA or a saved session), then request finance data or submit changes. The library also supports account refreshes and CSV balance-history uploads. The main implementation is concentrated in one source file, so domain nodes represent method families within that file, not separate modules. The excerpts show several GraphQL calls and direct HTTP requests; other capability coverage comes from the README, so unsampled internal links are omitted.

Main entry points: [`monarchmoney/monarchmoney.py`](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py) (GraphQL requests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session and authentication"]
  node_auth["Login and MFA<br/>[monarchmoney.py]"]
  node_saved_session["Saved session<br/>[monarchmoney.py]"]
end

subgraph group_accounts["Accounts"]
  node_account_methods["Account methods<br/>[monarchmoney.py]"]
  node_refresh["Account refresh<br/>[monarchmoney.py]"]
  node_holdings["Holdings and history<br/>[monarchmoney.py]"]
end

subgraph group_transactions["Transactions and budgets"]
  node_transactions["Transaction methods<br/>[monarchmoney.py]"]
  node_categories_tags["Categories and tags<br/>[monarchmoney.py]"]
  node_budgets["Budget methods<br/>[monarchmoney.py]"]
end

subgraph group_insights["Financial insights"]
  node_cashflow["Cashflow methods<br/>[monarchmoney.py]"]
  node_recurring["Recurring transactions<br/>[monarchmoney.py]"]
end

node_developer(("Library user"))
node_client["MonarchMoney client<br/>[monarchmoney.py]"]
node_graphql["GraphQL requests<br/>[monarchmoney.py]"]
node_monarch_api{{"Monarch Money API"}}

node_developer -->|"uses"| node_client
node_client -->|"authenticates"| node_auth
node_client -.->|"saves or loads"| node_saved_session
node_account_methods -->|"sends queries"| node_graphql
node_refresh -->|"requests refresh"| node_graphql
node_holdings -->|"fetches data"| node_graphql
node_transactions -->|"sends queries"| node_graphql
node_categories_tags -->|"sends queries"| node_graphql
node_budgets -.->|"sends queries"| node_graphql
node_cashflow -->|"fetches data"| node_graphql
node_recurring -.->|"fetches data"| node_graphql
node_graphql -->|"sends GraphQL"| node_monarch_api
node_auth -->|"sends login requests"| node_monarch_api

click node_client "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_auth "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_saved_session "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_account_methods "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_refresh "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_holdings "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_transactions "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_categories_tags "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_budgets "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_cashflow "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_recurring "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"
click node_graphql "https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_saved_session,node_developer,node_client toneBlue
class node_account_methods,node_refresh,node_holdings toneAmber
class node_transactions,node_categories_tags,node_budgets,node_graphql,node_monarch_api toneMint
class node_cashflow,node_recurring toneRose
```

## Components

### Session and authentication

- [Login and MFA](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [Saved session](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`

### Accounts

- [Account methods](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [Account refresh](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [Holdings and history](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`

### Transactions and budgets

- [Transaction methods](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [Categories and tags](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [Budget methods](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`

### Financial insights

- [Cashflow methods](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [Recurring transactions](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`

### Other components

- **Library user**
- [MonarchMoney client](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- [GraphQL requests](https://github.com/hammem/monarchmoney/blob/main/monarchmoney/monarchmoney.py): `monarchmoney/monarchmoney.py`
- **Monarch Money API**

## Connections

- Library user → MonarchMoney client: uses (evidence: `README.md`)
- MonarchMoney client → Login and MFA: authenticates (evidence: `monarchmoney/monarchmoney.py`)
- MonarchMoney client → Saved session: saves or loads (evidence: `README.md`)
- Account methods → GraphQL requests: sends queries (evidence: `monarchmoney/monarchmoney.py`)
- Account refresh → GraphQL requests: requests refresh (evidence: `monarchmoney/monarchmoney.py`)
- Holdings and history → GraphQL requests: fetches data (evidence: `monarchmoney/monarchmoney.py`)
- Transaction methods → GraphQL requests: sends queries (evidence: `monarchmoney/monarchmoney.py`)
- Categories and tags → GraphQL requests: sends queries (evidence: `monarchmoney/monarchmoney.py`)
- Budget methods → GraphQL requests: sends queries (evidence: `monarchmoney/monarchmoney.py`)
- Cashflow methods → GraphQL requests: fetches data (evidence: `monarchmoney/monarchmoney.py`)
- Recurring transactions → GraphQL requests: fetches data (evidence: `monarchmoney/monarchmoney.py`)
- GraphQL requests → Monarch Money API: sends GraphQL (evidence: `monarchmoney/monarchmoney.py`)
- Login and MFA → Monarch Money API: sends login requests (evidence: `monarchmoney/monarchmoney.py`)
