From 7a99414a634c1ce857f188b7898a08281fab6071 Mon Sep 17 00:00:00 2001
From: nabeel <nabeel.moeen@gmail.com>
Date: Wed, 27 May 2026 14:02:54 +1000
Subject: [PATCH] 2

---
 RUN_APP.md          | 152 ++++++++++++++++++++++++++++++++++++++++++++
 create_data_dir.bat |   5 ++
 2 files changed, 157 insertions(+)
 create mode 100644 RUN_APP.md
 create mode 100644 create_data_dir.bat

diff --git a/RUN_APP.md b/RUN_APP.md
new file mode 100644
index 0000000..a58a03b
--- /dev/null
+++ b/RUN_APP.md
@@ -0,0 +1,152 @@
+# 🚀 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.
diff --git a/create_data_dir.bat b/create_data_dir.bat
new file mode 100644
index 0000000..9621d08
--- /dev/null
+++ b/create_data_dir.bat
@@ -0,0 +1,5 @@
+@echo off
+cd /d C:\Users\Nabeel\Nextcloud\Projects\firefly_reports
+mkdir data
+echo ✓ Created data directory
+pause