9.7 KiB
9.7 KiB
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)
- Project structure and scaffolding
- Docker containerization setup
- Complete source code documentation
- API design and endpoints
- Database schema design
- Frontend component architecture
- 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):
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
cp .env.example .env
# Edit .env with your Firefly III details
Step 4: Install & Run
Local Development:
# 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):
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. 🚀