# 🚀 How to Run the Firefly III Analytics App

## Quick Start (3 Steps)

### Step 1: Set Up Environment Variables
Create/edit `.env` file in the project root:
```
FIREFLY_URL=https://firefly.scsimedia.duckdns.org
FIREFLY_API_TOKEN=your_api_token_from_firefly_iii
DATABASE_URL=sqlite:///./data/app.db
SYNC_INTERVAL_MINUTES=30
```

### Step 2: Start Backend (Terminal 1)
```bash
cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

You should see:
```
INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete
```

### Step 3: Start Frontend (Terminal 2)
```bash
cd frontend
npm start
```

Browser will auto-open at `http://localhost:3000`

---

## ✅ Verify It's Running

- **Backend API**: http://localhost:8000
- **Health check**: http://localhost:8000/health (should return `{"status": "healthy"}`)
- **Frontend**: http://localhost:3000

---

## 🐳 Option 2: Using Docker Compose (Easier)

If you have Docker installed:

```bash
# From project root
docker-compose up --build
```

This starts:
- Backend on http://localhost:8000
- Frontend on http://localhost:3000
- SQLite database at `./data/app.db`

Stop with: `Ctrl+C`

---

## 🔧 Troubleshooting

### Backend won't start - "ModuleNotFoundError: No module named 'app'"
```bash
cd backend
python -m uvicorn app.main:app --reload
```
Make sure you're IN the backend folder when running the command.

### "Address already in use" on port 8000
Change the port:
```bash
python -m uvicorn app.main:app --reload --port 8001
```

### Frontend won't start - "npm not found"
Install Node.js from https://nodejs.org (includes npm)

### "FIREFLY_API_TOKEN not set"
Make sure `.env` file exists in the project root with your token.

---

## 📋 What Happens When You Start

1. **Backend initializes**:
   - Connects to SQLite database
   - Creates tables if needed
   - Starts sync scheduler (runs every 30 min)
   - Starts FastAPI server

2. **Frontend starts**:
   - React dev server starts
   - Browser opens to http://localhost:3000
   - Dashboard loads with data from backend

3. **Data Sync**:
   - Background job fetches from Firefly III every 30 minutes
   - Data cached locally in SQLite
   - API endpoints return cached data

---

## 🎯 Default Ports

| Service | Port | URL |
|---------|------|-----|
| Backend | 8000 | http://localhost:8000 |
| Frontend | 3000 | http://localhost:3000 |
| Database | - | ./data/app.db (SQLite file) |

---

## 💡 Development Tips

### Run Backend with Hot Reload
```bash
cd backend
python -m uvicorn app.main:app --reload
```

### Run Frontend with Hot Reload
```bash
cd frontend
npm start
```

### View API Documentation
Open: http://localhost:8000/docs (Swagger UI)

### Clear Database and Restart
```bash
# Stop the servers (Ctrl+C)
rm data/app.db
# Restart - it will recreate the database
```

---

## 🔒 Security Notes

- Never commit `.env` to git (it's in `.gitignore`)
- Keep your Firefly III API token secret
- In production, use environment variables, not .env files
- See `ARCHITECTURE.md` for production deployment guide

---

**Your app is now running!** 🎉

Go to http://localhost:3000 and start viewing your financial analytics.