Kakei (家計) — Personal Finance App

A full-stack personal finance web app replacing Excel-based accounting. Tracks daily expenses, monthly budgets, credit card ledgers, advance budgets, and fund allocations.

Stack

• Backend: Express + TypeScript + Prisma + SQLite (port 3001)
• Frontend: React + Vite + TypeScript + Tailwind CSS (port 5173)

---

Quick Start

1. Install dependencies

Open two terminals.

Terminal 1 — Backend:

cd C:\Users\Metz Embile\dev\kakei\backend
npm install

Terminal 2 — Frontend:

cd C:\Users\Metz Embile\dev\kakei\frontend
npm install

2. Set up the database

cd C:\Users\Metz Embile\dev\kakei\backend
npx prisma migrate dev --name init
npm run prisma:seed

This creates backend/dev.db with all tables and seeds the default accounts and categories.

3. Run the app

Terminal 1 — Backend (port 3001):

cd C:\Users\Metz Embile\dev\kakei\backend
npm run dev

Terminal 2 — Frontend (port 5173):

cd C:\Users\Metz Embile\dev\kakei\frontend
npm run dev

Open http://localhost:5173 in your browser.

---

Features

Dashboard

• Monthly spending vs budget bar chart (Recharts)
• Quick stat cards: Total Spent, Income, CC Payment Fund, CC Allocation
• Recent 10 transactions
• CC payment balance per account

Transactions (/transactions)

• Month/year selector
• Full transaction form with all fields:
  • Basic: date, category, description
  • Cash payments: Wallet, BDO Payroll, GCash
  • CC charges: Miles+, Miles+ Oppa, BDO CC, BPI CC
  • CC payment source: Budget, Payroll, Others
  • Next-month CC charges and payment sources
• Edit and delete rows
• Column totals in footer

Monthly Budget (/budget)

• Income setup: income, savings target, CC budget/payroll/others
• Per-category budget inputs with progress bars
• Budget vs actual spending side-by-side
• Values auto-saved on blur

Credit Cards (/credit-cards)

• Ledger for CC payment allocations
• Types: "For CC Payment" and "Advance Payment"
• Filter by account and type
• Balance summary per account

Advance Budget (/adv-budget)

• Types: General, Grocery, Budget Next Month
• Filter by account and type
• Per-account per-type balance table

Fund Ledgers (/funds/:fundType)

Available fund types: Oppa, RK, Savings, Travel, Insurance, Forex, Investment (Peso), Investment (USD), Money 8

• Debit/credit ledger with running balance
• Per-account balance summary cards
• Filter by account

Account Summary (/accounts)

• Full matrix: each account × each fund type balance
• USD accounts converted to PHP using configurable exchange rate
• Grand total in PHP

Settings (/settings)

• USD → PHP exchange rate
• Account management (add, edit, activate/deactivate, delete)
• Category management (add, edit, reorder, delete)

---

Project Structure

kakei/
  backend/
    prisma/
      schema.prisma       # Database schema
    src/
      index.ts            # Express app + all API routes
      seed.ts             # Default data seeder
    .env                  # DATABASE_URL, PORT
    package.json
    tsconfig.json
  frontend/
    src/
      api/client.ts       # API functions for all endpoints
      components/
        Layout.tsx        # Sidebar navigation
      pages/
        Dashboard.tsx
        Transactions.tsx
        Budget.tsx
        CreditCards.tsx
        AdvBudget.tsx
        FundLedger.tsx
        Accounts.tsx
        Settings.tsx
      types/index.ts      # TypeScript interfaces
      App.tsx             # Routes
      main.tsx            # Entry point
    index.html
    vite.config.ts        # Proxy /api → :3001
    tailwind.config.js
    postcss.config.js
    package.json

---

API Endpoints

Method	Path	Description
GET/POST/PUT/DELETE	/api/accounts	Account CRUD
GET/POST/PUT/DELETE	/api/categories	Category CRUD
GET/POST/PUT/DELETE	/api/transactions	Transaction CRUD (filter: ?month=&year=)
GET/POST/PUT/DELETE	/api/monthly-budget	Budget CRUD (filter: ?month=&year=)
GET/POST/PUT/DELETE	/api/monthly-income	Income CRUD (filter: ?month=&year=)
GET/POST/PUT/DELETE	/api/cc-ledger	CC Ledger CRUD (filter: ?accountId=&type=)
GET/POST/PUT/DELETE	/api/adv-budget	Advance Budget CRUD
GET/POST/PUT/DELETE	/api/fund-ledger	Fund Ledger CRUD (filter: ?fundType=&accountId=)
GET/PUT	/api/config	App config (exchange rate)
GET	/api/reports/monthly-summary	Monthly spending vs budget
GET	/api/reports/account-summary	Per-account balance breakdown
GET	/api/reports/cc-balance	CC payment fund balances

---

Default Seeded Data

Accounts: Wallet, GCash, BDO Payroll, BDO Peso, BDO Optimum, BDO Dollar, BDO Checking, BPI Savings

Categories: Bills & Service, Education, Childcare, Fare, Grocery, Delivery, Dine-out, Coffee, Shopping, Travel, Charity, Electronics, Home, Kikay, Transaction, Exercise, Ent & Lei

Config: usdToPhp = 58.05