Skip to main content

Noxys Developer Handbook

Audience: developers joining the Noxys ecosystem (employees, contractors, OSS contributors). Purpose: explain how we build, test, ship and operate Noxys — the how, not the why.

Welcome​

Noxys is a multi-repository monorepo-style ecosystem (noxys-extension, noxys-console, noxys-api, noxys-doc, noxys-website, noxys-infra, …) building Europe's first sovereign AI Firewall. This handbook is your starting point.

Read in this order:

  1. Setup — local dev environment per repo
  2. Architecture — high-level system overview, bounded contexts, data flow
  3. Release process — staging → main, semver, ADR-013 retention
  4. Testing — TDD, integration, E2E expectations
  5. Security — secret management, threat modeling, compliance

Glossary​

Domain terminology lives in the Platform Glossary. When in doubt, use that page; when ambiguous, propose an addition via PR.

Decision history​

Architecture Decision Records (ADRs) live in docs/adr/. Every architectural choice is documented; every deviation requires an ADR amendment.

Contribution model​

  • Branch from staging — never directly from main. The pipeline is feat/* → staging → main.
  • PR review required for every change — no direct push to protected branches.
  • OpenAPI mandatory — every new API endpoint ships with an OpenAPI 3.1 spec in the same PR (CI enforces).
  • Tests in the same PR — code without tests is rejected.
  • Conventional commits — see release-process.

Where to ask​

  • Real-time chat: internal Slack #noxys-dev
  • Async: GitHub Discussions per repo
  • Synchronous: weekly tech sync (Mondays 10am CET)
  • Security or vulnerability reports: security@noxys.eu (PGP on the Trust Center)

Status of this handbook​

The handbook is maintained as living documentation. Each section is intentionally short and links out to authoritative sources (ADRs, project READMEs, docs.noxys.cloud sections). Contribute corrections via PR against noxys-doc.

Last reviewed: 2026-05-10 — next quarterly review: 2026-08-10.