> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neobank.proofof.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribute

> Set up a local development environment for the Perflo neobank platform with the locked toolchain and a single command.

# Contribute

The platform is a pnpm monorepo: a FastAPI service in `apps/api` and a Vite + React web app in `apps/web`. Both
dependency graphs are locked — Python through `uv.lock`, the web through `pnpm-lock.yaml` — and the Makefile
drives the common workflows with the same versions CI uses. After a one-time toolchain install, a single
`make up` brings the whole stack up against the deterministic `fake` adapter.

## Prerequisites

Install the locked toolchain before the first run:

| Tool             | Version         | Used for                                                               |
| ---------------- | --------------- | ---------------------------------------------------------------------- |
| Docker + Compose | 2.24.4 or newer | PostgreSQL, session and task Redis, Vault, API, worker, scheduler, web |
| Python           | 3.12            | API, worker, scheduler                                                 |
| uv               | 0.11.32         | Locked Python dependency management                                    |
| Node.js          | 24              | Web app                                                                |
| pnpm             | 11.5.2          | Locked web dependency management                                       |

The Python and Node version pins match CI exactly. `uv` and `pnpm` read their lockfiles with `--frozen`, so a
version skew fails loudly instead of resolving a different graph.

## First-time setup

<Steps>
  1. **Clone the repository.**

     ```bash theme={null}
     git clone https://github.com/gcharang/neobank-wrapper.git
     cd neobank-wrapper
     ```

  2. **Install locked dependencies.**

     `make install` runs `uv sync --frozen` inside `apps/api` and `pnpm install --frozen-lockfile` at the
     repository root.

     ```bash theme={null}
     make install
     ```

  3. **Install the Playwright browser.**

     `make browser-install` installs the Chromium binary that the end-to-end suite drives.

     ```bash theme={null}
     make browser-install
     ```

  4. **Generate the development environment.**

     `make env` copies `.env.example` to `.env` when no `.env` exists. The template ships with
     `NEOBANK_DEBUG_AUTH_ENABLED=true`, which lets the debug identity headers authenticate requests in
     development.

     ```bash theme={null}
     make env
     ```
</Steps>

## Run the stack

Bring every service up against the deterministic `fake` adapter:

```bash theme={null}
make up
```

`make up` builds and starts PostgreSQL, separate session and task Redis instances, Vault, the FastAPI API, the Celery worker, the Celery beat
scheduler, and the production-built web container. Open:

* **Customer app**: `http://localhost:3000`
* **API reference**: `http://localhost:8000/docs`

Confirm the API is ready with `curl --fail --silent http://localhost:8000/health/ready | jq`, which returns
`{"status":"ready"}`. To tear the stack down, run `make down`.

## Regenerate API types after a contract change

The TypeScript client in `apps/web` is generated from the FastAPI OpenAPI contract. After you change an API
route, request body, or response schema, regenerate the types from the repository root:

```bash theme={null}
pnpm gen:api
```

`pnpm gen:api` runs `openapi-typescript ../../contracts/neobank.openapi.json` inside the web package and writes
`apps/web/src/types/openapi.gen.d.ts`. Commit the regenerated file together with the contract change — `make ci`
enforces this with a git-diff guard inside the `contract` target.

<Note title="Do not hand-edit generated files">
  `contracts/neobank.openapi.json` and `apps/web/src/types/openapi.gen.d.ts` are both generated. Change the
  FastAPI source, rerun the export and `pnpm gen:api`, and let the CI diff guard confirm nothing drifted.
</Note>

## Next steps

<CardGroup cols="2">
  <Card title="Local development" icon="wrench" href="deploy/local-development">
    Fake and live stacks, the server overlay, and teardown.
  </Card>

  <Card title="CI & review lanes" icon="code-branch" href="contributing/ci-and-reviews">
    The `make ci` gate, integration and end-to-end suites, and the platform invariants.
  </Card>
</CardGroup>