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.)
         — provider traffic is direct; configured policy evaluation uses your server —

The proxy daemon runs on each workstation, not on the server. On supported configured paths, the daemon intercepts AI traffic locally and sends the content required for policy evaluation to the customer-operated policy engine. Provider requests then travel directly from the workstation to the configured LLM provider; the policy engine is not a relay to that provider.

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 — configured evaluation events recorded in PostgreSQL with hash-chain verification where enabled
• 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	Evaluation events with hash-chain verification where enabled and validated
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. Traffic from configured proxy-aware applications to supported AI destinations passes through here; unmanaged, bypassed, or unsupported paths require separate controls.

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 configured destinations from proxy-aware browsers and applications; CLI and API clients require explicit proxy and CA configuration unless they honor the OS proxy
• 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 is designed to remain in the workstation keystore)

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 supported CA workflow is designed to keep the private key in the workstation keystore. The application does not intentionally upload it to the Policy Engine or hosted portal. Only the CA public certificate is installed in the OS trust store and supported browsers. Administrators remain responsible for endpoint and keystore controls that can affect key custody.

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
   (the provider request is sent from the workstation; policy evaluation uses the customer-operated server in step 5)

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.