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. The version is in
.nvmrc. Node 22.12 or newer also works. With nvm, runnvm usein the repository folder. - Git, and a fork or clone of the repository.
-
Get the code and install exactly what the lockfile lists:
git clone <this-repo-url> openbridge cd openbridge nvm use npm ci
-
Start the app in development mode:
npm run dev -w @openbridge/web-app
Open http://localhost:5173. The dev server listens only on your own computer.
-
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 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/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 |
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