# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

KickItCA.org is the frontend for the California Smokers' Helpline (operated by UCSD). It is a **Next.js 11 / React 17 / TypeScript** app styled with **styled-components**, using **Yarn** and **Node 14**. Content is sourced from a headless WordPress CMS via Apollo GraphQL; tobacco-cessation intake forms post to UCSD backend APIs.

## Commands

```bash
yarn dev        # local dev server (next), with --trace-warnings
yarn build      # rm -rf .next && next build  (.next must be cleared, build is not incremental)
yarn start      # serve a production build
yarn lint       # eslint ./ --ext .js,.ts,.tsx
yarn format     # eslint --fix
yarn tsc        # TypeScript type-check (tsconfig is strict, noEmit)
```

**Before raising a PR, both must pass:** `yarn lint && yarn tsc`. Note: ESLint is set to `ignoreDuringBuilds` in `next.config.js`, so `yarn build` will NOT catch lint errors — run `yarn lint` separately.

## Environment

`.env` (loaded via dotenv in `next.config.js`) defines the WordPress endpoints:
- `NEXT_APP_WP_API_URL` — WordPress GraphQL endpoint (consumed by `pages/api/index.ts` Apollo client)
- `NEXT_APP_JSON_API_URL` — WordPress REST endpoint

`next.config.js` also defines build-time `env` (Recaptcha `GOOGLE_KEY`, GTM `GTM_KEY`) and two URL **rewrites** that intake APIs depend on:
- `/proxy/:path*` → `https://csh-apps.ucsd.edu/:path*` (UCSD intake/appointment backend; swap to `test-vision.ucsd.edu` for dev — see commented line)
- `/json-api/:path*` → WordPress REST API

i18n locales are `en` and `es` (default `en`).

## Architecture

### Content pages (WordPress-driven)
Marketing/content pages are fully CMS-driven and statically generated:
- `pages/[slug].tsx` uses `getStaticProps`/`getStaticPaths` to fetch a page by slug from WordPress GraphQL (`services/wpgraphql/`).
- A page is an array of **blocks**. `utils/componentMap.tsx` (`ComponentRenderer`) maps each block's GraphQL `__typename` to a React component in `src/components/blocks/`. To add a CMS block type: create the component under `src/components/blocks/`, export it + its name constant from `src/components/blocks/index.ts`, register it in `componentMap.tsx`, and add its fields to the GraphQL fragments in `services/wpgraphql/blocks.ts`.
- `services/formatData/` shapes header/footer GraphQL responses; `pages/_app.tsx` wraps every page with `Header`/`Footer` and the `LanguageProvider`.

### Intake forms — TWO separate systems
There are two distinct, independently-maintained form implementations. Identify which one you're touching before editing.

1. **Quit-now / payer intake** (the actively-developed one): `pages/form/intake/[formType]/[currentQuestion].tsx` is a single dynamic page driven by router params. Question definitions and UI strings live in `src/components/form/quit-now/data_questions`, and the question-type components in `src/components/form/quit-now/questions`. Per-payer entry points each have their own folder (`pages/form/intake/[formType]/{MEM,MEM26,IEHP,MOLINA,LACARE,KHS,HN,UCSD,scripps,...}/1.tsx`) — these insurance/program codes drive eligibility and which questions appear. The `[formType]` page also branches on a `srcCode` query param.

2. **Legacy `_resources` intake**: `src/forms/_resources/` holds declarative question/flow configs (`intake-self.ts`, `intake-other.ts`, `intake-pre.ts`, `eligibility.ts`, `approval.ts`, `underage.ts`, `non-resident.ts`, etc.), with flow business logic in `src/forms/_resources/hooks/intake-form.ts` and shared `BASE_*_URL` route constants + query keys in `src/forms/_resources/utils/formConstants.ts`. Referral forms (patient/student) also live here (`hooks/referral-form.ts`, `hooks/student-referral-form.ts`) and render via `src/components/blocks/patientReferralForm` and `studentReferralForm`.

### API layer for forms
`src/forms/_resources/utils/kicService.ts` (`KIC_SERVICE` class) is the single axios client for all intake/eligibility/appointment/referral calls. It hits relative `/proxy/...` and `/json-api/...` paths that resolve through the `next.config.js` rewrites to the UCSD and WordPress backends. Custom `ApiError` carries `context` + `code`; status codes and error messages come from `formConstants.ts`.

### Translations
- `src/forms/_resources/translations/_en/mcc-client.en.json` and `_es/mcc-client.es.json` hold form copy; consumed via `src/forms/_resources/hooks/translations.ts`.
- Content-page language state is held in `context/languageContext.tsx` (`'english'`/`'spanish'`) and toggled in the UI.

When adding/editing form questions or copy, keep the English and Spanish JSON in sync — recent work involves Spanish date-intake parsing and copy fixes.

## Conventions

- TypeScript is `strict` with `noUnusedLocals`/`noUnusedParameters` — unused vars/params will fail `yarn tsc`. `baseUrl` is the repo root, so imports like `src/...`, `services/...`, `utils/...`, `context/...` are absolute.
- Formatting is Prettier (`.prettierrc.js`) enforced through ESLint (airbnb config).
- Production deploys from the `master` branch. (The README references a `develop` branch; current active branches are feature branches off `master`.)