Skip to main content

​
Kalops Budget App

A Next.js budget tracking dashboard for the Kalops FinOps platform. Integrates with Airtable for data storage and Starling Bank for automatic transaction sync.

​
Features

  • Dashboard - Real-time budget performance, spending trends, and alerts
  • Transactions - View and manage transaction history with auto-categorization
  • Categories - Budget category tracking with visual progress indicators
  • Alerts - Configurable budget alerts and notifications
  • Widget - Embeddable widget for Kalweb integration

​
Tech Stack

CategoryTechnology
FrameworkNext.js 16 (App Router)
UIReact 19 + shadcn/ui + Tailwind CSS v4
ChartsRecharts
DataTanStack React Query
DatabaseAirtable
Bank IntegrationStarling Bank API
TestingVitest + Testing Library

​
Quick Start

​
Prerequisites

  • Node.js 20+
  • npm
  • Airtable account (see source repository for setup guide)

​
Installation

# Clone and navigate
cd finops/budget-app

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local
# Edit .env.local with your Airtable credentials

# Start development server
npm run dev
Open http://localhost:3000 to view the app.

​
Scripts

CommandDescription
npm run devStart development server
npm run buildBuild for production
npm run startStart production server
npm run lintRun ESLint
npm run testRun tests in watch mode
npm run test:runRun tests once
npm run test:coverageRun tests with coverage

​
Environment Variables

Copy .env.example to .env.local and configure:
VariableRequiredDescription
AIRTABLE_API_KEYYesAirtable Personal Access Token
AIRTABLE_BASE_IDYesAirtable Base ID
NEXT_PUBLIC_APP_URLYesProduction URL
STARLING_ACCESS_TOKENNoStarling Bank API token
NEXT_PUBLIC_LOCALENoLocale (default: en-GB)
NEXT_PUBLIC_CURRENCYNoCurrency (default: GBP)
See .env.example for all options.

​
Deployment

  1. Push to GitHub
  2. Import in Vercel Dashboard
  3. Set root directory: finops/budget-app
  4. Add environment variables
  5. Deploy

​
Docker (Self-hosted)

# Build image
docker build -t kalops-budget-app .

# Run with environment file
docker run -p 3000:3000 --env-file .env.local kalops-budget-app

# Or use Docker Compose
docker-compose up -d
See vercel.json and docker-compose.yml in the source repository for configuration details.

​
API Endpoints

EndpointMethodDescription
/api/healthGETHealth check with connectivity tests
/api/airtable/transactionsGETFetch transactions
/api/airtable/performanceGETCategory performance data
/api/airtable/categoriesGETBudget categories
/api/airtable/alertsGET, PATCHGet/acknowledge alerts
/api/budget/summaryGETDashboard summary

​
Project Structure

src/
├── app/                    # Next.js pages and API routes
│   ├── api/                # Backend API endpoints
│   ├── dashboard/          # Main dashboard page
│   ├── settings/           # Settings page
│   ├── transactions/       # Transactions page
│   └── widget/             # Embeddable widget
├── components/
│   ├── dashboard/          # Dashboard components
│   ├── ui/                 # shadcn/ui components
│   └── widget/             # Widget components
├── hooks/                  # Custom React hooks
└── lib/                    # Utilities, clients, types

​
Documentation

Additional documentation available in the source repository:
  • Airtable Setup Guide - Database configuration
  • Starling Bank Integration - Bank API setup
  • Architecture Overview - Technical architecture
  • Security Documentation - Security configuration

​
Testing

# Run all tests
npm run test:run

# Watch mode
npm run test

# With coverage
npm run test:coverage
Current coverage: 132 tests across 9 test suites.

​
Security

See SECURITY.md in the source repository for:
  • Rate limiting configuration
  • Security headers
  • Input validation
  • CORS settings

​
Contributing

  1. Create a feature branch
  2. Make changes with tests
  3. Ensure lint and tests pass
  4. Create a pull request
PR previews are automatically deployed via GitHub Actions.

​
License

Private - Kalops FinOps Platform