---
name: senederp-ngo-grant-hub
description: Describes how this repo models grants as the operational hub (tenant-scoped records, budget lines, amendments, API routes). Use when wiring new features to a grant, extending grant fields, or aligning UI with Laravel grant endpoints.
---

# Grant hub in this repo

## Core tables

- **`grants`** — `organisation_id`, unique `code` per org, lifecycle `status`, `funding_type`, currency and `amount_awarded`, dates, donor display fields, optional `metadata` JSON, `archived_at` for soft archive.
- **`grant_budget_lines`** — Child lines with `line_code` unique per grant, `amount_budgeted`, optional `cost_category`, `sort_order`, optional line `currency` (falls back to grant currency in UI).
- **`grant_amendments`** — Audit-friendly history: `effective_on`, `summary`, optional structured `changes` JSON, `user_id` of recorder.

## API (Sanctum auth)

- `GET /api/grants/meta` — vocabulary for selects (`funding_types`, `statuses`, `reporting_frequencies`) plus short field help.
- `GET|POST /api/grants` — list (filters: `status`, `funding_type`, `q`, `include_archived`, `page`, `per_page`) and create.
- `GET|PUT|PATCH|DELETE /api/grants/{grant}` — show, update, archive (`DELETE` sets `archived_at`; restore via `PATCH` with `archived_at: null`).
- Nested: `GET|POST /api/grants/{grant}/budget-lines`, `PUT|PATCH|DELETE …/budget-lines/{budget_line}`.
- `GET|POST /api/grants/{grant}/amendments`.

## Tenancy

Route models resolve only within the authenticated user’s `organisation_id`. Cross-tenant access returns 404.

## Identifiers (UUID, not `id`)

- **APIs and URLs:** use **`uuid`** for path parameters, query filters, and JSON the frontend stores (keys in maps, router params, links). Do not expose or depend on numeric **`id`** in client-visible contracts unless bridging legacy data.
- **Laravel:** route keys (`getRouteKeyName()`), implicit binding, and `whereUuid()` (or equivalent) should resolve grants, budget lines, and related resources by **`uuid`**.
- **Next.js:** prefer dynamic segments such as `/grants/[uuid]` (name the param for clarity) and types that carry `uuid` as the stable handle.

## Frontend

Next.js routes under `/grants` (list, `/grants/new`, detail under a **uuid** segment) call the above endpoints via `apiFetch`.

## Employee portal & HR (not a generic forms product)

- **Leave and time** are first-class under the **`hr`** module (`leave_requests`, `hr_time_entries`, `/hr` UI).  
- **Staff persona:** `GET /api/user` exposes `workspace_layout` (`full` | `employee`) and related flags; **`/me`** is the employee home with `GET /api/me/overview` aggregates.  
- **Travel clearance** uses the **`travel`** module and `business_trips` + approval `document_type` **`business_trip`** (not nested under `hr`).  
- The legacy **Forms** builder/submissions product has been **removed** from the codebase; future structured intakes should be dedicated bounded contexts (e.g. policy attestations), not a generic form engine.
