Concepts

The top-level container. One billing relationship, one set of members, one set of encryption keys, one set of AI provider keys.

Members have a role: owner (everything), admin (everything except billing), or member (read-only on most resources; can submit manual actions on Directives).

A product you collect signals for. Each App has a unique publicKey (starts with pub_) the widget authenticates with, and a per-App private-mode signing secret used to verify customer-issued JWTs.

A connected source-control repository linked to one App. PRs land on a configurable branch prefix (default userz/). Two providers are supported today:

• GitHub: install the Userz GitHub App; we mint short-lived installation tokens scoped to a single repo per agent run.
• GitLab: supply a project access token (or per-project OAuth token); stored encrypted at rest, decrypted only in memory at run time. Self-hosted GitLab is supported via a per-Repo baseUrl override.

The universal unit of input. Everything that enters Userz is a Signal — a widget submission, a connector message (Slack/Discord/Linear/GitHub/…), embedded telemetry, a manual-API push, even an in-product chat message. A Signal carries its content (text, optional severity, attachments, console logs, component target) plus provenance — the source kind, connector, and a deep-link back to where it came from.

A Signal runs a short FSM: received → sanitizing → sanitized (or flagged / spam / noise) → archived. The engine then evaluates each sanitized Signal — scoring it, connecting it to related signals, and promoting or attaching it to a Directive.

The universal unit of work — the thing the agent executes. A Signal (or a cluster of related signals) promotes to a Directive; related signals that arrive later attach to it, so its signalIds grow over its life. One Directive yields one PR.

Each Directive has a scale — quick / standard collapse to a single Worker, while planned / epic add an Orchestrator plus per-milestone Validators — and a unified status FSM (pending_triage → … → succeeded / failed). It carries the goal, an optional owner brief, per-role budget, and the opened PR URLs.

End-users can press Ctrl+Shift+S in the widget to capture several reports at once — up to 25 items, each with its own text, severity, screenshot, and target metadata — which arrive as a single Signal with multiple items.

Across signals, the engine connects related ones (embedding similarity, same conversation, same error fingerprint) and groups them into a SignalCluster. A cluster promotes to one Directive carrying every constituent Signal — so twenty reports of the same bug become one PR, not twenty. Each Signal keeps its own identity and provenance for back-linking to the reporter.

One execution of the AI agent. Append-only audit row recording which provider + model ran, tokens consumed, estimated cost, the resulting PR URL or rejection reason, and per-step timings. The full run log is retained for replay from the dashboard.

After the agent opens a PR, you can request revisions inline. Each PR has a Review conversation that the agent reads on the next iteration; per-line diff comments become part of the next run's context. The agent re-runs and commits on top of the same branch. Each plan caps the number of round-trips per PR.

Per-Org credential for the REST API (sk_…). The plaintext is shown exactly once at creation, we store only a salted, slow-hashed digest. Use it from your backend to read Directives, push Signals, manage apps, etc.

One row per (Org, kind, external-team) where kind is slack or discord. Stores the connection's credentials, encrypted at rest. App-level routing (which channel each App's events post to) lives on the App.

Mirror of the Org's Stripe subscription. We read this row in hot paths during agent runs and signal intake, so a Stripe outage doesn't block customer traffic. Billing webhooks keep it in sync.

Userz is bring-your-own-key across four providers — Anthropic, OpenAI, Moonshot (Kimi), and z.ai (GLM). Each Organization picks an agent model (the one that writes PRs) and a helper model (the one that sanitizes, summarizes, and builds context) independently, so you can pair an inexpensive helper with a powerful agent. Token-quota customers fall back to their own keys once the included quota is exhausted; pure-BYOK customers never touch the quota.