Expense Pet

Personal expense tracking app with gamification — virtual pet companion, points, and streaks.

Full-stack TypeScript monorepo with a React Native mobile app and Fastify backend.

Tech Stack

Layer	Technology
Mobile	Expo 55, React Native 0.83, Expo Router, NativeWind, TanStack Query
Backend	Fastify 5, Prisma 7, PostgreSQL 16
Auth	JWT (access + refresh tokens), argon2
AI Agent	Claude API (SSE streaming), budget insights
Validation	Zod v4 (shared schemas between mobile and backend)
Tooling	Turborepo, Biome.js, Husky, lint-staged
Testing	Vitest
Runtime	Node.js 25

Project Structure

expense-pet/
├── apps/
│   ├── api/          # Fastify backend
│   └── mobile/       # Expo React Native app
├── packages/
│   └── shared/       # Zod validation schemas (@expense-pet/shared)
├── docs/             # Architecture docs and product whitepaper
├── biome.json
├── turbo.json
└── docker-compose.yml

Features

• Expense tracking with categories (base + custom)
• Budget management with progress tracking
• AI assistant with streaming responses (Claude API)
• JWT auth with refresh token rotation

Prerequisites

• Node.js >= 25 (see .nvmrc)
• Docker (for PostgreSQL + Caddy reverse proxy)
• Expo Go app on iOS/Android, or a simulator

Getting Started

# Clone and install
git clone <repo-url>
cd expense-pet
nvm use
npm install

# Start PostgreSQL and Caddy
docker compose up -d

# Generate Prisma client and run migrations
cd apps/api
npx prisma generate
npx prisma migrate dev
cd ../..

# Start all apps in dev mode
npm run dev

The API runs on https://api.expense-pet.local (via Caddy).
Run the mobile app separately: cd apps/mobile && npm run dev

Scripts

npm run dev          # Start all apps (turbo)
npm run build        # Build all packages/apps
npm run test         # Run tests across workspaces
npm run lint         # Biome check (linting + formatting)
npm run lint:fix     # Biome auto-fix
npm run format       # Biome format
npm run typecheck    # TypeScript type checking
npm run clean        # Remove dist/, .turbo, node_modules

Architecture

• 3-layer pattern: Routes (HTTP) → Services (business logic) → Repository (Prisma)
• Shared Zod schemas as single source of truth for validation
• Feature-based folder organization in both API and mobile
• Conventional commits: feat:, fix:, chore:, test:, docs:

See docs/whitepaper.md for product overview and docs/archive/ for historical architecture docs.