FargoImport/INDEX.md

# FargoImport - File Index & Navigation

## 📖 Start Here

1. **New to the project?** → Read `QUICKSTART.md` (5 min read)
2. **Want full details?** → Read `README.md` (comprehensive)
3. **Need module reference?** → Check `PROJECT_SUMMARY.md`

---

## 🐍 Python Modules (7 files)

### Core Extraction
- **`wf_debit_extractor.py`** - Extract Wells Fargo payloads from HAR JSON
  - `WellsFargoPayloadExtractor` class
  - Methods: `extract_from_file()`, `extract_from_data()`, `get_objects()`
  - Usage: Extract proprietary JSON wrapped in `/*WellFargoProprietary%...%WellFargoProprietary*/`

### Data Processing
- **`transaction_processor.py`** - Transform raw transactions into structured format
  - `TransactionProcessor` class
  - Methods: `extract_transactions()`
  - Converts amounts to cents, timestamps to datetime, normalizes data

### External Integration
- **`ynab_client.py`** - Connect to YNAB API and fetch transactions
  - `YNABClient` class
  - Methods: `get_transactions_for_days()`, `get_account_balance()`
  - Configuration via `ynab.yml`

### Reconciliation
- **`reconcile.py`** - Compare Wells Fargo and YNAB transactions
  - `reconcile_transactions()` function
  - `main()` CLI entry point
  - Generates `reconciliation_report.json`

### Credit Module
- **`wf_credit_extractor.py`** - Credit extractor module (renamed from `extractor.py`)

### CLI & Examples
- **`main.py`** - Command-line interface for Wells Fargo extraction
  - Args: `--input`, `--output`, `--show-errors`
  - Usage: `python main.py --input posted.dat`

- **`example_usage.py`** - Wells Fargo transaction processing example
  - Demonstrates extraction → processing → JSON output
  - Output: `processed_transactions.json`

- **`ynab_example.py`** - YNAB transaction fetching example
  - Demonstrates YNAB API integration
  - Output: `ynab_transactions.json`

---

## ⚙️ Configuration (1 file)

- **`ynab.yml`** - YNAB API credentials and account mapping
  ```yaml
  ynab:
    - token: "your_ynab_api_token"
      plan_id: "your_budget_id"
      accounts:
          - name: "Credit Card"
            id: "account_uuid"
  ```

---

## 📚 Documentation (4 files)

| File | Purpose | Read Time |
|------|---------|-----------|
| `QUICKSTART.md` | Quick start guide with examples | 5 min |
| `README.md` | Full project documentation | 15 min |
| `PROJECT_SUMMARY.md` | Module reference & architecture | 10 min |
| `YNAB_MODULE.md` | YNAB client detailed docs | 5 min |

---

## 📊 Data Files (4 output files)

These are generated by running the example scripts:

- **`extracted.json`** - Raw Wells Fargo payload objects (from `main.py`)
- **`processed_transactions.json`** - Processed WF transactions (from `example_usage.py`)
  - 179 sample transactions
  - Fields: id, amount_cents, dates (timestamp & datetime), description

- **`ynab_transactions.json`** - YNAB transactions (from `ynab_example.py`)
  - Fetched from YNAB API
  - Fields: id, date, payee, category, amount, account, memo

- **`reconciliation_report.json`** - Comparison report (from `reconcile.py`)
  - Summary of both data sources
  - Totals and transaction counts
  - Full transaction lists

---

## 🎯 Common Tasks

### Extract Wells Fargo Data
```bash
# Display in console
python main.py

# Save to file
python main.py --output extracted.json

# Process transactions
python example_usage.py
```

### Fetch YNAB Data
```bash
python ynab_example.py
```

### Reconcile Both Sources
```bash
python reconcile.py
```

### Programmatic Usage
```python
from wf_debit_extractor import WellsFargoPayloadExtractor
from transaction_processor import TransactionProcessor
from ynab_client import YNABClient

# Wells Fargo
wf = WellsFargoPayloadExtractor()
payloads = wf.extract_from_file("posted.dat")
processor = TransactionProcessor()
wf_txns = processor.extract_transactions(payloads)

# YNAB
ynab = YNABClient()
ynab_txns = ynab.get_transactions_for_days(days=30)

# Access
for txn in wf_txns[:5]:
    print(txn["transaction_description"])
```

---

## 🔍 Module Dependencies

```
posted.dat (input)
    ↓
wf_debit_extractor.py
    ↓
transaction_processor.py
    ↓
example_usage.py → processed_transactions.json

ynab.yml (config)
    ↓
ynab_client.py
    ↓
ynab_example.py → ynab_transactions.json

Both ↓
reconcile.py → reconciliation_report.json
```

---

## ✅ File Status

| Type | Count | Status |
|------|-------|--------|
| Core Modules | 4 | ✅ Tested & Working |
| CLI/Examples | 3 | ✅ Tested & Working |
| Configuration | 1 | ✅ Ready |
| Documentation | 4 | ✅ Complete |
| Data Files | 4 | ✅ Generated |
| **Total** | **16** | **✅ Complete** |

---

## 🚀 Getting Started

1. **Read** `QUICKSTART.md` (2 min)
2. **Update** `ynab.yml` with your API token
3. **Run** `python example_usage.py` (verify WF extraction)
4. **Run** `python ynab_example.py` (verify YNAB connection)
5. **Run** `python reconcile.py` (generate comparison)

---

## 📞 Documentation Map

- Need quick answer? → `QUICKSTART.md`
- How do I use X? → `README.md` 
- What does Y do? → `PROJECT_SUMMARY.md`
- YNAB details? → `YNAB_MODULE.md`
- Code docstrings? → Open the `.py` file

---

## 🔗 Key Entry Points

**CLI Interface:**
- `main.py` - Extract Wells Fargo data from command line

**Programmatic API:**
- `wf_debit_extractor.py` - Wells Fargo extraction
- `transaction_processor.py` - Transaction processing
- `ynab_client.py` - YNAB integration
- `reconcile.py` - Reconciliation

**Examples:**
- `example_usage.py` - Wells Fargo example
- `ynab_example.py` - YNAB example

---

Generated: March 20, 2026