# 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