# Project plan — bigpond_frontend

Evidence date: 2026-10-19.

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

This plan describes branch `master` at `c5ef2b11a28f048fc83486c4f3533e2c8a72f43d` (2025-11-26 16:54:37 +0200, message `change overide`). That tip matches the snapshot recorded when this onboarding task was created. The repository has 1,025 commits. The first commit is `7892fe6` (2023-03-28, `Initial commit`).

The local scan path `~/projects/sonar_scan/repos/bigpond_frontend` 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/` directory before this set. A separate directory, `bigpond_frontend_qa/`, documents `bigpond_frontend_qa` and is not this repository.

## 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.

**Documented** in `README.md` and **implemented** in `package.json`: the application name is **BigPond** (`"name": "bigpond"`). The README describes a financial document platform with custom flows, AI matching, upload, and export.

**Inferred.** Audit firms use the app to keep clients and users, run a fixed Xero Testing upload (Excel, optional invoice images, bank CSV), and run a Workpapers flow that extracts and matches PDF and Excel documents with OpenAI.

Which name is canonical for customers is **Unknown / Requires Confirmation**. Both names are in the tree.

## Scope

In this `master` tree:

- A public landing page and contact form.
- Cognito sign-in (self-signup hidden) and a MySQL user row that must already exist.
- Admin screens for audit firms (companies), clients, and users, including CSV bulk user import.
- A Xero Testing screen: client, workflow type (Expense Document or Revenue Document), 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 (`/custommatch`): named flows of document steps, field definitions, file processing, match results, exports, and a zip of workpapers.
- An admin route `/logs` that exports workpaper processing logs. The sidebar link is commented out.
- 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.
- Bitbucket Pipelines SonarQube scan on `master`.

Not in this tree:

- A written milestone plan or roadmap beyond `README.md` and `CHANGELOG.md`.
- `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. CORS allow-lists and the Xero redirect use `https://www.auditwhizz.net`.
- `CONTRIBUTING.md`. `README.md` points at one.
- `sonarqube_scan.bat`. The task-creation file list included it. It is not in `master` at `c5ef2b1`.
- Automated tests that exercise the product. `src/App.test.js` still expects the Create React App “learn react” link.

## 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 bigpondpuloads)
        └── API Gateway
              apibigpond, apibigpondfiles,
              manageFileProcessTable, tempFileProceesTable
                │
                ├── bigpondexpress  →  MySQL
                ├── XeroExpress / xerotoken / xerotenants / xerorefresh
                │     / sendxeroemail / updatetableinvoice
                ├── generatefile, ZipObjects, ZipWorkPapers, deleteSessionUploads
                ├── openAIFileProcessing (schedule), processUnprocessedFiles (schedule), openaistart
                ├── manageFileProcessTable, tempFileProceesTable, tempFileProcessTable
                ├── contactmail, frontendLogs
                └── SES, Secrets Manager, SSM (ap-southeast-2)
```

Region used by the Lambdas and the imported auth resource 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/logsPage` | Workpaper log export. Admin route only. Nav link commented out | Implemented |
| `src/pages/callback` | Xero OAuth return | Implemented |
| `src/pages/auditPage` | Heading “Audit Page” only. Routed, not in the sidebar | Implemented |
| `amplify/backend/function/bigpondexpress` | Main MySQL API | Implemented |
| `amplify/backend/function/generatefile` | Builds the Xero Testing Excel workbook | 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

There is no project-plan document in the source repository. The dates below are commit timestamps or dates written in `README.md` / `CHANGELOG.md`.

| When | What | Provenance |
|---|---|---|
| 2023-03-28 | Initial commit, auth, S3 bucket function, Bitbucket pipeline file | Implemented (git) |
| 2024-01-09 to 2024-01-10 | README says matching UI and a 5-minute unprocessed-file schedule were added | Documented in `README.md`. Not re-mapped commit-by-commit |
| 2025-01-22 to 2025-01-30 | README says Custom Match Page, localStorage queue, and versioned `customFlowData` | Documented. The routed page in this tree is `customMatchPage`. `customFlowPage` is absent |
| 2025-07-24 to 2025-07-25 | Hierarchical export, workpaper logs, SonarQube hotspot fixes. Pull requests #7, #8, #9 from `dirk-dev` | Implemented (git) |
| 2025-07-30 to 2025-08-11 | Matching prompt, batch size, date format | Implemented (git). `CHANGELOG.md` top entry is 2025-08-08 |
| 2025-11-26 | API Gateway gzip override (`MinimumCompressionSize` 0), then `override.ts` renamed to `override.js` | Implemented (git `a9bba99`, `c5ef2b1`) |

## Implementation plan

No forward plan is written in the repository.

**Inferred** from commented navigation and `rules.md`: Custom Flow and POC were earlier screens and are not routed. Workpapers (`/custommatch`) is the screen both roles can open.

**Unknown / Requires Confirmation.** Whether Logs should be visible in the sidebar. `CHANGELOG.md` says a Logs link was added to admin and user navigation. `NavAdmin.jsx` comments that link out. `NavUser.jsx` has no Logs link. Role 3 has no `/logs` route.

## Known dependencies

- Amazon Cognito, API Gateway, Lambda, S3, SES, Secrets Manager, SSM, CloudWatch (console logs).
- MySQL, reached through the shared Lambda layer `createDBConnection`.
- OpenAI chat completions.
- Xero OAuth and connections API.
- npm packages in `package.json` (React 18, Amplify 5, MUI, Bootstrap, DataTables, xlsx, jsPDF, pdf.js, OpenAI SDK).
- SonarQube via Bitbucket Pipelines on `master` (`bitbucket-pipelines.yml`). `SONAR_HOST_URL` and `SONAR_TOKEN` are pipeline variables, not stored in the file.

## Current project status

**Implemented** and under active history through 2025-11-26. The latest commit does not change product screens. It renames Amplify API override files from TypeScript to JavaScript.

`amplify/backend/api/apibigpond/override.js` still uses TypeScript parameter syntax (`resources: AmplifyApiRestOverrides`). The other three override files (`apibigpondfiles`, `manageFileProcessTable`, `tempFileProceesTable`) use CommonJS `exports.override`. Whether the `apibigpond` file packages successfully is **Unknown / Requires Confirmation**.

There is no statement in the repository of a release version beyond `package.json` `"version": "0.1.0"`.