# Project plan — bigpond_frontend_qa

Evidence date: 2026-10-19.

Source repository: `git@bitbucket.org:overdrive/bigpond_frontend_qa.git`.

This plan describes branch `main` at `6b421ff0d237fb707fb1d618f1252f6262e3c895` (2025-07-21 14:35 +0200, message `init`). The parent commit is `2ec5f32` the same day (`Initial commit`). Those are the only two commits on `main`. The task-creation snapshot named the same tip.

The local scan path `~/projects/sonar_scan/repos/bigpond_frontend_qa` was not on this machine. Evidence is a read-only clone of the remote. The source repository was not modified.

Silicon Ark had no `bigpond_frontend_qa/` directory before this set.

## Product purpose

**Documented** on the public landing page (`src/components/welcome/index.jsx`): the product is **Audit Whizz**. The copy says the platform analyses accounting data and supporting evidence and generates audit workpapers.

**Implemented** package name is `bigpond` (`package.json`). The repository name is `bigpond_frontend_qa`. Navigation labels the older upload flow **Xero Testing** and the newer step flow **Workpapers**.

**Inferred.** Audit firms use the app to keep clients, users, and two document workflows: a fixed Xero/bank upload that builds an Excel workbook, and a configurable workpaper flow that extracts and matches PDF and Excel documents with OpenAI.

## Scope

In this `main` tree:

- A public landing page and contact form.
- Cognito sign-in (self-signup hidden) and a MySQL user row that must already exist or be created by an admin.
- Admin screens for audit firms (companies), clients, and users, including CSV bulk user import.
- A Xero Testing screen: client and workflow type, Excel / PDF / CSV uploads to S3, workbook generation, download, and an expense zip.
- A client action that emails a Xero connection link and a `/callback` page that stores Xero tokens.
- A Workpapers screen: named flows of document steps, field definitions, file processing, match results, exports, and a zip of workpapers.
- AWS Amplify API Gateway routes backed by Lambda (Express and single-purpose functions), MySQL, S3, SES, Secrets Manager, and SSM.
- Scheduled Lambdas that process files with OpenAI.

Not in this tree:

- A written milestone or roadmap. `README.md` has a changelog of features already in the tree. Git history does not preserve the dates in that changelog, because history was collapsed into the 2025-07-21 `init` commit.
- `src/pages/customFlowPage` and `src/pages/pocPage`. `rules.md` and commented navigation still name them. The routed workpaper UI is `src/pages/customMatchPage`.
- Amplify hosting config. `amplify/backend/hosting` is absent. The CORS allow-list and the Xero redirect use `https://www.auditwhizz.net`.
- Automated tests that exercise the product. `src/App.test.js` still expects the Create React App “learn react” link.
- A `CONTRIBUTING.md`. `README.md` points at one. The file is not in the repository.

## System architecture

Create React App (React 18) in the browser. AWS Amplify configures Cognito and calls API Gateway. Most product data goes through Lambda `bigpondexpress` (Express) into MySQL. Files go to S3. Document intelligence goes through OpenAI from Lambdas. Xero OAuth is a separate Express Lambda. Mail uses SES.

```text
Browser (React, Amplify UI Authenticator)
        │
        ├── Cognito (imported user pool, groups Admin / User)
        ├── S3 private uploads (Amplify Storage)
        └── API Gateway apibigpond (+ file and table APIs)
                │
                ├── bigpondexpress  →  MySQL (companies, users, clients, flows, per-session master tables)
                ├── XeroExpress / xerotoken / xerotenants / xerorefresh / sendxeroemail / updatetableinvoice
                ├── generatefile, ZipObjects, ZipWorkPapers, deleteSessionUploads
                ├── openAIFileProcessing, processUnprocessedFiles (schedules), openaistart
                ├── manageFileProcessTable, tempFileProceesTable, tempFileProcessTable
                ├── contactmail, frontendLogs
                └── SES, Secrets Manager, SSM (ap-southeast-2)
```

Region used by the Lambdas inspected is `ap-southeast-2`.

## Major components

