# rafaelfcarneiro/patty architecture

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

- Interactive diagram: https://gitdiagram.com/rafaelfcarneiro/patty
- Repository: https://github.com/rafaelfcarneiro/patty

## Overview

PATTY is a local-first personal finance manager whose primary workflow is an AI client calling the MCP server; REST and a dashboard are additional surfaces. Requests reach shared controllers and domain logic, which operate on encrypted libSQL data. Authentication and client setup govern access, while finance capabilities include transaction tracking, budgeting, credit cards, recurring rules, and investments. The README documents these product branches; sampled source confirms MCP-to-controller reuse, HTTP route mounting, and database construction, but not every domain handler’s internal calls.

Main entry points: [`src/controllers`](https://github.com/rafaelfcarneiro/patty/tree/main/src/controllers) (Request controllers), [`src/diplomat/db/driver.ts`](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/db/driver.ts) (Encrypted SQLite file), [`src/composition/auth.ts`](https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/auth.ts) (Authentication), [`src/diplomat/mcp/server.ts`](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/mcp/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_http["REST and UI<br/>[routes.ts]"]
  node_cli["CLI setup<br/>[commands.ts]"]
end

subgraph group_domain["Finance domain"]
  node_controllers["Request controllers"]
  node_transactions["Transactions<br/>[core.ts]"]
  node_accounts["Accounts and transfers<br/>[account.ts]"]
  node_budgets["Budgets and categories<br/>[budgets.ts]"]
  node_cards["Cards and bills<br/>[credit-card.ts]"]
  node_recurring["Recurring rules<br/>[recurring.ts]"]
  node_investments["Investments<br/>[portfolio.ts]"]
  node_importexport["Import and export<br/>[import.ts]"]
end

subgraph group_security["Identity and setup"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_signflow["Sign-in flow<br/>[wiring.ts]"]
  node_clientconfig["Client configuration<br/>[clients.ts]"]
end

subgraph group_storage["Persistence"]
  node_keychain["OS keychain"]
  node_repos["Database repositories"]
  node_database[("Encrypted SQLite file<br/>[driver.ts]")]
  node_schema["Database schema<br/>[schema.ts]"]
end

node_ai(("AI client"))
node_person(("Finance user"))

node_ai -->|"requests finance actions"| node_mcp
node_person -->|"uses dashboard"| node_http
node_person -->|"runs setup"| node_cli
node_mcp -->|"delegates to"| node_controllers
node_http -->|"routes requests"| node_controllers
node_controllers -.->|"handles domain requests"| node_transactions
node_controllers -.->|"handles domain requests"| node_accounts
node_controllers -.->|"handles domain requests"| node_budgets
node_controllers -.->|"handles domain requests"| node_cards
node_controllers -.->|"handles domain requests"| node_recurring
node_controllers -.->|"handles domain requests"| node_investments
node_cli -->|"configures clients"| node_clientconfig
node_auth -->|"creates sign-in"| node_signflow
node_auth -->|"builds dependencies"| node_repos
node_signflow -.->|"stores sign-in"| node_keychain
node_importexport -.->|"moves finance data"| node_database
node_repos -.->|"reads and writes"| node_database
node_database -->|"uses schema"| node_schema

click node_mcp "https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/mcp/server.ts"
click node_http "https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/http/routes.ts"
click node_cli "https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/cli/commands.ts"
click node_controllers "https://github.com/rafaelfcarneiro/patty/tree/main/src/controllers"
click node_transactions "https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/transaction/core.ts"
click node_accounts "https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/account/account.ts"
click node_budgets "https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/budgets.ts"
click node_cards "https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/credit-card/credit-card.ts"
click node_recurring "https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/recurring.ts"
click node_investments "https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/investment/portfolio.ts"
click node_importexport "https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/import.ts"
click node_auth "https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/auth.ts"
click node_signflow "https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/sign-in/wiring.ts"
click node_clientconfig "https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/client-config/clients.ts"
click node_repos "https://github.com/rafaelfcarneiro/patty/tree/main/src/diplomat/db/repos"
click node_database "https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/db/driver.ts"
click node_schema "https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/db/schema.ts"

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_mcp,node_http,node_cli,node_ai,node_person toneBlue
class node_controllers,node_transactions,node_accounts,node_budgets,node_cards,node_recurring,node_investments,node_importexport toneAmber
class node_auth,node_signflow,node_clientconfig toneMint
class node_keychain,node_repos,node_database,node_schema toneRose
```

## Components

### User interfaces

- [MCP server](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/mcp/server.ts): `src/diplomat/mcp/server.ts`
- [REST and UI](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/http/routes.ts): `src/diplomat/http/routes.ts`
- [CLI setup](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/cli/commands.ts): `src/diplomat/cli/commands.ts`

### Finance domain

- [Request controllers](https://github.com/rafaelfcarneiro/patty/tree/main/src/controllers): `src/controllers`
- [Transactions](https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/transaction/core.ts): `src/controllers/transaction/core.ts`
- [Accounts and transfers](https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/account/account.ts): `src/controllers/account/account.ts`
- [Budgets and categories](https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/budgets.ts): `src/controllers/budgets.ts`
- [Cards and bills](https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/credit-card/credit-card.ts): `src/controllers/credit-card/credit-card.ts`
- [Recurring rules](https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/recurring.ts): `src/controllers/recurring.ts`
- [Investments](https://github.com/rafaelfcarneiro/patty/blob/main/src/controllers/investment/portfolio.ts): `src/controllers/investment/portfolio.ts`
- [Import and export](https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/import.ts): `src/composition/import.ts`

### Identity and setup

- [Authentication](https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/auth.ts): `src/composition/auth.ts`
- [Sign-in flow](https://github.com/rafaelfcarneiro/patty/blob/main/src/composition/sign-in/wiring.ts): `src/composition/sign-in/wiring.ts`
- [Client configuration](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/client-config/clients.ts): `src/diplomat/client-config/clients.ts`

### Persistence

- **OS keychain**
- [Database repositories](https://github.com/rafaelfcarneiro/patty/tree/main/src/diplomat/db/repos): `src/diplomat/db/repos`
- [Encrypted SQLite file](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/db/driver.ts): `src/diplomat/db/driver.ts`
- [Database schema](https://github.com/rafaelfcarneiro/patty/blob/main/src/diplomat/db/schema.ts): `src/diplomat/db/schema.ts`

### Other components

- **AI client**
- **Finance user**

## Connections

- AI client → MCP server: requests finance actions (evidence: `README.md`)
- Finance user → REST and UI: uses dashboard (evidence: `README.md`)
- Finance user → CLI setup: runs setup (evidence: `README.md`)
- MCP server → Request controllers: delegates to (evidence: `src/diplomat/mcp/server.ts`)
- REST and UI → Request controllers: routes requests (evidence: `src/diplomat/http/routes.ts`)
- Request controllers → Transactions: handles domain requests
- Request controllers → Accounts and transfers: handles domain requests
- Request controllers → Budgets and categories: handles domain requests
- Request controllers → Cards and bills: handles domain requests
- Request controllers → Recurring rules: handles domain requests
- Request controllers → Investments: handles domain requests
- CLI setup → Client configuration: configures clients (evidence: `README.md`)
- Authentication → Sign-in flow: creates sign-in (evidence: `src/composition/auth.ts`)
- Authentication → Database repositories: builds dependencies (evidence: `src/composition/auth.ts`)
- Sign-in flow → OS keychain: stores sign-in
- Import and export → Encrypted SQLite file: moves finance data
- Database repositories → Encrypted SQLite file: reads and writes (evidence: `src/diplomat/db/repos/client-grants.ts`)
- Encrypted SQLite file → Database schema: uses schema (evidence: `src/diplomat/db/driver.ts`)
