# Modules

## Overview

Seven independent modules, all scoped per user. The only cross-reference is `Investment ↔ Record.linkedInvestment`.

```mermaid
flowchart TB
    subgraph Money["Money Tracking"]
        Income[Income Log]
        Personal[Personal Expenses]
        Business[Business Ledger]
    end

    subgraph Planning["Planning & Tracking"]
        Investments[Investment Tracker]
        Goals[Savings Goals]
        Debts[Debt Balance]
    end

    subgraph Maintenance["Project Maintenance"]
        Projects[Projects Tracker]
    end

    Income --> Dashboard[Dashboard]
    Personal --> Dashboard
    Business --> Dashboard
    Investments --> Dashboard
    Goals --> Dashboard
    Debts --> Dashboard
    Projects --> Dashboard

    Business -.->|linkedInvestment| Investments
```

---

## 1. Income Log

Tracks money received. Uses the same Record model, filtered by `type = revenue`.

### Fields

| Field | Type | Notes |
|---|---|---|
| `date` | Date | When received |
| `name` | String | e.g. "salary", "side income" |
| `amount` | Number | Positive integer |
| `ledger` | Personal / Business | Which pot it lands in |
| `categoryId` | ObjectId | Ref → Category (revenue type) |

### Behavior

- Revenue records appear in the dashboard as positive numbers
- Personal revenue feeds into Personal balance
- Business revenue feeds into Business net P&L
- The generic "Revenue" category is **Personal only** — Business gets explicit categories (Puppy Sale, Food Resale)

---

## 2. Personal Expenses

Tracks personal must-pays and discretionary spend. Uses the Record model with `ledger = Personal`.

### Fields

| Field | Type | Notes |
|---|---|---|
| `date` | Date | Transaction date |
| `category` | String | Food, Home, Transportation, etc. |
| `description` | String | What was purchased |
| `amount` | Number | Stored positive |
| `mustPay` | Boolean | Non-negotiable (rent, food, statutory) |
| `recurring` | Boolean | Monthly repeat flag (visual only in v1) |

### Dashboard Split

```mermaid
flowchart LR
    PE[Personal Expenses] --> MP[Must-Pay]
    PE --> DC[Discretionary]

    MP --> |"Rent, Food, Statutory"| MPV[Must-Pay Total]
    DC --> |"Shopping, Entertainment"| DCV[Discretionary Total]
```

### Recurring Flag

In v1, `recurring` is a **visual flag only** — it shows an icon on the record but does not auto-generate next month's entry. Auto-generation is deferred to v2.

---

## 3. Business Ledger ("Dog Venture")

Separate cost/revenue tracking. Uses Record with `ledger = Business`.

### Fields

| Field | Type | Notes |
|---|---|---|
| `date` | Date | Transaction date |
| `type` | Cost / Revenue | Mapped to Record `type` field |
| `category` | String | Dog Food, Deworming, Puppy Sale, etc. |
| `description` | String | What was bought/sold |
| `amount` | Number | Positive integer |
| `linkedInvestment` | ObjectId (optional) | Ties cost to an Investment entry |

### Business Categories

| Category | Type | Icon |
|---|---|---|
| Dog Food | expense | `fas fa-bone` |
| Deworming | expense | `fas fa-pills` |
| Pesticide | expense | `fas fa-bug` |
| Puppy Sale | revenue | `fas fa-dog` |
| Food Resale | revenue | `fas fa-store` |

### P&L Calculation

```
Business Net = Total Business Revenue - |Total Business Cost|
```

The Business column on the dashboard shows this as a single "Net" number.

---

## 4. Investment Tracker

Tracks specific investments and whether they're paying off.

### Fields

| Field | Type | Notes |
|---|---|---|
| `name` | String | e.g. "Freezer", "Breeding Pair" |
| `cost` | Number | Initial investment amount |
| `dateAcquired` | Date | Purchase date |
| `expectedReturnType` | Revenue / CostSavings / Both | What the investment produces |
| `returnToDate` | Number | Running total of returns |
| `status` | Recouping / BreakEven / Profitable | Derived from cost vs. returns |
| `notes` | String | Free-form |

