Bugdet

AI-powered personal finance tracker that automatically categorizes your bank transactions.

Bugdet helps you understand your spending by importing bank statements and using AI to intelligently categorize transactions. Upload your PDF bank statements, and let the AI do the heavy lifting.

Features

• Bank Statement Processing - Upload PDF bank statements for automatic parsing
• AI-Powered Categorization - Transactions are automatically categorized using AI via Vercel AI Gateway
• Custom Categories - Create and manage your own spending categories
• Categorization Rules - Define rules to automatically categorize recurring merchants
• Dashboard Analytics - Visual insights into your spending patterns
• Bulk Operations - Select and manage multiple transactions at once
• Two-Factor Authentication - Secure your account with 2FA
• Email Notifications - Get notified when your uploads are processed

Tech Stack

• Framework: Next.js 15 with App Router and Turbopack
• Language: TypeScript 5
• Database: PostgreSQL 16 with Drizzle ORM
• API: tRPC for end-to-end type-safe APIs
• Authentication: better-auth with email/password + 2FA
• AI: Vercel AI SDK with Vercel AI Gateway
• Background Jobs: Trigger.dev for async processing
• Caching: Upstash Redis for rate limiting and caching
• File Storage: Supabase for bank statement uploads
• Email: Resend with React Email
• UI: shadcn/ui + Tailwind CSS 4
• Linting: Biome

Getting Started

Prerequisites

• Node.js 22+
• pnpm 9+
• Docker (for local PostgreSQL and Redis)

Installation

1. Clone the repository

   git clone https://github.com/joaopcm/bugdet.git
   cd bugdet

2. Install dependencies

   pnpm install

3. Set up environment variables

   cp .env.example .env

   Fill in the required environment variables (see Environment Variables).

4. Start the database

   pnpm db:start

5. Run database migrations

   pnpm db:migrate

6. Start the development server

   pnpm dev

   This starts both Next.js (with Turbopack) and Trigger.dev dev server concurrently.

7. Open your browser

   Navigate to http://localhost:3000

Scripts

Command	Description
pnpm dev	Start Next.js + Trigger.dev development servers
pnpm build	Create production build
pnpm start	Start production server
pnpm lint	Run Biome linter
pnpm email	Start React Email dev server
pnpm db:start	Start PostgreSQL + Redis via Docker
pnpm db:stop	Stop database containers
pnpm db:generate	Generate Drizzle migrations
pnpm db:migrate	Run database migrations
pnpm trigger:dev	Start Trigger.dev local development
pnpm deploy:trigger:staging	Deploy background jobs to staging
pnpm deploy:trigger:production	Deploy background jobs to production

Environment Variables

Create a .env file based on .env.example. Here are the required variables:

Required Variables

Variable	Description
DATABASE_URL	PostgreSQL connection string
BETTER_AUTH_SECRET	Secret key for authentication encryption
BETTER_AUTH_URL	Base URL for auth endpoints (e.g., http://localhost:3000)
AI_GATEWAY_API_KEY	Vercel AI Gateway API key
RESEND_API_KEY	Resend API key for emails
RESEND_WAITLIST_SEGMENT_ID	Resend segment ID for waitlist
SUPABASE_URL	Supabase project URL
SUPABASE_ANON_KEY	Supabase anonymous key
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key
TRIGGER_SECRET_KEY	Trigger.dev secret key
UPSTASH_REDIS_REST_URL	Upstash Redis REST URL
UPSTASH_REDIS_REST_TOKEN	Upstash Redis REST token
BACKOFFICE_API_KEY	API key for admin operations
NEXT_PUBLIC_APP_URL	Public application URL
DATA_ENCRYPTION_KEK	32-byte hex key for tenant data encryption
UPLOAD_PASSWORD_ENCRYPTION_KEY	32-byte hex key for PDF password encryption

Generating Encryption Keys

Both DATA_ENCRYPTION_KEK and UPLOAD_PASSWORD_ENCRYPTION_KEY require 32-byte hex strings (64 characters). Generate them with:

openssl rand -hex 32

Project Structure

src/
├── app/                    # Next.js App Router
│   ├── (marketing)/        # Public landing page
│   ├── (app)/
│   │   ├── (auth)/         # Authentication pages
│   │   └── (logged-in)/    # Protected dashboard pages
│   └── api/                # API routes (tRPC, auth)
├── server/                 # Backend logic
│   ├── routers/            # tRPC routers
│   └── trpc.ts             # tRPC configuration
├── db/
│   └── schema.ts           # Drizzle database schema
├── trigger/                # Background job definitions
│   ├── ai/                 # AI processing tasks
│   └── emails/             # Email sending tasks
├── components/
│   ├── ui/                 # shadcn/ui components
│   └── emails/             # React Email templates
├── lib/                    # Shared utilities
│   ├── auth/               # Authentication config
│   └── rules/              # Categorization rule engine
└── hooks/                  # React hooks

Self-Hosting

For detailed self-hosting instructions, see the Self-Hosting Guide.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• How we use GitHub Issues to manage tasks
• Setting up your development environment
• Submitting pull requests
• Code style and conventions

License

This project is open source. See the repository for license details.

Links

• Documentation
• Contributing Guidelines
• Self-Hosting Guide