marketing-app/docs/superpowers/specs/2026-03-15-budget-allocation-redesign.md

Budget Allocation Redesign — Single Source of Truth + CEO Approval Workflow

Date: 2026-03-15 Status: Draft

Problem

The current budget system has two parallel sources of truth:

• Campaign.budget field (set directly on campaigns)
• BudgetEntries table (income/expense records linked to campaigns/projects)

These don't sync. The finance summary uses Campaign.budget for totalCampaignBudget but BudgetEntries for totalReceived (superadmin only). Managers see a completely different totalReceived calculation. There's no validation preventing over-allocation, and no approval workflow for incoming funds.

Design

Budget Hierarchy

Main Budget (sum of approved income BudgetEntries)
  │
  ├─ Expenses (BudgetEntries with type='expense', deducted from main)
  ├─ Campaign allocations (income BudgetEntries with campaign_id set)
  ├─ Project allocations (income BudgetEntries with project_id set)
  │
  └─ Available = Main Budget - expenses - campaign allocations - project allocations
       │
       Campaign "Summer Sale" ($10K allocated)
         ├─ Track "Facebook Ads" ($3K from campaign)
         ├─ Track "Google Ads" ($5K from campaign)
         └─ Campaign Available = $2K

Campaign allocation entries are a subset of income entries — they are income entries that happen to have a campaign_id set. An earmarked CEO-approved income entry counts as both totalReceived and totalCampaignBudget (which is correct — the money enters the system AND is allocated).

Single Source of Truth

BudgetEntries is the only source. Campaign.budget field is deprecated — kept in schema but ignored in all calculations.

All calculations:

• totalReceived = sum of all income BudgetEntries (same for all roles)
• totalExpenses = sum of all expense BudgetEntries
• totalCampaignBudget = sum of income BudgetEntries where campaign_id is set
• totalProjectBudget = sum of income BudgetEntries where project_id is set
• mainAvailable = totalReceived - totalExpenses - totalCampaignBudget - totalProjectBudget
• campaignAvailable(id) = campaign's allocated budget - sum of its tracks' budget_allocated
• remaining = mainAvailable (same thing — no more double-counting tracks)

Validation Rules

Action	Guard	Error message
All amounts	amount > 0	"Amount must be positive"
Create expense entry	mainAvailable >= amount	"Insufficient budget. Available: $X"
Set campaign budget (at creation or edit)	mainAvailable >= amount (or >= increase delta)	"Insufficient budget. Available: $X. Request more funds."
Decrease campaign budget	newBudget >= sum(tracks.budget_allocated)	"Cannot reduce below track allocations ($X assigned to tracks)"
Set project budget	mainAvailable >= amount (or >= increase delta)	"Insufficient budget. Available: $X. Request more funds."
Set track budget_allocated	campaignAvailable >= amount (or >= increase delta)	"Insufficient campaign budget. Available: $X of $Y allocated"
Create income entry	Must go through budget request workflow (superadmin only)	N/A — handled by request workflow

Race condition mitigation: Budget-modifying operations (campaign/project/expense creation, budget changes) acquire an in-memory mutex before reading availability and releasing after the write. Single-server app — no distributed lock needed.

Campaign/Project Deletion

When a campaign or project is deleted:

• All linked BudgetEntries have their campaign_id / project_id set to null
• This returns the allocated funds to the main available balance
• Tracks under the campaign are already deleted by the existing cascade logic

Budget Request Workflow (CEO Approval)

Who can request: Superadmin only. Who approves: CEO — external email address configured in Settings page.

Flow

1. Superadmin opens Finance page → clicks "Request Budget"
2. Fills form: amount, justification note
   Optional: earmarked for specific campaign or project
3. System creates BudgetRequest (status: pending)
4. System generates approval token + public URL (expires in 7 days)
5. System emails CEO: amount, requester name, justification, approve/reject links
   (no internal budget details exposed)

6a. CEO clicks Approve:
    → BudgetRequest.status = 'approved', resolved_at = now
    → Auto-creates income BudgetEntry (amount, source: "CEO Approved — {justification}")
    → If earmarked: BudgetEntry gets campaign_id or project_id
    → Email notification to superadmin: "Your budget request for $X has been approved"

6b. CEO clicks Reject:
    → BudgetRequest.status = 'rejected', resolved_at = now
    → CEO can add a response note
    → Email notification to superadmin: "Your budget request for $X has been rejected"

Idempotent: if CEO clicks approve/reject twice, return 200 with existing result — no duplicate entries.

New Table: BudgetRequests

Column	Type	Description
amount	Decimal	Requested amount (must be > 0)
justification	LongText	Why the money is needed
status	SingleLineText	pending / approved / rejected / cancelled
requested_by_user_id	Number	FK to Users
approval_token	SingleLineText	UUID for public approval URL
token_expires_at	DateTime	Token expiry (7 days from creation)
response_note	LongText	CEO's note on approval/rejection
resolved_at	DateTime	When CEO acted (null while pending)
earmarked_campaign_id	Number	Optional FK — intended campaign
earmarked_project_id	Number	Optional FK — intended project
created_budget_entry_id	Number	FK to the auto-created BudgetEntry (set on approval)

API Endpoints

