Architecture overview¶

Privyx is a privacy engine with an HTTP proxy around it. This page shows how the parts fit together. For what the proxy does from a user's point of view, see How it works.

Architecture¶

┌────────────────────────────────────────────────────────┐
│                      PRIVYX GATEWAY                     │
│                                                        │
│  HTTP ──┐                                              │
│  SSE ───┴──► Protocol / Provider Adapter               │
│                         │                              │
│                         ▼                              │
│                  Privacy Pipeline                      │
│                         │                              │
│        ┌────────────────┼────────────────┐             │
│        ▼                ▼                ▼             │
│     Detector          Policy          Operator         │
│        │                │                │             │
│        └────────────────┼────────────────┘             │
│                         ▼                              │
│                     Anchor                             │
│                         │                              │
│                         ▼                              │
│                       Vault                            │
│                         │                              │
│            Memory / SQLite / Redis                     │
└─────────────────────────┬──────────────────────────────┘
                          │
                          ▼
               ┌────────────────────┐
               │    AI Providers    │
               │ OpenAI Anthropic   │
               │ Gemini DeepSeek... │
               └────────────────────┘

Design Principles¶

Core does not depend on FastAPI.
Core does not depend on any provider SDK.
Provider is a plugin/adapter.
Detector is a plugin.
Operator is a plugin.
Vault is a backend abstraction.
Streaming is first-class.
SSE envelope is separated from text transformation.
Session state that outlives a request must not depend on process memory.
CLI is only orchestration/UI.
Observability must not leak into privacy logic.
No plaintext PII in logs by default.
All streaming algorithms are property-tested against random chunk boundaries.

Module Layout¶

Module	Purpose
`core/`	Engine, session, context, result, errors — transport-agnostic
`token/`	Logical token + configurable codec (the only place token syntax lives)
`privacy/`	Detectors, policies, operators, anchors, transforms
`streaming/`	Deanonymizer, recognizer, trie, buffer, SSE adapters
`vault/`	Memory, SQLite, Redis session storage
`providers/`	Generic, OpenAI, Anthropic transports (Google is a placeholder)
`proxy/`	HTTP/SSE proxy connecting engine to providers
`gateway/`	Optional FastAPI server
`cli/`	`privyx` orchestration layer
`config/`	Schema, loader, defaults, env
`security/`	Keys, crypto, secrets, redaction
`observability/`	Logging, metrics, tracing, audit
`plugins/`	Plugin registry, loader, hooks

Data Flow (Request)¶

Client → HTTP Proxy → Detect → Policy → Pseudonymize → Provider
                                                    ↓
Client ← HTTP Proxy ← Restore ← Vault ←────────────────┘

Data Flow (Streaming)¶

Provider → SSE event → Adapter → text delta → Privacy Stream Engine
                                          (codec recognizer + hold-back)
Client ← SSE event ← Adapter ← deanonymized delta

The hold-back scan guarantees streamed output equals batch output, even when a token is split across chunk boundaries.

Development¶

uv sync --all-extras
make test       # or: uv run pytest
make lint       # or: uv run ruff check src tests

See development/testing.md for the test strategy.