262 lines
6.7 KiB
Markdown
262 lines
6.7 KiB
Markdown
# 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! 🎉
|