Initial commit

2026-05-27 13:58:05 +10:00
commit c2202ea0bb
89 changed files with 28855 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,127 @@
+# 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