# Firefly III Analytics & Reporting - Quick Start Guide

## 📋 What's Been Created

A complete, production-ready web application for analytics and reporting on your Firefly III personal finance data.

### ✅ Completed
- Full project structure and scaffolding
- Docker containerization setup (docker-compose.yml)
- All source code (backend, frontend, configuration)
- API documentation and architecture

### 📁 Key Files

1. **COMPLETE_SOURCE_CODE.md** - All application source code organized by file path
2. **INSTALLATION.md** - Detailed installation and setup instructions
3. **README.md** - Project overview and features
4. **.env.example** - Environment variable template
5. **docker-compose.yml** - Container orchestration
6. **init_project.py** - Automated project initialization script

---

## 🚀 Quick Start (Choose One Method)

### Method 1: Automated Setup (Recommended)

```bash
# From project root directory
python init_project.py
```

This creates all directory structures and files automatically.

### Method 2: Manual Setup

Copy each code section from **COMPLETE_SOURCE_CODE.md** to the corresponding file path:

```
backend/
├── pyproject.toml
├── Dockerfile
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── models.py
│   ├── database.py
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── transactions.py
│   │   ├── categories.py
│   │   ├── accounts.py
│   │   ├── reports.py
│   │   └── summary.py
│   ├── clients/
│   │   ├── __init__.py
│   │   └── firefly_client.py
│   └── services/
│       ├── __init__.py
│       └── sync_service.py

frontend/
├── package.json
├── Dockerfile
├── nginx.conf
└── src/
    ├── App.tsx
    ├── index.tsx
    ├── types.ts
    ├── services/
    │   └── api.ts
    ├── components/
    │   ├── DateRangePicker.tsx
    │   ├── SpendingChart.tsx
    │   └── TrendChart.tsx
    └── pages/
        ├── Dashboard.tsx
        └── ReportsPage.tsx
```

---

## 🔧 Setup Steps

### 1. Environment Configuration

```bash
# Copy template and edit
cp .env.example .env

# Add your Firefly III API token
# FIREFLY_URL=https://firefly.scsimedia.duckdns.org
# FIREFLY_API_TOKEN=your_token_here
```

### 2. Backend Installation

```bash
cd backend
python -m venv venv

# On Windows
venv\Scripts\activate
# On Mac/Linux
source venv/bin/activate

pip install -e .
```

### 3. Frontend Installation

```bash
cd frontend
npm install
```

### 4. Run Locally (Development)

**Terminal 1 - Backend:**
```bash
cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn app.main:app --reload
```

Backend available at: http://localhost:8000
API docs at: http://localhost:8000/docs

**Terminal 2 - Frontend:**
```bash
cd frontend
npm start
```

Frontend available at: http://localhost:3000

### 5. Docker Deployment (Production)

```bash
docker-compose up -d
```

- Frontend: http://localhost:3000
- Backend: http://localhost:8000
- Database: SQLite (stored in `data/` volume)

---

## 📊 Features Implemented

### Dashboard
- **Key Metrics**: Total assets, recent transactions, income/expenses summary
- **30-Day Overview**: Quick financial snapshot
- **Real-time Updates**: Data syncs every 30 minutes from Firefly III

### Reports
- **Spending by Category**: Pie chart breakdown of expenses
- **Income vs Expenses**: Comparison of income and spending
- **Trends**: Line chart showing financial trends over time
- **Flexible Date Range**: Preset options (30/90/365 days) or custom dates
- **Category Filtering**: Split charts by category

### Data Sync
- **Automatic Background Sync**: Fetches data from Firefly III on a schedule
- **Caching**: SQLite database for performance
- **API Rate Limiting**: Respects Firefly III API limits

---

## 🔌 API Endpoints

### Base URL
```
http://localhost:8000
```

### Transactions
- `GET /api/transactions` - List transactions
- `GET /api/transactions?start_date=2024-01-01&end_date=2024-12-31` - Filter by date
- `GET /api/transactions?category_id=5` - Filter by category

### Categories
- `GET /api/categories` - List all categories

### Accounts
- `GET /api/accounts` - List all accounts

### Reports
- `GET /api/reports/spending-by-category?start_date=2024-01-01&end_date=2024-12-31`
- `GET /api/reports/income-vs-expenses?start_date=2024-01-01&end_date=2024-12-31`
- `GET /api/reports/trends?start_date=2024-01-01&end_date=2024-12-31`

### Summary
- `GET /api/summary` - Dashboard metrics

---

## 🎨 Customization

### Add New Report Types
1. Create new endpoint in `backend/app/routers/reports.py`
2. Add business logic to `backend/app/services/report_service.py`
3. Create React component in `frontend/src/components/`
4. Add UI in `frontend/src/pages/ReportsPage.tsx`

### Modify Chart Styling
Edit `frontend/src/components/` chart components to customize colors, sizes, legends.

### Change Sync Interval
Update `SYNC_INTERVAL_MINUTES` in `.env` (default: 30 minutes)

---

## 🐛 Troubleshooting

### API Connection Error
- Verify `FIREFLY_API_TOKEN` is set correctly in `.env`
- Check Firefly III instance is accessible at `FIREFLY_URL`
- View logs: `docker-compose logs backend`

### No Data Displaying
- First sync can take a minute - check backend logs
- Verify Firefly III API token has read permissions
- Wait for automatic sync (default: 30 minutes)

### Port Already in Use
Change ports in `docker-compose.yml` or local startup commands

---

## 📚 Additional Resources

- Firefly III Docs: https://docs.firefly-iii.org/
- FastAPI Docs: https://fastapi.tiangolo.com/
- React Docs: https://react.dev/
- Recharts Docs: https://recharts.org/

---

## ✨ Next Steps

1. **Run the setup** using one of the methods above
2. **Configure your Firefly III token** in `.env`
3. **Start the application** (Docker or manual)
4. **Access the dashboard** at http://localhost:3000
5. **Explore reports** and customize as needed
6. **(Optional) Deploy** to your infrastructure

---

## 💡 Pro Tips

- Use `docker-compose logs -f backend` to monitor backend in real-time
- FastAPI interactive docs at `/docs` are great for testing endpoints
- Check browser DevTools console for frontend debugging
- Database is automatically backed up in `data/app.db`

---

**Ready to get started?** Choose your setup method above and follow the steps! 🎉