Architecture
BankBird is a Laravel 11 application with Filament 5 as the admin panel. The app runs entirely on your own server — no external services except the optional AI API.
Browser / Livewire UI ↓ Filament 5 (Admin Panel) ↓ Controllers / Resources / Pages ↓ Services (ImportService, AiCategorizationService, ...) ↓ Eloquent Models (Transaction, Category, Merchant, ...) ↓ Database (MySQL of SQLite) ↓ (optional) AI API (Anthropic Claude / OpenAI GPT)
Directory structure
bankbird/ ├── app/ │ ├── Filament/ # Admin resources & pages │ ├── Models/ # Eloquent models │ └── Services/ # Business logic ├── database/ │ ├── migrations/ # Database schema │ ├── factories/ # Test factories │ └── seeders/ # Seed data ├── resources/ │ ├── views/ # Blade templates │ └── css/ js/ # Frontend assets └── tests/ # Feature & unit tests
Models
Transaction
The core of the app. Holds amount, date, description, category and merchant. Imported from bank exports.
Category
Hierarchical categories (e.g. Groceries > Albert Heijn). Linked to transactions.
Merchant
Shop or supplier patterns. Matched via regex against transaction descriptions.
ImportBatch
Tracks which PDF or CSV was imported, when, how many transactions and whether AI was used.
User
Standard Laravel User, extended with 2FA and preferences for the AI provider.
AiLog
Stores AI categorisation results for debugging and improving prompts.
Services
ImportService
Processes uploaded PDF/CSV files. Automatically detects the bank format and creates Transaction records.
import(UploadedFile $file)
detectFormat(string $content)
parseIng(string $content)
AiCategorizationService
Sends transaction descriptions to the configured AI API and processes the categorisation response.
categorize(Collection $transactions)
buildPrompt(array $transactions)
parseResponse(string $json)
MerchantMatchingService
Matches transaction descriptions against stored merchant patterns via regex and assigns the category.
match(Transaction $transaction)
findPattern(string $description)
learnFromTransaction(Transaction $tx)
ReportService
Generates overviews, statistics and export files based on filtered transactions.
monthly(int $year, int $month)
yearly(int $year)
export(Collection $transactions)
Workflows
Testing
BankBird uses PHPUnit for feature and unit tests. The test database runs automatically via SQLite in-memory.
# Run all tests php artisan test --compact # Single test file php artisan test tests/Feature/ImportTest.php # Filter by name php artisan test --filter=testImportIng