Design Decisions Ratification
This document records the ratified design decisions that underpin the Noxys platform. It is the canonical entry point for new contributors who need to understand why the system is built the way it is — not just how.
Every decision below is backed by an Architecture Decision Record (ADR) in the
internal vault (Noxys/03 - Decisions/). When an ADR ID is cited (e.g.
ADR-010), it is the authoritative source; this page is a curated digest.
Tech leads ratify changes via PR. Open an RFC issue in noxys-doc before
proposing an amendment. Out-of-band changes (Slack, email) are non-binding.
1. Architecture
1.1 Three-Deployment-Method Model
Noxys ships in exactly three deployment topologies. Any proposal for a fourth is rejected by default to keep the contract surface small.
| Method | Where it runs | Primary use case | Latency cost |
|---|---|---|---|
| Browser Extension | User device (Chrome/Edge/Firefox/Safari) | Shadow-AI discovery, prompt interception on consumer SaaS AI tools | None (in-browser) |
| Endpoint Agent | User device (Windows/macOS/Linux) | Native LLM clients, IDE plugins, terminal-based AI | < 5 ms local hook |
| Forward / Reverse Proxy | Customer network or Noxys SaaS edge | Server-to-AI traffic, agent platforms, batch pipelines | < 30 ms p95 |
Rationale: each method addresses a distinct interception point; covering all three guarantees no AI egress channel escapes policy enforcement.
Refs: ADR-005, ADR-019.
1.2 Multi-Tenant Isolation via Postgres RLS
All tenant data is isolated through PostgreSQL Row-Level Security (RLS)
policies driven by current_setting('app.tenant_id'). Application code never
filters by tenant_id directly — RLS is the floor.
- Single shared database, schema-level isolation per logical concern.
SET LOCAL app.tenant_idis enforced at every connection checkout (Go middleware) and tested in CI via a "tenant escape" fuzz suite.- Cross-tenant queries (admin only) require an explicit
BYPASSRLSrole with audit logging.
Refs: ADR-002, ADR-018.
1.3 Stack
| Layer | Choice | Why |
|---|---|---|
| API | Go 1.22+ | Predictable latency, native concurrency for proxy, small binary, mature TLS |
| Console (web UI) | TypeScript + React + Vite | Ecosystem, i18n maturity, fast HMR for design iteration |
| Browser extension | TypeScript + Manifest v3 (Plasmo) | Cross-browser parity, modern service-worker model |
| Endpoint agent | Go (shared with API) | One language across server-side surfaces |
| Database | PostgreSQL 16+ | Native RLS, partial indexes, JSONB, logical replication |
| Cache / queue | Redis 7+ | Token-bucket rate limiting, ephemeral session state |
| Object storage | S3-compatible (MinIO self-hosted, AWS S3 SaaS) | Portability, EU regions |
| Billing | Stripe | EU VAT MOSS, SCA, established |
Refs: ADR-001, ADR-003, ADR-009.
2. AI Provider Strategy
2.1 EU-Sovereign First
The default upstream LLM for detection, classification, and coaching is Mistral (EU-hosted, FR jurisdiction). Customer-facing AI features may use other providers only via an opt-in policy.
2.2 Internal Engineering AI
Internal code generation (developer tooling, not customer data) is permitted to use Anthropic Claude. No customer prompts or PII ever leave the EU detection pipeline through this channel.
2.3 Multi-Provider Routing
The proxy supports policy-driven routing across providers via the
PROXY-6 adapter layer. Supported providers as of 2026-Q2:
- EU: Mistral, Aleph Alpha, OVHcloud AI Endpoints
- US (opt-in): OpenAI, Anthropic, Google Gemini, AWS Bedrock
- Self-hosted: vLLM, Ollama, llama.cpp endpoints
Refs: ADR-007, ADR-021, PROXY-6 sprint spec.
3. Data Residency
- Default: EU-only. All databases, object stores, queues, and inference endpoints reside in EU regions (FR/DE/NL primary).
- Tenant choice: Enterprise tenants may pin region (
eu-fr,eu-de,us-east-1) at provisioning. Migration between regions is a paid service. - Sub-processor map: Live at
/legal/sub-processors. Updated within 30 days of any change per GDPR Art. 28.
Refs: ADR-004, /legal/sub-processors.
4. Compliance Frameworks Supported
| Framework | Scope | Status |
|---|---|---|
| GDPR | EU personal data, DPIA, Art. 30 register | Native |
| NIS2 | Critical entities, incident reporting | Native |
| DORA | Financial sector ICT risk | Native (Enterprise) |
| EU AI Act | High-risk AI use, transparency obligations | Native |
| ISO/IEC 22989 | AI concepts and terminology | Aligned |
| ISO/IEC 23053 | AI/ML framework | Aligned |
| OECD AI Principles | Trustworthy AI | Aligned |
| HIPAA | US healthcare PHI | Optional add-on (US region) |
| PCI-DSS v4.0 | Payment card data | Inherited via Stripe; PAN never stored |
| SOC 2 Type II | Security & availability | Roadmap 2026-Q4 |
Refs: /security/compliance, ADR-012.
5. Authentication & Identity
5.1 JWT with jti Revocation
API tokens are short-lived JWTs (15 min) with a refresh token (7 days). Every
JWT carries a jti claim checked against a Redis revocation set on each
request — enabling instant logout and breach response.
Refs: ADR-013, AGENT-3 sprint.
5.2 MFA — TOTP Mandatory for Admins
TOTP (RFC 6238) is the mandatory second factor for any console role with write scope. WebAuthn/passkey support is planned for 2026-Q3.
Refs: ADR-014, CON-8 sprint.
5.3 SSO
Supported IdPs: Microsoft Entra ID, Google Workspace, Okta, generic SAML 2.0, generic OIDC. SCIM 2.0 for provisioning.
Refs: ADR-015, /integrations/sso-configuration.
6. Pricing & Packaging
Three tiers (post-ADR-010, which collapsed the prior 4-tier Starter/Business
split into a single Pro tier).
| Tier | Price | Seats | Target |
|---|---|---|---|
| Free | €0 | Up to 8 users | Discovery, individuals, evaluation |
| Pro | €12 / user / month | Unlimited | SMB and mid-market |
| Enterprise | Custom | Unlimited | Regulated industries, self-hosted, custom DPA |
Refs: ADR-010.
7. Detection Layer
Noxys uses a multi-method ensemble for prompt risk detection. No single method gates a decision — votes are weighted by signal class.
| Method | Strength | Latency budget |
|---|---|---|
| Regex (curated rule packs) | Deterministic, fast, explainable | < 1 ms |
| Microsoft Presidio (analyzers) | Mature PII NER, broad locale coverage | < 20 ms |
| Mistral classifier (small distilled model) | Context-aware, multilingual semantic risk | < 80 ms |
| Z-score baseline (per-user behavioural) | Anomaly detection on prompt volume, length, topic shift | Async (offline) |
The orchestrator merges signals and emits a single decision: allow,
coach, redact, or deny.
Refs: ADR-016, ADR-022.
8. DLP & SIEM Integrations
Out-of-the-box egress to external security tooling:
- CEF over Syslog (UDP/TCP/TLS) — Splunk, QRadar, ArcSight, Sekoia, HarfangLab
- Generic webhook (HMAC-signed) — any downstream
- Microsoft Purview — labels, DLP policies, incidents
- Microsoft Sentinel — Log Analytics ingestion
- Microsoft Defender for Cloud Apps — Shadow-AI catalog sync
Refs: ADR-017, /integrations/overview.
9. Prompt Storage Tiers
Captured prompts are stored under one of four storage classes, tier-gated and per-tenant KMS-encrypted. By default, no Noxys staff has raw access.
| Class | Content retained | Default tier | KMS |
|---|---|---|---|
| Aggregate | Counts and risk-class histograms only | Free | Platform KMS |
| Hashed | SHA-256 of normalised prompt; no plaintext | Pro | Platform KMS |
| Redacted | Prompt with detected entities replaced by tags | Pro / Enterprise | Per-tenant KMS |
| Raw | Full plaintext prompt + response | Enterprise (opt-in) | Per-tenant KMS, dual-control unseal |
Refs: ADR-020.
10. API Contract Discipline
10.1 OpenAPI 3.1 Mandatory
Every public API endpoint must ship with an OpenAPI 3.1 spec in the same
PR that adds it. CI gate (openapi-lint + oasdiff breaking) blocks merges
that violate this rule.
Backfill obligation: ADRs 014 through 024 carry a backfill task for any pre-existing endpoint missing a spec.
10.2 Versioning
URI-versioned (/v1/, /v2/). Breaking changes require:
- New major version path.
- Old version supported for 12 months minimum.
- Deprecation notice in
SunsetHTTP header per RFC 8594.
Refs: ADR-023, ADR-024.
11. Where to Go Next
- Platform architecture — runtime view
- C4 model — context / container / component diagrams
- Security & compliance — control mapping
- Developer handbook — local setup, release process
- API reference — endpoint catalogue
Change log
| Date | Change | Author |
|---|---|---|
| 2026-05-13 | Initial ratification doc (DOC-5, closes #20). | Tech leads |