Local Development Setup

Prerequisites

• Node.js 20+
• Python 3.11+ (Butler Tax backend uses uv)
• MongoDB (local instance, port 27017)
• Firebase project with Admin SDK credentials
• Git

Repository Layout

Clone the three repositories side-by-side under a parent directory (commonly butlerseries/):

butlerseries/
├── butler-platform/
├── butler-tax/
└── butler-law/

Environment Variables

Butler Tax Backend (butler-tax/backend/.env)

MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=butler_tax
FIREBASE_CREDENTIALS_PATH=./firebase-admin-key.json
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
PLATFORM_API_URL=http://localhost:8003
LAW_API_URL=http://localhost:8002
ENVIRONMENT=development

Butler Tax Frontend (butler-tax/frontend/.env.local)

VITE_API_BASE=http://localhost:8001/api/v1
VITE_LAW_URL=http://localhost:3002
VITE_HOUJIN_API_KEY=...

VITE_LAW_URL is the cross-service switch target: when the signed-in account also has a Butler Law contract, the Tax sidebar shows a link to it.

Butler Law Frontend (butler-law/frontend/.env.local)

NEXT_PUBLIC_AUTH_URL=http://localhost:3003
NEXT_PUBLIC_TAX_URL=http://localhost:3001

NEXT_PUBLIC_TAX_URL is the symmetric counterpart of VITE_LAW_URL: when the account also has a Butler Tax contract, the Law sidebar shows a link back to Butler Tax. Both checks read the same /stripe/credits (butler_tax / butler_law) response, so no backend change is needed.

Firebase Credentials

Either:

• Place a service-account JSON at butler-tax/backend/firebase-admin-key.json (path is configured via FIREBASE_CREDENTIALS_PATH), or
• Run gcloud auth application-default login to use ADC.

Without either, PII routes (/clients, /company-profiles, /bank-accounts) return errors. Non-PII routes still work because of lazy Firestore init.

Starting Services

Butler Tax Backend

cd butler-tax/backend
uv sync                         # install deps
ENVIRONMENT=development uv run uvicorn app.main:app --reload --port 8001

Butler Tax Frontend

cd butler-tax/frontend
npm install
npm run dev

Butler Platform (Auth)

cd butler-platform/auth/backend
ENVIRONMENT=development uv run uvicorn app.main:app --reload --port 8003

cd butler-platform/auth/frontend
npm install && npm run dev

Studio Admin

cd butler-platform/studio_admin/frontend
npm install && npm run dev

Butler Law

cd butler-law/backend
ENVIRONMENT=development uv run uvicorn main:app --reload --port 8002

cd butler-law/frontend
npm install && npm run dev

Seed Data

cd butler-tax/backend
uv run python seed.py

This creates a tax firm, two corporate clients, sample employees, documents, and transactions for local development.

Running Tests

Butler Tax Backend (pytest)

cd butler-tax/backend
uv run pytest                    # 521 tests
uv run pytest tests/test_approvals.py   # specific file
uv run pytest -k "test_matching"        # by keyword

Butler Tax Frontend E2E (Playwright)

cd butler-tax/frontend
npx playwright test              # 154 tests, all stubbed (no backend needed)
npx playwright test --ui         # interactive UI mode
npx playwright test rbac         # filter by file name

Documentation Site

cd butler-platform/docs
npm install
npm run dev                      # http://localhost:5173