Open Source
How the open source New Zealand rates API is built: Cloudflare Workers, D1, Elysia, hourly scrapers, and the repository layout. MIT licensed.
Rates API is an open source project that operates on Cloudflare Workers. The repository contains the API Worker, the documentation app, the landing page, the scraper scripts, the tests, and the GitHub Actions workflows.
Architecture
| Component | Function |
|---|---|
| API Worker | Serves /api/v1/*, /openapi, and /openapi/json |
| Docs Worker | Serves this Fumadocs site at www.ratesapi.nz/docs |
| Landing page Worker | Serves the TanStack Start app in apps/web at www.ratesapi.nz. It sends a redirect from the apex domain to www. |
| Cloudflare D1 | Keeps the newest datasets and the historical snapshots |
| Scraper scripts | Collect rates from the interest.co.nz pages |
| GitHub Actions | Do checks, builds, data collection, deployment, and uptime checks |
Technology Stack
| Layer | Tools |
|---|---|
| Runtime | Bun and Cloudflare Workers |
| API routes | Elysia |
| Schemas | Elysia t and TypeBox validation at runtime |
| API reference | The Elysia OpenAPI plugin with Scalar |
| Docs site | Next.js, Fumadocs UI, and Fumadocs MDX |
| Landing page | TanStack Start, React, and Tailwind CSS |
| Data storage | Cloudflare D1 |
| Scrapers | Cheerio |
| Code quality | Oxlint, Oxfmt, TypeScript (tsgo), Fallow, React Doctor, and Bun tests |
Repository Structure
| Path | Contents |
|---|---|
apps/api/src/ | The code of the API Worker |
apps/api/src/routes/ | The Elysia route groups |
apps/api/src/models/ | The runtime schemas and the TypeScript types |
apps/api/src/lib/ | Shared API functions |
apps/api/bin/ | The scraper scripts, the D1 scripts, and the uptime script |
apps/api/test/ | The API, scraper, and data loader tests |
apps/docs/app/ | The Next.js App Router routes of the docs site |
apps/docs/content/docs/ | The MDX documentation pages |
apps/docs/test/ | The docs content tests |
apps/web/ | The landing page |
.github/workflows/ | The CI, deploy, scraping, monitoring, Fallow, and React Doctor workflows |
Changes to the Project
- API changes: Change the route handlers, the schemas, the OpenAPI descriptions, and the contract tests together.
- Scraper changes: Change the scraper normalization, the validation, and the D1 write behavior together.
- Documentation changes: Change the MDX files in
apps/docs/content/docs. Then runbun run check. - Deployment changes: Change the Worker configuration and the CI build job together.
Write the OpenAPI descriptions and the documentation pages in ASD-STE100 Simplified Technical English.
To start, read Local Development. To operate a copy of the service, read Deployment.
Last updated on
Core Concepts
How Rates API collects New Zealand rates from interest.co.nz each hour, and how snapshots, lender IDs, date filters, and errors operate.
Local Development
Clone Rates API, install it with Bun, start the API, docs, and landing page, and load real New Zealand rate data into a local D1 database.