# Running the AS0558844 modernization on Windows

The generated application uses:

- Python with FastAPI for the backend.
- TypeScript and React for the frontend.
- In-memory state.

Java and Neo4j are not required to run this generated application.

## 1. Install prerequisites

Use Windows 10 or Windows 11 with PowerShell.

Install Node.js 22 LTS from:

<https://nodejs.org/en/download>

Install `uv`:

```powershell
winget install --id=astral-sh.uv -e
```

Close and reopen PowerShell, then check the installations:

```powershell
node --version
npm --version
uv --version
```

Vite requires Node.js 20.19+ or 22.12+. Node.js 22 LTS is recommended for this
package.

## 2. Start the backend

Open PowerShell and enter the application backend directory. Replace
`C:\workspace\brsp-synthesis-engine-hsbc` with the location where the project
was copied or cloned.

```powershell
cd "C:\workspace\brsp-synthesis-engine-hsbc\hsbc\dist\application\backend"

uv python install 3.12
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
```

The API will be available at:

- <http://127.0.0.1:8000>
- <http://127.0.0.1:8000/docs>

Keep this PowerShell window open.

## 3. Start the frontend

Open a second PowerShell window:

```powershell
cd "C:\workspace\brsp-synthesis-engine-hsbc\hsbc\dist\application\frontend"

npm ci
npm run dev -- --host 127.0.0.1 --port 5173
```

Open:

<http://127.0.0.1:5173>

Keep this PowerShell window open while using the application.

## 4. Run automated validation

Backend:

```powershell
cd "C:\workspace\brsp-synthesis-engine-hsbc\hsbc\dist\application\backend"

uv run --extra test pytest
```

Frontend:

```powershell
cd "C:\workspace\brsp-synthesis-engine-hsbc\hsbc\dist\application\frontend"

npm ci
npm test
npm run build
npm audit --audit-level=low
```

Expected baseline:

- 17 backend tests pass.
- 5 frontend tests pass.
- The production build succeeds.
- The dependency audit reports zero known vulnerabilities.

## 5. Stop the application

Press `Ctrl+C` in each PowerShell window.

The application uses in-memory storage. Imports, adjustments, export jobs, and
period changes made during a run are reset when the backend stops.

## Troubleshooting

### `uv` is not recognized

Close and reopen PowerShell after installing `uv`. If necessary, install it
using the official PowerShell installer:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### `npm` is not recognized

Reinstall Node.js 22 LTS and ensure that the installer adds Node.js to `PATH`.
Then open a new PowerShell window.

### Port already in use

Find and stop the existing process, or choose another port. If changing the
backend port, also update the frontend proxy in:

`application\frontend\vite.config.ts`

