# ESA Funding Integration

## Purpose

`ESAFunding` renders backend-owned ESA funding training content through the three-layer frontend architecture.

```text
View -> Business Logic -> API/Data Access -> Backend
```

Static ESA explanatory copy, the state-variation notice/checklist, key points, and approved-use cards live in dedicated frontend constants. Editable campus ESA content lives in the backend content catalog. Staff acknowledgments use the existing policy-document acknowledgment subsystem, so they appear in the header notification flow and leadership acknowledgment reporting.

## Frontend Layers

View:

- `frontend/src/components/frameworks/ESAFunding.tsx`
- `frontend/src/components/esa-funding/EsaFundingView.tsx`
- `frontend/src/components/esa-funding/EsaFundingHeader.tsx`
- `frontend/src/components/esa-funding/EsaFundingHero.tsx`
- `frontend/src/components/esa-funding/EsaFundingStateNotice.tsx`
- `frontend/src/components/esa-funding/EsaFundingKeyPoints.tsx`
- `frontend/src/components/esa-funding/EsaFundingApprovedUses.tsx`
- `frontend/src/components/esa-funding/EsaFundingImpactRoles.tsx`
- `frontend/src/components/esa-funding/EsaFundingFaq.tsx`
- `frontend/src/components/esa-funding/EsaFundingQuickReference.tsx`
- `frontend/src/components/esa-funding/EsaFundingResources.tsx`
- `frontend/src/components/esa-funding/EsaFundingAcknowledgement.tsx`
- `frontend/src/components/esa-funding/EsaFundingEditor.tsx`
- `frontend/src/components/esa-funding/EsaFundingIcon.tsx`

Business logic:

- `frontend/src/business/esa-funding/hooks.ts`
- `frontend/src/business/esa-funding/selectors.ts`
- `frontend/src/business/esa-funding/types.ts`

Shared contracts:

- `frontend/src/shared/types/esaFunding.ts`
- `frontend/src/shared/constants/esaFunding.ts`
- `frontend/src/shared/constants/contentCatalog.ts`

## Backend Contract

The page reads:

- `GET /api/content-catalog/read/esa-funding-content`
- `GET /api/policy_documents?category=handbook_policy&tag=ESA+Funding`
- `GET /api/policy_acknowledgments`
- `POST /api/policy_acknowledgments`

Content payload is seeded in:

- `backend/src/db/seeders/content-catalog-data/content-catalog-seed-payloads.ts`

## Behavior

- `useEsaFundingPage` loads campus-scoped ESA funding content and owns local FAQ expansion state.
- Static ESA intro, state notice/checklist, key points, and approved-use cards are read from `frontend/src/shared/constants/esaFunding.ts`.
- Selectors normalize legacy payloads, filter staff-only FAQ items for student/guardian users, handle FAQ toggling, and validate resource URLs.
- View components receive a prepared page model and do not call API/data access modules.
- Loading and error states are explicit through `StatePanel`.
- Resource records with valid `http` or `https` URLs render as external links. Invalid or placeholder URLs render as unavailable instead of using no-op click handlers.
- `MANAGE_ESA_FUNDING_CONTENT` users can edit the campus-scoped dynamic payload from campus effective scope. Parent-scope users manage a campus by drilling into that campus.
- ESA funding content editing is embedded inside each dynamic content section as a collapsible local editor next to the content it changes.
- Student and guardian users do not see staff-role guidance, the parent-conversation quick reference, or the staff acknowledgment card.
- Staff acknowledgments are persisted per current ESA policy-document version through `policy_acknowledgments`; editing ESA content sends the section name to the backend, bumps the linked document version, and drives the header notification text.

## Data Ownership Rules

- Static ESA explanatory copy, state checklist, key points, and approved-use cards may live in `frontend/src/shared/constants/esaFunding.ts`.
- Editable ESA funding records such as school impact items, staff role guidance, FAQs, parent conversation Q&A references, and resource records belong to backend `esa-funding-content`.
- Do not add frontend fallback ESA content payloads.
- Keep frontend logic limited to workflow state, audience filtering, resource URL validation, icon mapping, and presentation.
- Test-only fixtures may live in selector tests or `frontend/src/test-seeds/`.
