From db6ba2cedc3ec0d7fba2dd41ac669e63bcc55f59 Mon Sep 17 00:00:00 2001
From: andy <andy.conlon@gmail.com>
Date: Tue, 10 Feb 2026 15:16:43 -0500
Subject: [PATCH] docs: update README with setup, usage, and project structure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 71 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 56e9f73..a7f2126 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,73 @@
 # SpendingAnalysis
 
-vibe coded app to intake data from various sources to help analyze my spending habits
\ No newline at end of file
+Desktop app to intake data from various sources and analyze spending habits. Built with Python, PySide6 (Qt), and SQLite.
+
+## Features
+
+- **CSV Import** — drag-and-drop import wizard with configurable column mappings and duplicate detection
+- **Transaction Management** — browse, filter, and categorize transactions inline
+- **Spending Analysis** — trends, breakdowns, and forecasting charts
+- **Recurring Detection** — identify recurring charges across accounts
+- **Cross-Account Transfers** — automatic detection of transfers between accounts
+- **Rule-Based Categorization** — auto-categorize transactions using custom rules
+- **Household Tracking** — manage household members and shared expenses
+- **Dark / Light Themes** — toggle between themes from the sidebar
+
+## Requirements
+
+- Python 3.12+
+
+## Setup
+
+```bash
+# Clone the repo
+git clone https://gitea.conlon.fun/andy/SpendingAnalysis.git
+cd SpendingAnalysis
+
+# Create a virtual environment and install
+python -m venv .venv
+.venv\Scripts\activate      # Windows
+# source .venv/bin/activate  # macOS / Linux
+
+pip install -e .
+```
+
+## Running
+
+```bash
+# Via the installed entry point
+spending-analysis
+
+# Or run the module directly
+python -m src.main
+```
+
+The app stores its SQLite database at `~/.spending_analysis/spending.db`. Default categories are seeded on first launch.
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Project Structure
+
+```
+src/
+├── main.py              # Application entry point
+├── db.py                # SQLAlchemy engine / session setup
+├── seed.py              # Default category seeding
+├── models/              # SQLAlchemy models (account, category, transaction, rule, etc.)
+├── services/            # Business logic (import, categorization, analysis, forecasting)
+└── ui/                  # PySide6 views and themes
+    ├── main_window.py
+    ├── sidebar.py
+    ├── import_view.py
+    ├── transactions_view.py
+    ├── analysis_view.py
+    ├── recurring_view.py
+    ├── settings_view.py
+    └── themes/
+tests/                   # pytest test suite
+```
\ No newline at end of file