Docs/Contribute
Development
How to run HelpBites from source, find your way around, change it safely and get a change merged. HelpBites is in
public beta and moves quickly: main is always releasable, and CHANGELOG.md is the history.
Read CONTRIBUTING.md (licenses, the CLA, the rules of the road) before your first pull request.
What you need#
- Bun 1.x. It is the package manager, the script runner, the test runner and the production runtime.
- Docker with the Compose plugin, for MongoDB, Parse, Redis, Meilisearch and the bucket.
- Optional: Xcode 16 and XcodeGen for the native app.
Run it#
git clone https://github.com/elrumo/help-bites-oss.git && cd help-bites-oss
cp .env.example .env # the defaults already target the dev stack below
docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev \
up -d sb-mongo sb-parse sb-redis sb-meili sb-rustfs
bun install
bun run schema:apply # Parse classes, permissions, indexes (idempotent)
bun run search:setup # Meilisearch indexes and settings (idempotent)
bun run dev # http://localhost:3100The first visit asks you to create the operator account. The dev overlay publishes the services on localhost: Parse
:1337 (dashboard :4040, login admin/admin), Redis :6379, Meilisearch :7700, RustFS :9000/:9001. It is only
for development, never for production.
Useful extras:
bun run seed:knowledge # a demo knowledge model (against the running app)
bun scripts/dev-token.mjs <projectId> <userId> "Demo user" demo@example.com # an identity token, no host code
bun run reindex # rebuild the search index
bun run add-agent # another operator, from the CLI/demo serves the panel against canned data with no backend (app/utils/demoApi.ts): the quickest way to check a UI
change. The API reference is at /_docs/scalar; your own AI, email and GitHub setups are in Setting things up.
To run the real image instead, from your checkout: docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.
Checks#
| What | When | |
|---|---|---|
bun test |
Unit tests, the features map, the tenancy guard, the edition boundary, the native parity tests. No services needed apart from an optional Redis (REDIS_TEST_URL) for the usage counters |
Before every push |
bun run smoke |
End to end against the running stack | After changing a flow |
bun run smoke:isolation |
One workspace can never reach another's data | Whenever you touch an admin route |
bun run build |
The production build | Before a release; CI does it on every PR |
bun scripts/check-edition-build.mjs community |
The build holds no ee/ code |
CI does it |
CI (.github/workflows/ci.yml) runs the tests and the build on every pull request.
The layout#
app/ the Nuxt panel and the public pages (landing, docs, embeds)
pages/ routes; project sections are listed in app/utils/projectSections.ts
components/ UI; app/components/settings holds the settings tabs
utils/demoApi.ts canned data behind /demo
server/
routes/v1/** the API, one file per route, each with defineRouteMeta({ openAPI })
utils/ the logic: tenancy, auth, conversations, email, AI gateway, MCP tools
plugins/ boot-time checks and schedulers
shared/ TypeScript that the server and the panel share; ported by hand to Swift
public/*.js the drop-in scripts host sites include (MIT): widget.js, feedback.js, changelog.js …
cli/ `helpbites changelog` (MIT)
helpbites-native/ the SwiftUI iPhone, iPad and Mac app
scripts/ schema, search, migrations, seeding, smoke tests
docs/ these guides; shared/docs.ts picks which ones publish at /docs
i18n/locales/ en (required, the fallback), ca, es, ja, ko, zh
features.json the machine-readable map of what the product does
ee/ the hosted service's commercial layer. Not in this repositoryThree things worth knowing early:
- Parse is the database layer. Data lives in MongoDB behind Parse Server;
scripts/ensure-schema.mjsdeclares every class, permission and index and is safe to run any time. A schema change is a change to that file and a line in the changelog. - Everything is workspace-scoped. A workspace owns projects. Admin routes go through
requireMember/requireProjectand thescoped.*getters inserver/utils/tenancy.ts;tests/tenancy.guard.test.tsfails the build on a route that does not. - Two editions, one codebase. Community is everything here, unlimited. Cloud adds sign-up, plans and billing from a
private layer through the seams in
server/utils/edition.tsandapp/utils/editionUi.ts. Core never imports fromee/(Editions).
Adding a feature#
CLAUDE.md is the checklist, and it applies to people as much as to coding assistants. In short, a feature is done when it has:
- An edition decision (community and cloud by default), written into
features.json. - Web and native: a page under
app/pages/and a screen underhelpbites-native/App/Features/<Area>/, or the gap written down infeatures.json(notBuilt) and FEATURES.md §14. Anything both need goes inshared/, with a parity test where Swift copies constants (seetests/emailNativeParity.test.ts). - An API: routes under
server/routes/v1/**with OpenAPI metadata, accepting an operator session or anak_key, and an MCP tool inserver/utils/mcp/tools.tsplus a row in MCP.md (tests/mcpCoverage.test.tschecks). - A guide in
docs/(add it toshared/docs.tsto publish it), with curl examples, and for anything end users see a drop-in<script>inpublic/and a Swift snippet. - Strings through
$t()ini18n/locales/en.json(add the other five when you can). - Its entry in
features.json,docs/FEATURES.md, a line under Unreleased inCHANGELOG.md, and a decision on the landing page (landing.listed; the page and itslanding.*words are in the cloud repo).
tests/features.test.ts fails when features.json names a file, route, doc or key that does not exist.
The native app#
helpbites-native/ is one SwiftUI target for iPhone, iPad and Mac (iOS 18, macOS 15), generated by XcodeGen.
cd helpbites-native
xcodegen generate # after adding or removing files
open HelpBitesNative.xcodeprojSet APP_BASE_URL in Config/Debug.xcconfig to your server (the simulator default is http://localhost:3100; a device
needs an HTTPS tunnel or your LAN address) and your team in project.yml, then run the HelpBitesNative scheme. The share
extension needs the App Group group.com.helpbites.operator on both targets. The app's version is MARKETING_VERSION in
project.yml, kept equal to package.json by a test. More in helpbites-native/README.md.
Conventions#
- Match the surrounding code: comment density, naming, idiom. No new dependency for something a few lines can do.
- Comments say why, not what. Tests sit in
tests/and are named for what they protect. - Public scripts (
public/*.js) have no dependencies and start with the SPDX header; they must work from one tag with onlydata-project="pk_…". - Errors are
createError({ statusCode, statusMessage })with a message a person can act on. - Pull requests are small and say what and why. The template asks for
bun test, workspace scoping and the CLA.
Releasing#
Maintainers: RELEASING.md covers the version, the tag, Docker Hub and the public changelog.