Initial commit
This commit is contained in:
nabeel
261
QUICKSTART.md
Normal file
261
QUICKSTART.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# 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! 🎉
|
||||
Reference in New Issue
Block a user