Skip to main content

​
Overview

BudgetBee is organized as a monorepo using Turborepo for build orchestration and pnpm workspaces for dependency management. This structure enables code sharing across multiple applications while maintaining clear boundaries between packages.

​
Workspace Configuration

The monorepo is defined in pnpm-workspace.yaml: 
packages:
    - "apps/*"
    - "packages/*"

​
Directory Structure

budgetbee/
├── apps/
│   ├── currency-api/     # Currency conversion API
│   ├── docs/             # Documentation site (Mintlify)
│   ├── site/             # Landing page
│   └── web/              # Main application
├── packages/
│   ├── billing/          # Polar billing integration
│   ├── core/             # Auth, database, feature flags
│   ├── email/            # Email utilities (Resend)
│   ├── fz-datetime/      # Datetime utilities
│   ├── tsconfig/         # Shared TypeScript configs
│   └── ui/               # Shared UI components
├── infra/
│   └── docker-compose.yml  # PostgreSQL + PostgREST
├── scripts/              # Setup and utility scripts
├── .env                  # Environment variables (gitignored)
├── Makefile              # Development commands
├── package.json          # Root package configuration
├── pnpm-workspace.yaml   # Workspace definition
└── turbo.json            # Turborepo configuration

​
Applications (apps/)

​
Main Application (web)

The primary BudgetBee application built with Next.js. Local URL: http://localhost:3001 Key Features:
  • User authentication and authorization
  • Budget management and tracking
  • Transaction recording
  • Organization management
  • Subscription billing

​
Landing Page (site)

Marketing website built with Next.js. Local URL: http://localhost:3000 Features:
  • Product information
  • Pricing plans
  • Authentication endpoints (/api/auth/*)
  • JWKS endpoint for JWT verification

​
Documentation (docs)

This documentation site built with Mintlify. Local URL: http://localhost:3002

​
Currency API (currency-api)

Microservice for currency conversion rates.

​
Packages (packages/)

​
Core (@budgetbee/core)

@budgetbee/core

Authentication, database access, and core business logic
Key Exports: 
// Authentication (server-side)
import { auth } from "@budgetbee/core/auth";

// Authentication (client-side)
import { authClient } from "@budgetbee/core/auth-client";

// Database access
import { db, getDb } from "@budgetbee/core/db";
import { getAuthAdminClient } from "@budgetbee/core/db-pool";

// Feature flags
import { getFeatureFlag } from "@budgetbee/core/feature-flags";

// UI components
import { SomeComponent } from "@budgetbee/core/ui/some-component";
Technologies:
  • Better Auth for authentication
  • Polar Better Auth plugin for billing
  • PostgREST client for database access
  • PostgreSQL for data storage
  • Redis for caching
Learn more →

​
UI (@budgetbee/ui)

@budgetbee/ui

Shared React components built with shadcn/ui
Key Exports: 
// UI components
import { Button } from "@budgetbee/ui/core/button";
import { Dialog } from "@budgetbee/ui/core/dialog";
import { Card } from "@budgetbee/ui/core/card";

// Hooks
import { useSomeHook } from "@budgetbee/ui/hooks/use-some-hook";

// Utilities
import { cn } from "@budgetbee/ui/lib/utils";

// Styles
import "@budgetbee/ui/globals.css";
Component Library:
  • 30+ shadcn/ui components
  • Radix UI primitives
  • Tailwind CSS styling
  • Custom theme support
  • Chart components (Recharts)
Learn more →

​
Billing (@budgetbee/billing)

@budgetbee/billing

Polar integration for subscription management
Key Exports: 
import { polar } from "@budgetbee/billing";
import { 
  isPro, 
  isTeams, 
  isProOrHigher,
  isTeamsOrHigher 
} from "@budgetbee/billing";
Features:
  • Polar SDK integration
  • Subscription tier helpers
  • Webhook handling
  • Usage tracking
Learn more →

​
Email (@budgetbee/email)

Email templates and Resend integration for transactional emails.

​
Datetime (@budgetbee/fz-datetime)

Date and time utilities for timezone handling and formatting.

​
TypeScript Config (@budgetbee/tsconfig)

Shared TypeScript configuration presets:
  • base.json - Base configuration
  • nextjs.json - Next.js specific config
  • react-library.json - React library config

​
Turborepo Configuration

BudgetBee uses Turborepo for efficient builds and caching: 
{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}
Key Features:
  • Parallel task execution
  • Intelligent caching
  • Dependency graph awareness
  • Task orchestration

​
Package Manager

BudgetBee uses pnpm for fast, disk-efficient dependency management: 
{
  "packageManager": "[email protected]"
}
Benefits:
  • Faster installs than npm/yarn
  • Efficient disk usage with content-addressable storage
  • Strict dependency resolution
  • Better monorepo support

​
Running Commands

​
Run in all workspaces

pnpm -r <command>

​
Run in specific workspace

pnpm --filter @budgetbee/core <command>

​
Run with Turborepo

pnpm turbo <task>

​
Infrastructure

​
Docker Compose

The infra/ directory contains Docker configuration for:
  • PostgreSQL - Primary database
  • PostgREST - REST API for PostgreSQL
cd infra
docker compose up -d

​
Database Migrations

Migrations are stored in packages/core/migrations/ and run in order:
  1. better-auth-migrations.sql - Auth tables
  2. init.sql - Initial schema
  3. migration_YYYY_MM_DD_*.sql - Dated migrations

​
Adding New Packages

To add a new shared package:
1

Create package directory

mkdir packages/my-package
cd packages/my-package
2

Initialize package.json

{
  "name": "@budgetbee/my-package",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    "./": "./index.ts"
  }
}
3

Add dependencies

pnpm add <package> --filter @budgetbee/my-package
4

Use in other packages

{
  "dependencies": {
    "@budgetbee/my-package": "workspace:*"
  }
}

​
Best Practices

Keep packages focused - Each package should have a single, well-defined responsibility.
Use workspace protocol - Always use workspace:* for internal dependencies.
Shared configs - Use @budgetbee/tsconfig for TypeScript configuration.
Avoid circular dependencies - Keep the dependency graph acyclic.

​
Next Steps

Core Package

Deep dive into authentication and database access

UI Package

Explore the component library

Build docs developers (and LLMs) love

Get started for freeTalk to us