Skip to content
PromptGlassDocs

Architecture

PromptGlass has three layers. Sensors observe AI usage. The control plane classifies, enforces policy and attributes each event to a person. The analytics plane stores events and computes adoption, efficiency, cost and risk. The same architecture runs in SaaS, on your Kubernetes cluster, or air-gapped.

Component diagram

Section titled “Component diagram”
                       ┌────────────────────────── Sensors ──────────────────────────┐
  Browser AI apps ───▶ │ Browser extension   (prompts, pastes, uploads, coaching UI) │
  Desktop / IDE AI ──▶ │ Endpoint agent      (app discovery, local models, IDE use)  │
  Web & API traffic ─▶ │ Gateway             (forward proxy + OpenAI/Anthropic API)  │
  Vendor admin APIs ─▶ │ SaaS connectors     (M365 Copilot, OpenAI, Anthropic, ...)   │
                       └──────────────┬──────────────────────────────────────────────┘
                                      │  events (gRPC/TLS 1.3, mTLS for agents)
                       ┌──────────────▼───────────── Control plane ──────────────────┐
                       │ API ─ Policy engine ─ Detector workers ─ Identity resolver   │
                       │            │                 │                  │            │
                       │            └──── NATS event bus (JetStream) ────┘            │
                       └──────────────┬──────────────────────────────────────────────┘
                                      │
                       ┌──────────────▼───────────── Data plane ─────────────────────┐
                       │ PostgreSQL     tenants, users, policies, connectors, audit   │
                       │ ClickHouse     usage events, detections, tokens, cost         │
                       │ Object store   encrypted prompt/response content (S3 API)    │
                       └──────────────┬──────────────────────────────────────────────┘
                                      │
                       Console (web UI) · REST API · MCP server · SIEM / webhooks / export

Request path through the gateway

Section titled “Request path through the gateway”

When a sensor can act inline (the gateway, and the browser extension for web apps), the policy decision happens before the prompt leaves your network:

  1. The sensor intercepts the request and pulls out the prompt text, attachments and metadata (app, model, user and device).
  2. The detector pipeline runs in the gateway process: fast regex and checksum detectors first, then dictionaries and exact-data-match hashes, then ML classifiers when a rule needs them.
  3. The policy engine evaluates the rules in order and returns one action: allow, log, coach, redact, block or route.
  4. The sensor applies the action. For redact it replaces sensitive spans with tokens such as [PERSON_1]. It can restore them in the response if the policy allows.
  5. An event goes to NATS asynchronously, so the user’s request never waits on storage.

Connectors and the endpoint agent are observe-only. They produce the same event shape, but they can’t block, because the traffic didn’t pass through PromptGlass.

Event model

Section titled “Event model”

Every interaction becomes one event:

Field Example Notes
event_id evt_01JD4… ULID
ts 2026-11-02T14:03:11Z
sensor gateway / extension / agent / connector:m365
actor.pid u_7f3a… Pseudonymous ID. The real identity is held separately.
actor.department, actor.cost_center Finance, CC-410 From SCIM
app chatgpt, claude, m365-copilot From the AI app catalog
model gpt-4.1, claude-sonnet-4-5 When known
tokens.in, tokens.out, cost.usd 812, 410, 0.0061 Measured at the gateway, estimated elsewhere
detections[] [{class: pci.card, count: 1}]
action redact
content_ref s3://…/evt_01JD4….enc Only if the storage mode keeps content
topic contract-review Clustered use-case label

What is stored where

Section titled “What is stored where”
Store Holds Encryption
PostgreSQL Configuration, policies, users, identity mapping, admin audit log At rest by the database; the identity mapping is also encrypted at the application layer
ClickHouse Event metadata, detections, token counts and cost. No prompt text. At rest by disk or volume
Object storage Prompt and response content, when the storage mode is full or redacted Envelope encryption: a per-tenant data key wrapped by your KMS or HSM key

The storage mode decides how much content is kept: full, redacted, metadata-only or hashed. You set it per policy rule. See data residency and retention.

Scaling characteristics

Section titled “Scaling characteristics”
  • Gateway: stateless and scaled horizontally with an HPA. Detector models load into memory at startup.
  • Detector workers: run deep classification asynchronously for observe-only sensors and connectors.
  • ClickHouse: a single node is enough for most organizations. Use a replicated cluster for HA. See high availability.

Failure behavior

Section titled “Failure behavior”

Each policy sets on_error: fail_open (default) or fail_closed. If the gateway can’t reach the policy engine or a detector times out, fail_open forwards the request and records a degraded event. fail_closed blocks it with a clear message to the user. Regulated data classes usually use fail_closed.