# Finance Module Walkthrough

This guide outlines the end‑to‑end workflow for importing a bank statement and posting the
resulting transactions. The APIs are part of the PHP backend and follow the
MVC structure documented in `AGENTS.md`.

## 1. Upload a Bank Statement

Use `POST /api/gltransactions/importStatement` with a multipart form containing
`statement` (CSV or XLSX file) and `account_id` for the bank account.
The service parses the file and attempts to match each line against existing
general ledger entries.

```bash
curl -b cookie.txt -F "statement=@bank.csv" \
     -F "account_id=1" \
     http://localhost/api/gltransactions/importStatement
```

The response contains `matched` transactions and `groups` of unmatched rows
with AI‑suggested account codes.

## 2. Review AI Suggestions

Unmatched rows are grouped by a normalized description. Each group includes the
AI suggested account code so similar descriptions can be reviewed together. The
front‑end module `Reconciliation.js` renders these groups and allows the user to
enter the final account ID for posting.

## 3. Confirm or Adjust Splits

For each group the user can edit the proposed account and post the entries. The
module sends a request to `POST /api/gltransactions/postBatch` containing the
bank account line and the counter‑account line for every statement row.

## 4. Posting to GL/AP/AR

The `GLTransactionsController` uses `ModelHandler` which has child definitions
for `ap_transactions` and `ar_transactions`. When transactions are inserted with
those child arrays, rows are automatically created in the AP or AR tables. This
means the same API call posts data to all three tables.

## 5. Automatic Report Updates

Reports read directly from the GL, AP and AR tables using the `DataLoader`
utility. Once the transactions are inserted they appear immediately in the
financial reports without further action.