Architecture

BitDrip is a self-hosted system with two deployment tiers: a server tier that runs centrally on your infrastructure, and a workstation tier that runs on each end-user device.

Two-Tier Model

┌─────────────────────────────────────────────────────────────┐
│ Your Server (one per organisation)                          │
│                                                             │
│  ┌──────────────────────┐   ┌──────────────────────────┐   │
│  │   Policy Engine      │──▶│   PostgreSQL             │   │
│  │   :3002              │   │   Audit + config         │   │
│  └──────────────────────┘   └──────────────────────────┘   │
│           │                 ┌──────────────────────────┐   │
│           └────────────────▶│   Redis                  │   │
│                             │   Policy cache           │   │
│  ┌──────────────────────┐   └──────────────────────────┘   │
│  │   Dashboard :3000    │   Admin UI                        │
│  └──────────────────────┘                                   │
└─────────────────────────────────────────────────────────────┘
                    ▲
                    │  Evaluation requests + heartbeats
                    │  (content hash, policy decision)
                    │
┌─────────────────────────────────────────────────────────────┐
│ Each End-User Workstation                                   │
│                                                             │
│  ┌──────────────┐     ┌──────────────┐  ┌──────────────┐   │
│  │   Browser    │     │  CLI / SDK   │  │  Tray App    │   │
│  │  (any)       │     │   Tools      │  │  (control)   │   │
│  └──────┬───────┘     └──────┬───────┘  └──────┬───────┘   │
│         │ PAC file           │ system proxy     │ manage    │
│         └─────────┬──────────┘                 │           │
│                   │ HTTPS (intercepted)         │           │
│         ┌─────────▼─────────────────────────────▼─────┐    │
│         │             Proxy Daemon                     │    │
│         │  :3001  MITM TLS · PAC server · cert install │    │
│         └─────────────────────┬─────────────────────────    │
│                               │                             │
└───────────────────────────────┼─────────────────────────────┘
                    │
                    ▼
         LLM Provider (OpenAI, Anthropic, etc.)
         — LLM traffic goes direct, never via your server —

The proxy daemon runs on each workstation, not on the server. Each workstation's proxy daemon intercepts AI traffic locally and sends evaluation requests to the central policy engine. The actual LLM conversation travels directly from the workstation to the LLM provider — your server never carries LLM traffic.

Server Components

Policy Engine

The core service. Evaluates content against your organisation's compliance rules and returns block/warn/log decisions.

Responsibilities:

• Rule evaluation — regex patterns, entity detectors, custom rules
• Audit logging — every evaluation written to PostgreSQL with a SHA-256 hash chain
• User and organisation management — REST API for users, roles, API keys
• License enforcement — validates license.jwt on startup via native C++ addon
• Redis caching — compiled rule sets cached to keep evaluation latency under 100ms

Port: 3002

Dashboard

A React SPA served by nginx. Communicates with the Policy Engine API.

Responsibilities: Policy configuration, compliance reports, audit log viewer, user management, fleet health, CA lifecycle management.

The dashboard has no backend of its own — all data comes from the Policy Engine API.

Port: 3000

PostgreSQL

All persistent state:

Table	Purpose
organizations	Tenant records, license tier
users	User accounts, roles, hashed passwords
user_sessions	Active JWT sessions
api_keys	Hashed API keys with per-key rate limits
audit_logs	Immutable evaluation log with SHA-256 hash chain
policies	Custom policy rules per organisation
compliance_profiles	Active compliance framework per organisation
workstations	Enrolled devices and heartbeat state
ca_events	CA rotation and lifecycle audit trail

Redis

Cache only — no data that cannot be reconstructed from PostgreSQL:

Key pattern	TTL	Content
policy:{orgId}	5 min	Compiled rule set
ratelimit:{userId}	1 min	Request rate counter
session:{jti}	Session expiry	Active session marker

Redis failure causes cache misses (slower evaluation) but no data loss.

Workstation Components

Proxy Daemon

Runs on each end-user machine. All HTTPS traffic to AI services passes through here.

Responsibilities:

• MITM TLS termination — intercepts HTTPS connections using a locally-installed CA certificate and presents a dynamically signed certificate for each AI domain
• PAC file serving — http://localhost:3001/proxy.pac routes traffic from browsers, CLI tools, and API clients automatically via system proxy settings
• Content evaluation — decrypts the request body and sends it to the Policy Engine before the request reaches any AI service; the policy decision is made locally and the request is either blocked (HTTP 403 returned immediately) or forwarded to the upstream AI API
• Heartbeat — status ping to the Policy Engine every 5 minutes

Port: 3001 (on the workstation)

The proxy daemon is stateless. It holds no audit state — that is the Policy Engine's responsibility.

Tray App

Desktop application (macOS, Windows, Linux) that manages the proxy daemon on each workstation. Provides start/stop controls, routing toggle, CA certificate status with expiry alerts, and one-click daemon updates via the system tray. All tray actions are equivalent to bitdrip CLI commands.

CA Certificate Trust Chain

A local CA must be generated and installed on each workstation before the proxy daemon can intercept HTTPS traffic.

bitdrip cert generate
  └─► CA keypair generated — private key stored in OS keychain via keytar
      (private key never leaves the workstation — NIST SP 800-57)

bitdrip cert install
  ├─► macOS: security add-trusted-cert (System Keychain)
  ├─► Linux Debian/Ubuntu: /usr/local/share/ca-certificates/ + update-ca-certificates
  ├─► Linux RHEL/Fedora: /etc/pki/ca-trust/source/anchors/ + update-ca-trust
  ├─► Firefox: certutil → NSS database (~/.mozilla/firefox/*/cert9.db)
  └─► Chrome: certutil → NSS database (~/.pki/nssdb)

One-time setup per workstation.

The CA private key never leaves the workstation. It is not uploaded to the Policy Engine, the portal, or any remote service. Only the CA public certificate is shared (with the OS trust store and browsers). This means each workstation has its own CA — there is no shared root key across your fleet.

Request Lifecycle

1. Browser or CLI tool sends HTTPS request to api.openai.com
2. PAC file routes the connection to proxy-daemon :3001 (on the workstation)
3. Proxy daemon presents a dynamically signed certificate for api.openai.com
4. Proxy daemon decrypts the request body
5. Proxy daemon POSTs body to Policy Engine :3002 (on the server)
6. Policy Engine:
   a. Checks Redis cache for compiled rule set
   b. Evaluates content against active compliance profile
   c. Writes audit record to PostgreSQL
   d. Returns: { action: "block"|"warn"|"allow", riskScore, matchedRules }
7. If block: proxy returns HTTP 403 to the caller
   If allow: proxy re-encrypts and forwards to the upstream AI API
   (LLM traffic goes direct — never via your server)

Target round-trip: < 100ms

Port Summary

Component	Port	Runs on
Dashboard	3000	Server
Policy Engine	3002	Server
Proxy Daemon	3001	Each workstation
PostgreSQL	5432 (internal)	Server
Redis	6379 (internal)	Server

License Validation

On startup, the Policy Engine loads license.jwt and validates it using a native C++ addon:

1. Verifies the Ed25519 signature against Anchor Cyber Security's embedded public key
2. Checks the expiry claim (exp)
3. Phones home to portal.bitdrip.app to verify license status and register the deployment fingerprint

The binary's SHA-256 hash is verified against a sidecar file at build time before it is loaded, preventing tampering with the validation logic.