Skip to content
Developer guide

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

PathWhat 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 test

The 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.

Sibling checkouts may be on another branch. To build against a specific sibling version, add a worktree of it and point a 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.yaml is a Go-only template for a machine with no Dart SDK. It writes into grpc itself, so run it from the repository root with the same grpc/api/proto input and no -o.
  • Running buf from inside grpc/ picks up a competing buf.yaml and breaks import resolution.
  • When ui changes judgement.proto, copy it again into proto-vendor/. grpc/cmd/judgement_vendored_test.go fails 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 stale

Each 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:

  1. the --dart-define, baked in at compile time;
  2. 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.go fails). 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_ENABLED is off; a new outward channel gets its own PULSE_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:

WorkflowJobWhat it checks
ci.ymlbackendChecks out the siblings, runs buf generate, go vet ./..., go build ./..., go test -race ./... (which includes TestAPIReferenceIsCurrent)
ci.ymlfrontendflutter analyze and the gated flutter test with measured floors
ci.ymlarb 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.ymllicence policyFails on stale third-party notices or a denied licence
sovereignty.ymlThe shared blocklist of external-AI SDKs and removed dependencies, applied to every pull request
gatekeeper.ymlgatekeeperLint and policy checks
tide-code-review.yml, tide-agent-triage.yml, tide-agent-selfheal.ymlTIDE’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.