Level 3 — Components: noxys-api
The Component view zooms inside a single container. We document noxys-api
here because it is the authoritative control plane and the most frequently
modified backend service.
Diagram
Components
HTTP / API layer
| Component | Responsibility |
|---|---|
| Middleware chain | Authentication (JWT / API key), tenant resolution, rate limiting, request-id propagation, structured logging, OpenTelemetry tracing. |
| Extension handlers | High-volume endpoints called by browser / VS Code extensions — event ingest, policy sync, catalog lookup. Optimised for low latency. |
| Admin handlers | Console-facing CRUD for policies, users, tenants, audit, reports. |
| Webhook handlers | Inbound webhooks from Stripe and IdP. Signed and replay-protected. |
Domain services
| Component | Responsibility |
|---|---|
| Policy Engine | Evaluates an AIInteraction against the active policy graph and returns a verdict (Block / Coach / Log). Implements default-deny (S2 sprint). |
| Audit Service | Ingests audit events, ensures prompt content is never persisted in raw form, fans out to SIEM connectors and the local audit store. |
| Catalog Service | Manages the AI service catalog (sanctioned / under review / blocked). Powers extension policy decisions about which AI service is being used. |
| Tenant Service | Provisions tenants, enforces isolation, manages quotas, integrates with SCIM for user provisioning. |
| Report Service | Compiles DPIA, transparency reports, audit exports. Delegates rendering to the PDF Renderer. |
| Detection Orchestrator | Routes prompts that need Tier 2 (synchronous) or Tier 3 (asynchronous) detection, applies short-lived verdict caching in Redis. |
Data access (Repository Pattern)
Each repository encapsulates a single aggregate. All queries are parameterised and row-level-security policies enforce tenant isolation at the database layer.
| Repository | Aggregate |
|---|---|
TenantRepo | Tenant, plan, quota, SCIM mapping |
PolicyRepo | Policy graph, rules, snapshots |
UserRepo | User, role, group membership |
AuditRepo | AuditEvent metadata (no raw prompt content) |
CatalogRepo | AI service entries, sanction status |
Integrations
| Client | Target | Notes |
|---|---|---|
Presidio Client | noxys-presidio sidecar | Tier 2 PII / Risk Signal detection. Sends tokenised payloads. |
AI Forge Client | noxys-ai-forge | Producer of async Tier 3 jobs via Redis stream. |
SIEM Connector | Customer SIEM | Pluggable backend — syslog RFC 5424, Splunk HEC, generic webhook, Sentinel, Sekoia. |
Stripe Client | Stripe | Subscription state, invoices. |
IdP Client | Entra ID / Okta / Workspace | OIDC, SAML, SCIM. |
Email Client | Postmark / SES | Invitations, password reset, alert digests. |
PDF Renderer Client | noxys-pdf-renderer | HTML → signed PDF for DPIA, transparency, audit packs. |
Cross-cutting concerns
- OpenAPI 3.1 — every endpoint exposed by an
*Handlerscomponent MUST have a matching spec shipped in the same PR (see OpenAPI policy). - Observability — every component emits OpenTelemetry traces;
request-idflows from middleware through services to integrations. - Multi-tenancy invariant — every query goes through a repository; raw SQL outside the repository layer is forbidden (enforced in code review).
- No raw prompt persistence — the Audit Service hashes prompts at the boundary; downstream stores see only metadata (per ADR-002).