Skip to main content

​
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: 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

​
Run the stack

Bring every service up against the deterministic fake adapter:
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:
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.
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.

​
Next steps

Local development

Fake and live stacks, the server overlay, and teardown.

CI & review lanes

The make ci gate, integration and end-to-end suites, and the platform invariants.