128 lines
3.4 KiB
Markdown
128 lines
3.4 KiB
Markdown
# 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**
|
|
```bash
|
|
cd firefly_reports
|
|
```
|
|
|
|
2. **Create environment file**
|
|
```bash
|
|
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**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|