Method	Path	Auth	Description
GET	/api/budget-requests	Superadmin	List all requests (sorted by CreatedAt desc)
POST	/api/budget-requests	Superadmin	Create new request, sends email to CEO
PATCH	/api/budget-requests/:id/cancel	Superadmin	Cancel a pending request
GET	/api/budget-approval/:token	Public	Get request details for approval page
POST	/api/budget-approval/:token/respond	Public	Approve or reject (body: `{ action: 'approve'

Public Approval Page: /approve-budget/:token

Minimal page showing:

• Requested amount
• Requester name
• Justification note
• Earmarked for (campaign/project name, if set)
• Two buttons: Approve / Reject
• Optional text field for response note
• States: loading, active, success, already-handled, expired

Same pattern as existing public review pages (PublicReview.jsx, PublicPostReview.jsx).

Token validation: check token_expires_at > now and status === 'pending'. Expired tokens show "This request has expired" with no action buttons.

Settings: CEO Email

Add to Settings page (superadmin only):

• Field: "CEO / Budget Approver Email"
• Stored in AppSettings table (key-value: { key: 'ceo_email', value: 'ceo@company.com' })

AppSettings table schema:

Column	Type	Description
key	SingleLineText	Setting key (unique)
value	LongText	Setting value

Add to REQUIRED_TABLES. Read via GET /api/settings/:key (superadmin), write via PATCH /api/settings/:key (superadmin).

Finance Page Changes

Add a "Budget Requests" section to the Finance page:

• Shows all requests with status badge (pending/approved/rejected/cancelled)
• Pending requests show a subtle banner at top: "1 budget request pending CEO approval"
• Each row: amount, justification (truncated), status, date, earmarked for, resolved_at
• Superadmin sees "Request Budget" button in the page header

Campaign Creation Change

When creating/editing a campaign with a budget:

1. Acquire budget mutex
2. Server calculates mainAvailable
3. If budget > mainAvailable: return 400 with { error: 'Insufficient budget', available: mainAvailable }
4. If OK: create campaign, then auto-create BudgetEntry (type=income, campaign_id=new campaign ID, amount=budget)
5. Campaign.budget field is still written for backward compat but NOT used in calculations
6. Release mutex

When increasing a campaign's budget:

• Delta = newBudget - currentAllocated (where currentAllocated = sum of income BudgetEntries with this campaign_id)
• Acquire mutex, check mainAvailable >= delta, update BudgetEntry amount, release

When decreasing a campaign's budget:

• Check newBudget >= sum(tracks.budget_allocated for this campaign)
• If not: return 400 "Cannot reduce below track allocations"
• Update BudgetEntry amount (freed funds return to main automatically)

Track Creation/Edit Change

When creating/editing a track with budget_allocated:

1. Calculate campaignAllocated = sum of income BudgetEntries with this campaign_id
2. Calculate tracksTotalAllocated = sum of all tracks' budget_allocated for this campaign (excluding current track if editing)
3. campaignAvailable = campaignAllocated - tracksTotalAllocated
4. If budget_allocated > campaignAvailable: return 400
5. If OK: save normally

Finance Summary Endpoint Fix

GET /api/finance/summary — rewrite calculation:

// Single source of truth — BudgetEntries only
const incomeEntries = budgetEntries.filter(e => (e.type || 'income') === 'income');
const expenseEntries = budgetEntries.filter(e => e.type === 'expense');

const totalReceived = incomeEntries.reduce((s, e) => s + (e.amount || 0), 0); // SAME for all roles
const totalExpenses = expenseEntries.reduce((s, e) => s + (e.amount || 0), 0);

const totalCampaignBudget = incomeEntries
  .filter(e => e.campaign_id)
  .reduce((s, e) => s + (e.amount || 0), 0); // FROM ENTRIES, not Campaign.budget

const totalProjectBudget = incomeEntries
  .filter(e => e.project_id)
  .reduce((s, e) => s + (e.amount || 0), 0);

const mainAvailable = totalReceived - totalExpenses - totalCampaignBudget - totalProjectBudget;

// Track spending stays within campaign allocation — not subtracted from main
const remaining = mainAvailable; // Simple. No double-counting.

Migration

Existing data:

1. For each campaign with budget > 0 that has NO corresponding income BudgetEntry with that campaign_id: auto-create an income BudgetEntry linked to that campaign
2. Skip campaigns with budget = 0 or budget = null
3. Log migrations to console for audit
4. Run once on server startup (idempotent — skip if matching entry already exists)

Email Templates

Budget request email to CEO:

• Subject: Rawaj — Budget Request: $X
• Header: Rawaj branded (dark forest #0a1f1c)
• Body: "{requester} is requesting $X. Justification: {note}"
• CTA: "Review Request" button → public approval page
• No internal budget details

Approval/rejection notification to superadmin:

• Subject: Rawaj — Budget Request Approved/Rejected: $X
• Body: result + CEO's response note if any

Out of Scope

• Multi-currency support
• Budget periods/fiscal years
• Partial approval (CEO can't approve a different amount)
• Delegation (CEO can't forward approval to someone else)
• Audit log (beyond the BudgetRequests table itself)
• Currency precision (uses NocoDB Decimal as-is)