​
Architecture Overview

This document provides an overview of the Billy monorepo architecture, including the project structure, design patterns, and key technologies.

​
Monorepo Structure

Billy is organized as a monorepo using Turborepo, which provides efficient build caching and task orchestration. 
billy/
├── apps/                   # Application workspaces
│   ├── app/                # Main Next.js application
│   ├── docs/               # Documentation (this site)
│   ├── storybook/          # Design system
│   └── ...                 # Other applications
├── packages/               # Shared package workspaces
│   ├── commons/            # Common utilities
│   ├── ui/                 # UI components
│   ├── db/                 # Database utilities
│   └── ...                 # Other packages
├── cloudflare_queues/      # Cloudflare Workers and Queues

​
Technology Stack

​
Frontend

  • Framework: Next.js with App Router
  • Language: TypeScript
  • Styling: Tailwind CSS
  • State Management: React hooks + Context
  • UI Components: Custom design system + Radix UI

​
Backend

  • Database: Supabase (PostgreSQL)
  • Authentication: Supabase Auth
  • API: Next.js route handlers
  • Queue System: Cloudflare Queues, Qstash, Inngest
  • Webhooks: Hookdeck

​
Infrastructure

  • Hosting: Vercel
  • CDN: Cloudflare
  • Monitoring: Sentry
  • Analytics: Vercel Analytics

​
Package Architecture

​
Apps

​
Main Application (apps/app)

The primary Next.js application that serves the Pennylane Connect platform. Key Features:
  • User authentication and management
  • Integration management
  • Invoice processing
  • CRM integrations
  • Admin dashboard
Structure: 
apps/app/
├── src/
│   ├── app/                # Next.js App Router pages
│   ├── components/         # React components
│   ├── lib/                # Utility functions
│   ├── hooks/              # Custom React hooks
│   ├── types/              # TypeScript definitions
│   └── integrations/       # Third-party integrations
├── public/                 # Static assets
└── fixtures/               # Test data and fixtures

​
Storybook (apps/storybook)

Component documentation and testing environment.

​
Packages

​
Commons (packages/commons)

Shared utilities and helper functions used across the monorepo. Features:
  • Date formatting and manipulation
  • String utilities
  • Validation helpers
  • Common business logic

​
Database (packages/db)

Database utilities and type definitions. Features:
  • Database connection management
  • Query builders
  • Migration utilities
  • Type-safe database operations

​
UI Components (packages/ui)

Reusable UI components shared across applications. Features:
  • Atomic design principles
  • Accessibility-first components
  • Theme support
  • Responsive design

​
Security Architecture

​
Authentication & Authorization

  • Supabase Auth: JWT-based authentication
  • Role-based access control: User, admin, and organization roles
  • API key management: Secure integration credentials

​
Data Protection

  • Encryption: Database column encryption for sensitive data
  • Input validation: Zod schema validation
  • SQL injection prevention: Parameterized queries
  • CORS protection: Configured for production domains

​
Environment Security

  • Secrets management: Environment variables for sensitive data
  • No hardcoded secrets: All credentials externalized
  • Secure defaults: Production-ready security configurations

​
Testing Architecture

​
Testing Strategy

Billy follows a comprehensive testing strategy using Vitest:
  • Unit tests: Individual function and component testing
  • Integration tests: API endpoint and database testing
  • E2E tests: Full user workflow testing
  • Performance tests: Load and stress testing

​
Test Organization

src/
├── components/
│   ├── Button.tsx
│   └── Button.test.tsx      # Tests alongside source
├── lib/
│   ├── utils.ts
│   └── utils.test.ts
└── __tests__/               # Shared test utilities
    ├── setup.ts
    └── helpers.ts

​
Performance Architecture

​
Build Optimization

  • Turborepo caching: Intelligent build caching
  • Code splitting: Dynamic imports and lazy loading
  • Bundle analysis: Webpack bundle optimization
  • Tree shaking: Unused code elimination

​
Runtime Performance

  • Database indexing: Optimized query performance
  • Caching strategies: Redis and in-memory caching
  • CDN optimization: Static asset delivery
  • API optimization: Efficient data fetching

​
Deployment Architecture

​
Vercel Deployment

  • Preview deployments: Automatic PR deployments
  • Production deployment: Main branch deployment
  • Environment management: Staging and production configs
  • Monitoring: Built-in performance monitoring

​
Cloudflare Integration

  • Edge computing: Global CDN and caching
  • Queue processing: Background job processing
  • Security: DDoS protection and WAF
  • Analytics: Performance and usage metrics

​
Monitoring & Observability

​
Application Monitoring

  • Sentry: Error tracking and performance monitoring
  • Vercel Analytics: User behavior and performance
  • Custom metrics: Business-specific KPIs

​
Infrastructure Monitoring

  • Vercel Dashboard: Deployment and function monitoring
  • Supabase Dashboard: Database performance and usage
  • Cloudflare Analytics: CDN and security metrics

​
Development Workflow

​
Code Quality

  • ESLint: Code linting and style enforcement
  • Prettier: Code formatting
  • TypeScript: Static type checking
  • Husky: Git hooks for quality gates

​
CI/CD Pipeline

  • GitHub Actions: Automated testing and deployment
  • Vercel: Automatic deployment on push
  • Quality gates: Tests, linting, and type checking
  • Security scanning: Dependency vulnerability checks

​
Scalability Considerations

​
Horizontal Scaling

  • Stateless design: No server-side state dependencies
  • Database connection pooling: Efficient database connections
  • Queue-based processing: Asynchronous job processing
  • CDN distribution: Global content delivery

​
Performance Optimization

  • Database query optimization: Efficient data access patterns
  • Caching strategies: Multi-layer caching approach
  • Asset optimization: Image and bundle optimization
  • API rate limiting: Protection against abuse
This architecture overview provides a high-level understanding of the Billy system. For implementation details, refer to the specific package documentation and code examples.