chiban-org/chiban-oss

What it does

Chiban is software for the land-use office of a small US town — a clerk, a part-time building inspector and volunteer boards. It keeps each parcel's record in one place: applications, notices, hearings, decisions, permits, inspections and complaints. Residents can see the public part of a parcel's history without an account.

State rules are shipped as a "state pack": deadlines with the statute behind them, notice and decision wording, appeal routes, building code editions, Right-to-Know exemptions and retention schedules. Staff edit forms, fees, conditions and templates in the app. Data can be exported as plain text plus original files, spreadsheets and PDF/A copies, per a written format guide, so a town is not locked into Chiban's tooling.

Try the demo first

A live demo runs the fictional Town of Alder Pond, NH, with accounts for the clerk, building inspector, board member, applicant, contractor and administrator. Data resets nightly and no mail is sent, which makes it the fastest way to evaluate the workflows before installing anything.

Run it locally

Requirements: Node.js 24+, pnpm 9, Docker with Compose, and Ghostscript 10 on the PATH. OCRmyPDF with English Tesseract data is only needed for migrating scanned legacy files.

pnpm install
cp .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Put the generated key in .env under k1 in CHIBAN_SECRET_KEYS, then start services, migrate, seed the demo data and run the app:

docker compose -f docker-compose.dev.yml up -d --wait
pnpm db:migrate
pnpm storage:init
pnpm db:seed:demo
pnpm dev

In a second terminal run pnpm worker; without it, emails stay queued, exports never start and scheduled jobs never run. The app serves at http://localhost:3000 and Mailpit shows outgoing mail at http://localhost:8025. With ENABLE_DEV_SIGN_IN=true and NODE_ENV not production, http://localhost:3000/dev/sign-in lists the demo users and lets you sign in as any role.

Production deployment

The self-hosting guide describes a single Linux host with Docker Compose: Caddy, the app, a worker, PostgreSQL with PostGIS and Garage for object storage, with images pinned by digest. Backups, restore checks, upgrades, outbound mail and card payments each have dedicated documentation.

Constraints

• Only one state pack exists, New Hampshire (packs/nh). Adding another state is real work; the state pack guide explains what it involves.
• Payment adapters: no live processor key is in the repo. Stripe runs against a stateless mock that sends no webhooks, and the Clover adapter has not been verified against a live merchant account. Simulated payments can be enabled for development.
• USPS address checks are optional; without credentials the fields act as plain text. Rate is 30 lookups per minute per signed-in user, with one-day caching of repeated addresses.
• pnpm db:reset:demo drops every table named by DATABASE_URL, so only point it at a disposable database.
• Licensed under AGPL-3.0, which matters if you plan to modify and host a network-facing service.

Tech stack

Next.js 16 / React 19, tRPC, Drizzle ORM on PostgreSQL 16 with PostGIS, MapLibre with PostGIS-served vector tiles, S3-compatible storage and pg-boss for background jobs. Tests use Vitest with an integration lane against real PostGIS, plus Playwright.

HotRepo's take

The project entered the TypeScript new-project list on 2026-11-14 with 126 stars and 6 stars gained in a roughly one-hour window, while forks remained at zero. That is a single snapshot, not evidence of sustained momentum, and with no discussion threads to draw on there's no community signal either way. The more useful observation is scope: the README is explicit that cross-state coverage doesn't exist yet, so the honest evaluation is whether a New Hampshire town's workflows match the shipped pack, not whether the general pitch sounds right.