firefly_reports/QUICKSTART.md

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)

# 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

# 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

cd backend
python -m venv venv

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

pip install -e .

3. Frontend Installation

cd frontend
npm install

4. Run Locally (Development)

Terminal 1 - Backend:

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:

cd frontend
npm start

Frontend available at: http://localhost:3000

5. Docker Deployment (Production)

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! 🎉