> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets

> Create, view, and manage organization budgets with line items, approval history, variance analysis, and forecast tabs.

The `/fa/budgets` route redirects to the Budgets & Forecasts hub at `/fa/budgeting?tab=budgets`. Route: `/fa/budgets`

## Overview

`/fa/budgets` is a legacy route that now redirects to `/fa/budgeting?tab=budgets` (the Budgets & Forecasts hub, Budgets tab). The hub displays the budget list, active-alert summary card, and pending approvals. Users can create a new budget (launches the Budget Wizard) or navigate to an existing budget's detail page.

See [Budgets & Forecasts](/fa/budgets-forecasts) for the hub documentation.

## Who it's for

Access follows your organization's role and module configuration. Creating budgets requires permission `fa.budgets.create`.

## Before you start

* Any existing bookmarks or links to `/fa/budgets` will land on the Budgets tab of the hub automatically.
* Know the budget name, fiscal period, and version type (`annual`, `revised`, `forecast`, etc.) before creating.
* Have GL accounts, funds, departments, and programs ready for line-item coding.

## Steps

<Steps>
  <Step title="Navigate to Budgets">
    Visit `/fa/budgets` — the browser is redirected to `/fa/budgeting?tab=budgets`.
  </Step>

  <Step title="Create a budget">
    Click **Create Budget** to open the Budget dialog, or use the wizard at `/fa/budgets/wizard`.
  </Step>

  <Step title="Open a budget">
    Click a budget row to navigate to `/fa/budgets/:id`.
  </Step>
</Steps>

## Viewing a budget

Selecting a budget opens its detail view at `/fa/budgets/:id`. Five URL-synced tabs are available: Overview, Lines, Approval, Variance, and Forecast. The Overview tab shows a `BudgetSummaryCard`. The Lines tab displays `BudgetLineGrid` with an option to add new lines via `BudgetLineForm`. The Approval tab shows `BudgetApprovalHistory`. Active alerts are shown via `BudgetAlertCard`. When the budget status is `pending_approval`, Approve and Reject buttons open `BudgetApprovalDialog`. A `BudgetActionsMenu` provides additional actions. A `BudgetAllocationDialog` is accessible for allocation operations. The breadcrumb is set from `budget.version_name`.

Before you start:

* The budget must already exist (created via the Budget Creation Wizard at `/fa/budgets/wizard`).
* An organization must be selected.

Key concepts:

* `version_name` — the display name of the budget version
* `status` — budget lifecycle state; `pending_approval` enables approval actions
* `BudgetLineGrid` — component rendering budget line items
* `BudgetApprovalDialog` — approval/rejection modal with action type `approve` or `reject`
* Tab URL state — `?tab=overview|lines|approval|variance|forecast`

1. Open the Budgeting Hub at `/fa/budgeting?tab=budgets` and click a budget row, or navigate to `/fa/budgets/:id` directly.
2. Review the **Overview** tab: the budget summary card shows key metrics.
3. Review or edit **Lines**: the Lines tab shows all budget line items. Click Add Line to open `BudgetLineForm`.
4. Review **Approval** history in the Approval tab.
5. When status is `pending_approval`, use the Approve or Reject buttons to open `BudgetApprovalDialog`.
6. Use **Variance** and **Forecast** tabs for variance analysis and forecast data.

## Creating a budget

New budget creation is handled by the Budget Creation Wizard. The route `/fa/budgets/new` redirects to `/fa/budgets/wizard`. The wizard is rendered by `BudgetCreationWizardPage` using the `ModuleWizardRenderer` infrastructure.

The wizard supports 4 steps:

1. **Budget Header** — form step for budget metadata
2. **Copy Template** — optional step; pre-populates budget lines from a template (triggered when navigated from Template Library with `location.state.fromTemplate`)
3. **Enter Budget Lines** — custom step for line-item entry
4. **Review & Submit** — summary and submission step

On completion: a `fa_budgets` record is created via Supabase direct insert, budget lines are created, and `useSubmitBudgetForApproval` handles approval workflow submission.

**Permission gate:** `fa.budgets.create` (wizard route level)

Optionally: select a budget template from the Template Library before creating.

1. Navigate to `/fa/budgets/new` (redirected to `/fa/budgets/wizard`), or click **New Budget** from the Budgeting Hub.
2. Complete each wizard step.
3. On the Review & Submit step, submit the budget. The wizard triggers the approval workflow via `useSubmitBudgetForApproval`.

<Warning>
  SME: The exact fields for each wizard step are implemented in wizard step components not fully readable from the page wrapper alone. Confirm step-by-step field requirements with the implementation team.
</Warning>

## Related

<Columns cols={2}>
  <Card title="Finance & Revenue" icon="building-columns" href="/fa/overview">
    Finance & Revenue core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/fa.tsx
  * src/cores/fa/pages/BudgetsPage.tsx
  * src/cores/fa/pages/BudgetingHubPage.tsx
  * src/cores/fa/pages/BudgetDetailPage.tsx
  * src/cores/fa/wizards/budget-creation/BudgetCreationWizardPage.tsx
  * src/cores/fa/hooks/useBudgets.ts
  * src/cores/fa/hooks/useBudgetAlerts.ts
  * src/platform/wizards/ModuleWizardRenderer.tsx
</Accordion>