Repository navigation
Developer Setup
This page gets the OpenBridge code running on your computer and shows you where things are. It is for anyone who wants to change code, rule data, or the wiki and run the same checks CI runs.
-
Node 24 LTS, 24.15 or newer. The version is in
.nvmrc. Node 22.22.2 or newer also works. Older versions print "Unsupported engine" warnings duringnpm ci. With nvm, runnvm usein the repository folder. - Git, and a fork or clone of the repository.
No setup at all: on the repository page choose Code, then Codespaces, then Create
codespace. It opens a ready-made environment in your browser with Node, the dependencies, and the
test browser already installed (from .devcontainer/). GitHub
gives every account free Codespaces hours each month. Skip step 1 below. In step 2, Codespaces offers
to open the app on port 5173; the link works only for you.
-
Get the code and install exactly what the lockfile lists:
git clone https://github.com/UbiquitousKiwi/OpenBridge.git openbridge cd openbridge nvm use npm cinpm cimay print "deprecated" and "N vulnerabilities" notices. They come from development tools only (npm audit --omit=devreports none), so you do not need to runnpm audit fix. -
Start the app in development mode:
npm run dev -w @openbridge/web-app
Open http://localhost:5173. Use
localhost, not127.0.0.1: the dev server listens only on your own computer. Press Ctrl+C to stop it. npm may then print a "lifecycle script failed" line, which is normal. -
Run the full quality gate. This is what CI runs, and it must pass before you open a pull request:
npm run verify
It runs formatting, lint, type checks, unit tests, the build, adapter validation, golden test cases, reason-key and readability checks, and the wiki check.
-
For changes to the user interface, also run the end-to-end and accessibility tests. The first time, install the test browser:
npx playwright install chromium npm run e2e
| Command | What it does |
|---|---|
npm run format |
Apply Prettier formatting |
npm test |
Unit tests only |
npm test -w @openbridge/eligibility-engine |
Unit tests for one package |
npm run test:fixtures |
Golden test cases only |
npm run validate:adapters |
State adapter schema and sources, then test cases |
npm run check:wiki |
Wiki links, pictures, sidebar, em dashes, emoji |
npm run screenshots |
Remake the pictures in docs/screenshots/
|
npm run rules:apply -- proposal.json --dry-run |
Preview a rule toolkit proposal without writing |
npm run build:local -w @openbridge/web-app |
Single-file offline build in dist-local/
|
The full list is in AGENTS.md section 3.
| Path | What is there |
|---|---|
packages/shared |
Types, money and date helpers, reason-code keys |
packages/eligibility-engine |
The pure rules engine, one evaluator per program |
packages/form-assembly |
Document model to PDF |
packages/web-app |
The React app: screens, translations, stores, offline support |
packages/mcp-server |
MCP server so AI assistants can use the engine |
packages/rule-toolkit |
The offline rule toolkit for experts (no code needed) |
packages/org-dashboard |
Placeholder for a later organization dashboard (no code yet) |
data/ |
Federal tables, state adapters with test cases, referrals |
scripts/ |
Data seeding and CI checks |
tooling/ |
Shared build tooling |
packaging/ |
Files shipped in the hosted and local downloads |
infra/ |
Reference static hosting on AWS (CDK) |
docs/ |
Privacy model, adapter guide, deployment, decisions (ADRs) |
wiki/ |
This wiki's source |
.kiro/specs/openbridge/ |
Requirements, design, and task plan |
.kiro/steering/ |
Coding and review standards |
More detail: .kiro/steering/structure.md and
Architecture.
- Read
AGENTS.md. Its rules apply to people as much as to AI agents. - Read
CONTRIBUTING.mdfor the branch, commit, and pull request workflow. - Pick an issue labeled
good first issueorhelp wanted, and comment that you are on it. - For rule data, start with Add or change a rule. For the engine, start with How the rules engine works.
OpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers