Firefly III Analytics & Reporting

A flexible web application for analytics and reporting on Firefly III personal finance data.

Features

• 📊 Interactive dashboard with key financial metrics
• 📈 Flexible date range selection for custom reporting periods
• 📉 Multiple chart types: trends, category breakdowns, income vs expenses, budget vs actual
• 🎯 Dynamic filtering and grouping by category and account type
• 🚀 Responsive design for desktop and mobile
• 🔐 Secure connection to your Firefly III instance
• 💾 Local SQLite caching to minimize API calls

Quick Start

Prerequisites

• Docker and Docker Compose
• Firefly III instance with API token

Setup

1. Clone this repository

   cd firefly_reports
   

2. Create environment file

   cp .env.example .env
   

3. Configure your Firefly III instance Edit .env and set:

   FIREFLY_URL=https://firefly.scsimedia.duckdns.org
   FIREFLY_API_TOKEN=your_api_token_here
   

4. Start the application

   docker-compose up -d
   

5. Access the dashboard

   • Frontend: http://localhost:3000
   • API: http://localhost:8000

Architecture

firefly_reports/
├── backend/              # FastAPI backend
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   ├── database.py
│   │   ├── models.py
│   │   ├── routers/      # API endpoints
│   │   ├── services/     # Business logic
│   │   └── clients/      # Firefly III API client
│   ├── Dockerfile
│   └── pyproject.toml
├── frontend/             # React frontend
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   └── App.tsx
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
└── .env

Project Structure

• Backend: Python FastAPI with SQLAlchemy ORM, SQLite database
• Frontend: React 18 with TypeScript, Recharts for visualizations
• Database: SQLite with caching for Firefly III data

Development

Backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm start

API Endpoints

• GET /api/transactions - Cached transaction data
• GET /api/categories - Category data
• GET /api/accounts - Account information
• GET /api/reports/{report_type} - Generate reports (spending-by-category, trends, budget-vs-actual, income-vs-expenses)
• GET /api/summary - Dashboard summary metrics

Reports Available

1. Spending by Category - Breakdown of expenses by category
2. Income vs Expenses - Comparison of income and expenses over time
3. Budget vs Actual - How actual spending compares to budgets
4. Trends - Financial trends over time (line charts)
5. Account Balances - Net worth and account balance trends

Configuration

See .env.example for available environment variables:

• FIREFLY_URL - Your Firefly III instance URL
• FIREFLY_API_TOKEN - Your Firefly III API token
• SYNC_INTERVAL_MINUTES - How often to sync data (default: 30)

License

MIT