Plaid AI Budget Builder

A self-hosted, open-source application that connects to your bank accounts via Plaid, stores transaction data locally, and exposes a REST API that any AI chatbot (Claude, ChatGPT, Grok, etc.) can query to generate personalized budgets and spending insights.

All data stays on your machine.

---

Prerequisites

• Plaid account (free Development tier — up to 10 accounts)
• Node.js 18+ or Docker

---

Quick Start

git clone https://github.com/dantethera/project-budget
cd project-budget
cp .env.example .env

Edit .env and fill in your Plaid credentials:

PLAID_CLIENT_ID=your_client_id
PLAID_SECRET=your_secret_key
PLAID_ENV=sandbox        # or "development" for real bank data
PORT=3000

Then run:

npm install
npm start

Visit http://localhost:3000 to link your bank accounts.

---

Docker Setup

cp .env.example .env   # fill in credentials
docker-compose up

Data is persisted in a named Docker volume (budget-data).

---

Linking Bank Accounts

1. Visit http://localhost:3000
2. Click "Link Bank Account" — this opens Plaid Link
3. Search for your bank and log in
4. Click "Sync Transactions" to pull your transaction history

For real bank data, set PLAID_ENV=development in your .env file. For testing with fake data use PLAID_ENV=sandbox.

---

API Reference

All endpoints return JSON. Set x-api-key header if API_KEY is configured in .env.

Accounts

Method	Endpoint	Description
GET	/api/accounts	List all linked accounts with balances
GET	/api/accounts/:id	Single account details
DELETE	/api/accounts/:id	Unlink account and delete local data

Transactions

Method	Endpoint	Description
GET	/api/transactions	List transactions (see filters below)
GET	/api/transactions/:id	Single transaction
PATCH	/api/transactions/:id/category	Override transaction category

Transaction filters (query params):

• startDate — YYYY-MM-DD
• endDate — YYYY-MM-DD
• accountId — filter by account
• category — filter by category string
• limit — max results (default 100, max 1000)
• offset — pagination offset

Analytics

Method	Endpoint	Description
GET	/api/summary	Totals, by-category breakdown, largest transactions
GET	/api/insights	Month-over-month trends, recurring charges, recommendations

Summary params: startDate, endDate, groupBy (day/week/month/category)

Sync

Method	Endpoint	Description
POST	/api/sync	Manually sync all accounts with Plaid
GET	/api/sync/status	Last sync status per account

Auto-sync runs daily at 3am.

---

Using with AI Chatbots

After starting the server, paste this into your AI chat:

I have a personal finance API running at http://localhost:3000/api

Available endpoints:
- GET /api/transactions?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&limit=1000
- GET /api/summary?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD&groupBy=category
- GET /api/accounts
- GET /api/insights

Please query my spending data and help me:
1. Understand where my money is going
2. Build a realistic monthly budget
3. Identify subscriptions I should cancel
4. Show month-over-month trends

The AI will call your endpoints, analyze the data, and return personalized insights.

---

Security & Privacy

• All transaction data is stored in a local SQLite database (~/.plaid-budget/data.db by default)
• Plaid access tokens are stored locally — never sent anywhere except Plaid's API
• No analytics, no telemetry, no cloud sync
• Set API_KEY in .env to require authentication on all API calls
• Never commit your .env file

Data flow

Plaid API → Local Express server → SQLite (local file) → REST API → AI chatbot

---

Environment Variables

Variable	Required	Default	Description
PLAID_CLIENT_ID	Yes	—	Your Plaid client ID
PLAID_SECRET	Yes	—	Your Plaid secret key
PLAID_ENV	No	sandbox	sandbox, development, or production
PORT	No	3000	Server port
DB_PATH	No	~/.plaid-budget/data.db	SQLite database path
API_KEY	No	—	If set, all API calls require x-api-key header

---

Project Structure

src/
├── server.js           # Express app + cron job
├── db/
│   ├── index.js        # SQLite init
│   └── schema.sql      # Database schema
├── middleware/
│   └── auth.js         # Optional API key auth
└── routes/
    ├── plaid.js        # Plaid Link flow
    ├── accounts.js     # Account management
    ├── transactions.js # Transaction queries
    ├── sync.js         # Plaid sync (cursor-based)
    ├── summary.js      # Spending analytics
    └── insights.js     # Trends & recommendations
public/
└── plaid-link.html     # Bank linking UI

---

License

MIT