Ledgerly/SPECS.md

# Ledgerly — Application Specification

Ledgerly is a single-user, command-line personal finance tracker. It records
income and expense transactions against named categories, keeps a monthly
budget per expense category, and reports monthly totals, per-category totals,
and budget status. All state lives in one SQLite file.

Status: **active — this file is the source of truth for the application.**

---

## 1. Goals

- G1 Zero runtime dependencies beyond the Python standard library.
- G2 All money math exact: integer cents; no floats in storage or domain logic.
- G3 Plain-text output that is stable and script-friendly.
- G4 Domain logic fully tested: ≥ 95% line coverage of `ledgerly/` application code.

## 2. Non-goals (v0.1)

- Web UI, authentication, multi-user.
- Multi-currency, taxes, transfers between accounts.
- Recurring transactions, reminders.

## 3. Tech stack

| Concern     | Choice                                    |
|-------------|-------------------------------------------|
| Language    | Python 3.13 (supports 3.10+)              |
| Storage     | SQLite (≥ 3.40) via stdlib `sqlite3`      |
| CLI         | stdlib `argparse` (subcommands)           |
| Tests       | pytest 8.x                                |
| Coverage    | coverage.py 7.x, gate at 95%              |
| Packaging   | PEP 621 `pyproject.toml`, no install req. |

## 4. Domain model

### 4.1 Entities

- **Category** — `name` (unique, case-insensitive, ≤ 50 chars), `kind` ∈ {income, expense}.
- **Transaction** — `id` (auto), `amount` (> 0, integer cents), `category` (must exist),
  `date` (YYYY-MM-DD, 2000-01-01…2100-12-31), `note` (≤ 200 chars, optional).
- **Budget** — monthly limit for one expense category: `category` + `amount` (> 0).
  A budget is defined once and applies to every month.

### 4.2 Value objects / read models

- **Money** — immutable, total-ordered, stored as signed integer cents.
  `Money.parse()` accepts decimal input (≤ 2 decimals, half-up rounding).
  Formats as `$1,234.56`; negatives as `-$1.00`.
- **Month** — `(year, month)` with year in 2000…2100; `Month.from_str("YYYY-MM")`;
  exposes `first_day`, `last_day`, `range`.
- **MonthSummary** — month, income, expenses, `net` (= income − expenses, may be negative).
- **CategoryTotal** — category, kind, total for a period.
- **BudgetLine** — category, budget, spent; `remaining` (may be negative), `is_over`.

### 4.3 Rules

| ID  | Rule |
|-----|------|
| R1  | Transaction amount must be > 0. |
| R2  | Budget amount must be > 0. |
| R3  | Amounts have at most 2 decimal places (parsed, half-up rounded). |
| R4  | Dates are valid ISO, between 2000-01-01 and 2100-12-31. |
| R5  | Category names: non-empty, ≤ 50 chars, unique case-insensitively. |
| R6  | Category kind ∈ {income, expense}. |
| R7  | Budgets may only attach to expense categories. |
| R8  | Transactions must reference an existing category. |
| R9  | A category that has transactions or a budget cannot be deleted. |
| R10 | Note ≤ 200 chars; blank notes are stored as NULL. |
| R11 | Budget report lists every budgeted expense category for the month, plus any expense category with spending but no budget (budget shown as $0). |
| R12 | Deleting a transaction requires its id; unknown id is an error. |

## 5. Architecture

Principles: SOLID, KISS, CQRS, Law of Demeter.

- **DIP / SRP** — services depend on a `Repository` protocol, not on SQLite.
  One module per concern:
  - `money.py` — Money value object and parsing.
  - `models.py` — entities, value objects, input sanitizers (name/note/date/month).
  - `db.py` — schema DDL and connection factory.
  - `repository.py` — `Repository` protocol + `SqliteRepository` (only module that speaks SQL).
  - `services/ledger.py` — category & transaction commands/queries.
  - `services/budgets.py` — budget commands/queries.
  - `services/reports.py` — read-only reporting queries.
  - `cli.py` — argument parsing, dispatch, presentation (strings in, strings out).
  - `__main__.py` — process entry point (`python -m ledgerly`).
- **CQRS** — every service method is either a command (state change) or a query
  (read-only). Commands never return read-model aggregates; queries never mutate.
- **Law of Demeter** — call chain is strictly CLI → service → repository;
  each layer sees only the next.
- **Errors** — `LedgerlyError` base with `ValidationError`, `NotFoundError`,
  `ConflictError`. The CLI maps them to exit codes; no string matching.

## 6. Persistence

