Contributing
Coding standards
A digest of the practices that govern Go, MCP, React, the phone app, testing, and visual design in this repo.
This page is a digest. The full standard is the set of files in
practices/ in the
repository, one file per language or surface, and every pull request is
reviewed against those files. Read the file for the language you are touching
before writing code; this page tells you what to expect from it.
Go
Full text: practices/go.md
and practices/architecture.md.
- Interfaces are defined at the consumer side (
EventBuslives where the domains that call it live), kept small (1–3 methods), and returned as structs, accepted as interfaces. - Sentinel errors (
ErrNotFound,ErrConflict,ErrUnauthorized), wrapped with context at the boundary; event handlers distinguishErrRetryablefromErrFatal. log/slogonly — no third-party logger, nofmt.Println. Every request or message handler carries atrace_id-scoped child logger throughcontext.Context.- Constructor injection, no global singletons, no DI framework.
- Table-driven tests with
testify(requirefor preconditions,assertfor checks). - Queries are hand-written
.sqlfiles;sqlcgenerates the typed Go. See ADR 0009. - SQLite has one writer: every write goes through the storage serializer,
transactions begin
IMMEDIATE, pooled connections stay warm, and lists paginate in SQL, by keyset or behind the MCP offset contract, with indexes that carry their tiebreaker. - Loops that deliver committed rows wake on the serializer’s commit
broadcast instead of polling, and a slow client gets its own bounded send
queue so it never stalls the others. Packages that start goroutines guard
them with
goleak. - Everything a client reads (HTTP, MCP, live frames, and the event payloads
webhooks and automations receive) encodes through one JSON encoder,
jsonx, so an empty list is always[]; long lists encode through plain wire structs. - Event schemas are generated from each topic’s payload type with
make event-schemas, and a contract test fails on any change that would break a consumer, so the published catalog only grows. - Access answers are memoised per request and dropped at every commit, so a list never needs its own permission cache. A list that pages filters by access in its SQL, reads one page of rows, and reports a total that counts exactly what the pages hold.
- The architecture guide opens with three principles: a one-way door is a bug, build the smallest model that makes behavior unsurprising, and keep complexity in the adapters.
MCP
Full text: practices/mcp.md.
The MCP server runs on the official Go SDK behind one stateless endpoint,
POST /mcp, and domains declare tools through a typed contract instead of
importing the SDK. Tools are shaped per task and kept under a budget a test
enforces: one-field setters fold into patch-style updates, list variants into
filtered lists. Names are <object>_<verb> in the glossary’s words, every
parameter is described, every tool carries read-only and destructive hints,
lists page in SQL with an honest total, a call to a tool that changes
something writes an audit row, and a tool’s failure comes back as an
isError result that says how to recover.
React (the Frontend Commandments)
Full text: practices/react-guide.md.
F1–F7 are hard rules for anything in web/ — a PR that breaks one is not
done, regardless of what nearby code does:
- F1 — Page → Feed → Section → Card. Every screen decomposes into named,
single-responsibility components; no inline
.map()rendering a<section>or large JSX block. - F2 —
&&, negative-first. Loading → error → empty → data, each its own&&block. Noif (x) return <Component/>for rendering. - F3 — Shared display components.
LoadingDisplay,ErrorDisplay,NoDataDisplay,Container— never hand-rolled equivalents. - F4 —
&&for components, ternaries only for values. Never a ternary choosing between two components. - F5 —
useState/useEffectare a last resort. Server state lives in TanStack Query, cross-surface state in Zustand, form state in React Hook Form; effects are for real side effects only. - F6 — No prop drilling. Past ~2 levels, the child fetches its own data or reads a store instead.
- F7 — Files own one concern. Pages stay thin; sub-components live in
components/<domain>/.
Live data follows a few rules of its own. Each domain’s hooks file exports a
live follower that decides what a pushed frame changes in that domain’s
cache. The server’s audience rules and the topics the followers follow are
pinned together: make live-topics regenerates the topic list and tests on
both sides fail when they drift, so a new live topic ships with its rule,
the regenerated list and a follower. A frame that carries the entity patches
the cache from its payload; otherwise only the queries its ids name refetch.
Every ticket view goes through one cache module, and a page’s batch reads are
keyed by project rather than by every id. Every page is its own chunk that
the shell never imports, and rows of a live list are memoised components
with stable props.
Every control that changes something is drawn by an action component, which
hides it or shows it locked with the reason from the viewer’s permissions. The
permission is a typed value from make permission-catalog, so a misspelt one
fails typecheck. Every request that writes declares the permission its route
checks, and a test reads those declarations against the server’s route table.
The phone app
Full text: practices/native.md.
The Expo app inherits the web guide, F1–F7 included, with a Screen in place of a Page. Every query is one declaration naming the topics that refresh it, typed against the event catalog, and the live dispatcher and stale times are derived from those declarations; a query cached until pushed with no topic fails typecheck. Chat frames patch the cached thread; record queries are matched by id or key through one helper; the session token is read once at launch; and icons import by path, which a lint rule enforces.
TypeScript outside the browser
Full text: practices/typescript.md.
The SDK and the automations host run on Bun and test with bun test; the
desktop shell is Electron with the same strictness flags as the web app and
the Electron security checklist (context isolation on, node integration off,
a preload bridge with an explicit allow-list) stated as absolutes.
The same file covers client-core/, the code the web and phone apps both
run (the permission table, chat and embed rules, people, the live socket,
the query retry rule). It is a folder, not a package, imported by full path
as @nexul/client-core/<module>; it holds no React and no platform API, and
its tests run once, in the web’s job.
Testing
Full text: practices/testing.md.
Coverage (80% gate, 90% target) is a floor, not a goal — error paths, state transitions, and idempotency come before happy paths. Mock at the interface boundary; prefer fakes over mocks for repos. A flaky test is a bug: fix it or delete it, never skip or retry-mask it, and async code is tested by draining, never by sleeping. A performance fix ships with a guard test that fails when the fix is reverted, and its numbers come from a production or release build on realistic data. A test that only restates the types or the implementation, cannot fail, or duplicates another goes, one package per pull request with before and after counts and timings; the enforced guards and the auth, permission, storage and event suites stay unless the owner agrees.
Design language — frosted panels and one ember accent
Full text: practices/design-language.md.
One design language covers the web app, the public site and the phone app:
the file opens with a shared core and has a section per surface. In the web
app every page’s content floats in a raised, frosted panel over a near-black
canvas that carries a soft light field; light mode is its own soft grey
canvas with white panels. One ember accent, the brand token, marks the
primary action, the active nav item, selection, your own chat messages,
checked controls and progress, and nothing else; focus is an ink outline, and
status keeps its own hues as a dot or icon beside plain text. Page titles are
set in Fraunces, technical data (ids, repos, timestamps) in JetBrains Mono,
everything else in Inter. The public site uses the same tokens and roles:
website/src/styles/tokens.css maps the app’s values onto the docs theme, and
reading pages keep their text on the canvas. The phone app carries the same
tokens in native/src/global.css, on solid surfaces with no blur. When a
design needs a new token, add it to every surface’s token file that uses it
(web/src/index.css, website/src/styles/tokens.css, native/src/global.css);
never a one-off colour.
What enforces the rules
A rule a linter can check is checked by a linter. Go runs golangci-lint
(config in .golangci.yml) and govulncheck in CI and through make lint
and make vuln; the coverage gate is make coverage; sqlc vet and
sqlc diff keep generated code honest. Every TypeScript package runs its
typecheck and test scripts in CI, and Dependabot opens grouped weekly
update pull requests per directory. Tests guard the rest: the live topic
contract, the event-schema contract, the JSON encoder’s parity with the old
output, memoised access answering what an unmemoised check does, list tools
showing each viewer what the row-by-row check showed and reading one page of
rows, every changing route writing an audit row, goroutine leaks, the web
shell’s import graph, and the requests a live frame or a phone session
sends. On the phone, a query cached until pushed with no topic fails
typecheck, and a lint rule keeps icons imported by path and the SDK’s event
types imported as types only.
Hard rules from AGENTS.md
These apply everywhere, regardless of surface:
- Early return, no
else. In Go and TypeScript alike — handle the exceptional case and return, leave the happy path unindented. - No barrels. No
index.tsre-export files. Import by full path. - Structured logging.
slogin Go, console with a propagatedtrace_idin TypeScript. Nofmt.Println, noconsole.login production code. - Comments are sparse. Default is no comment. One exists only to say a why, a non-local warning, or a pointer — never to restate the code, never a change-history note, one line, and no commented-out code.
- Tablet and desktop. Build the web app at 768px first and verify at 768 / 1024 / 1440px before calling web work done; phones are served by the Android app. The website stays mobile-first at 320 / 375 / 414px.
- Fast by default, kept fast by a test. Lists page and filter by access in SQL, clients refresh only what a frame names, background loops wait on the commit broadcast instead of polling. A performance fix ships with a before and after number from a production build and a guard test that counts something deterministic.