initial commit

1 files changed, 147 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3845713
--- /dev/null
+++ b/README.md
@@ -0,0 +1,147 @@
+# CashFlo - Cash Flow Projection & Reconciliation App
+
+A Qt-based cash flow projection application with SQLite backend for managing financial transactions and forecasting future cash flow.
+
+## Features
+
+### Core Functionality
+- **Transaction Management**: Add, edit, and delete transactions with date, amount, account, and description
+- **Transaction Types**: 
+  - **Estimated**: Future projections based on recurring rules
+  - **Actual**: Confirmed transactions after reconciliation
+- **Recurring Rules**: Define repeating transactions with various schedules:
+  - Daily
+  - Weekly (specify day of week)
+  - Bi-Weekly (every 2 weeks)
+  - Monthly (specify day of month)
+  - Yearly
+- **Projection Generation**: Automatically create estimated future transactions from recurring rules
+- **Reconciliation**: Convert estimated transactions to actuals with updated amounts
+- **Date Range Filtering**: View transactions within specific date ranges
+- **Running Balance**: See projected balance based on selected date range
+
+## Building the Application
+
+### Prerequisites
+- Qt 6 (with Widgets and SQL modules)
+- C++17 compiler
+- SQLite (included with Qt)
+
+### Build Instructions
+```bash
+cd /home/calvin/CashFlo
+qmake6
+make
+./CashFlo
+```
+
+## Usage Guide
+
+### 1. Setting Up Recurring Rules
+1. Click the **"Recurring Rules"** tab
+2. Click **"Add Recurring Rule"**
+3. Enter details:
+   - Name (e.g., "Rent", "Salary")
+   - Frequency (Daily, Weekly, Monthly, etc.)
+   - Start Date
+   - Number of occurrences (-1 for indefinite)
+   - Amount (negative for expenses, positive for income)
+   - Account name
+   - Description
+
+**Examples:**
+- **Monthly Rent**: Frequency: Monthly, Day: 1, Amount: -2350.00, Occurrences: 12
+- **Bi-weekly Salary**: Frequency: Bi-Weekly, Day: Friday (5), Amount: 3500.00
+- **Weekly Grocery**: Frequency: Weekly, Day: Saturday (6), Amount: -250.00
+
+### 2. Generating Projections
+1. Set your desired date range (From/To dates)
+2. Click **"Generate Projection"**
+3. The system will create estimated transactions based on your recurring rules
+4. View all projected transactions in the Transactions tab
+   - Yellow rows = Estimated transactions
+   - Green rows = Actual transactions
+
+### 3. Adding Manual Transactions
+1. Go to the **"Transactions"** tab
+2. Click **"Add Transaction"**
+3. Enter date, amount, account, description, and type (Estimated/Actual)
+
+### 4. Reconciliation (Closing the Books)
+When an estimated transaction occurs and you want to record the actual amount:
+1. Select the estimated transaction in the table
+2. Click **"Reconcile (Est → Actual)"**
+3. Enter the actual amount (can be different from estimate)
+4. The transaction is now marked as "Actual" and the amount is updated
+
+### 5. Viewing Cash Flow
+- The **"Projected Balance"** shows the cumulative balance for the selected date range
+- Sort transactions by clicking column headers
+- Adjust date range to see different projection periods
+
+## Database Schema
+
+### Transactions Table
+```sql
+id INTEGER PRIMARY KEY
+date TEXT (ISO format)
+amount REAL (negative=expense, positive=income)
+account TEXT
+description TEXT
+type TEXT ('estimated' or 'actual')
+recurring_id INTEGER (links to recurring rule, -1 if manual)
+```
+
+### Recurring Rules Table
+```sql
+id INTEGER PRIMARY KEY
+name TEXT
+frequency TEXT ('daily', 'weekly', 'biweekly', 'monthly', 'yearly')
+start_date TEXT
+end_date TEXT (optional)
+amount REAL
+account TEXT
+description TEXT
+day_of_week INTEGER (1=Mon, 7=Sun, -1 if not applicable)
+day_of_month INTEGER (1-31, -1 if not applicable)
+occurrences INTEGER (-1 for indefinite)
+```
+
+## Database Location
+The SQLite database is stored at:
+- Linux: `~/.local/share/CashFlo/cashflow.db`
+- Created automatically on first run
+
+## Use Cases
+
+### Example: 3-Month Budget Planning
+1. Add recurring rules for:
+   - Rent (-$2,350/month on 1st)
+   - Salary (+$7,000/month, bi-weekly)
+   - Utilities (-$150/month on 15th)
+   - Groceries (-$250/week on Saturdays)
+2. Set date range: Jan 1 - Mar 31
+3. Generate projection
+4. View projected balance to see cash flow over 3 months
+
+### Example: Reconciling Actual Expenses
+1. At end of month, review estimated transactions
+2. Select each estimate (e.g., "Grocery estimated $250")
+3. Reconcile with actual amount (e.g., actual was $267.43)
+4. Transaction converts to "Actual" with correct amount
+5. Projected balance updates to reflect reality
+
+## Tips
+- Use negative amounts for expenses (outflows)
+- Use positive amounts for income (inflows)
+- Generate projections after adding/updating recurring rules
+- Reconcile regularly to keep projections accurate
+- Use descriptive account names (e.g., "Checking", "Savings", "Credit Card")
+
+## Future Enhancements (Potential)
+- Multiple accounts with transfers
+- Categories and reporting
+- CSV import/export
+- Charts and visualizations
+- Budget vs actual comparison
+- Search and filtering