308 lines
9.7 KiB
Markdown
308 lines
9.7 KiB
Markdown
# Firefly III Analytics - Project File Index
|
|
|
|
## 📚 Documentation Files (Complete)
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| **README.md** | Project overview, features, and architecture |
|
|
| **QUICKSTART.md** | Quick start guide with setup instructions |
|
|
| **INSTALLATION.md** | Detailed installation steps (manual and Docker) |
|
|
| **COMPLETE_SOURCE_CODE.md** | All application source code organized by path |
|
|
| **plan.md** | Implementation plan and phases |
|
|
| **FILE_INDEX.md** | This file |
|
|
|
|
---
|
|
|
|
## 🔧 Configuration Files (Complete)
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| **.env.example** | Template for environment variables |
|
|
| **.gitignore** | Git ignore patterns |
|
|
| **docker-compose.yml** | Docker Compose configuration for multi-container setup |
|
|
| **init_project.py** | Python script to auto-generate all project files |
|
|
|
|
---
|
|
|
|
## 🎯 Implementation Status
|
|
|
|
### ✅ Completed (Infrastructure)
|
|
- [x] Project structure and scaffolding
|
|
- [x] Docker containerization setup
|
|
- [x] Complete source code documentation
|
|
- [x] API design and endpoints
|
|
- [x] Database schema design
|
|
- [x] Frontend component architecture
|
|
- [x] Installation and setup guides
|
|
|
|
### 🔄 In Progress / Ready to Implement
|
|
- [ ] Create backend directory structure and files (see COMPLETE_SOURCE_CODE.md)
|
|
- [ ] Create frontend directory structure and files (see COMPLETE_SOURCE_CODE.md)
|
|
- [ ] Set up Python virtual environment and dependencies
|
|
- [ ] Set up Node.js dependencies
|
|
- [ ] Test API endpoints with FastAPI docs
|
|
- [ ] Test frontend components
|
|
- [ ] Deploy with Docker Compose
|
|
- [ ] Connect to live Firefly III instance
|
|
|
|
### ⏳ Not Yet Started
|
|
- [ ] Advanced filtering features (budget categories, tags)
|
|
- [ ] Export functionality (PDF, CSV)
|
|
- [ ] User authentication (if multi-user)
|
|
- [ ] Data visualization enhancements (more chart types)
|
|
- [ ] Performance optimization (pagination, lazy loading)
|
|
- [ ] Testing suite (unit and integration tests)
|
|
|
|
---
|
|
|
|
## 📂 Project Directory Structure (To Be Created)
|
|
|
|
```
|
|
firefly_reports/
|
|
├── .env # Environment variables (create from .env.example)
|
|
├── .env.example # Template ✅
|
|
├── .gitignore # Git ignore patterns ✅
|
|
├── README.md # Project overview ✅
|
|
├── QUICKSTART.md # Quick start guide ✅
|
|
├── INSTALLATION.md # Installation steps ✅
|
|
├── COMPLETE_SOURCE_CODE.md # All source code ✅
|
|
├── docker-compose.yml # Docker setup ✅
|
|
├── init_project.py # Project init script ✅
|
|
│
|
|
├── backend/
|
|
│ ├── pyproject.toml # Python dependencies
|
|
│ ├── Dockerfile # Backend Docker image
|
|
│ ├── app/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── main.py # FastAPI application
|
|
│ │ ├── config.py # Settings/configuration
|
|
│ │ ├── models.py # SQLAlchemy ORM models
|
|
│ │ ├── database.py # Database initialization
|
|
│ │ ├── routers/
|
|
│ │ │ ├── __init__.py
|
|
│ │ │ ├── transactions.py # Transaction endpoints
|
|
│ │ │ ├── categories.py # Category endpoints
|
|
│ │ │ ├── accounts.py # Account endpoints
|
|
│ │ │ ├── reports.py # Report generation endpoints
|
|
│ │ │ └── summary.py # Dashboard summary endpoints
|
|
│ │ ├── clients/
|
|
│ │ │ ├── __init__.py
|
|
│ │ │ └── firefly_client.py # Firefly III API client
|
|
│ │ └── services/
|
|
│ │ ├── __init__.py
|
|
│ │ └── sync_service.py # Background data sync
|
|
│
|
|
├── frontend/
|
|
│ ├── package.json # NPM dependencies
|
|
│ ├── Dockerfile # Frontend Docker image
|
|
│ ├── nginx.conf # Nginx configuration
|
|
│ ├── public/
|
|
│ │ └── index.html # HTML template
|
|
│ └── src/
|
|
│ ├── App.tsx # Main App component
|
|
│ ├── index.tsx # React entry point
|
|
│ ├── types.ts # TypeScript interfaces
|
|
│ ├── services/
|
|
│ │ └── api.ts # API client and calls
|
|
│ ├── components/
|
|
│ │ ├── DateRangePicker.tsx
|
|
│ │ ├── SpendingChart.tsx
|
|
│ │ └── TrendChart.tsx
|
|
│ └── pages/
|
|
│ ├── Dashboard.tsx # Dashboard page
|
|
│ └── ReportsPage.tsx # Reports page
|
|
│
|
|
├── data/ # SQLite database (created at runtime)
|
|
│ └── app.db
|
|
│
|
|
└── venv/ # Python virtual environment (created at runtime)
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Getting Started
|
|
|
|
### Step 1: Review the Plan
|
|
Read **QUICKSTART.md** or **INSTALLATION.md** to understand the setup process.
|
|
|
|
### Step 2: Create Project Files
|
|
Choose one of two methods:
|
|
|
|
**Automated (Recommended):**
|
|
```bash
|
|
python init_project.py
|
|
```
|
|
|
|
**Manual:**
|
|
- Copy code from **COMPLETE_SOURCE_CODE.md**
|
|
- Create files in the directory structure shown above
|
|
|
|
### Step 3: Set Up Environment
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your Firefly III details
|
|
```
|
|
|
|
### Step 4: Install & Run
|
|
**Local Development:**
|
|
```bash
|
|
# Backend
|
|
cd backend && python -m venv venv && source venv/bin/activate && pip install -e . && uvicorn app.main:app --reload
|
|
|
|
# Frontend (new terminal)
|
|
cd frontend && npm install && npm start
|
|
```
|
|
|
|
**Docker (Production):**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Step 5: Access the App
|
|
- **Frontend**: http://localhost:3000
|
|
- **API Docs**: http://localhost:8000/docs
|
|
|
|
---
|
|
|
|
## 📖 Source Code Reference
|
|
|
|
### Backend Architecture
|
|
- **Framework**: FastAPI (async Python web framework)
|
|
- **Database**: SQLAlchemy ORM + SQLite
|
|
- **Task Scheduling**: APScheduler for background sync
|
|
- **API Client**: httpx for async HTTP requests
|
|
|
|
### Frontend Architecture
|
|
- **Framework**: React 18 with TypeScript
|
|
- **Charts**: Recharts for interactive visualizations
|
|
- **HTTP Client**: Axios for API communication
|
|
- **Styling**: Inline CSS + responsive design
|
|
- **Deployment**: Nginx reverse proxy in Docker
|
|
|
|
### Data Flow
|
|
```
|
|
Firefly III API
|
|
↓
|
|
firefly_client.py (async HTTP client)
|
|
↓
|
|
sync_service.py (background task every 30 min)
|
|
↓
|
|
SQLite Database (cached data)
|
|
↓
|
|
FastAPI routers (serve data)
|
|
↓
|
|
React Components (display charts)
|
|
↓
|
|
User Dashboard (http://localhost:3000)
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 API Endpoints Summary
|
|
|
|
| Endpoint | Method | Purpose |
|
|
|----------|--------|---------|
|
|
| `/` | GET | Health check |
|
|
| `/health` | GET | API status |
|
|
| `/api/transactions` | GET | List transactions |
|
|
| `/api/categories` | GET | List categories |
|
|
| `/api/accounts` | GET | List accounts |
|
|
| `/api/reports/spending-by-category` | GET | Spending breakdown |
|
|
| `/api/reports/income-vs-expenses` | GET | Income vs expenses |
|
|
| `/api/reports/trends` | GET | Financial trends |
|
|
| `/api/summary` | GET | Dashboard metrics |
|
|
| `/docs` | GET | Interactive API documentation |
|
|
|
|
---
|
|
|
|
## 💾 Database Schema
|
|
|
|
### transactions
|
|
- id (PK), firefly_id (unique), date, amount, description, type
|
|
- category_id (FK), from_account_id (FK), to_account_id (FK)
|
|
- notes, created_at, updated_at
|
|
|
|
### categories
|
|
- id (PK), firefly_id (unique), name (unique), type
|
|
- created_at, updated_at
|
|
|
|
### accounts
|
|
- id (PK), firefly_id (unique), name (unique), type
|
|
- balance, currency_code, active, created_at, updated_at
|
|
|
|
### sync_logs
|
|
- id (PK), entity_type, last_sync, status, message
|
|
- created_at
|
|
|
|
---
|
|
|
|
## 🎯 Feature Checklist
|
|
|
|
### Dashboard
|
|
- [ ] Display total assets
|
|
- [ ] Show recent transactions count
|
|
- [ ] Display last 30 days income/expenses summary
|
|
- [ ] Auto-refresh every 5 minutes
|
|
|
|
### Reports
|
|
- [ ] Spending by category (pie chart)
|
|
- [ ] Income vs expenses (comparison)
|
|
- [ ] Trends over time (line chart)
|
|
- [ ] Flexible date range selector
|
|
- [ ] Preset date options (30/90/365 days)
|
|
- [ ] Category filtering
|
|
- [ ] Chart export (future)
|
|
|
|
### Backend
|
|
- [ ] Transaction fetching from Firefly III
|
|
- [ ] Category fetching from Firefly III
|
|
- [ ] Account fetching from Firefly III
|
|
- [ ] Background sync scheduler
|
|
- [ ] Report generation endpoints
|
|
- [ ] Summary/dashboard endpoints
|
|
- [ ] Error handling and logging
|
|
- [ ] CORS configuration for frontend
|
|
|
|
### Frontend
|
|
- [ ] Dashboard page with metrics
|
|
- [ ] Reports page with selector
|
|
- [ ] Date range picker component
|
|
- [ ] Chart components (pie, line)
|
|
- [ ] Navigation between pages
|
|
- [ ] Error states
|
|
- [ ] Loading states
|
|
- [ ] Responsive design
|
|
|
|
---
|
|
|
|
## 🔐 Security Notes
|
|
|
|
- ✅ API token stored in environment variables (not in code)
|
|
- ✅ CORS configured for local development
|
|
- ✅ HTTPS recommended for production
|
|
- ✅ No sensitive data logged
|
|
- ✅ Database credentials in .env only
|
|
|
|
---
|
|
|
|
## 📞 Support Resources
|
|
|
|
- **Firefly III API Docs**: https://api-docs.firefly-iii.org/
|
|
- **FastAPI Docs**: https://fastapi.tiangolo.com/
|
|
- **React Documentation**: https://react.dev/
|
|
- **Recharts Examples**: https://recharts.org/en-US/examples
|
|
|
|
---
|
|
|
|
## 📝 Notes
|
|
|
|
- All code is documented and ready to use
|
|
- Comments included where logic needs clarification
|
|
- Type hints used throughout for clarity
|
|
- Async/await patterns for optimal performance
|
|
- SQLite for simplicity (can be upgraded to PostgreSQL)
|
|
|
|
---
|
|
|
|
**Status**: Ready for implementation! All documentation and source code complete. 🚀
|