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

# CI & review lanes

> The make ci gate, the integration and end-to-end suites, the three independent review lanes, and the platform invariants every change must respect.

# CI & review lanes

Every change runs through the same gate in development and in CI: `make ci`, then three independent review
lanes. The gate is the floor — passing it means the change is safe to propose, not that it ships. The review
lanes are what decide that.

## make ci

`make ci` is an aggregate target that runs the seven checks below in order. Run it from the repository root
before opening a pull request:

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

| Target       | What it checks                                                                                                                                                                                                        |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contract`   | Renders the FastAPI OpenAPI document and asserts it matches `contracts/neobank.openapi.json`, checks the pinned Perflo contracts, and compares a temporary TypeScript generation against the checked-in client types. |
| `lint`       | `ruff format --check` and `ruff check` for the API and the Caddy validation script; Biome for the web app.                                                                                                            |
| `typecheck`  | `basedpyright` for the API and the Caddy script; `tsc` for the web app.                                                                                                                                               |
| `test`       | `pytest --cov=neobank --cov-report=term-missing` for the API; Vitest for the web app.                                                                                                                                 |
| `build`      | Production build of the web app and `compileall` of the API sources and scripts.                                                                                                                                      |
| `docs`       | `scripts/check_docs.py` for frontmatter and TODO/TBD hygiene, Helm chart lint, Compose config validation for the three overlays, Caddyfile validation, and Mintlify validation of the public `docs-site/`.            |
| `migrations` | Alembic `upgrade head`, `check`, `downgrade base`, then `upgrade head` again — a full round trip against a throwaway database.                                                                                        |

<Warning title="The gate is the floor">
  A green `make ci` certifies that the build, types, contract, and tests are clean. It does not certify that
  the change is correct, safe, or well-shaped. The three review lanes below are mandatory for any behavioral
  change and must return clean before the work is complete.
</Warning>

## Integration and end-to-end suites

Two suites run outside `make ci` because they need external resources:

* **PostgreSQL concurrency** — `make integration` runs the integration suite under `pytest -m integration`,
  which exercise the PostgreSQL race conditions the in-memory database cannot reproduce. Set
  `NEOBANK_TEST_DATABASE_URL` to a connection string whose database is named `neobank_test`; the target fails
  fast if the variable is unset.

  ```bash theme={null}
  export NEOBANK_TEST_DATABASE_URL='postgresql+psycopg://user:pass@localhost:5432/neobank_test'
  make integration
  ```

* **Browser end-to-end** — `pnpm test:e2e` drives the customer and operator flows through the Playwright
  Chromium installed by `make browser-install`. The Playwright configuration builds and starts the production
  preview server; the suite intercepts API routes, so the Compose stack is not required.

  ```bash theme={null}
  pnpm test:e2e
  ```

## The review lanes

Before completing any behavioral change, run `make ci` **and** dispatch three independent review lanes. All
three must return clean. Never ship past a flag — if a lane reports a substantive issue, fix it and rerun that
lane; never unilaterally descope what a reviewer reports.

| Lane                      | Focus                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| Clean code                | Style, dead branches, duplication, naming, unused code.                                     |
| Architecture and security | Abstractions, layering, coupling, and the platform invariants below.                        |
| QA sign-off               | Edge cases, error paths, and that tests cover what matters rather than only the happy path. |

Run the lanes in parallel so they are cheap and fast. Re-run only the lane that flagged after a fix.

## Platform invariants

The invariants below are non-negotiable. They come from `AGENTS.md` and every change must preserve them:

* **Never expose card or token secrets.** No endpoint returns a card PAN, CVV, raw token, refresh token, or
  unmasked bank identifier.
* **Mutations are idempotent before submission.** Every financial mutation creates an idempotent operation
  before the provider is called, so a transport retry never becomes a double payment.
* **Transport-uncertain writes fail closed.** A provider write whose result is transport-uncertain becomes
  `indeterminate` and is never retried automatically.
* **Sessions match their route class.** Customer routes use customer sessions; operator routes are view and
  suspend only; agent routes require an OAuth scope **and** an active customer mandate bound to the client ID.
* **Production requires live credentials.** Production refuses `fake` and uses each customer’s Vault-encrypted live device session.

## Next steps

<CardGroup cols="2">
  <Card title="License" icon="scale-balanced" href="contributing/license">
    Apache License 2.0 — what it permits and the patent grant that matters for partners.
  </Card>

  <Card title="Production readiness" icon="circle-exclamation" href="get-started/production-readiness">
    What works today, what is blocked on Perflo, and the launch gate.
  </Card>
</CardGroup>