AI-powered expense categorization and anomaly detection platform built with FastAPI, Next.js 14, and GPT-4o-mini.
- AI Transaction Categorization: Automatic categorization using GPT-4o-mini with confidence scores
- Anomaly Detection: Statistical + AI-powered detection of unusual spending patterns
- Plaid Integration: Connect bank accounts for automatic transaction syncing
- Idempotent APIs: Safe batch ingestion with deduplication
- Real-time Processing: Celery-based async task queue for categorization and anomaly detection
| Component | Technology |
|---|---|
| Frontend | Next.js 14 (App Router), TypeScript, Tailwind CSS, React Query |
| Backend | FastAPI, Python 3.11+, SQLAlchemy 2.0 |
| Database | PostgreSQL 15 |
| Cache/Queue | Redis, Celery |
| AI | GPT-4o-mini via LiteLLM |
| Banking | Plaid API |
| Observability | OpenTelemetry, Prometheus, Structlog |
- Docker & Docker Compose
- OpenAI API key
- Plaid sandbox credentials (optional, for bank integration)
-
Clone and configure
cd finlens cp .env.example .env # Edit .env with your API keys
-
Start services
docker-compose up -d
-
Run migrations and seed data
docker-compose exec backend alembic upgrade head docker-compose exec celery-worker python -c "from app.workers.tasks import seed_default_categories; seed_default_categories.delay()"
-
Access the app
- Frontend: http://localhost:3000
- API Docs: http://localhost:8000/docs
- Metrics: http://localhost:8000/metrics
# Batch ingest transactions (idempotent)
curl -X POST http://localhost:8000/api/v1/transactions/batch \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)" \
-d '{
"transactions": [
{"amount": 42.50, "description": "UBER EATS", "date": "2026-01-20"}
]
}'
# List transactions with pagination
curl "http://localhost:8000/api/v1/transactions?page=1&per_page=20"
# Filter by anomaly status
curl "http://localhost:8000/api/v1/transactions?is_anomaly=true"# List unreviewed anomalies
curl "http://localhost:8000/api/v1/anomalies?is_reviewed=false"
# Review an anomaly
curl -X POST http://localhost:8000/api/v1/anomalies/{id}/review \
-H "Content-Type: application/json" \
-d '{"is_false_positive": false, "note": "Confirmed suspicious"}'# Get categories with stats
curl http://localhost:8000/api/v1/categories/stats┌─────────────────────────────────────────────────────────────┐
│ Next.js 14 Frontend │
│ (Dashboard, Transactions, Anomalies) │
└──────────────────────────┬──────────────────────────────────┘
│ REST API
┌──────────────────────────▼──────────────────────────────────┐
│ FastAPI Backend │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Transactions│ │ Anomalies │ │ Plaid │ │
│ │ API │ │ API │ │ API │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ┌──────▼────────────────▼────────────────▼──────┐ │
│ │ Service Layer │ │
│ │ Categorizer │ AnomalyDetector │ Idempotency │ │
│ └──────────────────────┬────────────────────────┘ │
└────────────────────────────┼────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────────┐
│ PostgreSQL │ │ Redis │ │ Celery │
│ (data) │ │ (cache/ │ │ Workers │
│ │ │ dedup) │ │ (async tasks) │
└─────────────┘ └─────────────┘ └────────┬────────┘
│
┌────────▼────────┐
│ GPT-4o-mini │
│ (via LiteLLM) │
└─────────────────┘
Transactions use SHA-256 hash of (account_id, amount, date, description) for deduplication:
- Redis stores hashes with 24h TTL for fast lookup
- Database has unique constraint on
tx_hash - API accepts
X-Idempotency-Keyheader for request-level idempotency
- Celery workers with
rate_limit: "50/m"for LLM calls - Redis-based distributed locks prevent concurrent processing
- Queue depth monitoring via Prometheus metrics
Weighted scoring (0-1 scale):
score = 0.4 * amount_z_score + 0.35 * merchant_novelty + 0.25 * time_pattern
Threshold: 0.6 triggers anomaly flag + LLM explanation
docker-compose exec backend pytest -vdocker-compose exec backend ruff check app/
docker-compose exec frontend npm run lintdocker-compose exec celery-worker celery -A app.workers.celery_app inspect active| Component | Usage | Cost/Month |
|---|---|---|
| GPT-4o-mini | 10k transactions @ ~150 tokens | ~$1.50 |
| Plaid Sandbox | Unlimited | $0 |
| Self-hosted | Docker | $0 |
MIT