| Component | Role | Evidence |
|---|---|---|
| `src/router/index.jsx` | Role gates after Cognito authentication | Implemented |
| `src/context/authContext.jsx` | Loads the MySQL user, session id, clients, and bank numbers | Implemented |
| `src/pages/landingPage`, `components/welcome`, `components/contactForm` | Public Audit Whizz page and contact mail | Implemented |
| `src/pages/companyPage`, `clientPage`, `userPage` | Audit firms, clients, users | Implemented |
| `src/pages/workflowPage` | Xero Testing uploads and workbook generation | Implemented |
| `src/pages/customMatchPage` | Workpapers: steps, matching, results, export | Implemented |
| `src/pages/callback` | Xero OAuth return | Implemented |
| `amplify/backend/function/bigpondexpress` | Main MySQL API | Implemented |
| `amplify/backend/function/generatefile` | Builds the Xero Testing Excel workbook from the session table | Implemented |
| `amplify/backend/function/openAIFileProcessing` | Document extract and match (`gpt-4.1`) | Implemented |
| `amplify/backend/function/XeroExpress` | Xero URL, callback helpers, client access | Implemented |

## Milestones

No milestone plan is in the repository.

**Inferred sequence from what is already built**, not a dated plan:

1. Cognito login, companies, clients, users, and the Xero Testing upload/generate path.
2. Xero tenant connection, token storage, and disconnect when a client is deactivated.
3. Workpapers (custom match): step builder, OpenAI extract/match, local persistence, company-scoped saved flows, Excel/CSV/PDF export, workpaper zip.
4. Bulk user import, contact form, and OpenAI usage logging (`workpaper_logs`, described in `NewKnowledgeBase.md` and `CHANGELOG.md`).

Whether any of these are still being changed on another branch is **Unknown**. `git branch -a` on this clone shows only `main`.

## Implementation plan

There is no separate implementation plan in the repo. Current delivery shape:

- Frontend: `npm start` / `npm run build` via `react-scripts` 5.0.1.
- Backend: Amplify Gen 1 CloudFormation under `amplify/backend` (API Gateway, Lambda, imported Cognito, S3).
- Quality gate in `bitbucket-pipelines.yml`: SonarQube scan, and only on branch `{master}`. The repository’s current branch is `main`, so that pipeline definition does not run on the branch this plan describes. **Requires confirmation** whether a `master` branch is still the pipeline target.

## Known dependencies

- AWS: Cognito, API Gateway, Lambda, S3, SES, Secrets Manager, SSM, Amplify.
- MySQL (RDS). Connection details come from SSM parameter `rdsDetails` and a Secrets Manager secret referenced in the Lambdas. A second secret name, `DatabaseCredentials`, is used by `processUnprocessedFiles`.
- OpenAI chat completions. `openAIFileProcessing` uses model `gpt-4.1`. `processUnprocessedFiles` uses `gpt-4o`. The key is read from Secrets Manager secret `OpenAIKey` in the scheduled processor. `README.md` also names `REACT_APP_OPENAI_API_KEY`.
- Xero API (`https://api.xero.com`), including connection delete when a client is set inactive.
- Browser libraries: React Bootstrap, MUI, DataTables, xlsx-js-style, jsPDF, pdf.js, axios.

A committed `.env` contains `REACT_APP_XERO_CLIENTID`, `REACT_APP_XERO_CLIENTSECRET`, and `REACT_APP_OPENAI_API_KEY`. Values are not copied into Silicon Ark. Those credentials are in git history and need rotation. See the confirmation list.

## Current project status

**Implemented** and present on `main` as of 2025-07-21. No later commit is on `origin/main`.

The public name (Audit Whizz), the repo name (`bigpond_frontend_qa`), and the npm name (`bigpond`) are all in use at once.

`rules.md` says the focus area is `src/pages/customFlowPage` and that the page is “currently correct”. That directory is not in the tree. Treat `rules.md` as stale relative to `customMatchPage`.

## Unknown / Requires Confirmation

- Whether `https://www.auditwhizz.net` is the live site for this commit.
- Whether Amplify environment `dev` (bucket name `big-pond-uploads-bucket123209-dev`, Lambda `openAIFileProcessing-dev`) is production or a development stack.
- Whether guest API Gateway permissions (CRUD on many `apibigpond` paths, including unauthenticated) are intentional.
- Whether role id `2` exists in `user_role`. The UI only offers role `1` (Admin) and `3` (User). Any other `role_id` stays on the loading spinner.
- Whether the committed `.env` secrets are still valid. They should be rotated because they are in the repository.
- Whether `customFlowPage` was renamed to `customMatchPage` or removed on purpose.
- Whether the Sonar pipeline should target `main`.
- Database schema beyond the SQL strings in the Lambdas. There are no migration files.