### Return Types

| Type | Meaning | Example |
|---|---|---|
| Revenue | Generates direct income | Breeding pair → puppy sales |
| CostSavings | Reduces ongoing costs | Freezer → bulk buying savings |
| Both | Generates income AND reduces costs | Freezer → resale revenue + bulk savings |

### Status Logic

```mermaid
flowchart TD
    A[returnToDate / cost] --> B{Ratio}
    B -->|"< 50%"| C[Recouping]
    B -->|"50-99%"| D[BreakEven]
    B -->|"≥ 100%"| E[Profitable]
```

### Cross-Reference

Business costs can optionally link to an Investment via `Record.linkedInvestment → Investment._id`. This allows attributing specific expenses to the investment they're part of (e.g. dog food costs linked to the Breeding Pair investment).

---

## 5. Goals (Tiered)

Savings goals ranked by priority.

### Fields

| Field | Type | Notes |
|---|---|---|
| `name` | String | e.g. "Emergency Fund" |
| `targetAmount` | Number | Goal amount |
| `savedAmount` | Number | Current progress |
| `tier` | MustFund / ActivelySaving / Someday | Priority ranking |
| `targetDate` | Date (optional) | Deadline |

### Tier System

```mermaid
flowchart TD
    MF[Must Fund] --> |"Non-negotiable savings"| Red["Red — Urgent"]
    AS[Actively Saving] --> |"Currently contributing"| Blue["Blue — In Progress"]
    SD[Someday] --> |"Aspirational"| Gray["Gray — No Pressure"]
```

### Progress Calculation

```
percent = (savedAmount / targetAmount) × 100
```

Displayed as a progress bar on both the list page and dashboard summary.

---

## 6. Debt Balance (HELB)

A passive, always-visible balance. Not a monthly must-pay, no urgency styling.

### Fields

| Field | Type | Notes |
|---|---|---|
| `name` | String | e.g. "HELB" |
| `totalOwed` | Number | Original debt |
| `amountPaid` | Number | Running total paid |
| `status` | NotRepaying / ActivelyRepaying | Flips when income allows |

### Computed Field

```
remainingBalance = totalOwed - amountPaid
```

Never stored — computed on every read.

### Status Behavior

- **NotRepaying**: Default. Shown quietly on dashboard, no red/warning styling.
- **ActivelyRepaying**: Flips once income allows. Still quiet — no alerts, no due-date pressure.

---

## 7. Projects Tracker

A deliberately simple maintenance list for software systems being run.

### Fields

| Field | Type | Notes |
|---|---|---|
| `name` | String | Project name |
| `status` | Active / Maintenance / Paused / Archived | Current state |
| `lastTouched` | Date | Last activity |
| `nextStep` | String | What to do next |
| `notes` | String | Free-form scratchpad |

### Dashboard Sort

Default sort: `lastTouched` ascending. This surfaces stale projects first — the ones that haven't been touched in the longest time appear at the top.

### Status Meanings

| Status | Meaning |
|---|---|
| Active | Currently being worked on |
| Maintenance | Keeping alive, occasional fixes |
| Paused | On hold, will return |
| Archived | Done or abandoned |

---

## Module Independence

```mermaid
flowchart TB
    Record[Record] -->|linkedInvestment| Investment[Investment]
    
    Record -.- |"no link"| Debt[Debt]
    Record -.- |"no link"| Goal[Goal]
    Record -.- |"no link"| Project[Project]
    
    Debt --- User[User]
    Goal --- User
    Project --- User
    Investment --- User
    Record --- User
```

**Design principle:** no relational sprawl. Each module is self-contained except for the single Investment ↔ Record cross-reference. This keeps the codebase simple and the data model easy to reason about.