Initial commit

2026-05-27 13:58:05 +10:00
commit c2202ea0bb
89 changed files with 28855 additions and 0 deletions
--- a/FILE_INDEX.md
+++ b/FILE_INDEX.md
@@ -0,0 +1,307 @@
+# 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. 🚀