231 lines
6.2 KiB
Markdown
231 lines
6.2 KiB
Markdown
# 🚀 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
|
||
```bash
|
||
# Automated (recommended)
|
||
python init_project.py
|
||
|
||
# OR manually: Copy code from COMPLETE_SOURCE_CODE.md
|
||
```
|
||
|
||
### 2️⃣ Configure
|
||
```bash
|
||
cp .env.example .env
|
||
# Edit .env and add your Firefly III API token
|
||
```
|
||
|
||
### 3️⃣ Run
|
||
```bash
|
||
# 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
|
||
|
||
1. **First Time Setup**
|
||
- Copy .env.example → .env
|
||
- Add your Firefly III API token
|
||
- Run init_project.py OR manual setup
|
||
- Start the application
|
||
|
||
2. **First Run**
|
||
- Backend syncs with Firefly III (takes 1-2 minutes)
|
||
- Dashboard shows your financial metrics
|
||
- Reports available with flexible date ranges
|
||
|
||
3. **Daily Usage**
|
||
- Access http://localhost:3000
|
||
- View dashboard
|
||
- Generate custom reports
|
||
- Explore spending trends
|
||
|
||
4. **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)**
|
||
```bash
|
||
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
|
||
|
||
1. **Pick a documentation file above** (QUICKSTART, INSTALLATION, or ARCHITECTURE)
|
||
2. **Read through it** (takes 5-10 minutes)
|
||
3. **Follow the setup steps**
|
||
4. **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! 📊
|