6.2 KiB
🚀 START HERE - Firefly III Analytics Project
Welcome! This is your complete Firefly III analytics application. Here's how to get started:
📖 Choose Your Path
⚡ I want to get started in 5 minutes
→ Read: QUICKSTART.md
📚 I want detailed setup instructions
→ Read: INSTALLATION.md
🏗️ I want to understand the architecture
→ Read: ARCHITECTURE.md
📋 I want to see what's included
→ Read: DELIVERABLES.md
💻 I want to see all the source code
→ Read: COMPLETE_SOURCE_CODE.md
🎯 Quick Start (3 Steps)
1️⃣ Setup Project
# Automated (recommended)
python init_project.py
# OR manually: Copy code from COMPLETE_SOURCE_CODE.md
2️⃣ Configure
cp .env.example .env
# Edit .env and add your Firefly III API token
3️⃣ Run
# Option A: Docker (easiest)
docker-compose up -d
# Option B: Local development
# Terminal 1 - Backend
cd backend && source venv/bin/activate && uvicorn app.main:app --reload
# Terminal 2 - Frontend
cd frontend && npm install && npm start
4️⃣ Access
- Dashboard: http://localhost:3000
- API Docs: http://localhost:8000/docs
📂 What's Included
📚 Documentation (Start with one of these)
├── README.md ← Overview and features
├── QUICKSTART.md ← 5-minute setup guide
├── INSTALLATION.md ← Detailed installation
├── ARCHITECTURE.md ← System design & diagrams
├── COMPLETE_SOURCE_CODE.md ← All 40+ source files
├── FILE_INDEX.md ← Directory structure
├── DELIVERABLES.md ← What's included
└── DELIVERY_SUMMARY.md ← Project summary
🔧 Configuration
├── .env.example ← Copy to .env and edit
├── docker-compose.yml ← Multi-container setup
├── .gitignore ← Git configuration
└── init_project.py ← Auto-setup script
💻 Source Code (40+ files)
├── backend/ ← FastAPI application
│ ├── app/
│ │ ├── main.py ← FastAPI app
│ │ ├── models.py ← Database models
│ │ ├── database.py ← Database setup
│ │ ├── routers/ ← API endpoints
│ │ ├── clients/ ← Firefly III API client
│ │ └── services/ ← Background sync
│ ├── Dockerfile
│ └── pyproject.toml
│
└── frontend/ ← React application
├── src/
│ ├── App.tsx ← Main component
│ ├── pages/ ← Dashboard, Reports
│ ├── components/ ← Charts, Date picker
│ ├── services/ ← API client
│ └── types.ts ← TypeScript types
├── Dockerfile
└── package.json
✨ Features
✅ Dashboard - Key financial metrics at a glance
✅ Reports - Multiple report types with charts
✅ Charts - Pie charts, line charts, comparisons
✅ Flexibility - Custom date ranges and filtering
✅ Sync - Automatic data updates every 30 minutes
✅ Responsive - Works on desktop and mobile
✅ Secure - Token in environment, no hardcoded secrets
🔄 Typical Workflow
-
First Time Setup
- Copy .env.example → .env
- Add your Firefly III API token
- Run init_project.py OR manual setup
- Start the application
-
First Run
- Backend syncs with Firefly III (takes 1-2 minutes)
- Dashboard shows your financial metrics
- Reports available with flexible date ranges
-
Daily Usage
- Access http://localhost:3000
- View dashboard
- Generate custom reports
- Explore spending trends
-
Customization (optional)
- Modify chart colors in components/
- Add new report types
- Change sync intervals
- Deploy to cloud
📊 Technology Stack
Backend: Python, FastAPI, SQLAlchemy, SQLite
Frontend: React, TypeScript, Recharts, Axios
Deployment: Docker, Docker Compose, Nginx
🎓 Learning Resources
- Firefly III API: https://docs.firefly-iii.org/
- FastAPI: https://fastapi.tiangolo.com/
- React: https://react.dev/
- Recharts: https://recharts.org/
❓ FAQ
Q: Do I need to install anything special?
A: Python 3.11+, Node.js 18+, and Docker (for containerization). Python/Node not needed if using Docker.
Q: How do I get my Firefly III API token?
A: Log into Firefly III → Settings → API → Create new token → Copy to .env
Q: Can I run this locally without Docker?
A: Yes! See INSTALLATION.md for Python/Node setup.
Q: Is my data secure?
A: Yes. Token is in .env only, never in code. Data stays local.
Q: Can I deploy to the cloud?
A: Yes! Docker image can run anywhere (AWS, Azure, DigitalOcean, etc.)
Q: What if I have issues?
A: Check INSTALLATION.md for troubleshooting section.
📞 Support
- Check the FAQ section in INSTALLATION.md
- Read the Architecture in ARCHITECTURE.md
- View API docs at http://localhost:8000/docs (when running)
- Review source code in COMPLETE_SOURCE_CODE.md
✅ Ready to Start?
Choose your starting point:
👇 Fastest (Docker)
python init_project.py
cp .env.example .env
# Edit .env with your API token
docker-compose up -d
# Open http://localhost:3000
👇 Detailed (Manual) Read INSTALLATION.md → Copy code from COMPLETE_SOURCE_CODE.md → Follow steps
👇 Learning (Local) Read QUICKSTART.md → Setup locally → Explore API at http://localhost:8000/docs
🎯 Your Next Step
- Pick a documentation file above (QUICKSTART, INSTALLATION, or ARCHITECTURE)
- Read through it (takes 5-10 minutes)
- Follow the setup steps
- Enjoy your analytics dashboard! 🎉
You have everything you need. Let's go! 🚀
Questions? Check the documentation files above—they have comprehensive guides and examples.
Happy analytics! 📊