Developer guide
This guide is for people changing PULSE (Prescriptive Unified Lead & Social Engine) by Runink, or building against its API.
Architecture in one paragraph
A Go gRPC backend (grpc/) and a Flutter app (flutter/, web and Android)
talk over gRPC and gRPC-Web on one port. The backend keeps all its data
(every table, account, session and media file) in a sealed appfs root on the
cluster’s object store; there is no database, and one writer, so one
instance. All AI is the platform’s own: the model router in front of
Distro-built mistral.rs, TIDE’s ttsd for speech; no third-party model, no
vector index (product facts are read by direct corpus interaction). TIDE
builds nothing here but deploys it: its pulse-operator runs the instance in
pulse-system. See the Admin guide.
Repository layout
| Path | What it holds |
|---|---|
grpc/ | The Go backend, module github.com/org-runink/pulse (Go 1.26) |
grpc/main.go, grpc/cmd/ | The Cobra entry point and every service. cmd/serve.go wires everything together; cmd/rbac_policy.go holds every method’s least role. |
grpc/api/proto/pulse/v1/ | The .proto files, package pulse.v1, one or more services each |
grpc/api/proto-vendor/ | A verbatim copy of runink/ui/judgement/v1/judgement.proto, resolved but never generated |
grpc/api/v1/ | Generated Go code. Gitignored: run buf generate before the first build |
grpc/internal/ | ai, db, scoring, apply, metasearch, auditdeadline, skills, skillcheck, carousel, speech, connector clients (hubspot, github, googleanalytics, googleads, …), telephony, voice, webrtc, and more |
grpc/agents/ | Agent parameters (pulse.ini), prompt templates, and the content skills (skills/<channel>/<skill>/SKILL.md) |
grpc/data/corpus/ | The product-fact files generation is grounded in, read directly by search and file read |
grpc/tools/ | arbguard (the arb keys CI check, its own module) and apidoc (generates the API reference) |
flutter/lib/ | The Flutter app: core/ (gRPC channel, generated stubs, theme) and features/ (one folder per screen) |
website/ | This documentation site (Hugo + Hextra, theme vendored) |
The platform pieces are not here. Self-healing, the event mesh, secrets and PKI, the object store, the inference engine, the operator, and infrastructure code live in Runink TIDE or in the shared libraries. Never add them to this repository.
Build and test
You need Go 1.26+, buf with local protoc-gen-go, protoc-gen-go-grpc
and protoc-gen-dart on your PATH (remote BSR plugins silently write
nothing), and Flutter 3.44.2. The backend builds only with the sibling
repositories checked out next to pulse/: inference, security, mesh,
store, crawler, ui, billing and ml.
# from the repository root
buf generate grpc/api/proto --template grpc/buf.gen.yaml -o grpc # Go (gitignored)
buf generate grpc/api/proto --template grpc/buf.gen.dart.yaml # Dart (committed), no -o
cd grpc && go build ./... && go vet ./...
cd grpc && TIDE_ENVELOPE_KEK="$(head -c32 /dev/urandom | base64 -w0)" go test ./...
cd flutter && flutter pub get && flutter analyze && flutter testThe tests need TIDE_ENVELOPE_KEK because the store refuses to open without
the key that seals stored credentials; any 32 random bytes, base64 encoded,
will do. The server is pure Go, so no C toolchain is needed. After a dependency
change, run sh scripts/gen-third-party-notices.sh.
Nothing in this repository needs a secret or a private tool to build or test: an outside contributor with the siblings checked out runs exactly the commands above, and CI runs the same ones.
GOWORK file outside the
repository at it. Don’t switch a shared checkout.To run the backend, see Run PULSE locally.
Regenerate the protobuf code
Run the two buf generate commands above from the repository root, and
always pass the grpc/api/proto input:
- The Go run needs
-o grpc, or the code lands at the repository root. - The Go run does not generate Dart, and nothing tells you. Skip the second and the app compiles against the old messages, and a new field reads as null on the client.
- The Dart output under
flutter/lib/core/grpc/is committed. Commit it with the proto change. grpc/buf.gen.go.yamlis a Go-only template for a machine with no Dart SDK. It writes intogrpcitself, so run it from the repository root with the samegrpc/api/protoinput and no-o.- Running
buffrom insidegrpc/picks up a competingbuf.yamland breaks import resolution. - When
uichangesjudgement.proto, copy it again intoproto-vendor/.grpc/cmd/judgement_vendored_test.gofails until you do.
Regenerate the API reference
The service pages of the API reference are generated
from the protos and cmd/rbac_policy.go. After changing either:
cd grpc && go run ./tools/apidoc # rewrite the pages
cd grpc && go run ./tools/apidoc -check # exit 1 if a page is staleEach page keeps its hand-written introduction above the generator’s marker
line; everything below it is rewritten. TestAPIReferenceIsCurrent (in
go test ./...) fails while a page is stale, and the generator refuses a
service that no page lists or a method with no role, so a new RPC cannot ship
undocumented. To place a new service, add it to pages in
grpc/tools/apidoc/render.go.
The app’s backend address
The Flutter client reads PULSE_BACKEND_URL from a --dart-define. It is
resolved in this order:
- the
--dart-define, baked in at compile time; - on native,
http://localhost:50051.
A deployment sets the define to the backend’s https address when it builds the
Android and iOS app. The backend serves no web bundle (PULSE ships as an Android
and iOS app), so a production backend also needs CORS_ALLOWED_ORIGINS set to
pinned origins or it refuses to boot.
Shared UI components
Pages that more than one Runink app shows come from org-runink/ui: design
tokens and transport (foundation), billing, datasources, profile,
access, voice, comms, and judgement. PULSE mounts the Go handler with
its own hooks and depends on the Flutter package by path. To try an unmerged
ui branch, use a private GOWORK and a gitignored
flutter/pubspec_overrides.yaml.
Rules for contributions
PULSE is proprietary.
- New files start with an SPDX header:
SPDX-License-Identifier: LicenseRef-Runink-Proprietary.
- Never call a third-party model or AI API, and never add a vector index or
similarity search (
cmd/no_rag_guard_test.gofails). Model output is TOON, never a JSON-schema wrapper, and the plan gate judges what a model proposes before it is saved. - Nothing may publish while
PULSE_APPLY_ENABLEDis off; a new outward channel gets its ownPULSE_PUBLISH_<CHANNEL>key. See Switches and arming order. - A figure PULSE could not read is shown as not measured, never as 0.
- No Python and no YAML or go-toml import anywhere in the tree (tests enforce both).
- Release builds stay hardened: Go
-trimpath -ldflags="-s -w", Flutter web--no-source-maps.
Pull requests and CI
Branch from origin/main and open a pull request against main; the owner
squash-merges. These checks run:
| Workflow | Job | What it checks |
|---|---|---|
ci.yml | backend | Checks out the siblings, runs buf generate, go vet ./..., go build ./..., go test -race ./... (which includes TestAPIReferenceIsCurrent) |
ci.yml | frontend | flutter analyze and the gated flutter test with measured floors |
ci.yml | arb keys (pull requests) | grpc/tools/arbguard: fails when the pull request drops a translation key the base branch has, unless it is declared in flutter/lib/l10n/removed_keys.txt |
license-policy.yml | licence policy | Fails on stale third-party notices or a denied licence |
sovereignty.yml | The shared blocklist of external-AI SDKs and removed dependencies, applied to every pull request | |
gatekeeper.yml | gatekeeper | Lint and policy checks |
tide-code-review.yml, tide-agent-triage.yml, tide-agent-selfheal.yml | TIDE’s review, triage and self-heal agents |
The review agent runs when a pull request is opened or pushed to. To ask for a
review again, comment @tide_check once on the pull request
(@tide_review, @core_check and @core_review are still accepted).
How a change ships
A merge to main triggers cd-backend.yml: it builds the pulse-backend
image (backend and web app together) and rolls the one pod in pulse-system
when the image digest changed. It also rebuilds every night, because the
shared ui components compiled into the image are outside its path filter.
The commit production runs is stamped on the live PulseControlPlane as
runink.org/commit; see
How a change reaches production.
Cluster topology and the operator’s resource belong to TIDE: change those in
TIDE, never the live Deployment.
The backend image
grpc/Dockerfile builds the image from the repository root. Its base images
come through the BASE_REGISTRY build argument,
each pinned by digest; the image has no Flutter stage. See
Image build arguments.