SQLite file with foreign keys enforced. Default location `~/.ledgerly/ledgerly.db`;
overridable with `--db PATH` (global option). Tests use `:memory:` or a temp file.

```sql
PRAGMA foreign_keys = ON;

CREATE TABLE IF NOT EXISTS categories (
    id   INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL UNIQUE COLLATE NOCASE,
    kind TEXT NOT NULL CHECK (kind IN ('income', 'expense'))
);

CREATE TABLE IF NOT EXISTS transactions (
    id           INTEGER PRIMARY KEY AUTOINCREMENT,
    amount_cents INTEGER NOT NULL CHECK (amount_cents > 0),
    category_id  INTEGER NOT NULL REFERENCES categories (id),
    date         TEXT    NOT NULL,                 -- YYYY-MM-DD
    note         TEXT
);
CREATE INDEX IF NOT EXISTS idx_tx_date     ON transactions (date);
CREATE INDEX IF NOT EXISTS idx_tx_category ON transactions (category_id);

CREATE TABLE IF NOT EXISTS budgets (
    category_id  INTEGER PRIMARY KEY REFERENCES categories (id),
    amount_cents INTEGER NOT NULL CHECK (amount_cents > 0)
);

CREATE TABLE IF NOT EXISTS meta (
    key   TEXT PRIMARY KEY,
    value TEXT
);
```

First run seeds (exactly once — a `meta` marker row records that seeding
happened, so deleted categories never resurrect):
income `Salary`, `Other Income`; expense `Rent`, `Groceries`, `Utilities`,
`Dining Out`, `Transport`, `Entertainment`, `Health`, `Savings`, `Other`.

## 7. CLI reference

Global options: `--db PATH` (default `~/.ledgerly/ledgerly.db`), `--version`.

| Command              | Options                                                             | Effect |
|----------------------|---------------------------------------------------------------------|--------|
| `add AMOUNT`         | `--category NAME` (req), `--date YYYY-MM-DD` (default today), `--note TEXT` | record a transaction (R1, R3, R8, R10) |
| `list`               | `--month YYYY-MM` (default current), `--category NAME`, `--all`     | list transactions, newest first (R5, R8) |
| `delete ID`          | —                                                                   | delete a transaction (R12) |
| `categories`         | —                                                                   | list categories |
| `category-add NAME`  | `--type income\|expense` (req)                                      | add a category (R5, R6) |
| `category-del NAME`  | —                                                                   | delete an unused category (R9) |
| `budget-set CATEGORY AMOUNT` | —                                                  | set/replace the monthly budget (R2, R7) |
| `budget-del CATEGORY`| —                                                                   | remove a budget |
| `budget-show`        | `--month YYYY-MM` (default current)                                 | budgets vs. spending for the month (R11) |
| `report`             | `--month YYYY-MM` (default current)                                 | monthly summary + category breakdown |

Exit codes: **0** success · **1** domain error (`error: …` on stderr) ·
**2** usage/parsing error (argparse).

## 8. Testing & coverage

- pytest; one test module per source module.
- Persistence exercised through `SqliteRepository` on `:memory:`.
- Services tested against the real repository (the protocol is the contract;
  the real thing is the fixture).
- CLI tested by calling `main(argv, db_path=tmp)` and asserting captured
  stdout/stderr and exit codes.
- Gate: `coverage run -m pytest` with `[tool.coverage.report] fail_under = 95`
  over `ledgerly/`. Excluded: `ledgerly/__main__.py` (2-line entry tool file);
  `tests/` and stdlib are not application code.

## 9. Milestones

- M1 — this spec.
- M2 — core value objects (`money.py`, `models.py`) + errors.
- M3 — schema + repository (`db.py`, `repository.py`).
- M4 — services (`services/ledger.py`, `services/budgets.py`, `services/reports.py`).
- M5 — CLI, entry point, `pyproject.toml`, README.
- M6 — test suite; coverage gate green.

## 10. Decisions log

- D1 Integer cents over floats: exactness, SQL CHECK constraints, no drift.
- D2 Stdlib-only runtime: KISS, zero-install, nothing to pin.
- D3 Budgets are per-category and month-agnostic (apply every month) —
  simplest mental model; month is a reporting axis, not a budget axis (R11).
- D4 Month is the only time filter in v0.1 (KISS).
- D5 Category names are case-insensitively unique; stored casing is preserved
  (UNIQUE COLLATE NOCASE + `COLLATE NOCASE` lookups).
- D6 Unbudgeted spending surfaces with budget $0 (R11) — no silent leaks.
- D7 CLI handlers return strings; `main()` is the only place that prints
  (keeps the CLI trivially testable).