Skip to content
Nexa Engineering Handbook

Nexa Engineering Handbook

Build Nexa consistently, securely, and predictably

Section titled “Build Nexa consistently, securely, and predictably”

This handbook defines how Data Ready AI engineering teams design, build, test, secure, package, and internally deploy the Nexa platform. It converts scattered practices into a shared operating model across React, Node.js, FastAPI, container, Kubernetes, and Terraform repositories.

Handbook status: Version 2.0 establishes the internal product-development baseline. Customer distribution, Harbor-based release delivery, Databricks Apps, Snowflake Native Apps, and other specialised repository types will be added as separate extensions.

What this handbook solves

Section titled “What this handbook solves”

Nexa has grown into a multi-service, multi-cloud product. Several teams have independently created workflows, scans, test approaches, and branch conventions. The result works, but it creates duplicated CI code, inconsistent quality gates, unclear promotion rules, and avoidable operational risk.

The handbook provides one answer to recurring questions:

  • What must a developer do before opening a pull request?
  • Which branch deploys to each internal environment?
  • Which checks block a merge?
  • How are release bugs fixed with only dev, test, and prod environments?
  • How do repositories consume common CI workflows?
  • Which security tools are authoritative, and where do their responsibilities stop?
  • How are Docker images built once and published unchanged to ECR, ACR, and the Snowflake image registry?
  • What must Kubernetes and Terraform repositories validate before merge?

Operating model

Section titled “Operating model”
flowchart LR
  Dev[Developer practice] --> Repo[Repository governance]
  Repo --> CI[Reusable CI]
  CI --> Registry[ECR / ACR / SPCS]
  Registry --> CD[Argo CD Image Updater]
  CD --> Env[Dev / Test / Prod]
  Env --> Feedback[Testing and operational feedback]
  Feedback --> Dev

How rules are expressed

Section titled “How rules are expressed”
  • MUST is mandatory unless an approved exception exists.
  • SHOULD is the expected practice; deviations require a clear reason.
  • MAY is optional guidance.
  • Current state documents the process Nexa can execute today.
  • Target state describes an approved maturity improvement and its prerequisites.

First reading path

Section titled “First reading path”

New engineers should read Engineering Principles, Developer Hygiene, End-to-End Lifecycle, Branching Model, Pull Requests, and the standard for their repository type. Platform engineers should additionally read the entire CI, CD, Kubernetes, Terraform, and security sections.