# Budget Tracker (Manage · `Src\Marketing` — ad budget)

**Context:** Manage portal · **Routes:** `manage.marketing.budget.*` (`/manage/marketing/budget`, `/plan`, `/daily`, `/summary`, `/moves`, `/guide`) · **Permissions:** `view-marketing` reads every tab; `manage-marketing` is needed for every write, because the `marketing` role is a read-only external specialist · **Nav:** its own **Budget Tracker** entry in *Sales & Marketing* (Operations suite), with the `ads-budget` SectionTabs strip: Tracker · Plan · Daily Data · Daily Summary · Reserve Log · How to use.

Built 2026-11-04 from the team's [Propertylab Ads Budget Plan](https://docs.google.com/spreadsheets/d/1oVQ4OqmNlkMbqoCL5QRLghpznx2ouj9tol3buxRHqB8/edit) workbook. The tabs have the workbook's names and order.

## What it does

Tracks ad spend across Meta, TikTok and Google against an approved budget: for a chosen month, each campaign's budget, spend, pacing, cost per lead and month-end forecast, with totals by channel. Budget can be moved between campaigns or out of a reserve, and every move is logged.

## How it works

- **Data is typed in.** There is no link to Meta, TikTok or Google here: someone adds one Daily Data row per campaign per day. `Source` records where the figures came from, but no sync writes it. `meta_ad_insights` already holds Meta spend per ad per day (see the [Marketing doc](/docs/modules_handbook/manage/meta-ads/marketing/readMe.md)), so filling Meta rows from it is the obvious next step. It needs a rule tying each line to a campaign or ad set, because the two lines of the Meta group campaign are ad sets of one campaign.
- **Nothing derived is stored.** [`AdBudgetTracker`](/app/Services/Marketing/AdBudgetTracker.php) works every figure out on each request, so editing a budget or a day's spend moves everything at once. A total's ratios come from its own sums, never from averaging its rows.
- **One plan at a time.** `AdBudgetPlan::current()` is the plan reaching furthest ahead. There is no screen to create a plan or extend its months yet: **the seeded plan ends in Jan 2027**, and a new plan needs that screen or a migration.
- **The plan arrives by migration** (`seed_ad_budget_plan_nov_2026`), so the page is right after a deploy with no manual step. It skips itself if any plan exists.
- **The month** lives in `?month=2026-11`. The tab strip keeps it through `carry: ['month']` on each tab, so all tabs stay on one month. With no month in the URL, the page shows today's month, held inside the plan.

### The figures

Taken from the workbook's formulas.

| Figure | Rule |
|---|---|
| Active days | Last day of month − the later of (first of month, go-live) + 1, never below 0 |
| Days elapsed | Latest date with **any** Daily Data row in the month − the same start + 1, never below 0. Counts to the latest data rather than today, so a day not typed in yet does not read as underspending |
| Monthly budget | Plan budget + moves in − moves out, for moves dated in that month |
| Budget to date | Monthly budget × days elapsed ÷ active days |
| Pacing | No days elapsed: Not started. No budget to date: No budget. Spend above budget to date by more than the tolerance: Overspending. Below by more than the tolerance: Underspending. Else On track |
| Daily spend needed | Remaining budget (never below 0) ÷ days left |
| Forecast | Spend + average daily spend × days left |
| CPL status | No target: No CPL target. No leads of either kind: Spend, no leads (or No leads yet with no spend). Else CRM CPL if there are CRM leads, otherwise platform CPL, compared with the target |
| Leads expected | Monthly budget ÷ target CPL |

### Where it differs from the workbook

- **Two charts instead of one.** The workbook plots spend and platform leads on two y-axes. Daily Summary gives each its own chart.
- **The workbook's two check rows are gone.** "Spend not matched to a campaign" and "budgets incl. reserve minus plan total" catch typos in free-typed names. Here a campaign is chosen from a list and a move always has both ends, so neither can be non-zero. The Plan tab warns instead if the lines stop adding up to the total budget.
- **Stricter Daily Data.** One row per campaign per day is enforced (the workbook only asks for it), and future dates are refused, because one would stretch days elapsed and turn every campaign to Underspending.
- **Plan rollups are worked out, not hand-listed:** a total per channel; "Registration and search" is every campaign with a target CPL; "Traffic and awareness" is every campaign without one; a group campaign is the lines sharing a `rollup_group`. The workbook's "Google Search" row is left out since the line itself shows it, and TikTok and Google totals are added.
- **A line with spend or moves can't be removed**, nor can the Reserve.

⚠️ A move can take a line below zero. The workbook allows this too, and the Tracker shows a negative reserve in red rather than refusing it.

## Related files

**Backend**
- [`src/Marketing/AdBudgetPlan.php`](/src/Marketing/AdBudgetPlan.php), [`AdBudgetLine.php`](/src/Marketing/AdBudgetLine.php) (channels, pacing and CPL rules), [`AdBudgetLineMonth.php`](/src/Marketing/AdBudgetLineMonth.php), [`AdBudgetEntry.php`](/src/Marketing/AdBudgetEntry.php) (sources), [`AdBudgetMove.php`](/src/Marketing/AdBudgetMove.php)
- `src/Marketing/Repositories/AdBudget{Plan,Line,Entry,Move}Repository.php` + `src/Marketing/Facades/` of the same names
- [`app/Services/Marketing/AdBudgetTracker.php`](/app/Services/Marketing/AdBudgetTracker.php)
- `app/Http/Controllers/Manage/Marketing/AdBudget{,Plan,Lines,Entries,Moves}Controller.php`, `Concerns/AdBudgetProps.php`
- `app/Http/Requests/Manage/Marketing/AdBudget/{Plan,Line,Entry,Move}Request.php`

**Frontend**
- `resources/js/Pages/Manage/Marketing/Budget/{Tracker,Plan,Daily,Summary,Moves,Guide}.vue`
- `resources/js/Pages/Manage/Marketing/Budget/Partials/` — `MonthPicker`, `DailyBarChart`, `PlanFormModal`, `LineFormModal`, `EntryFormModal`, `MoveFormModal`
- [`resources/js/utils/adBudgetFormat.js`](/resources/js/utils/adBudgetFormat.js)
- `Components/SectionTabs.vue` (`ads-budget`, `carry`), `Layouts/ManageLayout.vue` (sidebar entry)

**Migrations**
- `2026_11_04_100001_create_ad_budget_tables.php`, `2026_11_04_100002_seed_ad_budget_plan_nov_2026.php`

**Routes:** `routes/web.php`, `Route::prefix('budget')` inside the marketing group

**Tests:** [`tests/Feature/Marketing/AdBudgetTrackerTest.php`](/tests/Feature/Marketing/AdBudgetTrackerTest.php)
