Architecture

Vicket splits cleanly between components you own (rendered on your domain) and a hosted data plane (run by us). The boundary is a stable REST API.

┌────────────────┐      ┌────────────────────┐
│  Your website  │ ───▶ │  Owned components  │
│  (any stack)   │      │  (in your repo)    │
└────────────────┘      └─────────┬──────────┘
                                  │  X-Vicket-Key: pk_...
                                  ▼
┌────────────────────┐      ┌──────────────────┐      ┌────────────────────┐
│  Agent dashboard   │ ◀──▶ │  Vicket API (Go) │ ◀──▶ │  Postgres + workers│
│  (hosted by us)    │      │  multi-tenant    │      │  event bus, SLA    │
└────────────────────┘      └──────────────────┘      └────────────────────┘

The components call the API directly from the browser with the site's publishable key. The backend enforces the site's origin allowlist (CORS) and per-site rate limits, so the key can ship in your bundle. See api-authentication.

Tenancy model

The hierarchy is org, then site, then resource. An org is the top-level tenant, typically one per company. A site is a branded customer-facing surface, typically one per product or per client. Statuses, priorities, workflows, tickets, articles, and FAQs all live inside an org; most can be scoped to specific sites.

This means an agency running support for ten clients creates one org and ten sites. A SaaS company with three products creates one org and three sites. See organizations-and-sites.

Data ownership

You own the presentation layer: every component the CLI installs lives in your repo and ships in your bundle. There is no Vicket iframe, no Vicket CSS, no Vicket JS loaded at runtime. Restyle, fork, or replace anything.

We own the data plane: Postgres storage, the API, the workflow runtime, the agent dashboard, auth (WorkOS-backed), and outbound notifications. You never run a database, never rotate JWT secrets, never page on disk space.

The contract between the two is the public REST API documented in api-endpoints.

Reliability

The API writes ticket events to Postgres in the same transaction as the resource change, so there is no separate event store to drift. A pool of workers polls the event table and drives the workflow engine, SLA timers, and outbound notifications. Every workflow run is recorded for audit.

The agent dashboard uses a session cookie (api-authentication) and authorizes every request against the roles-and-permissions matrix.